pr2/pdoc/apiguide.pdoc

@endcode

If you want to make sure that your PR2 instance is functional, you should be able to test it by calling:
@code
$prm->renderPrint();
@endcode

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


@section pr2_apiguide_loading 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.

@subsection pr2_apiguide_loading_slots Slots

The slots available by default in your output buffer are:
<B>For Page Content</B>
- Main
- SideBar
- ContentWellSideBar
- ContentWellSideBar2
- ContentWellColumn2
- ContentWellColumn3

<B>For the Page Head</B>
- ExtraJS
- ExtraCSS
- Keywords
- ExtraHeadTags
- LibHeadTags
- CustomCSSLinks
- DefaultCSSLinks
- CustomJSLinks
- DefaultJSLinks
- OnLoad

<B>For Page Navigation and Naming</B>
- CollName
- TopBarNavWell1
- TopBarNavWell2
- TopBarNavWell3
- PageName
- PageTitleRightText
- Path

<B>For Tabs Bars:</B>
- TabsBar1
- TabsBar2

<B>For Feature Wells:</B>
- UpperFeatureWell
- UpperFeatureWellColumn2
- LowerFeatureWell
- LowerFeatureWellColumn2
- LowerFeatureWell
- LowerFeatureWellColumn3

<B>For the Bottom Bar</B>
- BottomBarLeftText
- BottomBarRightText

<B>For Metrics Sites</B>
- Omniture
- Analytics

<B>Reserved</B>
- HiddenTempBuffer
- windowTitle
- title
- Flash

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

@subsection pr2_apiguide_loading_simplest The Simplest Page Load

You load content into your page using the load() function, which accepts three parameters:
- <B>$input</B>: a string or object to load into your page
- <B>$options</B>: an associative array of options for how it is to be loaded
- <B>$name</B>: (optional) a name for the load so that you can refer back to it later

In the simplest case, if
- $input is a string in StdXML3 format, and
- you want to load it to the Main (default) slot,

then you can run the following:
@code
$prm->load($input);
@endcode

If your input is HTML instead of StdXML3, you can use the options array to specify that:
@code
$prm->load($input, array('inFormat' => 'html'));
@endcode

@subsection pr2_apiguide_loading_background 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().

@subsection pr2_apiguide_loading_types 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:
- inFormat: xml
- outFormat: html

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.
@code
$prm->load($input, array('inFormat' => 'html'));
@endcode

@subsection pr2_apiguide_loading_translators 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 <tt>translator_type</tt> (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.

@code
/* 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');
@endcode

@subsection pr2_apiguide_loading_targets 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 <tt>trans_target</tt>. 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.
@code
$prm->load($input, array('inFormat' => 'html', 'trans_target' => 'SideBar'));
@endcode

@subsection pr2_apiguide_loading_modes 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:
@code
$prm->load($input, array('inFormat' => 'html', 'trans_target' => 'SideBar', 'trans_mode' => 'set'));
@endcode

@subsection pr2_apiguide_loading_tk2 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:
@code
$prm->add(new TKLabel('Hello, World!'));
@endcode

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:
@code
$prm->add(new TKLabel('Hello, World!'), array('trans_target' => 'SideBar'));
@endcode

@subsection pr2_apiguide_loading_snap2 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:
@code
$s = Snap2::lookup('//test/sherpa');
$prm->load($s);
@endcode


@section pr2_apiguide_layout Page Layouts and Templates

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

- A page layout writes the actual HTML code for one type of page design
- A page template determines what chunks or "meta-slots" of the page layout show up, in what order, and with what internal design

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.)
@code
$prm->setOption('layout', 'SShodorLayout');
@endcode

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:
@code
$prm->setOption('template', 'SplashPageTwoColsRightSideBar');
@endcode

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().


@section pr2_apiguide_rendering 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:
@code
$prm->renderPrint();
@endcode


@section pr2_apiguide_misc 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:
@code
if($error) {
    $prm->flashAndExit('You made my program angry! Goodbye.');
}
@endcode

@section pr2_apiguide_summary 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.
@code
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();
@endcode

@section pr2_apiguide_extending 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.

@code
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();
    }
}
@endcode

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

*/

---