As part of a long-term collaborative partnership with the University of Victoria's Geography Department, Chocolate Lily has been working on producing a customized version of Open Outreach suitable for community mapping. In a nutshell, we have been able to take the work we produced on a customized site build in 2013 and bundle those features into a new distribution called StoriedMaps. This blog post will walk through the steps followed as well as the successes and challenges.
The background
The Department of Geography and the Community Mapping Collaboratory have a strong history of working with community groups and First Nations to produce mapping solutions that engage and inform. Moving to a digital platform has led to numerous challenges in keeping up with changing technologies and responding to increased requests for assistance with on-line mapping.
Our initial work with UVic led to much of the functional development in the Debut Location feature that provides mapping functionality in the Open Outreach distribution. Building on that initial work, in 2013 Chocolate Lily used Open Outreach as a basis for building the Community Green Map for the Capital Regional District. One of the key strategies of this site build was to develop the tools that would be useful in creating a more generic and reusable solution for community mapping. Budget limitations meant that rather moving directly into features bundling, the site would be built first and then at a later phase, the added functionality would be packaged and further refined.
The site added some important new components to what already exists in Debut Location, creating a new concept (and content type) of “stories” that would be linked to locations. Stories enabled a way to share the richness behind place that encompasses community mapping, including photographs and videos.
The location content type was also enhanced to add in more fields (using conditional fields) to collect additional data if a location was an organization or business. In Open Outreach we have limited the use of Panels to the home page. For this site build, we expanded Panels use, creating a custom panels layout of the location node page so that in addition to the basic node information we could link to related stories about the location providing greater depth. We also created a page for featured sites so that the information about locations could be shown in a text and graphics format in addition to the map view.
The site also used the beautiful icons of the Green Map system and so we chose to also highlight the icons, creating new views and a panels page to showcase them and also a customized taxonomy landing page to better capture the listings by term. Also part of the map were specialized icons developed by UVic's Ken Josephson that reflect the natural beauty of Southern Vancouver Island and the Gulf Islands such as the camas meadow icon).
We also updated the home page building on the basic Open Outreach look and using the Outreach theme, but customizing so that the locations, stories and icons would be prominently featured.
Features or a distro?
In late 2014, the second phase of the project got underway with the aim of producing a platform that could be used more generally for community mapping purposes. Here the strength and long-term nature of the partnership with UVic, and in particular key players Peter Keller, Ken Josephson and Maeve Lydon, proved an asset as we were able to meet with some frequency to flesh out the various options and how best to take a small amount of phase two funding to quickly develop a new tool.
There were a number of key decisions to be made. Should we create a whole new distribution or just a feature or feature set? Where would code reside? Who would maintain? What should it be called?
As the developers and maintainers of Open Outreach, we know first-hand how much work it is to build a distribution and also to do the routine tasks of maintenance that are required on a regular basis. For example, in 2014 we issued ten releases. Most of those were just to keep all contributed modules up to date, an especially critical task if there has been a security release. Some module updates are seamless, while others require a great deal of work to ensure that the package of modules and configuration still all works.
So without on-going funding for the project, we were loathe to take on another distribution. But we also recognized that with just a new feature or features set, end users would still be left with a lot of work they would need to do to add in additional required modules and to make any of the other configuration changes that might be needed. We were also clear that the community mapping functionality was a specialization beyond the core use case for Open Outreach and so didn't want to just roll in the new work.
In the end, we opted for a hybrid solution. We would create a new feature called StoriedMaps which could be hosted on drupal.org. Then we would use GitHub to package it up so that users could download all needed components at once.
Creating StoriedMaps
One of the first tasks in pulling functionality off the prototype site was to determine which functionality was broad based enough that it should go straight into Debut Location and which was more properly confined to the new StoriedMaps feature. As in most projects, this planning stage is critical. We decided that the more fully developed pop-up on the map display as well as icon clustering were both well suited to Debut Location, so those fixes were applied there and a new release of that feature issued.
Rather than create one feature we decided that it would make sense to group them into a core feature (StoriedMaps Core) with extensions to location as well as a new home page. All functionality related to the new story content type would go into StoriedMaps Story and all functionality related to icons (and terms) would go into a StoriedMaps Icon feature. This allowed for a relatively straightforward but sometimes time-consuming job of creating new features, ensuring that all required elements were added—which any feature builder knows requires much testing and re-adding, retesting, and so on until everything is there.
StoriedMaps Core was posted as a project on drupal.org with the other two as sub-modules. This provided us with a working repository for the code and a Drupal presence for the project.
Packing it all up
The next task was to ensure that there would be an easy way to get going with StoriedMaps for community groups, First Nations or the university itself for projects it's supporting. Hosting on drupal.org would be problematic due to licensing of icon sets, which are often licensed under Creative Commons or some other license not compatible with the GPL. Also, as noted above, we wanted to use the core of Open Outreach rather than creating a whole new stand-alone distro and drupal.org doesn’t (yet) support creating a distribution that depends on another distribution. What we really wanted was a new flavour or version of Open Outreach.
Setting up a repository
We decided to host the project on GitHub. We started with a repository for Open Outreach, https://github.com/nedjo/openoutreach which we forked to begin our new repository, https://github.com/UVicCMC/storiedmaps. That way, commits to the StoriedMaps repository would be just for what was specific to StoriedMaps. Once we’d made the fork, we added the StoriedMaps Core project to profiles/openoutreach/modules/contrib and also added dependencies of the StoriedMaps modules that weren’t already in Open Outreach.
Tweaks and customizations
With the basics in place, it was now time to make some customizations to the Open Outreach install profile so that it would recognize the StoriedMaps features.
Open Outreach uses the Subprofiles module to allow users to select at install time which features to enable. To make StoriedMaps show up here, we edited the open_outreach.info file, replacing the subprofiles information with a StoriedMaps version. While we were at it, we customized the name and description in open_outreach.info for StoriedMaps.
We edited the install code to set the new panels-based home page as the home page.
The new home page (and some of the other panels page displays) need the full width with no sidebars. Since a fix that will get the panels setting to override the block regions to respect blocks set by Context hasn’t yet reached the stable release of CTools, we needed to update a context that sets the login block in the second sidebar, moving it to the footer region. We did this using hook_context_load_alter().
Custom sample content
Open Outreach supports sample or default content using the Migrate module. A key customization step was making sure that StoriedMaps installed with sample content appropriate to its focus.
A useful (if almost completely undocumented) feature of Open Outreach is that sample content can easily be customized. The steps are:
- Create a new directory called local in the openoutreach_migrate module’s directory.
- Copy over all the contents of the module’s migrate directory.
- Make any customizations. For example, edit one or more of the .csv files to change the sample content records that are created. You can also use your own images by copying them into the appropriate subdirectory of the images directory and updating image paths in the .csv files.
Using this approach, we replaced the more generic sample location type taxonomy term import and icons with an actual set of icons ready to use for many community mapping projects and updated the sample location content so it would be more reflective of the new community mapping style.
Since we were adding a new content type, story, we also needed to add a new corresponding migration. Because a new migration can inherit most of what it needs from a parent migration, the changes needed to add a new migration for the story content type were minimal. With the new migration in place, all we needed were a corresponding .csv file and images.
The final product
With all these pieces in place, StoriedMaps is now available for groups to begin using. The GitHub download contains everything needed to start into site installation (as long as one has the technical skill and set up to install a regular Drupal site.)
Groups can opt to use the icon set that comes with the download or choose their own for their specific site use case. (Currently the install comes with a minimal, sample icon set, but a full icon set is coming soon.)
Documentation on the openoutreach.org site will support users with most of the content creation tasks, and additional documentation specific to StoriedMaps is also available.
The lessons
While it's early days to see how this new platform is working for UVic and its community partners, there are already some good learnings that we have drawn from this project.
- While it is obviously easier to build features as you go, this two-phased approach of bundling the configuration in a follow-up phase was more smooth than we had imagined.
- Determining what fixes/additions should go where was a key piece.
- The hybrid approach of creating a new Open Outreach-based package without all the on-going work of replicating and maintaining a separate distro seems to be a good solution. It is one that might work well for large organizations that would like a customized version of Open Outreach to use on the number of sites, for example regional branches.