API Guide

Table of Contents

  1. Introduction
  2. Creating a PR2 Instance
  3. Loading Content
  4. Page Layouts and Templates
  5. Rendering and Printing
  6. Other Miscellaneous Functions
  7. Summary
  8. Extending PageRender2

Introduction

The PageRender2 API is generally concerned with the loading of content into various named "slots" in an output buffer. When PR2 renders the final page, it grabs the content from all of the slots, puts them together using the page layout and template, and prints the output to the screen.

PageRender2 works with a few straightforward commands, but you can pass options to alter the behavior of each of these commands.

Creating a PR2 Instance

First, you need to include the PageRender2 libraries. If you are using the sherpa template, all of the following will be done for you in the config/standardIncludes.php5 file.

If you are not using sherpa, create a PR2 instance as follows:

SAutoLoad::addModule('pr2');

Next, create an instance of PR2 or of a local PR2: 

$prm = new PageRender2();
/* or $prm = new LocalPageRender2() */

If you want to make sure that your PR2 instance is functional, you should be able to test it by calling: 

$prm->renderPrint();

It can already build you a page! But that is a pretty boring page. So the next (and most important) subject is...

Loading Content

As you collect the various components of your page, you will want to load them into named "slots" in the page buffer, which store certain parts of the page. When PR2 renders the page, all those parts will be put together to make a meaningful whole.

Slots

The slots available by default in your output buffer are: For Page Content

For the Page Head

For Page Navigation and Naming

For Tabs Bars:

For Feature Wells:

For the Bottom Bar

For Metrics Sites

Reserved

Look at the documentation for the SPageTemplate you are using to find out what slots to load your content into.

The Simplest Page Load

You load content into your page using the load() function, which accepts three parameters:

In the simplest case, if

then you can run the following: 

$prm->load($input);

If your input is HTML instead of StdXML3, you can use the options array to specify that: 

$prm->load($input, array('inFormat' => 'html'));

What Page Loads Do

Every time you call load(), your input content is passed through a translator object. The simplest translator passes content directly to the page without changing it at all. More complex translators can reformat the content or even add interactive features via javascript (such as in-page search).

The translator that PR2 will use is determined by the options you pass to load().

Specifying Types When Loading

The translator's input type must match your input, and its output type must match the target format for your output page. The default types are:

You can indicate that your input is something other than the default type by passing an option to the load function, as we saw above. This code snippet is simply telling PR2 that the input string is HTML rather than the default, XML. 

$prm->load($input, array('inFormat' => 'html'));

Specifying Translators When Loading

PR2 chooses its translators based on their input and output types. If the input type of your content changes, so does the default translator. For every type, there is a default translator. Shown below are the default translators for each type: xml: STransStdXML3 html: STransHTML object: STransObject

So, when you specify inFormat to be html, PR2 simply chooses the STransHTML translator and passes your input through that.

You can pick which translator is used by changing the option specifying which translator handles your type of input. You simply change the value for the option translator_type (where type is your input type) to the translation class you want to use. The translator can either be a default translation class (in common/pr2/translate), or a custom translation class (in project/app/translate).

Below is an example of picking the STransBookXML class to translate your input XML. Note that specifying inFormat to be xml is unnecessary as xml is the default inFormat.

/* ex. choosing a non-standard translator for XML */
$prm->load($input, array('inFormat' => 'xml', 'translator_xml'=>'STransBookXML'));

/* ex. to load your navigation XML */
$prm->load($navXML, array('inFormat' => 'xml', 'translator_xml' => 'STransNavXML'), 'Nav');

Specifying Targets When Loading

One more thing you are likely to change in the load options is the target of the translation: the slot in which the output content should end up.

The option for the translation target is trans_target. Simply specify a slot name for this option, and the content will be added to that slot rather than to the Main (default) slot.

For instance, the following code would use the default translator for HTML (STransHTML) and would direct its output to the SideBar slot in the page buffer. 

$prm->load($input, array('inFormat' => 'html', 'trans_target' => 'SideBar'));

Specifying Modes When Loading

Finally, a seldom-changed option, you can change the mode of the load so that the translator overwrites the content of the slot rather than appending to it (the default). We could modify the last code sample to "set" rather than "append" as follows: 
$prm->load($input, array('inFormat' => 'html', 'trans_target' => 'SideBar', 'trans_mode' => 'set'));

Loading TK2 Objects

You'll often want to load TK2 view objects to your PR2 page. This is done with the add() function as follows: 
$prm->add(new TKLabel('Hello, World!'));

Of course, you can add any TK2 view to your PR2 page, no matter how complex. You can also pass the standard translator options to the add function. For example, if we wanted to load the TK2 item into the SideBar: 

$prm->add(new TKLabel('Hello, World!'), array('trans_target' => 'SideBar'));

Loading SNAP2 Content

It is frequently useful to display SNAP2 content through a PR2 page. Therefore, PR2 auto-detects SNAPResource and SNAPVersion objects when they are passed to load() to make things super-easy. For example: 
$s = Snap2::lookup('//test/sherpa');
$prm->load($s);

Page Layouts and Templates

PR2 layouts and templates define how the page content, stored in slots, will be combined to form an output page.

To make your page be a typical Shodor-style page, set your page layout to SShodorLayout. This layout class knows how to write out the HTML for all possible parts of a Shodor-style page. (You don't need to do this in your code, since it is the default layout.) 

$prm->setOption('layout', 'SShodorLayout');

Then, if you want to re-order, hide, or change the style of the meta-slots, you can use a page template. For instance, to choose a template that hides the PageTitle and PathBar, shows the UpperFeatureWell, sets the UpperFeatureWell to display as two columns, and sets the ContentWell to display with a right side bar, you could use the template called SplashPageTwoColsRightSideBar: 

$prm->setOption('template', 'SplashPageTwoColsRightSideBar');

Layouts and templates are documented on a class-by-class basis. Some templates may only look good for certain layouts. For instance, the PrintTemplate looks good under SShodorLayout, but not HPCULayout.

In addition to using globally available layouts and templates, you can extend them to create local layouts and templates in your own project. You can extend SShodorLayout (or SLayout) and SPageTemplate and store your classes in app/layout and app/template. If you are doing this, be sure to add those folders to the search path using SAutoLoad::addSearchPath().

Rendering and Printing

The final step in using PR2, after loading your content in, is to render the page (combine all the slots into a meaningful page using a layout/template) and print the page buffer to the screen.

This can all be done using the renderPrint() command: 

$prm->renderPrint();

Other Miscellaneous Functions

Often, you want to exit out of a PR2 page that you are in the process of building because some fatal error has occurred (for instance, a user has passed the script invalid input or tried to access a page for which he/she does not have permission).

In these cases, it is useful to use the flashAndExit() function to render and print a pretty error page and then exit the script immediately. Here's an example: 

if($error) {
    $prm->flashAndExit('You made my program angry! Goodbye.');
}

Summary

Here's a sample controller script that fetches XML from a file and content from SNAP2, then loads them both into the content of a page. It assumes we are in a project with a standardIncludes file. 
include_once("../../config/standardIncludes.php5");

/* create your page */
$prm = new PageRender2();

/* load in your static XML content */
$xml = file_get_contents("$PROJECT_ROOT/content/sampleList.xml");
$prm->load($xml);

/* load in your SNAP2 content */
$rsrc = Snap2::lookup('//test/sherpa');
$prm->load($rsrc);

/* render your page to the screen */
$prm->renderPrint();

Extending PageRender2

Most projects have a local version of PageRender2 that defines special behaviors for rendering. For instance, you might want to change some of PR2's options site-wide, or you might want to override the renderPrint() function so that some last-minute items are added to your page right before it gets printed out.

Here is the default LocalPageRender2 provided by the sherpa site template. In this class, the local PR2 overrides the constructor to set the collection name slot to the name of the project at the time the PR2 instance is created. This value could be changed in the code as the controller runs.

It also overrides renderPrint() so that it can generate and add the navigation XML to the page at the last minute. This allows controllers to keep modifying/adding items to their NavXMLModule until the moment the page is rendered to the screen. This allows pages to add tabs, etc. more easily.

class LocalPageRender2 extends PageRender2  {

    public function __construct() {
        global $SITE_PATH, $PATH, $STRING;
        parent::__construct();
        // get the page of this PR2 and set the default Collection Name
        // to be the full name of this site.
        $this->getPage()->setSlot('CollName', $STRING['siteName']);
    }

    public function renderPrint() {
        global $snm;
        // load the site nav before rendering and printing any page
        if (isset($snm) and ($snm instanceOf NavXMLModule)){
            $nav = $snm->generateXML();
            $this->load($nav, array('translator_xml'=>'STransNavXML'), 'Nav');
        }
        parent::renderPrint();
    }
}

These are the most frequent reasons for extending PageRender2, but there are many other possibilities!

Generated on Wed Nov 24 02:01:29 2010 for Common by  doxygen 1.5.6