Tutorial: Creating a group collaboration community with Drupal

(Original article: Tutorial: Creating a group collaboration community with Drupal)

Introduction

This tutorial will walk you step-by-step through how to make your own Dgroups site. For more information, read our Case Study.

This tutorial is for people who want a site which contains:

• Group-based management of users and their collaboration
• Mailing list Integration with Sympa, an open source mailing list manager
• A savvy method of theme customization to create an entirely new look and feel based on a tested design
• An events calendar to track goings-on
• A way for users to upload and share resources

Overview

Group-based management

At the heart of the Dgroups community is the Organic Groups module. This module offers a number of features, including:

• Allows users to create and manage their own groups (open, moderated, or invite-only)
• Allows users to subscribe to a group to keep abreast on their activities
• Groups have their own unique pages, which can be customized with their own theme, to create a separate look and feel from other groups

In short, this module allowed Dgroups to cater to the vastly varying needs within its user base, and create a platform where collaboration can take place quickly and efficiently. Find out how to use Organic Groups to leverage the power of grassroots organization to propel your website forward.

Mailing list Integration

Mailing lists are an essential ingredient to an effective activism platform. Dgroups needed a flexible way to integrate Drupal with a mailing list manager in order to leverage this power. This tutorial will show how to use the Mailhandler and Listhandler modules to synchronize a mailing list manager with Drupal forums.

Theme Customization

Leverage the power of tried and tested XHTML and CSS, but customize it with your own unique look and feel. We'll show you how to take an existing Drupal theme and create a layout particular to your own web site, and how to have precise control over navigation menus.

Uploading and Sharing Resources

Fundamental to collaboration is the ability to share documents, images, and other files. We will show how to create a custom module to handle resource uploads, and use PHP to create a page for filtering resources for each group.

Prerequisites

This tutorial assumes that Drupal is already installed and running on a web server. If assistance is required with this step, please reference the Drupal Installation and Upgrading handbook.

It also assumes that the Sympa mailing list manager is installed and functioning. For more details, please see the documentation on Sympa's website.

Setting up an OSDgroups Server

Step 0: Setting up a Server

The OSDgroups/AMP test server is based on FreeBSD. Here are some tips on installing and setting up your system:

• First Install FreeBSD - we created a fresh server using FreeBSD 5.4-RELEASE. You can follow the instructions in the handbook and update your kernel and system user applications to incorporate the security fixes since the release date. (Richard Bejtlich has written an excellent article which describes how to do this). Once you have your base system ready you can begin to install applications required for OSDGroups/LAMP. The Setting up OSDgroups/AMP on FreeBSD page describes the package installation process for setting up FreeBSD as the host system for your OSDgroups/AMP community.

NB: books on FreeBSD are available.

• If you use Red Hat Enterprise Linux server you can follow these instructions for Setting up OSDgroups/LAMP on RHEL.

Step 1: Modules

Error creating thumbnail:

Drupal modules screen

In order to facilitate collaboration, the Dgroups site uses several modules which enable community-building.

Core Modules

• Go to administer >> modules and enable the following modules:
  • Forum, to enable threaded discussions (Forum handbook page)
  • Path, to allow the renaming of URLs (Path handbook page)
  • Search, to enable a search engine for the site (Search handbook page)
  • Upload, to allow users to upload and attach files (Upload handbook page)

Contributed Modules

• The following additional modules are used to create a Dgroups-like site:
  • Event (Event help)
  • Flexinode (Flexinode help)
  • Listhandler (Listhandler help)
  • Mailhandler (Mailhandler help)
  • Organic Groups (Organic Groups help)
• Download and install each of the above modules. The general procedure for this is:

cd modules
wget http://drupal.org/files/projects/modulename-X.X.X.tar.gz
tar -zxvf modulename-X.X.X.tar.gz
mysql -uusername -p database <>

• Enable the modules in administer >> modules

Configuring Events

Error creating thumbnail:

Events calendar

After enabling the modules in administer >> modules do the following:

• Go to administer >> content >> content types and click add content type.
• Enter event as the name of the content type, and a description and help text if desired.
• Go to administer >> content.
• Click on the configure tab, then the content-types sub-tab.
• Next to event, click the configure link.
• Under Show in event calendar choose All views.
• Go to administer >> settings and go to Date settings to set options such as time zone and date format.
• Go to administer >> settings >> event to customize options such as 12 vs. 24 hour clock.
• Finally, view the calendar by going to http://www.example.com/event.

Note that you may repeat these steps to add additional types of events rather than just "events"--for example, "meeting" or "conference call." The calendar can then be filtered to only show certain types of events.

Configuring Organic Groups

• Go to administer >> settings >> og and click the Enable button to enable organic groups.
• Change any other settings, as applicable.
• If you would like each group to be able to select its own theme, go to administer >> themes and select the Enabled checkbox next to each theme you would like groups to be able to choose from.
• Go to administer >> blocks and enable the following blocks:
  • Group details: Show details about the group, as well as display links to create group-specific content
  • Group Subscribers: Will show last X users who've subscribed to the group
  • My groups: a panel for each user to track which groups they're a member of

Setting Permissions

Error creating thumbnail:

Access control screen

• Go to administer >> access control to access Drupal's permission system. Here are some recommended additional permissions for authenticated user:
  • flexinode module - create event content
  • forum module - create and edit own forum topics
  • og module - create groups
  • path module - create URL aliases
  • search module - search content
  • user module - access user profiles

Step 2: Theme Customization

Drupal has several Themes available for download. This section gives an overview on how to create a custom look for Drupal based on a pre-existing theme.

Installation

Error creating thumbnail:

CivicSpace theme

• Download and install the CivicSpace Theme

cd themes
wget http://drupal.org/files/projects/civicspace-X.X.X.tar.gz
tar -zxvf civicspace-X.X.X.tar.gz

• If not already present in themes/engines, also download and install the PHPTemplate theme engine:

cd engines
wget http://drupal.org/files/projects/phptemplate-X.X.X.tar.gz
tar -zxvf phptemplate-X.X.X.tar.gz

Creating a Layout

Error creating thumbnail:

Default Columbus theme

• Change into the layouts directory and create a copy of the existing columbus layout to use as a basis

cd $DRUPAL_DIR/themes/civicspace/layouts
cp -r columbus newlayout
mkdir newlayout/images

• Alter layout.css, which defines the overall width of columns and content areas, to fit your needs. Here is the Layout.css used on the Dgroups site, as an example.
• Alter custom.css, which indicates the site colors, typefaces, and images. Here is the Custom.css used on the Dgroups site, as an example.
• Upload images required for the theme into the newlayout/images directory.

Customizing the Navigation Menu

In order to better control the look of the navigation menu, you can make use of Drupal's blocks feature. This allows you to create areas of the page using your own customized text, HTML, and PHP.

Go to administer >> blocks and click add block. An unordered list can be used to create the menu style that the Drupal-generated menus use, which then are styled using your theme. Then, to recreate the login/logout links, you can use the following PHP (make sure that the Input format is set to PHP):

uid) {
?>
Log Out

Log In

Step 3: Setting up Groups

Error creating thumbnail:

Group membership panel

Groups are at the heart of a collaborative community. They can be used for sharing information privately, or for organizing users into working teams.

Create Group

• Go to create content >> group
• Enter a title and description of the group.
• Enter a path alias which contains the group's name, all in one word. If you want, words can separated by hyphens (for example, group-name). This allows the group page to be accessible via group-name rather than by node/##.
• Choose subscription requests settings. A group can be:
  • Open (anyone can join)
  • Moderated (join requests are approved by the group administrator)
  • Invite-only (only the administrator can initiate join requests)
• If you wish this group to be available for users to choose from when they register, check registration form
• If you'd like this group to be listed in the public groups directory, check list in groups directory.
• Click Submit when finished.

Create a Forum

• Go to administer >> forums
• Click add forum
• Enter a forum name and description
• Make a note of the ID that is created for later Mailhandler configuration (viewable by clicking on edit forum and taking the number at the end of the URL)

Create Content for Group

• In the Group Details block, choose create forum topic (for example)
• Enter content as you normally would do
• Uncheck Public if you would like to restrict this node to only appropriate groups
• Check the box next to each group in Audience which should be able to access this content.

Managing Group Membership

In the Group Details block, choose the X subscriber link to view a list of group subscribers.

• If the group is set to Moderated you can choose to approve or deny users.
• To add other users to the list, go to add subscribers. Enter the usernames, separated by a comma.

Step 4: Sympa Integration

Error creating thumbnail:

Synchronized messages forum

These steps allow synchronization between forum posts and mailing list messages, so that users can participate in discussion either via e-mail or the Web.

Initial Setup

• In your sites/default/settings.php file, add the following line just before the line which starts with $db_prefix (replace username, password, localhost, and database as required):

$db_url['sympa'] = 'mysql://username:password@localhost/sympa';  # sympa database.
$db_url['defaul'] = 'mysql://username:password@localhost/drupal'; # drupal database.

• Place the sympa2drupal.php script in the root of your site and access it with your browser. This will go through Sympa's database and add a Drupal user for each Sympa subscriber, a Drupal Organic Group for each mailing list, and assign each Drupal user to the correct groups. Once the script has finished running, you may remove it.

• Place the og_sympa.module file in the modules directory and enable it from administer >> modules. This module will automatically subscribe new Drupal group members to the appropriate mailing lists.

Mailhandler Configuration

• Go to administer >> mailhandler to configure Mailhandler.
• Click add mailbox to add a new mailbox. A mailbox for each group needs to be created.
• Fill in an E-mail address and Second e-mail address. The second e-mail address will be used by Listhandler to synchronize Drupal forum posts with the mailing list.
• Each setting from Folder to Extra commands will depend on your specific mail setup. Check with your system administrator if you are unsure what these setting should be.
• Mime preference can be set to either send e-mails in HTML or Plain text (generally preferred by mailing list users).
• Security in this type of use should be set to Disabled
• From header can be left empty.
• Default commands is where forum synchronization happens. Enter the following two commands:
  • tid: 9 (replace 9 with the taxonomy term ID which corresponds to the group's forum) This command assigns all mailing list posts to the proper forum.
  • og: [154] (replace 154 with the group's node ID) This command will also assign the post to the proper group.
• Make any configuration changes necessary to administer >> listhandler. This will synchronize forum posts to the mailing lists in Mailhandler and vice-versa.

Step 5: Creating a Resources section

Error creating thumbnail:

Resources section

The finishing touch is the creation of a panel which allows groups to share files and documents.

Setting up a Resource Module

• Create a folder in your modules directory called resource and place resource.module inside
• Enable the resources module in administer >> settings

Setting up a Resource Page

• Create a new page by going to create content >> page
• Give the page a title of Resources and a Path alias of resources.
• For Body, insert the contents of Resources_page_source and change your Input type of PHP code. This creates a page which sorts the resources for each group.
• To access a particular group's resource section, use one of the following URLs, depending on whether you have Clean URLs enabled (replace 1 with the group ID):
  • ?q=resources&group=1
  • /resource?group=1

Result

The result of using this flexible combination of modules and techniques is the empowerment of your users to self-organize, and the provision of the tools required to do so. These strategies can be used in a multitude of different scenarios, from political and global activism as in the case of Dgroups, to any group of users who wish to more effectively manage their personnel, activities, and communications.