Documentation updates
authorEarl Miles
Wed, 26 Jul 2006 16:53:40 +0000 (16:53 +0000)
committerEarl Miles
Wed, 26 Jul 2006 16:53:40 +0000 (16:53 +0000)
API.txt
README.txt
TODO.txt
layouts/threecol_25_50_25.inc
layouts/threecol_25_50_25_stacked.inc
layouts/threecol_33_34_33.inc
layouts/threecol_33_34_33_stacked.inc
layouts/twocol.inc
layouts/twocol_stacked.inc

diff --git a/API.txt b/API.txt
index e69de29..a658952 100644 (file)
--- a/API.txt
+++ b/API.txt
@@ -0,0 +1,125 @@
+The API for expanding the panels module comes in two pieces. First there is the \r
+layout API, which adds to the list of layouts you need. Second is the content\r
+types API, which lets modules supply content to the panels. Natively, panels\r
+module supports the content types of 'block', which just renders the output\r
+of a block, 'node' which simply renders a node_view, 'custom' which allows the\r
+user to enter custom content with filtering, and finally 'views' because I\r
+wrote them both.\r
+\r
+Where to put your code:\r
+=======================\r
+\r
+With both types, there are two ways to implement a new type. First, you can\r
+implement the hook in your module and provide the necessary data. Or you\r
+can create a .inc file in the right format, and drop it into the proper\r
+directory in the panels module. Both are very similar, and only requires\r
+a minor naming adjustment.\r
+\r
+When using the .inc file, in place of 'hook' in the various hooks, use\r
+panels_FILENAME. \r
+\r
+Creating a new Layout Type:\r
+===========================\r
+\r
+A layout consists of 4 things:\r
+\r
+1) A bit of HTML in a theme function. I use heredoc notation to make it\r
+   extra easy to convert these to .tpl.inc files in case they are to\r
+   be overridden in php template.\r
+2) A bit of CSS to describe how the layout should be, well, laid out.\r
+3) An icon that is 50x75 which gives the user a visual indication of\r
+   what the layout looks like.\r
+4) An implementation of hook_panels_layouts() to tell panels the necessary \r
+   information.\r
+\r
+hook_panels_layouts returns an array with the following information:\r
+\r
+'module' => The module name providing this. This is necessary because it\r
+            uses drupal_get_path('module', $module) to get the proper\r
+            path for included CSS.\r
+'title'  => The title of the layout presented to the user. Use t().\r
+'icon'   => The filename of the icon to use when listing avialable layouts.\r
+'theme'  => The theme function that contains the HTML, without the theme_ \r
+            part.\r
+'css'    => The CSS file.\r
+'content areas' => an array in the form of 'name' => t('Title') of content\r
+                   areas supported by the layout. For example, the simple\r
+                   2 column layout uses array('left' => t('Left side'), \r
+                   'right' => t('Right side')); -- the name is the internal\r
+                   identifier. Your theme function will see it as \r
+                   $content['name'] (so twocol gets $content['left'] and\r
+                   $content['right']).\r
+\r
+\r
+Creating a new Content Type:\r
+============================\r
+\r
+Content types require 1 hook and two callbacks. The hook defines what content \r
+types are available, the first callback displays the content in a dashboard, \r
+and the other callback does all of the administrative functions.\r
+\r
+hook_panels_content_types returns an array with the following information:\r
+'callback'  => The function to display the content.\r
+'admin'     => The function to administer the content.\r
+\r
+The callback function receives one argument: The $configuration array, as\r
+defined by the administrative callback.\r
+\r
+The administrative callback recieves 3 arguments:\r
+\r
+$op     -- the operation to perform. See below.\r
+&$arg1  -- The first argument should be a reference and its meaning varies \r
+           based on the op.\r
+$arg2   -- The second argument is optional, not a reference, and should \r
+           default to NULL.\r
+\r
+Administrative operations:\r
+\r
+'list':     $arg1 is the configuration array.\r
+    This op is called when panels lists what content is in a content\r
+    area. It generally returns something similar to this:\r
+    return '<strong>Views</strong>: ' . $view->name . ' (' . $view->description . ')';\r
+\r
+'add button': arguments not used here.\r
+    This op is called to display the 'add content type' button; it can also\r
+    display additional information (such as the list of blocks or the\r
+    autocomplete to select a node).\r
+\r
+    The actual button should look something like this:\r
+        $form['submit'] = array(\r
+          '#type' => 'button',\r
+          '#value' => t('Add view'),\r
+        );\r
+\r
+    And it's a good idea to do this, but it's not required:\r
+\r
+        $form['#prefix'] = '<div class="container-inline">';\r
+        $form['#suffix'] = '</div>';\r
+\r
+'add': $arg1 == the $configuration array\r
+    This op is called to see if your add button has been clicked. It *must*\r
+    start off by checking to see if this is true:\r
+\r
+        if ($_POST['op'] != t('Add view')) {\r
+          return;\r
+        }\r
+\r
+    If it is true, it should process that information and return a $configuration\r
+    array populated from whatever other form items were presented in 'add button'\r
+    and whatever defaults make sense.\r
+\r
+'edit': $arg1 == the $configuration array\r
+    This op is called to provide an edit form for a content type. It *must*\r
+    ensure *all* information from the conf array is available, even if it\r
+    is just hidden; panels has no way to remember this data between form\r
+    clicks, so any data not put here will be lost. No buttons need to be\r
+    added to the form.\r
+\r
+'validate': $arg1 == $form_values, $arg2 == $form\r
+    Called to validate the 'edit' form above.\r
+\r
+'save': $arg1 == $form_values\r
+    Called to convert a $form_values back into a $configuration array. All\r
+    of the default types just send $form_values back as $configuration,\r
+    but if you need to do some kind of transformation, this is where it\r
+    happens.\r
index d41f669..131f305 100644 (file)
@@ -9,4 +9,10 @@ file without breaking it.
 \r
 Perhaps most importantly, unlike the dashboard module it requires no fiddling \r
 with PHP code to include the things you want; the interface lets you add blocks, \r
-nodes and custom content just by selecting and clicking. 
\ No newline at end of file
+nodes and custom content just by selecting and clicking. \r
+\r
+If you want to override the CSS of a panel, the easiest way is to just copy\r
+the CSS into your theme directory and tweak; panels will look there before\r
+including the CSS from the module, and if it exists, will not include the\r
+module's CSS. If you want to just change a tiny bit but keep the basic\r
+structure, just add your changes to your style.css instead.
\ No newline at end of file
index 16a7341..6022dd1 100644 (file)
--- a/TODO.txt
+++ b/TODO.txt
@@ -1,14 +1,12 @@
 TODO:\r
 \r
-? content type: phptemplate\r
+This is a brief list of the things that may still need to be done. No guarantee\r
+of them ever getting done.\r
+\r
+content type: phptemplate\r
 \r
-content templates:\r
-  1 x 2 x 1\r
-  3 col -- even\r
 access control to pages\r
 access control to content types\r
 \r
 dashboard node extension\r
 \r
-write help\r
-document plugin API\r
index 821137f..b3c16fd 100644 (file)
@@ -5,7 +5,6 @@
 function panels_threecol_25_50_25_panels_layouts() {\r
   $items['threecol_25_50_25'] = array(\r
     'module' => 'panels',\r
-    'path' => 'layouts',\r
     'title' => t('Three column 25/50/25'),\r
     'icon' => 'layouts/threecol_25_50_25.png',\r
     'theme' => 'panels_threecol_25_50_25',\r
index f03b0f4..e8ae62c 100644 (file)
@@ -7,7 +7,6 @@
 function panels_threecol_25_50_25_stacked_panels_layouts() {\r
   $items['threecol_25_50_25_stacked'] = array(\r
     'module' => 'panels',\r
-    'path' => 'layouts',\r
     'title' => t('Three column 25/50/25 stacked'),\r
     'icon' => 'layouts/threecol_25_50_25_stacked.png',\r
     'theme' => 'panels_threecol_25_50_25_stacked',\r
index 429db38..b732e70 100644 (file)
@@ -6,7 +6,6 @@
 function panels_threecol_33_34_33_panels_layouts() {\r
   $items['threecol_33_34_33'] = array(\r
     'module' => 'panels',\r
-    'path' => 'layouts',\r
     'title' => t('Three column 33/34/33'),\r
     'icon' => 'layouts/threecol_33_34_33.png',\r
     'theme' => 'panels_threecol_33_34_33',\r
index 4af9abc..fd34a34 100644 (file)
@@ -7,7 +7,6 @@
 function panels_threecol_33_34_33_stacked_panels_layouts() {\r
   $items['threecol_33_34_33_stacked'] = array(\r
     'module' => 'panels',\r
-    'path' => 'layouts',\r
     'title' => t('Three column 33/34/33 stacked'),\r
     'icon' => 'layouts/threecol_33_34_33_stacked.png',\r
     'theme' => 'panels_threecol_33_34_33_stacked',\r
index 28e6a5e..01f6a3c 100644 (file)
@@ -6,7 +6,6 @@
 function panels_twocol_panels_layouts() {\r
   $items['twocol'] = array(\r
     'module' => 'panels',\r
-    'path' => 'layouts',\r
     'title' => t('Two column'),\r
     'icon' => 'layouts/twocol.png',\r
     'theme' => 'panels_twocol',\r
index fc1a2c9..72266c7 100644 (file)
@@ -7,7 +7,6 @@
 function panels_twocol_stacked_panels_layouts() {\r
   $items['twocol_stacked'] = array(\r
     'module' => 'panels',\r
-    'path' => 'layouts',\r
     'title' => t('Two column stacked'),\r
     'icon' => 'layouts/twocol_stacked.png',\r
     'theme' => 'panels_twocol_stacked',\r