In this article, I'll do a similar walkthrough as I did in my earlier post of how to implement a configuration preset storage in your module and make it exportable with CTools. Only this time, the user interface will be provided automatically by CTools, which means there will be a lot less code. As a maintainer of the FFmpeg Converter module, this is a big win since the amount of code I have to maintain is reduced significantly.

Configuration presets, as I call them in this article, are collections of settings that are bundled up and used in different situations on a site. The screenshot above shows FFmpeg Converter's list of presets in the administration section of a Drupal site. A better-known example is ImageCache and its presets that allow you to set up groups of customized image manipulations that can then be picked up and used on different parts of the site.

To give a quick explanation of what exportables are, here's a quote from the old, now deprecated article:

There is a well known problem with configuration driven development, which is the way things work in Drupal most of the time. You can quickly set up large portions of a site just by clicking around in the admin interface. However, when it comes to doing things like deploying new features on running live sites, things get trickier. This is because there is no clean separation between the content and the configuration on the site. /.../ The solution to this problem, most of the time, is to capture the configuration in code somehow. The code can then be version controlled and distributed between different sites, or different versions of a site...

CTools has quickly become the workhorse of choice for managing this kind of exportability. So, let's take a look at how it's done.

Getting started

As in the previous article, I'll use FFmpeg Converter as an example of how to utilize Ctool's APIs for making modules' configuration presets importable and exportable. (In fact, a good part of this post will be just a straight copy.) This time though, we won't have to create an interface for adding, removing, editing and reverting these presets – CTools does it for us.

There are a couple of references you can check while you read this if you need more information:

• The export.html and export-ui.html help files in your CTools module directory.
• api.drupal.org and/or drupalcontrib.org for learning about different API functions.
• Stella Power has also written a blog post on the subject of CTools exportables, although that doesn't include the Export UI.

Defining your data

Just as before, we start by defining the table structure for the presets. CTools requires that the exportables live in their own database table and have at least a machine readable name field, and a database-only numeric primary key. This is what FFmpeg Converter's preset table looks like:

As always in Drupal, the table structure is defined in the ffmpeg_converter.install file:

That looks more or less like a standard Drupal install file, except for the export part of the schema array. This is specific to Ctool's export API, and it defines how this table's content will be imported and exported. This is the basic thing that is needed for the information to be exportable.

CRUD functions

How about the standard CRUD (create, read, update, delete) functions that you usually use to handle your objects? The truth is, with CTools Export UI you don't actually need them for the configuration UI itself. They may still be convenient, and the good news is that CTools has a complete set already defined, such as ctools_export_crud_load() etc.

FFmpeg Converter has its own _load function defined since it does a couple of extra steps with the preset when it's loaded. (We used to *need* to define this function in order to use CTools exportables, but that was before the Export UI.)

To make the CTools Export API use this function rather than ctools_export_crud_load() when loading preset objects, I've added this function as load callback in the export part of the hook_schema() declaration above. This is all optional however, so you can just omit load callback if you don't need this.

Defining default presets

In order to provide some default configuration, you can implement a couple of hooks that CTools provides. These presets will show up in the admin interface without the user having to do anything other than activating the module. This is exactly how third party modules would do to provide their own default, code defined, presets. It is also how Features saves preset data in code.

The administration interface

Time to take a look at the parts that really differ from before. Instead of defining a number of page callbacks and then start building pages for listing, adding/editing, deleting, importing and exporting presets, we just expose our preset schema to the Export UI. We do this by telling CTools that we want to define an 'export_ui' plugin:

After that we need to create the plugin directory plugins/export_ui in the module directory. Within this directory, we place the main plugin file called ffmpeg_converter_ctools_export_ui.inc. The directory structure should look like this:

In this file, we and add the plugin definition:

Starting at the top, we begin by defining which database schema this plugin deals with. Then we provide the permission that should be required for users to administer the presets, followed by a definition of the menu link which will point to the admin page. Below that are a couple of string definitions that will be used in user texts on the administration pages.

Finally the 'form' array defines the name of the function that generates the preset add/edit form, as well as form validation and submit functions. We put all of these form functions in the same plugin file:

And that's it! If all went well there should now be a complete admin interface looking similar to the image at the top, located at admin/build/ffpeg_converter in this case.

A couple of things have changed compared to the interface in the previous article. For instance, the admin page now resides under Admin > Build rather that Admin > Settings (update: this can be overridden in the plugin), and there is now an advanced – perhaps too advaced – interface for filtering the preset list page.

If you want to do customizations of how the UI looks and behaves, that's certainly possible. The way to do that is to add a 'handler' key to the $plugin definition where you define your own export_ui handler. This hander would be a class that inherits ctools_export_ui and only contains the actual overrides that you want to do. Custom handlers are out of scope for this article, but a working example can be found in the 6.x-2.x version of FFmpeg Converter.

Conclusion

I hope this can provide a good starting point for module developers who want to make their configuration presets a part of the whole exportables paradigm. With CTools' Export UI, this previously daunting task can now be achieved with a minimum of effort and in a stable, standardized fashion.