README.txt

   1
   2 Panels Everywhere is an advanced method to completely do away with Drupal's
   3 restrictive blocks system and instead use the much more freeing Panels Layout
   4 system to control how your pages look. Panels Everywhere modifies the page as
   5 it is being rendered to 'wrap' the content in a display and can even take
   6 over your page theme to do away with the need for a page.tpl.php.
   7
   8 Doing this requires that you set up a few things properly, because Drupal is
   9 not really designed for this kind of behavior.
  10
  11 Getting Started
  12 ===============
  13
  14 Be sure that you have a version of Chaos Tools Suite newer than 12-28-2009 --
  15 this is either the current -dev or CTools 1.3 if it is out. At the time of
  16 this writing, CTools 1.3 has not yet been released, so you will need to use
  17 a -dev version (or from CVS).
  18
  19 Step 1
  20 ------
  21
  22 First, back up your site database, just in case. This will make it easy to
  23 completely revert if you decide that Panels Everywhere is not for you. It
  24 is also recommended that you first experiment with this on a small test site
  25 so that you can get a feel for the effects this will have. Sites are best
  26 built from the ground up on Panels Everywhere. Converting an existing site
  27 may be quite difficult.
  28
  29 Step 2
  30 ------
  31 Enable Panels Everywhere. If not using UID 1, be sure the user you're using
  32 has 'administer page manager' privileges.
  33
  34 Navigate to Administer >> Site building >> Panels >> Settings >> Everywhere.
  35
  36 Check the box to enable the site template.
  37
  38 Check the box to enable the sample variant.
  39
  40 You may check the box to override the page template, but only if you either
  41 enable the sample variant, or have already created a site template variant
  42 to handle page duties.
  43
  44 Step 3
  45 ------
  46 Navigate to Administer >> Site Building >> Pages and edit the site_template
  47 (Default site template) page.
  48
  49 Edit your new variant. Customize it if you like. There are some very
  50 important parts of this sample variant:
  51
  52   o The "Page content" pane is absolutely critical. That is the pane that
  53     will hold the actual content of the page you are looking at. If this
  54     pane does not exist, *no content will be rendered*, only the page
  55     template. Think of this as being the $content variable in your
  56     page.tpl.php -- you need that and cannot live without it.
  57
  58   o The "Title type" is set to "From pane" and the Page content pane is
  59     selected as the title. (That is why that pane has a thicker border).
  60     This is how the title of the content gets to be the title of the
  61     page.
  62
  63   o The Navigation, Header and Messages panes are conveniences that
  64     group common page navigation together. For customized sites it is
  65     highly likely that you will theme these or do away with them and
  66     use the individual pieces.
  67
  68
  69 Step 4
  70 ------
  71 You might also consider creating a completely blank theme, because existing
  72 themes will have CSS that expects different markup. To create a blank theme:
  73
  74 1) mkdir sites/all/themes/blank
  75 2) Create the following five lines in a file named blank.info:
  76
  77 name = Blank
  78 description = Blank
  79 core = 6.x
  80 stylesheets[all][] = blank.css
  81 engine = phptemplate
  82
  83 3) Visit Administer >> Site building >> Themes and change your theme to the
  84    blank theme.
  85
  86 Step 5
  87 ------
  88
  89 You can add additional variants and easily section off your site by using
  90 the selection rules. In particular, there are two selection rules you should
  91 be interested in:
  92
  93 o You can easily add a String: comparison selection rule and write regular
  94   expressions against the URL to use that.
  95
  96 o You can use the Context exists selection rule using the "Managed page"
  97   context. By using this, you can force the site_template to not run on
  98   actual Page Manager pages and use the site_template only as a wrapper
  99   for non Page Manager content. If you do this, you need to make sure that
 100   your other pages contain all the navigation they need.
 101
 102 Extras
 103 ======
 104
 105 For best results, customized layouts are the way to go. They can include as
 106 much or as little of the page template as you need, and are easily selectable.
 107 When you customize a layout, if it will be heavily styled, it is recommended
 108 that you provide a separate admin layout (in the layout.inc there are
 109 'admin theme' and 'admin css' settings) to provide a less styled layout for
 110 the purposes of editing. This will be critical to keep the editing UI from
 111 getting too messy.
 112
 113 The navigation, header and messages blocks can be easily customized by copying
 114 the appropriate pane-*.tpl.php files from the themes directory to your theme,
 115 changing them, and clearing cache. If you need to add additional variables,
 116 look at the theme.inc file. You can create similar preprocess functions in
 117 your template.php. The token function can accept any variable that would
 118 normally appear in your page.tpl.php.
 119
 120 You can easily add more variants and use the regular expressions in the
 121 String: comparison selection rules to change which display gets used based on
 122 the URL. You can also use the "Context: exists" selection rule to provide
 123 default panels only for content that is not already in a panel by checking to
 124 see if the "Managed page" context exists.
 125
 126 If you have a lot of different site templates or pages that include their own
 127 navigation, you can also consider using Mini Panels to create common navigation
 128 sidebars for easier maintenance.
 129
 130 Contexts
 131 ========
 132
 133 Your site template will now attempt to find contexts from the environment as
 134 best as it can. It handles all of the default Drupal locations, and if using
 135 a Page Manager page it can do some inheritance.
 136
 137 Currently Panels Everywhere can find the following contexts:
 138   o url: The internal URL of the page.
 139
 140   o alias: The alias of the page. Most of the time this is the URL actually
 141         visited, but beware that if the page has multiple aliases, it will
 142         be the *first* alias Drupal finds. i.e, if foo has aliases of 'bar'
 143         and 'baz', when visiting 'bar' or 'baz' the alias will always appear
 144         as 'bar' because it comes first in the list.
 145   o user: The logged in user.
 146
 147   o node:  The node being viewed. If visiting node/% or if visiting a page
 148         manager page that contains a node context, that node will be used.
 149         If the page manager page has multiple node contexts (due to
 150         relationships or multiple nid arguments) only the first node will
 151         appear in context.
 152
 153   o account: A user context for the user being viewed. Will appear on profile
 154          pages and on any page manager page with a user context (not
 155          counting the logged in user.)
 156
 157   o term: The taxonomy term being viewed if on a taxonomy term page. This
 158          won't work if viewing multiple terms (i.e, taxonomy/term/1,2) unless
 159          using a page manager page that derives a single term context.
 160
 161 In addition, before this is actually utilized you can use
 162 hook_panels_everywhere_contexts(&$contexts, $placeholders).
 163
 164 If you add contexts, use this function:
 165   panels_everywhere_site_template_add_context($contexts, $context, t('Human readable identifier'), 'keyword', 'internalid');
 166
 167 If $placeholders is TRUE, create your context using
 168 ctools_context_create_empty('type'); if $placeholders is FALSE, create
 169 your context using ctools_context_create('type', $object). If no object
 170 exists, create it as an empty context. It is important that an empty context
 171 appears even if there is not an object to keep the UI consistent.
 172
 173 Making Panels Everywhere aware themes
 174 =====================================
 175
 176 To make a theme PE aware, all that really matters is to provide a default site
 177 template that matches what the theme's page.tpl.php should be. To do this,
 178 create a site template in your site. Export the handler via the bulk export
 179 mechanism. Edit your .info file to contain these lines:
 180
 181 ; We provide default page manager pages for our site template
 182 api[page_manager][pages_default][version] = 1
 183 api[page_manager][pages_default][path] = pages
 184
 185 The bulk export will give you a .pages_default.inc file -- just place that in
 186 the 'pages' directory. Your new site template should be immediately available.
 187
 188 It's a very good idea to add a 'selection criteria' so that this template will
 189 only activate when your theme is the active theme.
 190
 191 You can also give your theme a hybrid mode where it will be smart and use its
 192 normal page.tpl.php if the site_template is not in use, and use a stripped
 193 down page.tpl.php if it is. Place the following code in your theme (chances
 194 are you already have a preprocess page).
 195
 196   function MYTHEME_preprocess_page(&$vars) {
 197     if (!empty($vars['panels_everywhere_site_template'])) {
 198       $vars['template_file'] = 'page-panels-everywhere';
 199     }
 200   }
 201
 202 Then copy panels_everywhere/theme/page.tpl.php to
 203 page-panels-everywhere.tpl.php in your theme. Once this is done, your theme
 204 will play nice with Panels Everywhere even if the option to take over the
 205 page template is not enabled.
 206
 207 There is rather a lot of information available via this variable if you like.
 208 The actual template used will be in $vars['panels_everywhere_site_template']['handler']
 209 and the contexts will be in $vars['panels_everywhere_site_template']['contexts'].