Last updated April 10, 2013. Created by indytechcook on February 9, 2012.
Edited by Kristen Pol, barraponto, brantwynn, chrisjlee. Log in to edit this page.
This page contains documentation for the Bean module.
Bean is an acronym that stands for Block Entities Aren't Nodes. This is a play on the numerous "nodes as blocks" modules that were common practice in Drupal 6.
How Beans interface with Blocks
Each bean instance has a corresponding block. Users interact with them in the same way they might use any other block in Drupal. The Bean module does not attempt to interface with the placement of blocks. Bean deals only with the creation of customized, fieldable blocks.
Block Types
Like "Content Types" for nodes, beans have Block Types. A block type is the bundle for a set of block entities (aka beans). Block Types define the configuration model for each individual bean.
How to make a Block Type
Users can create new block types through using the Bean UI or they can program new block types as bean plugins in code within their modules.
http://youtu.be/Eu1YNy-BNG8 - Bean Admin UI Tutorial
How to make a Bean
Once a block type has been defined, one can make a bean (block entity) through the admin UI
Visit: /block/add.
Choose the type of block that you would like to create and use the form to create a new bean.
Block placement and configuration can be handled through the Blocks system or contribs that deal with block placement (ie: context, display suite et al).
Developer Documentation
See Bean Examples for an up-to-date plugin implementation.
If you have already implemented Bean plugins, keep an eye on the API changes.
Themer Documentation
In the case where a Bean plugin provides a .tpl file, theme output of the Bean can be overridden. Output for node listings inside a Bean often make use of view modes- these can be styled according to the ID selector of the individual Bean or the class wrapper for the entire Bean type.
Articles and Videos
- http://treehouseagency.com/blog/neil-hastings/2011/09/21/building-custom...
- https://gist.github.com/1460818
- Drupal Bean module tutorial
- http://youtu.be/Eu1YNy-BNG8 - Bean Admin UI Tutorial
- https://github.com/skwashd/bean_boxes - Easily convert Boxes to Beans
- Views without Views
- An Introduction to Bean Module
Warning for Bean All Module
Note that the Bean All module will hijack the core block system (by design) which will prevent you from putting blocks into regions using the core block UI. This has caused some confusion during development for some so this warning has been added to help future developers!
Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.
Comments
Why?
There is something I don't get: why using beans and its UI when you have content types and the possibility to use it the exact same way?
Create a new Bean? Well, I create a new Content type. The UI is just the same.
The only difference I see is that you can manage your blocks in the block page... But who wants to give this block page to her/his client? He's just going to mess up the whole website.
It would be way better if you had no possibility whatsoever to see the block on its own page (on the URL block/my-block) as it is for nodes, but only to edit it in the admin.
Sadly, with Bean UI, blocks become... nodes.
I am sure I don't get the point... Please tell me what I get wrong!
"Reality is that which, when you stop believing in it, doesn't go away." -Philip K. Dick
Because
First of all, block content is not actual content, at least not in the sense we regard nodes to be content. Promotional blocks, with an image and a url or node path are very common patterns that are either solved with promotional fields in the actual node or (worse) content types. Beans are a particular solution that keeps our node interfaces clean, while providing the features we need.
And although the Block API allows us to write a settings form, it doesn't account for multiple block configurations, like menu_block or boxes offer. These modules had to implement it from scratch, worrying about database schemas and the likes. Beans, being entities, provides a lot of these basic functionalities out-of-the-box.
Capi Etheriel
Web Stategist, Developer, Designer and Scraper
Hacker Transparency Movement
http://barraponto.blog.br http://zerp.ly/barraponto
block URL
The only reason blocks have a URL is because the entity_api module requires a url for an entity. I like the idea of adding a permission for that page. I created an issue here http://drupal.org/node/1535444
Keep in mind...
Keep in mind that you do not need to open up the block menu/config to clients. User friendly modules like Context Layouts and Panels allow for user-friendly block placement. Blocks as a system should exist as entities and be silo'd away from content nodes. This allows for better site architecture and keeps Content Types that are specific towards using nodes as blocks out of the picture. The system of fieldable block types is something that many have already found an invaluable asset to their Drupal site building process.
Theme Hook Suggestions when using Display Suite with Beans
When using Display Suite you may need to theme Bean Blocks according to their Bean Type.
e.g. block__bean__BEAN-TYPE.tpl.php
In ordinary use plain vanilla beans use bean.tpl instead of block.tpl. However using Display Suite with Beans will result in bean.tpl being completely overridden and block.tpl being used. Themers will then want to style block.tpl to be in harmony with the Bean Type (and the DS style applied to it).
Out of the box neither Bean nor Display Suite provide theme hook suggestions that would allow themers to make a copy of block.tpl and rename it to match a Bean Type.
The following code enables block__bean__BEAN-TYPE as a block.tpl theme suggestion (when pasted into a theme’s template.php file).
<?php/*
* Implements template_preprocess_block
*
* enable bean blocks to be themed by bean-type:
* i.e. block__bean__BEAN-TYPE.tpl
*
* rename 'themename' to match the name of your theme
*/
function themename_preprocess_block(&$variables) {
// select Bean Blocks and ignore other Blocks
if (!empty($variables['block']->module) && isset($variables['elements']['bean'])) {
$bean_array = $variables['elements']['bean'];
$child_key_array = element_children($bean_array);
$bean = $bean_array[$child_key_array[0]];
if (!empty($bean['#bundle'])) {
$variables['theme_hook_suggestions'][] = 'block__' . $variables['block']->module . '__' . $bean['#bundle'];
}
}
}
?>
Not just for display suite
Note that this type of thing is useful to all, not just those using display suite.
Also, for reference, this is the related issue in the bean issue queue - #1361756: More theme candidates
updated theme_hook_suggestions code
I keep an updated gist of this code at:
https://gist.github.com/paulhhowells/4722363
(which is coded more defensively than the example above)
Caution
"Beans are a particular solution that keeps our node interfaces clean, while providing the features we need." - I think this is an interesting module and concept but I would caution people who use this that this in terms of usage this could open up a can of worms as far as your clients are concerned. I just started a contract where the developer before me used BEANs very aggressively and now beans has seemingly become the defacto standard for adding content to the site and the client seems to think this is normal. It has sort of become a way to go around using nodes and panels and blocks and views and all kinds of other "normal" Drupal tools and I am having trouble wrapping my head around how to work with it. Imagine pages where the main content is a bean for example - try theming this. Go ahead I dare you!
Drupal 7.0
Well...
I know you used quotes around "normal" but its borderline trolling what you're doing here. :) In my opinion, there's nothing "normal" about using a UI to create queries (Views) but people do it all the time. Does this mean Views isn't awesome? Of course not. In Drupal, and in life, there are always going to be new things to learn. So complaining that you don't like learning how to properly use bean is a bit lazy IMO. People often get a quick RTFM when doing this in other places. I'm trying not to do this here as I know the documentation could be better.
From what you're describing, I don't think anyone had ever intended for Bean to be used in that way - but that doesn't mean there's anything wrong with that approach - especially if it makes sense to the client. As always, "with great power comes great responsibility" resonates in the world of Drupal. One can build a site many different ways - which is great... but it doesn't mean that anyone should try to do what you're describing here if they don't understand how Beans work.
In my experience, Beans are often used as a compliment to nodes - much like Views. There are cases where one might need a View, and there are others where one could need a Bean or a Fieldable Panels Pane or something else. You can write theme templates for your Bean types, so I'm not sure exactly why you'd have trouble on the front-end with this module. But if you're having trouble with the documentation, please just ask us - we're on IRC in #drupal-beans every day. Admittedly, we do need help making the docs as good as possible. Of course, you could be a part of this if you wanted...
Sorry if this sounded like a
Sorry if this sounded like a criticism of Beans. It wasn't meant to be. I think it is a brilliant idea and well implemented. And you're right there is nothing wrong with clients using beans however they want. Now that I know about this module I could see myself using it in the future if I don't feel like creating a custom block module or entity...
Drupal 7.0
Possible application of Beans
It sure looks cool and nice as a project, but to be honest I didn't see anybody pointing a real life website that uses beans and it is a justified use. I have read though, this interesting discussion unrelated to beans, but related to entities, about commerce websites, where products didn't have to be nodes, but just entities. This is the only interesting use of entities that I heard of.
I have an idea for some time now, and I didn't find a way to implement it with the existing plugins, but entities, and beans seem so close to it. I want to edit a node by editing multiple entities, which entities can be some placeholders for my content.
I would like to be able at the editing time of a node to add a bean, that would be part of the new node. The node will eventually contain one or more beans, that will make up the content.
Why this approach? The beans will contain pre-formated content snippets, with an image, a title, and text, which will become a paragraph, (or chapter), if you want. I can do that with entities, but the solution I found was creating node for any new entity created. So in the end I would have had one main node and several nodes included in the main node. That is killing the SEO. I tried it also with field group, and it wasn't elegant enough. I need this to be transparent for a user, and it should be defined in the content type, so when the regular user starts to edit an article, they can add one or two or five content blocks as needed, (read beans).
Would this be achievable at this point? If not, maybe someone like my idea, and makes a plugin for beans.
Dorian
Drupal enthusiast
http://www.head-massage.net
Case Study
You might want to check out http://energy.gov
http://www.slideshare.net/zroger/energygov-case-study-badcamp-2011
The best solution depends on your specific use case
I have done something like this where each page is made up of reusable sub-blocks of content.
Originally I was going to use beans as the sub-blocks via the block reference module, however I determined that due to the very large number of these blocks for this site, the performance implications of using blocks were not ideal, so I ended up using a second node type for the sub-blocks via the entity reference module, which meant I also inherited the masses of drupal modules out there that are still specifically aimed at nodes and bypassed some of the downsides of using such a large number of blocks on the site.
It really comes down to your specific requirements as to what is the best solution for your needs, but beans are a viable solution in some cases.
We typically use beans on
We typically use beans on reusable types of blocks. As an example, say our site editors needs to be able to create promotional blocks that all have a similar layout. We create a bean that might have a required title, image and url and we theme it all to link the image and title to the url. This is probably the most common thing we do with them. We can also implement custom slideshow bean types and do the theming/js from the module level to allow editors to create multiple slideshows across the site. Those are two use cases for you.
Los Angeles Web Design and development for Drupal.
Yeah those are common uses.
Yeah those are common uses.
Also in some cases just to make admin editable blocks when admins don't have access to administer blocks.
It gives them a more familiar interface without exposing too much.
when I've added a new block
when I've added a new block type I dont see anything to pick from when adding a new block?
File support request
You won't get much help here. This is a docs page. You need to use the issue queue and file a support request. The comments on this page are for commenting on the docs, so its not a good place to get your questions answered.