Organic Groups (OG) for Drupal 6 is a powerful and widely used module for creating websites that enable group collaboration or to create 'mini sites' within a bigger Drupal site. The Drupal 7 version of Organic Groups is a total rewrite, taking advantage of many new Drupal 7 features, in particular the new APIs for entities and fields.
One of the big differences between the Drupal 6 and Drupal 7 versions is an expansion of the concept of what a 'group' is. In D6, a group is a node, and other nodes can be assigned to it as the content of the group. In D7, any type of entity can be a group and any type of entity can belong to a group.
In this article we'll take a high level look at the new architecture of an Organic Groups group, and walk through the steps to build a basic group in Drupal 7.
What is a Group?
Looking at the illustration above you can see a group is made up of many different types of entities. At the center is the group entity itself, which is often a node. A group entity is the 'parent' for all the things that belong to a group.
Users and content are the two kinds of entities that can belong to a group. Each user and each piece of content is connected to the group with an additional entity. This entity is a special OG membership entity that links users and content to their associated group. At a high level, it's simply a record in a table that tracks which entities belong to which groups.
There are actually two different 'group entities' in the current architecture. One is the content type or other entity you designated as your 'group', and the other is a special OG entity that you probably won't even realize is there. The OG entity behind the group node is the real 'group', and the id of the OG entity is the Group ID (or GID). This is one of the most confusing things about the architecture of OG in Drupal 7. There are two different 'group' entities, and the NID of the group node is not the GID of the group. This may change in the future, so see the notes at the end of this article for more information.
Group Entities
To get started with Organic Groups, we need to decide which type of entity will be the group 'parent'. In the Drupal 6 version this was always a content type (a node), but in Drupal 7 it can be any kind of entity. It will still be a content type in many cases, but it doesn't have to be. One example of another way to set this up is the way the Energy.gov site was constructed where they used taxonomy terms as groups. (See Case Study: Energy.gov for more details about that.)
For the example we're building here, we'll assume we are going to use a content type called 'Group' as our group container, similar to the way we would have done this in the D6 version of Organic Groups.
Group Content Entities
Next we need to decide what types of entities can belong to our groups. We could have several content types for this purpose, perhaps creating and designating 'Articles' and 'Images' and 'Events' as types of content that can belong to groups.
Group content is not limited to node entities or content types. Other types of entities can belong to groups as well. The entities that are available are limited only by the modules that are installed on the site. For instance, if the Media module is installed, the media entity type can be group content. If the Commerce module is installed, product entities can belong to groups. If the Bean module is installed, block entities can be given group membership. (And note that since any entity can be the group entity, all of these types of entities could also be used as the group entity type.)
Users are another, special, kind of group 'content' entity. They are connected to groups in the same way that content is, with the OG membership entity, but they also have some special properties so users can be given roles and permissions that control what they can do within the group.
Any type of entity can belong to a group. In fact, the group entities themselves can also be designated as potential content for other groups. If set up this way we could have groups that contain other groups, creating subgroups.
Download and Enable Modules
Once we have a mental map of which entities will be groups and which will be group content, we can start building the site by downloading and enabling the Organic Groups module. Organic Groups is dependent on the Entity API module, so we need that, too.
The D6 version of Organic Groups is a monolithic module that does practically everything you might need your group to do. The D7 version has gone the other way. Everything is abstracted out into modules for specific purposes, and some of the functionality has even been moved to separate projects. Some of the spinoff projects just have notices on the project page saying that the functionality will ultimately be moved, so things may change.
The spin-off modules currently include the following:
- OG Content Links - creates an 'Add Content' field that will display links to let users add new content to the group
- OG Views - provides a 'Group View' field you can add to a group entity to display a view of the group content on the group page. Note that this module currently isn't required for Views integration, but apparently will be in the future. If you want to embed a view of the group content into the group page without using Panels you may want the field it provides.
- OG Theme - creates a 'Group Theme' field that lets users choose which theme to use for a group
- OG Language - provides a 'Group Language' field that lets users choose which language applies to a group
Within the core OG code there are some other changes. For instance, there is now a module that comes with OG called OG Context. If you will have any need to know which group you are in when you view a node or a page, you will need to enable the OG Context module.
OG UI has also been split out into a separate module. If you just enable the core OG module and can't figure out why nothing seems to be showing up in the administration pages to help you set your groups up, you may have missed this module. Obviously the reason for this is that you can disable it later, when the groups are all properly configured.
Building Our Groups
In the D7 version, with fields in core, we use special OG fields to connect all these entities together. If you've use Node Reference fields before, you'll recognize the pattern -- each entity has a field or fields that allow you to indicate which other entities they are connected to. To make this work, we have to add the OG fields to the entity, in the same way we would add a Node Reference field.
So we'll start by creating a new content type called 'Group'. Scrolling down to the bottom of the content type edit screen we can see a Group tab that allows us to indicate if this content is a group or group content. We need to indicate it is a Group type.
Next, we can edit existing content types (or add new ones) and edit them. Using the same Group tab we used above, we mark them as a Group content type to allow content of that type to be associated with a group.
After marking a content type as group content, we might go to the Manage Fields screen for each content type to add OG fields to it. When we do we will see that there is an option to add a Group audience field, which is the field to choose which group the group content should belong to. But we won't see any other of the special OG fields there. This is another one of the confusing aspects of the Drupal 7 version. It uses fields but you can't control them completely from the Manage Fields screen.
To add the special Organic Groups fields, we need to go to the Organic Groups administration section. Looking at the site configuration screen illustrated below, we will see a number of options. The one we want is Organic Groups field settings.
Once there (at admin/config/group/fields), we will see a screen like the following:
Some things were automatically handled when we marked the content type as OG group or group content types, but our group and group content entities are still missing a lot of the fields we will want on them. To add the rest of the fields we have to select an entity/bundle in the top selector, and then choose the fields that need to be added to it in the bottom selector. The available fields are sub-divided by group and group content, to indicate which fields can be added to the group entity and which belong on the group content entities. To add a field to a content type we select the content type in the top and the field in the bottom and click on Add field.
If we want to have the possibility of private groups, we can add the Group Visibility field to the group. If we want to have per-group permissions that override the global roles and permissions we can add the Group roles and permissions field to the group entity type. If we have used some of the spin-off modules mentioned above, we will see options to add fields like the Group content links
The group content entities get different fields. They need a Group audience field and perhaps a Group visibility field (to let authors choose if the content is publicly visible).
Note that the Users entity gets the same Group audience field that group content gets. This is the field that will keep track of which groups a user belongs to.
When the fields are all set up, you can select an entity in the list below and see which fields have been assigned to it.
At this point you can go back to the Manage Fields screen for the entity and you will see all the OG fields where you can re-arrange them as desired. You can also check their settings. One setting you will want to double-check for sure is whether the Group audience field is a single value or multiple value field. If you want to be able to join users or content to more than one group you need to be sure the field is configured as a multiple value field.
You'll want to make some changes to the way the fields are displayed on the Manage Display screen. Many of the special OG fields have a format called Group subscription. This is a setting that will adjust the display based on the permissions of the user who is viewing the page. If they are not a member and they have permission to join a group, they will see a link to join the group. If they are a member they will see a message that they are already a member and what their role is.
The Group content links and Group views fields need to be moved from the default format to the Group content links and Group views formats, respectively.
With those changes, we can create a new group node, and the node edit screen will display our OG fields. There we can choose whether this entity is a group, whether it should be public or private, which types of content can be created, what permissions apply, and which view to use for the display of group content.
And the finished node looks like this:
We can now see our subscription status to the group, the description of the group, links to add new content, and a view of any existing group content (at the moment, of course, there is none). And the group administrator will see a new Group tab next to the View and Edit tabs. That Group tab takes you to the group administration page, where you can add or manage group members and do other group administration.
Next Steps
That is a very rudimentary introduction to how to set up Organic Groups. There is much more than can be done. You can go back to the Organic Groups administration page and investigate all the other options there. There are options to do things like set up global roles and permissions for your groups and identify how context will work.
You also can go to Views and configure special views of group content or group members. And you can use Panels to glue it all together. There's also a OG Example Feature included in OG which creates a simple configuration of OG (this requires the Features, CTools, and Panels modules).
I mentioned above that there may some architectural changes coming. There is an issue about getting rid of the 'extra' group entity in the OG issue queue. The idea is to simplify the configuration and organization of OG going back to the pattern used in D6, where the group entity IS the group, and the group entity ID is the GID of the group. Also see OG and Entity reference, where Amitaibu (Amitai Burstein), the OG maintainer, is looking for sponsorship to make that change.
Reference Material
Module List
- Organic Groups - the core OG code
- Entity API - required to use OG
- OG Content Links - creates an 'Add Content' field that will display links to let users add new content to the group
- OG Views - provides a 'Group View' field you can add to a group entity to display a view of the group content on the group page.
- OG Theme - creates a 'Group Theme' field that lets users choose which theme to use for a group
- OG Language - provides a 'Group Language' field that lets users choose which language applies to a group
Documentation
- The Organic Groups drupal.org Handbook page
- The Drupalcon CPH session
- Brusseles Drupal developers session about OG7
- OG7 tutorials by bjlewis2
- Drupalcon London session about OG7
- Drupalcamp Spain - Sevilla session about OG7