Theming Custom Pages

When you want to have a different design from one page to the next on your site you use $CUSTOMPAGES in your theme.php.

Prior to .7 you could only define one set of custom pages - giving you a maximum of two different designs.

A popular use of this among site designers is to have a two column layout for the forums of the site (to maximise viewing space) and three columns for the rest of the site.

This is how it works:

  $HEADER = "the html that gives a three column layout";
  $FOOTER = "the html that gives a three column layout";
  $CUSTOMHEADER = "the html that gives a two column layout"; 
  $CUSTOMFOOTER = "the html that gives a two column layout"; 
  $CUSTOMPAGES = "forum.php forum_post.php forum_viewforum.php forum_viewtopic.php"; 

This gives you the two column layout on all your forum pages.

With .7 comes an expansion to this system to allow you to define as many sets of custom pages as you wish to use - you could even have each page on your site as a custom design if you wished.

Here's how it works:

  $HEADER = "the default html layout";
  $FOOTER = "the default html layout";
  $CUSTOMHEADER['multicolour_links'] = "the multicoloured links html layout";
  $CUSTOMFOOTER['multicolour_links'] = "the multicoloured links html layout";
  $CUSTOMPAGES['multicolour_links'] = "links.php";
  $CUSTOMHEADER['my_forum'] = "the forum pages html layout";
  $CUSTOMFOOTER['my_forum'] = "the forum pages html layout";
  $CUSTOMPAGES['my_forum'] = "forum.php forum_post.php forum_viewforum.php forum_viewtopic.php"; 

As you can see, you can define as many layouts as you wish and give them any name you like, in this example we decided to use the names 'multicolour_links' and 'my_forum' to give us a helpful identifer as to what each set of custom pages were being used to do.

When creating the custom page in an existing theme: copy your current header section, rename it $CUSTOMHEADER and remove the columns you no longer wish to utilize. Do the same for the footer section renaming the copied $FOOTER section to $CUSTOMFOOTER.

The $CUSTOMPAGES[] field is a space-separated list of pages on which the particular layout is to be used. The code searches for one of these values within the current URL (including the query part) - so specifying 'page.php?2', for example, will also match 'page.php?24' and 'page.php?299'.

For 0.7.9 onwards, adding a '!' at the end of the page name matches only URLs ending with the specified string - so page.php?2! will match only page 2, while page.php?24' and 'page.php?299' will be displayed in some other way. Note that this option is available only with URLs having a 'query' part (i.e. the bit after '?').

The old system without the id's will also still work so existing themes are all still compatible with 0.7; however it is recommended that new themes use the array system described above to ensure long-term compatibility.

One final point to note is that unlike the old system where if you were using $CUSTOMPAGES, you had to define both $CUSTOMHEADER and $CUSTOMFOOTER - with the new system, you do not need both the custom header and footer and instead you can define just $CUSTOMHEADER on its own and the normal default $FOOTER will be used in the absence of the $CUSTOMFOOTER and vice versa, $HEADER will be used in the absence of $CUSTOMHEADER.

For more information and an example, look at the e107 core theme, 'reline' In theme.php al the sections are annotated to show what each does.

As of e107 v0.8+, the following scheme should be used in theme.php:

  $HEADER['my_layout'] = "the default html layout";
  $FOOTER['my_layout'] = "the default html layout";

  $HEADER['multicolour_links'] = "the multicoloured links html layout";
  $FOOTER['multicolour_links'] = "the multicoloured links html layout";

  $HEADER['my_forum'] = "the forum pages html layout";
  $FOOTER['my_forum'] = "the forum pages html layout";

ie. $CUSTOMHEADER and $CUSTOMFOOTER should no longer be used. The specification of custompages for each layout are stored in a separate configuration file: theme.xml (more on that later) These custompages are simply defaults, and can be edited from with the admin area. (no need to edit the theme.php file any more).