first import

sites/all/modules/panels/help/api.html

@@ -0,0 +1,44 @@
+<p>Panels is a pluggable rendering engine. Apart from its datastructure, almost nothing in Panels is hardcoded; every level of its rendering process is controlled by plugins (of the <a href="topic:ctools/plugins">CTools</a> variety), and therefore can be overriden. Some of these plugins' behaviors are obvious from the UI, whereas others are much more under-the-hood.</p>
+<p>Most site builders and module authors will find that plugins are the only way they need to interact with Panels to do what they want. However, if you are building whole new UIs/applications that are to be driven by the Panels engine, you'll also need the more traditional API that manages Panels editing and CRUD. Panels Node and Mini Panels are examples of 'applications' in this sense, as is <a href="http://drupal.org/project/og_panels">OG Panels</a>.</p>
+<p>This page is divided into two sections, the first dealing with Panels' rendering system & the plugins the drive it, and the second with the requirements for creating a Panels-driven application/UI. The former is a good starting place and should be of interest to anyone wanting to begin working with the Panels API.</p>
+
+<h2>The Panels Rendering System</h2>
+<p>Panels' rendering system takes a fully-loaded panels_display object and turns it into HTML. It doesn't care how that object was built or where it comes from - it's just a rendering engine. So long as the calling code provides a well-formed panels_display object, the engine will spit out HTML. Exactly how that process works is determined entirely by plugins.</p>
+<p>Panels utilizes eight different types of plugins within its rendering system, four owned by Panels and four by CTools. Let's run through that list.</p>
+<dl>
+<dt><a href="topic:panels/plugins-layout">Layout plugins</a></dt>
+<dd><em>Owned by Panels.</em></dd>
+<dd>Layout plugins provide the HTML output skeleton for any panel: they define a set of regions and (optionally) accompanying CSS/JS, very analogous to how themes define block regions. While layout plugins with complex logic are possible (the Flexible layout, for example), most layouts are nothing more than a region list, a tpl.php skeleton, and some CSS.</dd>
+<dt><a href="topic:panels/plugins-style">Style plugins</a></dt>
+<dd><em>Owned by Panels.</em></dd>
+<dd>Style plugins control the markup that wraps both individual panes and whole panel regions. A basic style plugin need not provide more than some basic CSS and a theme function or tpl.php file.</dd>
+<dt><a href="topic:ctools/plugins-style-bases">Style Bases</a></dt>
+<dd><em>Owned by CTools.</em></dd>
+<dd>Panels implements the 'style_bases' plugin type in order to interact with the Stylizer system, which technically lives in CTools, though true 'ownership' is a little blurred. Regardless, Panels uses this plugin to interact with Stylaizer in order to allow the creation of style plugins in the UI.</dd>
+<dd>This plugin is probably of interest only to module developers; site builders can safely skip it.</dd>
+<dt><a href="topic:ctools/context-context">Context plugins</a></dt>
+<dd><em>Owned by CTools.</em></dd>
+<dd>Context plugins are abstracted wrappers around bits of data - a node, user, or taxonomy term are easy examples. Panels uses context plugins so that it can work with all these different bits of data without caring about the details of the datastructure itself. Context can be a confusing concept, and you can learn more in the <a href="topic:ctools/context">CTools help</a>.</dd>
+<dd>Note that <a href="topic:ctools/context-arguments">argument</a> and <a href="topic:ctools/context-relationships">relationship</a> plugins are technically also used by Panels, but because they're really means for creating more context, they don't get separate entries in this list.</dd>
+<dt><a href="topic:ctools/plugins-content">Content Type plugins</a></dt>
+<dd><em>Owned by CTools: can utilize context.</em></dd>
+<dd>At the heart of the Panels rendering process, content type plugins define the rendering logic for every pane. Offering Panels a renderable chunk from your module means defining one of these. For those accustomed to the block system, they can be thought of as a more verbose block definition, contained neatly inside a single plugin.</dd>
+<dd>Content type plugins rely on context to provide them with source data, when necessary; this makes content plugins nice and portable.</dd>
+<dt><a href="topic:ctools/context-access">Access plugins</a></dt>
+<dd><em>Owned by CTools: can utilize context.</em></dd>
+<dd>Access plugins are essentially portable access checking logic, responsible for answering "Yes" or "No" given some contextual data. Panels uses these to define 'visibility rules' on individual panes. The other place these are commonly seen is in defining 'Selection rules' on Page Manager variants.</dd>
+<dd>If your module introduces new permissioning concepts or access logic (NOT a basic hook_perm() implementation), you may want to consider also encapsulating that logic in one or more of these plugins. For example, Organic Groups might implement an access plugin to allow/deny based on group membership, or the Date module might implement allow/deny logic based on request time.</dd>
+<dt><a href="topic:panels/plugins-cache">Cache plugins</a></dt>
+<dd><em>Owned by Panels; should utilize context.</em></dd>
+<dd>Panels cache plugins define caching strategies that can be applied to individual panes, or to whole displays. Caching plugins must deal with two basic issues: the cache backend to use for reading/writing, and TTL-managing strategies.</dd>
+<dd>TTL strategies can (and should) integrate heavily with the context, as that is where the real differential benefit of Panels-based caching is vs. standard core caching.</dd>
+<dt><a href="topic:panels/plugins-renderers">Display Renderers</a></dt>
+<dd><em>Owned by Panels: utilizes everything else.</em></dd>
+<dd>In the simplest terms, display renderers take a fully-loaded panels_display object and render it. They are very complex, powerful plugins - one could use them to cause Panels to bypass every single other plugin in this list. Fortunately, there is virtually no circumstance under which one would need to implement these plugins in the process of building a single site; only contrib developers working on highly complex use cases are likely to ever need them.</dd>
+<dd>In short, each display renderer plugin <strong>is</strong> a self-contained Panels rendering engine. If you want to grok the Panels rendering system, study these.</dd>
+</dl>
+
+
+<h2>Panels-based Applications</h2>
+<p>At its core, Panels is a rendering engine with no UI (though it does provide common elements for reuse in admin UIs). So if you're working with Panels via the web UI, it means you're working with a Panels application. The three that ship with this version of Panels are Mini Panels, Panel Nodes, and the integration with CTools' Page Manager.</p>
+<p>Panels also implements a task_handler plugin, which is owned by Page Manager in CTools. Task handlers aren't strictly a part of Panels' rendering system itself though (strictly speaking, they wrap it), so we won't cover them here.</p>

sites/all/modules/panels/help/panels.help.ini

@@ -0,0 +1,74 @@
+[advanced help settings]
+line break = TRUE
+
+[glossary]
+title = Panels glossary of terms
+weight = 100
+
+[about]
+title = About Panels
+weight = -100
+
+[common-tasks]
+title = Accomplishing common tasks in Panels
+weight = -50
+
+[tutorials]
+title = Panels tutorials and how-tos
+weight = -30
+
+[tutorial-landing]
+title = Creating a simple landing page
+parent = tutorials
+
+[tutorial-node]
+title = Styling a node page
+parent = tutorials
+
+[tutorial-vocabulary]
+title = Styling a vocabulary
+parent = tutorials
+
+[apps]
+title = Panels-based applications
+parent = api
+
+[panels-pages]
+title = Panel pages, via Page Manager
+parent = apps
+
+[panels-mini]
+title = Mini panels
+parent = apps
+
+[panels-node]
+title = Panel nodes
+parent = apps
+
+[api]
+title = Working with the Panels API
+weight = 50
+
+[render-api]
+title = Panels plugins
+parent = api
+
+[plugins-layout]
+title = Layout plugins
+parent = render-api
+weight = -10
+
+[plugins-style]
+title = Style plugins
+parent = render-api
+weight = -7
+
+[plugins-cache]
+title = Cache plugins
+parent = render-api
+weight = -4
+
+[plugins-renderers]
+title = Display Renderer plugins
+parent = render-api
+weight = -1

sites/all/modules/panels/help/plugins-layout.html

@@ -0,0 +1,87 @@
+<h2>Getting Started:</h2>
+<p>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 <a href="topic:ctools/plugins-implementing">ctools: plugins</a>.</p>
+
+<p>For purposes of this example, our module name is going to be "layout_sample" and our plugin will be "first_layout".</p>
+
+<h2>Directory Structure:</h2>
+<p>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:
+<pre>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.php</pre>
+The name of our .inc file is going to be the key to the entire layout plugin.</p>
+
+<h2>The .module File:</h2>
+<p>First, declare where your custom layouts reside by implementing the CTools hook <code>hook_ctools_plugin_directory()</code>:
+<pre>
+/**
+ * Implements hook_ctools_plugin_directory().
+ */
+function layout_sample_ctools_plugin_directory($module, $plugin) {
+  if ($module == 'panels' && $plugin == 'layouts') {
+    return 'plugins/layouts';
+  }
+}
+</pre>
+
+<h2>The .inc File:</h2>
+<p>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:
+<pre>
+  $plugin = 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'),
+    ),
+  );
+</pre>
+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:
+<ol>
+<li><strong>Title:</strong><br />The title of our layout. (Utilized within the panels administration screens)</li>
+<li><strong>Icon:</strong><br />The graphical representation of our layout. (Utilized within the panels administration screens)</li>
+<li><strong>Theme:</strong><br />The template file of our layout. (Sharp eyed readers will note that the theme definition utilizes underscores instead of dashes, and does not have ".tpl.php" after it. This is refering to the layout-sample-first-layout.tpl.php file all the same, it is simply how the naming convention works. Utilize dashes in the tpl file name and underscores when refering to it in your include file.)</li>
+<li><strong>CSS:</strong><br />The css file to be utilized for our layout. (Utilized within the panels administration screens, AND when viewing the actual panel itself.)</li>
+<li><strong>Panels:</strong><br />Defines all the various regions within your panel. This will be further utilized within our tpl.php file.</li>
+</ol>
+There are many additional properties that can be added to the include file. For purposes of this document we'll also make mention of the 'admin css' property. 'Admin css' is especially useful when utilizing a fixed width layout with fixed with panel regions. This can break under most administrative circumstances, and panels provides you with the ability to give an additional css layout for the administrative section. It's a simple nicety and looks like this:
+<pre>
+  $plugin = 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'),
+    ),
+  );
+</pre>
+</p>
+
+<h2>The tpl.php File:</h2>
+<p>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:
+<pre>&lt;div class="panel-display panel-stacked-twothirds-onethird clearfix" &lt;?php if (!empty($css_id)) { print "id=\"$css_id\""; } ?&gt;&gt;
+  &lt;div class="panel-panel panel-col-first panel-region-main"&gt;
+    &lt;div class="inside"&gt;&lt;?php print $content['main']; ?&gt;&lt;/div&gt;
+  &lt;/div&gt;
+
+  &lt;div class="panel-panel panel-col-last panel-region-right"&gt;
+    &lt;div class="inside"&gt;&lt;?php print $content['right']; ?&gt;&lt;/div&gt;
+  &lt;/div&gt;
+&lt;/div&gt;
+</pre>
+This is simply an example of what the html could look like. You can alter an update this html to fit your own needs.
+</p>
+
+<h2>The Other Files:</h2>
+<p>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.</p>