Using Blueprints to clone spaces in Open Atrium 2

Mike Potter, Software Architect
#Atrium | Posted

atrium-logo

Open Atrium 2 supports many different patterns for your site’s Information Architecture.  Through the use of Spaces, sub-Spaces, and Sections you can easily create a hierarchy of content within your Intranet.  However, it can be tedious to create every new section within every new space.  The new 2.15 release of Open Atrium adds “Blueprints” which will allow you to clone an existing space structure and automatically create the necessary sections!
Creating a Blueprint
To create a Blueprint, simply create a sample space that contains all of the sections and content that you want to bundle.  Let’s create a Blueprint for a basic “Project Space”.  In this example, we want our Project Space to contain an Event Calendar, a Discussion Forum, a Document section, and a Task list.

  1. Create a new Space called “Project Blueprint” and save it as a Draft so other users don’t see it.
  2. Create each Section: Calendar, Discussions, Documents, Tasks.  In the new 2.15 release you’ll notice that the “Create New Section” action in the drop-down menu on the toolbar allows you to choose which type of section you want to create.
  3. At this point you can adjust any other settings for the space, such as color scheme, banners, taxonomies, permissions, etc.  You can even create sub-spaces within this Space and create additional Sections within those sub-spaces.  You can also create sample content, such as a Welcome document, or sample discussion forum.
  4. You can also customize any of the Section or Space landing pages using the “Customize Layout” and “Customize Page” buttons.  You can place additional widgets on the landing pages, or make any other customizations needed for the Space.
  5. Once your sample space is set up the way you like, click on the “gear icon” in the upper-right portion of the Space landing page and select the “Create Blueprint from this Space” option.  You will be taken to a form where you can enter the to name your Blueprint (we’ll call it “Project Space” in this example) and also enter a short description for this Blueprint.  Be sure the “Clone an existing Space” checkbox is enabled and that the “Space to clone” is set to the “Project Space” node you created above.  All of this should be set by default, but it’s good to verify.  When you are done, click the Save button.

Viola! You have created your first Space Blueprint!

Using a Blueprint to create a new Space

Now when you select “Create New Space” in the toolbar drop-down menu you’ll see a choice for the different Blueprints available on your site.  Simply select “Create new Project Space” from the menu and you’ll be taken to a normal Create Space form where you can enter the name of your new project space.  All of the other fields on this page are filled in automatically with the values from the Blueprint.  Change anything you like, then click Publish when you are finished and your Blueprint will be cloned into your new space.
You will be redirected automatically to your new space landing page.  Click the drop-down menu in the toolbar next to the space name and you will see the Sections for Calendar, Discussions, Documents, Tasks that you created above.  You didn’t need to create these manually, they were created for you automatically by cloning the Blueprint!

That’s really all there is to it…it’s simple to use and simple to understand and will save you hours and hours of work.

Behind the Scenes

How does Open Atrium 2 accomplish this magic?  The Drupal node_clone module is being used for the heavy lifting of cloning the actual content nodes, such as spaces and sections.  It provides hooks such as hook_clone_access_alter() that can be used to add custom functionality for specific OA2 plugins.  Beyond that, the new oa_clone submodule handles all of the OA2-specific settings, such as the space and section panelizer layout.  In addition, a new hook_oa_clone_group_metadata() allows submodules to clone any additional space-specific settings, such as the space colors handled by the oa_appearance module.

In addition to cloning the nodes and settings, oa_clone creates a new “Space Blueprint” vocabulary term (previously called “Space Type”) to represent your new Blueprint.  New fields have been added to this vocabulary to indicate an existing space should be cloned when creating spaces using this taxonomy term.  By selecting the “Clone an existing Space” option, the panelizer layout is taken from the specified “Space to clone” along with all of it’s structure and content.

If you don’t want to clone an existing space you can still create your own Space Blueprint taxonomy term as in the past to point to a specific custom panelizer layout by selecting the “Specify layout and node types by hand” option.

By controlling the cloning process via the “Space Blueprint” taxonomy, you can easily integrate other Drupal tools for importing content into this architecture.  For example, imagine you have a list of Projects to be created already saved in a *.csv spreadsheet.  Using the Feeds module you can import that spreadsheet to create a new Space node for each entry.  By simply specifying the Space Blueprint taxonomy term from the spreadsheet, each new space can be created as a clone of existing space structures, building out all of the child pages that are needed for each space quickly and easily.

Cloning Content

In addition to creating a Blueprint from an existing space, you can also just clone content directly.  On any content page, a “Clone this content” option is added to the “gear” icon in the upper-right corner of the page for users that have permission to clone content.   You can use this to clone an entire space, sub-space, or section.  You can also use it to clone specific documents, discussion posts, events, or any other content in Open Atrium.  Any “child” content is also cloned, such as content with sections, or replies within a discussion topic.

Conclusion

The ability to create entire Space hierarchies by simply cloning a Blueprint greatly increases the day-to-day usability of Open Atrium 2.  By allowing site admins to create their own Blueprints directly from existing Space examples, rather than filling out complex forms makes it even easier.  Open Atrium 2 was designed to be used as a toolkit for building many different types of collaboration sites, from intranets to project management sites to web portals.  Each OA2 use-case requires a different content structure and set of content-type features.  Blueprints allow you to easy to design your site’s information architecture and keep it consistent across all of your Spaces.

(NOTE: The OA 2.15 release still calls the taxonomy “Space Type” rather than “Blueprint”.  The vocabulary was changed to “Blueprint” in the recent -dev version.)

To get more tips and tricks for getting the most out of Open Atrium, sign up to attend this month’s Open Atrium webinar!

 

 

Mike Potter

Mike Potter

Software Architect