THE GOAL: Flesh out a bunch of "todo" documentation for Panels/Page Manager in 4 hours or less. ;) What follows is a copy/paste of the existing docs from Advanced Help. Let's make the empty bullet list into full paragraphs. w00t!
== PAGE MANAGER DOCS ==
About Page Manager
The Page Manager module creates and manages pages in your Drupal site. Pages are defined as items that have a path and provide output to the user. It is a complete round trip from getting user input to providing user output.
There are two types of pages that the Page Manager currently supports:
Custom pages
Custom pages are defined completely by the administrator. Their path, access control and visible menu characteristics are completely arbitrary.
System pages
System pages are defined by Drupal and Drupal modules. They primarily override pre-existing pages to provide different functionality. They often do not allow such features as access control in favor of what already exists, and they will usually 'fall back' to default Drupal behavior.
Both types of pages figure out what to show the user by using Variants. Variants are output handlers, and every page should have at least one. Most pages will simply have only one. Pages with multiple variants will choose one and only one Variant to display content to the user and will use the Selection Rules to figure out which Variant to display.
Getting Started
This is a quick summary:
- Visit administer >> site building >> pages to get to the primary page manager interface.
- You can add custom pages for your basic landing pages, front pages, whatever you like for normal content display.
- You can use the system pages to create finer control of how taxonomy vocabularies, nodes and user profiles are displayed.
- When you add your first custom page, do not bother with the optional features. You will not need these until you get to more advanced tasks.
- The selection rules are the key to creating node displays for just one node type.
- Everything in this system is pluggable. A little PHP knowledge and exploration of the plugins directories can take you a long way.
Creating a page
With Page Manager, you can create your own custom pages with flexible layouts all with just a few clicks! In its simplest form, creating a page consists of four steps: Configuring some basic settings, choosing a layout for the page, configuring Panel settings, and finally selecting the content to appear in your panel.
From the page list at Administer >> Site building >> Pages, click "Add custom page".
http://img.skitch.com/20100819-rsdfpnbr4yujx33hqsg981fn7e.png
Options:
- Administrative title: The name that shows up in the administrative interface
- Machine name: The internal, machine-readable name of the page, referenced in theming and imports/exports
- Administrative description: A longer description to remind you of exactly what the page was for.
- Path: The URL to the page you are creating
- Make this site your home page: If selected, will change your site's home page to the custom page you're creating
- Variant type: PLEASE SOMEONE FILL THIS OUT :)
- Optional Features:
- Access Control
- Visible menu item
- Selection rules
- Contexts
Next, choose a layout for your page:
http://img.skitch.com/20100819-me12t7my81mgtt7r8upr9d5cug.png
Select from a Category of pre-fabricated layouts, such as 1, 2, or 3-Column layouts, or choose "Builders" to create your own customized layout that meets your exact needs.
The next screen prompts you to adjust panel settings.
http://img.skitch.com/20100819-q4jfdc5bbque8d915dnumsx2bj.png
- Administrative title: As above, a name for the Panel to refer to in the administrative interface.
- Disable Drupal blocks/regions: If selected, this Panel will completely take over the page, including any header, footer, or sidebar block regions. Useful for ultimate control over the page's presentation.
- Renderer: Select how the panel will be rendered out to the browser. Standard is typical and simply renders out the panel as-is. If you have the Panels In-Place Editor module enabled, this will also appear as an option. This option allows content editors to adjust the content of a panel in-place while looking at the page.
- CSS ID: Add a CSS ID to a panel to assist with targeted styling in your theme.
- CSS code: Here you can post a snippet of CSS code to assist with stying. It's vastly more recommended to move this sort of styling to your theme, but for quick adjustments this textarea is handy.
Finally, you'll be able to specify which content appears in your Panel's various regions.
http://img.skitch.com/20100819-gspehdq2yg2917ey8xstj2buap.png
- Title type: Specifies the page title of this panel. Options are:
- No title: As the name implies, the Panel will not specify a page title.
- Manually set: Specify the page title yourelf by entering it into the Title field
- From pane: Inherit the title from the selected Panel pane. To choose the pane from which to inherit, click its gear icon and select "Panel title".
Each panel region (top, left side, right side, etc.) has configuration options associated with it, which can be found by clicking the gear icon. If you select Add content, you are taken to a content selection screen, as shown below.
http://img.skitch.com/20100819-1ttybcx7fj61yxupb6kchp84ng.png
Content you can place within a panel region includes blocks (categorized according to type, with "Miscellaneous" as a general placeholder for contributed module blocks), views, menus, page elements (such as site logo, slogan, and footer message), existing node content, and even "custom" content that provides a simple title/body field for creating re-usable bits of content without going through the node system.
http://img.skitch.com/20100819-nmrpb19bgktpyuym9phhgd13gq.png
If the Stylizer module is enabled, you'll also see the a Style option underneath the panel region configuration. By selecting "Change", you can choose from a pre-configured style for this region (rounded corners, list, etc.) or create your own.
http://img.skitch.com/20100819-f1gntcpjnbx3s7isi1ixjkaw1c.png
By choosing a Custom style, you have full control over the borders of the pane, foreground/background color, font properties, and nearly anything else you can think of. You can then store this style for re-use in other panels and panes.
- Tutorial: Make a page that looks different for members
- Tutorial: Customize the look of a single node type -
- Tutorial: Customize the look of a single taxonomy vocabulary
- Custom pages
- Arguments
- Access control
- Menu items
- Variants
== PANELS DOCS ==
Installation
Installing Panels requires the following modules:
- Chaos tool suite (http://drupal.org/project/ctools), a set of generic APIs that Panels builds upon. Within CTools, the following sub-modules are either required or recommended:
- Chaos Tools (required) - underlying libraries supporting other modules
- Custom content panes - allows creation of low-overhead content that doesn't require the full use of the node system
- Custom rulesets - combinations of access plugins you can use for access control, selection criteria and controlling pane visibility
- Page manager - provides the capability to take over entire pages in Drupal and replace them with custom content
- Stylizer - create your own pane styles (colors, background, etc.) within the UI and reuse these styles on different panes or panels
- Views content panes - Allows Views to be included in Panels
- Panels (http://drupal.org/project/panels), of course! Panels includes the following recommended modules:
- Mini panels: The power of Panels in a block
- Panel nodes: The power of Panels in a node
- Panels In-Place Editor: Allows editors to edit a panel's content in-context while looking at the page.
Additionally, in order to use the Panels In-Place Editor, the following modules are required:
Getting Started
- What is Panels
- Panel styles - Panels styles are reusable bits of markup and css that can be used to style individual Panel regions or panes themselves. They are not only limited to css but can affect markup as well via template files that live in the /plugins/styles directory of your theme. They can be selected through the U/I and are handy for reusing styles throughout the site. Panels includes several example styles and is compatible with using Skinr styles as well, either as block styles if blocks are run through the system template, or through Skinr iteself through panel-pane.tpl.php.
- Selecting and modifying layouts - Panels supplies a number of preconfigured layouts, selectable when you initially create your panel. This can also be changed to a different layout from the 'layout' link in the panel's configuration screen. These basic layouts give users a set of regions to start adding content. Along with the preconfigured layouts is the 'Flexible' layout, which enables users to create a specialized layout that suits whatever needs they have. Choosing a layout is as simple as clicking the radio button or the image of the desired layout. Users can also create their own layouts through the API.
- Using caching with Panels
- Understanding contexts
- Accomplishing common tasks in Panels
- Create a simple landing page
- Start by creating a new Panel node at node/add/panel.
- Using Views with Panels
- Overriding user profiles with a Panel - User profiles have long been a difficult to theme are of Drupal sites. Panels offers the ability to control profile layout and content selection by enabling the user profile template at admin/build/panels/dashboard and editing at admin/build/pages/edit/user_view. You can have different layouts per role and and a default role to fall back on. Once again, system blocks, views, and page elements are available. Also to note, Panels now has support for the Content Profile module.
- Create and reuse a custom layout
- Controlling 'Node Edit' and 'Node Add' Pages- Besides controlling landing pages, user pages, and node layouts, Panels can also control the visible items and organization of node edit and node add pages for editing content. Under admin/build/pages/edit/node_edit, a new variant can be added to control forms for any of the standard selection criteria. A form option will be available in the UI that allows for controlling the order of form elements as well as the ability to add other content such as nodes, views, etc in a way that offers perspective for content editors.
- Panel sub modules
- Mini panels
- Panels also includes the "Mini Panels" module. You can use this to create smaller, reusable pieces of content with the features of full panels, but that can be used like blocks. For example, if you have sidebar content (composed of two columns blocks, views, and some static content) that is reused across your site, create a Mini Panel with a two column bricks layout. Add a block to the left, a view pane to the right, your static text to the bottom, and finish. This Mini Panel will then be available to your system as an ordinary block, or as panel content to go in the other panels.
- Node panes - Allows embedding specific nodes into panes without using contexts. While it is less powerful than using a node context, it can be simpler to use. Enable this module if you want nodes directly embedded into panel displays.
- Panel nodes
- Panel nodes are a content type which allows you to create node content, but use Panels' interface to customize the layout and content. Panel nodes behave like regular nodes. For example, they appear in your searches, can be published to the front page, flagged, used in Views, etc. However, their feature set is more limited than panel pages, namely that you cannot export panel nodes.
- Panel pages
- Panels glossary of terms
- Add Content / Activity - (SHOULD THE 'ADD CONTENT' PAGE STUFF BE INCLUDED HERE??)
- Panel: a "panel" consists of all the components that make up that page or series of pages -- variants, one or more layouts, regions, content panes, etc. A panel has a path that may be a single node, or a pattern that contains arguments.
- Panel node - Panel nodes are created like any other type of content within Drupal (generally from Create Content -> Panel). Panel nodes can be styled and laid out individually, making them best suited for static pages.
- (Panel) page
- Path
- (Panel) region
- Pane: the smallest container of content in a panel -- think of a pane like an individual block. A pane could be a node, view, node, or custom content.
- Style
- Layout - a layout is essentially a setup of panel regions that is preconfigured for selection by the user. Layouts come from the layout link, and give a list of available region setups, such as "three columns", or "two column brick". Layouts define the initial structure of your panel - a frame in which to begin placing content.
- Content: Any piece of information in Drupal that's available for use. Anything node can be considered content, along with anything you can convince panels to get its hooks on.
- Widget: content provided by Drupal modules that you can add to a panel. Widgets are items that do not fall under a category like View Panes or Menus, such as the search form or language switcher
- Variant: Variants are similar to displays within views; a panel can have multiple variants. A variant is one version of a panel setup.
- Canvas: when in the flexible layout builder, the canvas is the outermost container of your layout. You add columns to your canvas.
- Column: a layout must have one column, and can have as many vertical columns to contain your content as you wish. You can add rows to your columns.
- Row: rows go inside columns in your layout, to create horizontal containers for your content
- Context
- Argument
- Styling a node page - Besides allowing custom landing pages, Panels node variants allow all node pages of a particular content type to be themed through the UI instead of the PHPTemplate system (.tpl.php files). Layouts can be selected and content such as CCK fields, views, blocks, and page componets can be added to layout regions via a drag and drop interface. More complex contexts can be added as well for more fine grained control of which version of the page is displayed. Individual nodes can also have their own layouts if needed.
- Styling a vocabulary
- Panels API