Panels 3: Creating a custom layout in your theme

A panel layout is a layout that can be used by the Panels module. You can add content to defined content areas within a panel. The Panels module comes with several layouts, but you can also create your own for your own module or theme. Here we will create a layout for a theme.

Before we start, first you have to successfully install Panels 3.

1. The layouts which come with panels exist in files located within the Panels module directory at plugins/layouts, for example, /sites/all/modules/panels/plugins/layouts.

   Copy one of the existing layout's folder to your site's theme directory to use as our template or outline which we will then rename, twocol for example. If your theme was named mytheme, the twocol folder would be copied to /sites/all/themes/mytheme/layouts/twocol.

   This folder contains four files. These files are:

   • twocol.png, a screenshot of the layout.
   • twocol.css, a stylesheet for the layout.
   • twocol.inc, contains only an implementation of hook_panels_layouts().
   • panels-twocol.tpl.php, the template file for the layout.
2. We need to rename the files. We will be creating a simple layout with one row and two columns below, called onerowtwocols. Replace all the twocols names in the filenames with onerowtwocols, except for panels-twocol.tpl.php, which must be renamed to onerowtwocols.tpl.php (i.e. also remove panels- from the name-- NOTE: some versions require that you keep "panels"). You must also change any underscores into dashes in the name of panels-twocol.tpl.php (i.e. panels-twocol_wide.tpl.php will not work). Don’t forget to also rename the folder to onerowtwocols.
3. Now, we need to change our theme's info file, which in this example would exist in our root theme folder at /sites/all/themes/mytheme, called mytheme.info. We need to tell Drupal where the folder with the custom panel layouts for this theme will be located, by adding the following line to the bottom of the file:
   

   ; Panels layouts. You can place multiple layouts under the "layouts" folder.
   plugins[panels][layouts] = layouts
   

4. Now let’s dive into the code of the layout, which is really simple. We will start with the ‘hardest’ file: onerowtwocols.inc. If you have ever used the Forms API (or the Schema API, or the menu system) before, you should recognize the way this file is built up. The file is very self-explanatory, but we will begin at the beginning:
   • [see NOTE A below] The function name should be broken up into several smaller pieces and tied together using underscores like this: themename_layoutname_panels_layouts(). For our purpose this will become: mytheme_onerowtwocols_panels_layouts().
   • The internal name of layout should be $items['onerowtwocols']. If you have a feeling we’re starting to do the same thing over and over, you’re right, basically, we’re replacing every instance of twocols with our new name onerowtwocols.
   • The title will be displayed in Drupal, it is wrapped in the t() function which makes it translatable. We will use 'title' => t('One row, two columns'),.
   • The screenshot of the layout is next, it will be 'icon' => 'onerowtwocols.png',.
   • The theme will be the name of the template file without the .tpl.php extension, like this: 'theme' => 'onerowtwocols',. Starting to get bored yet?
   • The CSS: 'css' => 'onerowtwocols.css',.
   • In the panels array we will define the regions in which content can be placed once our layout is finished, just add a new item for each area, we will end up with this:
     

     'panels' => array(
     	'top' => t('Top'),
     	'left' => t('Left side'),
     	'right' => t('Right side')
     ),

   This was the hard part, now let’s continue with the easy and fun part!

   NOTE A: in later versions you do not need the function, but rather you will find a plugins array (in the .inc file) like this:

   $plugin = array(
     'title' => t('One row two columns'),
     'category' => t('onerowtwocols'),
     'icon' => 'onerowtwocols.png',
     'theme' => 'onerowtwocols',
     'css' => 'onerowtwocols.css',
     'regions' => array(
       'top' => t('Top'),
       'right' => t('Right side'),
       'left' => t('Left side')
     ),
   );
   

   ...so you just edit that array, more or less using instructions above (it is pretty obvious).

5. Edit the screenshot the way you want to best represent your layout, make sure you keep the filesize (in pixels) of the original png file so it will look nice and clean in the Panels user interface.
6. Now let’s start the actual layout part. Open onerowtwocols.tpl.php and take a moment to see how the two columns layout was set up. The little PHP snippets like print $content['left']; are used to define the area where content can be added. We will partly use the existing HTML and change some of our own. We will start at the outside and work our way in.
   • The outer div will almost stay the same, we will only change one class to our own:

     <div class="panel-display panel-1row2cols clearfix" <?php if (!empty($css_id)) { print "id=\"$css_id\""; } ?>>
     	<!-- Our content goes here -->
     </div>

     The PHP snippet inside the div makes it possible to use CSS from the Panels user interface. We will leave it in, but it is better to only use CSS through a stylesheet to separate style from our PHP.

   • Next we will create two rows:
     

     <div class="panel-display panel-1row2cols clearfix" <?php if (!empty($css_id)) { print "id=\"$css_id\""; } ?>>
     	<div class="panel-1row2cols-row clearfix"><!-- Our content goes here --></div>
     	<div class="panel-1row2cols-row clearfix"><!-- Our content goes here --></div>
     </div>

     Because we will not set a fixed width and height we can give both rows the same class.

   • Now we will create the two columns in the bottom row:
     

     <div class="panel-display panel-1row2cols clearfix" <?php if (!empty($css_id)) { print "id=\"$css_id\""; } ?>>
     	<div class="panel-1row2cols-row clearfix"><!-- Our content goes here --></div>
     	<div class="panel-1row2cols-row clearfix">
     		<div class="panel-1row2cols-left"><!-- Our content goes here --></div>
     		<div class="panel-1row2cols-right"><!-- Our content goes here --></div>
     	</div>
     </div>

   • Finally we will add our areas, using the names we used in the onerowtwocols.inc file:
     

     <div class="panel-display panel-1row2cols clearfix" <?php if (!empty($css_id)) { print "id=\"$css_id\""; } ?>>
     	<div class="panel-1row2cols-row clearfix"><?php print $content['top']; ?></div>
     	<div class="panel-1row2cols-row clearfix">
     		<div class="panel-1row2cols-left"><?php print $content['left']; ?></div>
     		<div class="panel-1row2cols-right"><?php print $content['right']; ?></div>
     	</div>
     </div>

7. This means there’s only one file left to edit, our css file. We will make the layout fit the area it will be in, so we won’t give any fixed widths:
   • The outer div and the rows will be 100%:

     .panel-1row2cols {
     	width: 100%;
     }
     .panel-1row2cols-row{
     	width: 100%;
     }

   • Our columns will float to the left and to the right:
     

     .panel-1row2cols-left {
     	float: left;
     }
     .panel-1row2cols-right {
     	float: right;
     }

8. Finally we will have to make our layout ready for use, by clearing the cache so it will actually show up with the other layouts.
9. Now go wild, create very complex layouts you can use with your panels! An example of a module implementing extra layouts is the Panels Extra Layouts module