Layout plugins are one of the simplest and most powerful sections of the panels api. There are two different ways that a layout can be implemented via panels. Panels supports both module and theme implementations of panels. The module implementation requires that hook_ctools_plugin_directory define the directory in which your layout plugins exist. (This same hook defines the directory for all panels plugins) Alternately, if you intend on implementing a layout in a theme this can be done primary through the theme's info file. The Ctools help does a great job of actually explaining this portion of the API ctools: plugins.
Ctools explains even the layout hooks a little in its example, but we'll recap quickly and expand on this information. As ctools explains, the actual plugin file must be named with care as it will directly affect your naming scheme for the hook within it. This is really no different from any other hook within drupal except that we'll be using multiple replacements in this case. The function we're looking to implement is an instance of:
function YOURMODULE_PLUGINNAME_OWNERMODULE_PLUGINTYPE()
In our case we already know that the function will be:
function YOURMODULE_PLUGINNAME_panels_layouts()
This is because the plugin type we're working with is a layout, and the module that implements these layouts is the panels module. For the rest of the naming scheme "YOURMODULE" will be replaced with either the name of your module that implements this layout, or the name of the theme, and "PLUGINNAME" will be replaced with whatever the name of the plugin file is. For purposes of this example our module name us going to be "layout_sample" and our plugin will be "first_layout".
We're going to assume that you've laid your directory structure out very similarly to how panels does it. Something like this is rather likely:
layout_sample layout_sample.info layout_sample.module plugins layouts first_layout first_layout.css first_layout.inc first_layout.png layout-sample-first-layout.tpl.phpThe name of our .inc file is going to be the key to the entire layout plugin.
We will start with the first_layout.inc file as it's the most important file we're dealing with here. First_layout.inc will look similar to the following:
function layout_sample_first_layout_panels_layouts() { $items['first_layout'] = array( 'title' => t('First Layout'), 'icon' => 'first_layout.png', 'theme' => 'layout_sample_first_layout', 'css' => 'first_layout.css', 'panels' => array( 'main' => t('Main region'), 'right' => t('Right region'), ), ); return $items; }The include file defines all the other files that our layout will utilize in order to be truly useful. The array is fairly self explanitory but for the sake of specificity:
function layout_sample_first_layout_panels_layouts() { $items['first_layout'] = array( 'title' => t('First Layout'), 'icon' => 'first_layout.png', 'theme' => 'layout_sample_first_layout', 'css' => 'first_layout.css', 'admin css' => 'first_layout_admin.css', 'panels' => array( 'main' => t('Main region'), 'right' => t('Right region'), ), ); return $items;
The tpl.php file is very similar to any other template file within drupal. The difference here is that we're being passed an array of regions through $content, and we also have a css id available to us for the entire panel in the form of $css_id. The template is very straight forward and will look similar to the following:
<div class="panel-display panel-stacked-twothirds-onethird clearfix" <?php if (!empty($css_id)) { print "id=\"$css_id\""; } ?>> <div class="panel-panel panel-col-first panel-region-main"> <div class="inside"><?php print $content['main']; ?></div> </div> <div class="panel-panel panel-col-last panel-region-right"> <div class="inside"><?php print $content['right']; ?></div> </div> </div>This is simply an example of what the html could look like. You can alter an update this html to fit your own needs.
The css and png files are as simple as any other css or png file you've ever utilized. Panels provides some images for its graphical representations of its layouts. I would heavily encourage you to modify these to suit your needs. The CSS files (admin and non) will be included at the appropriate times. Simply set them up to fit your purposes. If you're utilizing fixed width panel regions it's probably smart to provide an admin css file as well with your panel layout.