LJ Archive

Making Open Atrium Yours

Patrick Settle

Issue #888, April 2068

Open Atrium provides organizations and individuals with a free, robust and flexible project management tool—one that demonstrates just how powerful and beautiful Drupal can be.

Open Atrium is packed full of features right out of the box: a calendar, discussions, a notebook for project documentation and a flexible task manager. Even with hundreds of thousands of Open Atrium installs, it's most powerful feature is often never taken advantage of: Open Atrium is an open-source project.

Although people know what open source means, they don't take advantage of this feature enough, even though it is one of the best features any project could have. This feature empowers you to do so much more, but it doesn't mean that you need to be a hard-core developer to participate.

Let's explore some very real examples of the benefits of Open Atrium's open-source feature and look at how you can take advantage of this underutilized facet to make Open Atrium your own.

Set Yourself Apart

You probably wouldn't install Drupal for your business Web site and leave the default theme. Why would you do that with Open Atrium? Although Open Atrium's Ginkgo theme is a very usable theme, why not let your design and style shine through to your staff, customers and vendors by customizing the look and feel of Open Atrium with your own sub-theme?

One powerful aspect of Drupal's theme system is its ability to use sub-themes. Sub-themes allow you to use an existing theme as a jumping point, saving a significant amount of time, while still letting you apply your own design.

Crystal—a Sub-theme for Open Atrium

A good example of a sub-theme for Open Atrium is the Crystal sub-theme by Daniel O'Prey. Building off a previous sub-theme, Daniel created Crystal to be a clean app-like theme. Although it could be used on its own, let's use it here as a starting point for a new theme.

Installing a Sub-theme

Start by making a copy and renaming Crystal's theme folder into /sites/all/themes. For this example, name the sub-theme Baara, so its folder will be /sites/all/themes/baara. (If you want to use Crystal as is, there's no need to rename anything.)

Like any Drupal theme, this new sub-theme Baara will need a .info file that will define the name of the theme, a description, any CSS style files and regions or DesignKit options. You simply can rename crystal.info to baara.info, and using your favorite text editor, make changes as needed.

When finished, your .info file should look like this:

name = "Baara"
description = "A Ginkgo sub-theme to get work done, 
 ↪based on Crystal for Open Atrium."
core = "6.x"
atrium = "1.x"
engine = "phptemplate"
base theme = "ginkgo"

stylesheets[screen][] = "style.css"

regions[left] = "Left sidebar"
regions[right] = "Right sidebar"
regions[content] = "Content"
regions[header] = "Header"
regions[space_tools] = "Space tools"
regions[page_tools] = "Page tools"
regions[palette] = "Palette"

features[] = ""

; Designkit
designkit[color][background][title] = "Background"
designkit[color][background][description] = "Color for 
 ↪headers, other fills."
designkit[color][background][default] = "#44aa55"
designkit[image][logo][title] = "Logo"
designkit[image][logo][description] = "Header logo."
designkit[image][logo][imagecache] = "imagecache_scale:300x40"

The first six lines set the name and description of the new sub-theme, the version requirements for Drupal, and most important, it lets Open Atrium know that it's a compatible theme and defines the parent theme for the sub-theme (in this case, Ginkgo).

Sub-themes function just like normal Drupal themes. They can include images, stylesheets and templates. Stylesheets can be reused from the parent theme, or in this example case, be overridden by declaring them in the .info file, as seen on the line stylesheets[screen][] = "style.css", which will override the style.css file found in Ginkgo.

The “regions” entries list all regions available in your sub-theme. If you modify any of the template files to add new regions, you'll need to be sure to modify this list. It's important to note that while adding regions can be done easily, removing or renaming regions should be done with care and may cause complications, as many Open Atrium Features are built to expect those default regions.

If you plan on having additional customization that could be managed through the Drupal admin pages, the “designkit” entries allow you to specify the customizations you want to make available on /admin/build/themes/settings/baara. To learn more about DesignKit and how to use it, see the README.txt, which comes with the DesignKit module (drupal.org/project/designkit).

For additional information on Drupal theming and details on available options to use in the baara.info file, read the on-line Drupal Theming Guide (drupal.org/documentation/theme).

Ginkgo Sprite Overrides

With the new sub-theme folder created and .info file completed, you can turn your attention to applying style and design. Ginkgo's extensive use of sprites throughout its design allows you to make some pretty radical changes simply by modifying or replacing these images.

Ginkgo uses these sprites as background images to many of the elements throughout the site as defined in the style.css stylesheet. There are three main sprite images (along with RTL for right-to-left languages), which you will find in the Ginkgo images directory:

  • sprite_base.png — base UI elements, such as priority indicators and default user avatar placeholder images.

  • sprite_icons.png — Atrium Feature's icons used in menus.

  • sprite_skin.png — gradients and other backgrounds, along with the default logo.

To override these images in your sub-theme, re-declare them in your style.css and include the modified sprite images in your Baara theme's images folder. If you want to replace the default icons, you can modify the sprite_icons.png by inserting the custom icons. More-advanced sub-themes may take advantage of additional sprites, which you can include in your sub-theme's image folder.

Be sure to maintain the same metrics and coordinates of these sprite files from the originals; third-party Open Atrium features are built with this expectation.

A Style of Your Own

In the example .info file, you made the declaration stylesheets[screen][] = "style.css", which overrides the Ginkgo theme's style.css stylesheet. This not only allows you to override Ginkgo's sprite images, but also will house any other CSS style changes you need.

Be careful when overriding any of Ginkgo's design, as changes to templates and layouts may make it difficult to take advantage of community-contributed features.

If you don't have the time to create your own sub-theme, check out community.openatrium.com/shopresources/feature-directory for a listing of sub-themes created by other Open Atrium community members.

When Something Is Not Quite Right

Now that Open Atrium is looking more like your organization, let's consider the actual features of Open Atrium. Like a great many things in life, one size does not always fit all, and each organization that uses Open Atrium often has unique needs and requirements that require changes to the default settings included in Open Atrium.

Overriding Settings

There are three ways to override the settings in Open Atrium: simply make the changes in the Drupal configuration interface, fork the Atrium Feature you want to modify, or create the much more flexible custom feature override module.

The first option—making changes directly through the configuration pages—is immediate. It can be done by almost anyone with access, and it requires no programming. Although this sounds great, note that this technique comes with a great deal of risk—it's immediate, ready or not. Once you make that change, it's live. There is no chance to coordinate other related changes. In addition, all users with access can make a change, even if they didn't mean to make the change. It doesn't require programming, which means it's not in code. This could lead to a couple major issues. First, it's difficult to deploy to a production server. Someone has to write down every configuration change that was made, and then on production, walk back through each change. Second, there's no way to know what state the site is in, so did those changes get made? There's only one way to check—load each configuration page and look.

It's also important to note that if you change a setting through the configuration interface that belongs to a feature module, you may have trouble with future upgrades. When upgrading, you sometimes are required to “revert” the Feature module. This allows the Feature module to make any new changes to its configuration to support the upgrade. When this happens, any setting changes that you made through the configuration interface will be lost.

Custom Override Module

By far, the best way to manage setting overrides in Open Atrium is by making use of a custom override module. This is a simple module that houses a collection of Drupal module hooks and alters that capture the settings into code. This protects your changes from being lost during upgrades and provides these additional benefits:

  • Version control: make rollbacks more granular instead of rolling back the entire database.

  • Features can be turned on and off per group. Un-featured configurations are global in scope.

  • Easily see what has changed from one version of a feature to another using diff tools.

  • Use features on other sites, saving countless hours of filling out forms and clicking.

  • Features can be shared on feature servers, so you can share your work with the world (or a smaller team).

Creating a custom override module does require a basic understanding of the building blocks of Drupal and Open Atrium, and it requires that you are comfortable with code.

Table 1. Some Common Drupal Customizations

Blocks or boxesShow or hideModify the context that sets the block as visible or hidden (see the section on contexts).
BoxesModify outputUse hook_boxes_view_alter(&$box, $delta).
ContextsModify settingsUse hook_context_default_contexts_alter($contexts) in a custom module.
User permissionsModify settingsUse hook_user_default_permissions_alter(&$permissions) in a custom module.
Imagecache presetsModify a presetUse hook_imagecache_default_presets(&$default_presets) in a custom module.
Menu itemsModify menu attributes like path or remove an itemUse hook_menu_alter() in a custom module.
Site settingsModify default settingUse hook_strongarm_alter(&$items) in a custom module.
User rolesModify settingsUse hook_user_default_roles_alter(&$roles) in a custom module.
User rolesModify settingsUse hook_user_default_roles_alter(&$roles) in a custom module.
CCK fieldsAdd a new field to an existing content typeAdd the new field, and then create a new feature module that includes this field. The exported field will contain information that associates it with the content type.
ViewsModify general settingsModify with hook_views_pre_build() in a custom module.

Something's Missing

You may find that special tools are required for your organization, and although Open Atrium contains a powerful feature set, there's a chance that you'll need something different.

In some cases, you may find that the Open Atrium community already has created the tool you're looking for. For example, a popular tool that often is added to an Open Atrium install is Atrium Folders created by Nuvole. Atrium Folders provides a simple file repository feature. To install this feature, or any other feature or module created by the community, simply download, extract, copy to your /sites/all/modules/contrib folder and enable.

If your needs are even more unique, you can create your own feature or module as a solution. Being built on top of Drupal, Open Atrium includes a wide selection of building blocks contributed by the community, and it often provides an excellent starting point for creating a completely custom feature for your site.

The Next Step

So, you've installed Open Atrium, created a theme, customized Atrium features, added additional features or maybe even built your own. Where do you go from here?

The next step is to get involved directly with the Open Atrium project.

Open source not only means you have the freedom to customize and extend, but also the freedom to participate, and right now is a great time to start. Planning is underway to plot the path and direction Open Atrium will take as it's upgraded to 2.x.

Open Atrium 2.0 Roadmap

We've identified few key areas that we feel should be the focus for Open Atrium 2.0:

  • User interface.

  • Improved feature set.

  • Third-party integration.

Open Atrium's current Ginkgo theme is a vibrant breath of fresh air in the arena of Drupal themes. However, there is room for improvement with its user experience. We are looking to bring a new dynamic theme to Open Atrium 2.x that takes advantage of best practices and technology to provide a world-class user experience, one that fully supports today's mobile devices.

Improved Feature Set

Open Atrium 2.0 also will be improving existing features and adding new features that support the project management workflow. We plan to extend features, such as the Calendar/Task/To-Do feature and Notebook, while also improving their functionality. In addition, we plan to add useful features like Files and Timekeeping.

Additionally, Open Atrium's focus on project management calls for a shift from a generic “groups” concept to specialized projects. This, coupled with a new ability to assign users to organizations and set privileges around these organizations, could provide users with an intuitive way of managing their projects and team members.

Third-Party Integration

We know a lot of great tools exist that people rely on to get their jobs done. We should work toward building Open Atrium 2.0 with that in mind. Some areas we should look into are calendar, timekeeping and ticketing integration. Of course, a lot of solutions exist, so we're really going to need the community to identify and help build connections to those services.

Implementation and Community Participation

The community is an essential part of any open-source project, and Open Atrium is no exception. Many of these ideas for improvement have come directly from requests through e-mail, Twitter and https://community.openatrium.com.

Participation doesn't mean only coding; we want to hear your thoughts and ideas on this plan. However, like all open-source projects, we need developers and designers to help start building the next generation of Open Atrium. This release will not be possible without your coding contributions, testing efforts, documentation assistance and feedback. We are very excited about this next phase of Open Atrium and are excited to work with the community to make it happen!

Patrick Settle, Drupal developer, digs into his bag of tricks whenever he runs across a “new” challenge facing Open Atrium, which he's been developing since its beginnings. Thanks to 12 years in system administration for companies from SAIC to the WorldWatch Institute and eight years building Drupal, he's uniquely able to balance a versatility in infrastructure planning with a specialized knowledge of application development that benefits end users and administrators alike.

LJ Archive