CustomPage Documentation

Disclaimer: this documentation is under development.

Custom Page is an advanced theming tool, allowing developers to easily create pages with custom templates and maintain full control over the output (e.g. HTML).

To install:

1. Download the latest release.
2. Place it under a modules folder and enable.
3. Grant appropriate permissions to the users who should be able to use it.

To create a new page:

1. Go to [Administration -> Site Building -> Custom Pages -> Add a Custom Page] in the Drupal menu. If you don't have such a page make sure you've enabled Custom Page Admin UI.
2. Enter the Title, URL path and Key attributes for a custom page. "Key" is the name of a template file that creates for the path. For instance, enter "homepage" for both path and the key. In such case the URL http://example.com/homepage will be served by homepage.tpl.php file in the new theme created.

To create a template:

1. Create [key].tpl.php in the current theme's directory and enter the HTML markup. This template file will be inserted in the content area, the same way a node.tpl.php would be inserted in page.tpl.php for node pages. (Note: The caches may need to be cleared before Drupal picks up the new template, though. Drupal theming is heavily cached starting from version 6)
2. Insert dynamic components in your markup using Custom Page utility functions: custompage_view_tile(), custompage_node_tile(), custompage_menu_tile().
3. Syntax for node insertion:
   print custompage_node_tile( $key, $type = '' );
   where $key can be a node's node id (nid), in which case $type parameter is ignored, or it can be node's title, in which case the node_type needs to be indicated in the second $type parameter.
4. Insert a WebForm too, with its nid.
5. Syntax for a View insertion:
   print custompage_view_tile( $name, $title='', $display_id = 'block_1', $arg1, $arg2, $arg3...);
   where $name is the system name of the View, $title is the title that you want to append to the output, enclosed in H2 tags. If omited the $title parameter, View's title from View definition will be used. If a Boolean is FALSE passed, the title won't be appended at all. $display_id indicates whether you want to insert Block view or Page view of the View (or any other custom display that might have defined)
    
   $arg1, $arg2, $arg3... are view arguments. You can pass as many as you need.
6. Syntax for a Region insertion:
   print custompage_region_tile('regionname');
   this is also the way you should insert blocks in a template. You need to insert a region (pre-defined in a themename.info) and then use block management interface of Drupal to assign whatever blocks you need for the region. There's no separate block insertion function in custompage (by design)
7. Syntax for a Menu insertion:
   print custompage_menu_tile( $menu_name);
   where $menu_name is the system name of a menu as recorded in the {menu_custom} table. For primary links it's "primary-links", for secondary links: "secondary-links", for a custom menu with the machine-readable name like "summary-menu" it's "menu-summary-menu" etc.

Theming a Taxonomy Term Page

You can use CustomPage to create an original template for a term page

1. Create a new custompage with the path set to 'taxonomy/term/%'
2. In the corresponding tpl.php load term object with something like:
   
   $tid = arg(2);

if (is_numeric($tid)) {
  $term = taxonomy_get_term($tid);
}

   Theme term page header and load+add all nodes of a particular type filtered by the term_id with something like:
   

   print custompage_view_tile( 'my_awesome_view', $title=FALSE, 'block_1', $tid);

Multilingual:

1. Nodes: Indicate its nid when Inserting a node in the default language of the site (usually: English). A Custom Page will substitute a nid with the translated nid (if such exists or will display the default), when you switch to another language.

   The node must have Translation : "enable with translation" set for this to work, of course. Also you should translate a node via the translation tab in the node edit screen.

2. Views: Add the language filter to your nodes so it returns items in the current language. For more advanced configuration you may also consider Select Translation module for more advanced filtering.

On-Spot Editing:

• Users with the "edit custompage tiles" permission will be able to see a highlight when they hover their mouse over a Custom Page element (node or a view) and will be able to edit those on-the-spot, without going into the administration menu, search for the content and having to come back.

Packaging:

If you need to package a Custom Page with a module A template can be created from a module, as well, (and allow theme developers to override it!). There are two major ways of doing this:
• Implement [modulename]_[key] function with the following arguments: ($title, $user, $data). $title is the title of the page, $user as the currently logged-in user and $data is a dynamic array assembled from the hook_customdata_[key] calls.
• Implement a hook_theme() in your module
  function yourmodule_theme($existing, $type, $theme, $path) {
return array(
  'yourpath' => array(
   'arguments' => array('title' => '', 'user' => '', 'data' => ''),
   'template' => 'yourtplname',
  )
);
}
  ATTENTION: "yourpath" should match with the path you indicated in the CustomPage UI or in the hook_custompages() (if you registered a custompage via the API)

Dynamic Data:

• One way of inserting dynamic data in a custom page is to use the utility functions described above.
• Another way is to prepare any data-structure in helper modules. Any module can implement a [modulename]_customdata_[key] function and the data it returns will be merged into the $data variable array passed to the template. Custom Page also makes $title and $user variables available for the theme.

Hooks

Custom Page comes as a suite of two modules: custompage itself (the API and engine) and custompage_ui, the administration user interface to the module that allows to add/edit/delete custompage entries. Third-party modules can provide additional definitions via hook_custompages() implementations. Each such implementation should return an array of PHP Objects with the following properties: title, key, path, enabled.