We recently held a discussion about and demonstration on how to use Configuration Recipes at Backdrop LIVE, we followed up with a recorded Community Meeting that covers the same topic and demonstrates the six available recipes at that time.

As of today, there are seven recipes available on BackdropCMS.org. Recipes are simple modules that help you quickly add features to your site using a combination of configuration files and sample content. For the most part, recipes simply configure Backdrop CMS core and sometimes contributed modules to do things that you could also have configured yourself through the user interface. Using a recipe makes it much easier to accomplish these tasks without adding any underlying functionality to Backdrop CMS that did not exist already.

How to test a recipe:

I highly recommend that you take advantage of the disposable sandbox sites available at BackdropCMS.org, you are able to use the project installer to install and evaluate recipes, modules, or themes using these sandbox sites. These sites are VERY easy to spin up and only last 24 hours. They are a great place to try out a recipe quickly and make sure it does what you are looking for, before installing it on an existing site. There is no simple way to automatically delete a recipe once it has been installed, you will need to manually delete the individual components.

How to create a recipe:

Structurally, a recipe is simply a module that does not include any PHP code in the actual .module file. Some recipes do use PHP in the .install file to provide sample content or to change/update existing config files. This means that Recipes can be disabled and/or deleted after installing them without effecting the operations of your site. Disabling or deleting a recipe does not disable or delete the configuration or content that they created. 

Configuration recipes require version 1.20.0 or later of Backdrop CMS.

A recipe includes:

  • A config directory of the configuration files you are adding to the site. 
  • A .info file that looks something like this:
     - type = module
     - name = FAQ Recipe
     - description = A recipe to build a FAQ feature on your site.
     - package = Recipes
     - backdrop = 1.x

     - dependencies[] = system (>=1.20.0)
     - dependencies[] = [optional: required module (contrib or core)]
     - dependencies[] = [optional: required module (contrib or core)]

  • An empty .module file. The .module file is required by Backdrop CMS, but most recipes do not include any code in this file.
  • A .css file is optional and can be added to help the recipe look good out of the box, but should include a warning that the CSS will be disabled if the recipe is disabled. 
  • A .install file is optional and can be used to create an informational message displayed upon enabling the module, modify existing config files, or to add sample content. 
  • We recommend that sample content be created through a sub-module, leaving the site architect the option of enabling it or not. 

Take a look at how other Recipes are structured. 

ADVANCED: One strategy for creating a recipe is to start with a fresh site and to create a git repository for your active config directory. Then configure the functionality you wish to include in recipe and run a diff command on the active config directory to see which new files you need to add to your recipe. 

Sample Use Case: Adding Multiple Items to a Map

The Multi Location Map recipe creates a Locations content type, configures a view to display all available locations on the map, and adds a Map menu item to the main menu. It requires that you install and enable several contrib modules (Addressfield, Geofield, and Geocoder). It does require that you configure API keys for the GeoCoder module after enabiling the recipe.

This recipe does nothing that a site architect could not have done on their own with the listed contrib modules, but it speeds up and simplifies the configuration that might otherwise require a fair amount of time and experimentation if done manually. It's also an opportunity for a site architect to reverse engineer the content types and views to better understand how they work.

Limitations of recipes:

At this time, here are some of the know limitations of Configuration Recipes for Backdrop CMS.

  1. They can only add new configuration files such as new content types and views, they can not (are not good at) reliably modifying existing configuration files. You can add PHP code in the .install file to modify existing config files if you know they will be present, for example: if you require (create a dependancy) on a contrib module, you will be able to modify it's config with PHP code in the .install file. 
  2. You can not revert them and if you uninstall them, they do not remove the configuration or content that they created. 
  3. You must have permission to manage modules in order to add or manage a Configuration Recipe. 

Future of Configuration Recipes:

There is some discussion about changing the name to something more descriptive of what they actually are. If this is to happen, it should happen soon before too many people become comfortable with the current label. 

Some work has been done on a recipe manager that in the future might be able to:

  1. Create recipes through the User Interface
  2. Revert changes made to recipes after installation OR even allow removal of the content types and views that they created. 

There is discussion about creating a new project type for recipes to allow site admins to create different permissions for recipes than they have for other modules. 

I created a forum topic where you can post your own feedback on recipes or thoughts on how to make them better in the future. 

Until the time of this post, I am the only person that has released any Configuration Recipes for Backdrop CMS. It would great to see more people experimenting with and sharing their Recipes. The more people that use and share recipes, the more likely it will be that we'll get better tools for creating and managing recipe projects. 

Image Credit