As a front-end developer working with Drupal, I often need to create custom Ctools layout plugins. Ctools is an essential suite of tools for Drupal developers and the basis of many popular modules, including Views, Panels, Context and Display Suite. Its layout plugins provide a flexible alternative to Drupal’s core page region system.

Creating a custom Ctools layout plugin for Drupal is actually quite easy. You define your layout in a .info file, create the html structure in a template (*.tpl.php), style it in a stylesheet (*.css or *.scss) and provide a thumbnail image so the site administrator has an idea of what it looks like. Each of these files follows similar but slightly different naming conventions. This can be tedious when you need to create a number of custom layouts for a project as we often do at Aten.

My previous workflow looked like this.

1. Find another layout plugin – either an existing custom layout or one from the Panels module.
2. Copy that folder into the plugins folder in my module or theme.
3. Rename the folder to match my plugin.
4. Rename all the files to match my plugin’s name, using the appropriate naming convention and file extensions.
5. Edit the .info file to point to the appropriate files and change the array of regions to match the new layout.
6. Edit the template file to match the newly created regions.
7. Write the CSS to style the layout.
8. Create a new thumbnail image.

A lot of these steps consist of copy, paste, find and replace – the kind of stuff that’s better suited for computers. That's where Yeoman comes in. Yeoman is a scaffolding tool. It's most often used to quickly create boilerplate code that can be customized to your needs.

I recently published a Yeoman generator that automatically creates a ctools layout plugin based on a few simple settings. Now my workflow looks like this:

1. Create a directory for my plugin.
2. Type yo ctools-layout.
3. Answer questions about my layout.
4. Add any extra markup to the template file.
5. Write the CSS to style the layout.
6. Create a new thumbnail image.

The new workflow eliminates the tedious tasks and allows me to focus on the code that makes a given layout unique: markup, style and a thumbnail.

Here’s how to use it.

Install Yeoman
*note: Yeoman is a Node.js tool, so you need to install Node.js in order to use it.

To install Yeoman type the following into your terminal:

npm install yo -g

The -g flag installs this package globally. Doing so allows you to run the yo command outside of an existing node project. A common Yeoman use case is scaffolding out a brand new project, after all.

Note: Depending on your environment, you may need to run these commands with sudo.

Now you have the general Yeoman application. But to be useful, you need some generators.

npm install ctools-layout-generator -g

The ctools layout generator assumes you already have a custom module or theme that you are adding a layout to. For this example we'll assume this custom layout is in our theme. From your theme's root directory create a new directory for your layout plugin, change to your new directory and run the ctools_layout generator command.

mkdir plugins/layout/landing_page
cd plugins/layout/landing_page
yo ctools_layout

Yeoman will prompt you with a few questions about your layout, such as the name of your layout, the name of the module or theme it exists in and the regions you want to include. After answering the questions, Yeoman creates all the necessary files needed for a working layout.

The ctools layout generator makes no assumptions about what your layout looks like or the actual CSS styles and markup needed to make it functional. That's your world! It's completely up to you. It simply takes your list of regions and adds them to the layout's .inc file and to the template file in which you can add the appropriate markup.

Similarly, the generator will add a placeholder .png thumbnail of your layout. The generator has no idea what you have in mind for your layout, so you'll want to create your own thumbnail and save it over the placeholder. The thumbnail is important as it gives the end user a good idea of what the layout looks like. I've shared a Photoshop template that I use for creating layout thumbnails.

I hope you find this useful. If run into any problems or have feedback, please create an issue on github.

P.S. In case yeoman isn’t your thing, there is a drush plugin that has similar functionality and works for more than just layouts.