Pages and Templates

Pages

A page is the basic piece that handles each URL request. It is the basic functional unit of the system in a URL request is processed and displayed. The logic of a page is handled by a [[#Page Classes|class] which subclasses I2CE_Page via the action() method. Pages can be established to live directly under the base URL of the site, or under a module and all requests are delegated to the appropriate page by the wrangler. The GET and POST variables are (by-default) pre-processed by the page class. All pages, again by default, make use of a [#Template|templating] which acts as a wrapper for the Document Object Model (DOM). There is also a built in task and role based permission system.

There are also, by abuse of language, pages for the PHP CLI.

Wrangler

The wranger is the main software component which delegates URL Request to the appropriate page class. Let us suppose for this section that our site lives at the following base URL:

http://my.site.org/manage

Converting a URL to a Page

Pages can live directly under the base URL, or under a module. The wrangler processes the URL via the I2CE_Wrangler->processPath() method and returns a page name, the module the page name is registered with, and a request remainder. The module that a page name is registered under is often not the module that provides the page class. Let us outline the logic for the example:

http://my.site.org/manage/some/thing/is/here

• If there is nothing after the base URL, then the module is 'I2CE' and the page name is 'home'.
  There is no request remainder.
  This is not the case in the above example.
• If 'some' is registered as a page name provided by 'I2CE', then the module is 'I2CE' and the page name is 'some'.
  The request remainder is then thing/is/here.
  some is considered to be a page name registered under 'I2CE' if the magic data path /I2CE/page/some exists.
• Otherwise the module is 'some' and the following rules apply:
  • If there is nothing after the 'some', then the module is 'some' and the page name is 'home'
    There is no request remainder
    This is not the case in the above example.
  • If 'thing' is a registered as a page name for 'some' then, the module is 'some' and the page name is 'some.'.
    The request remainder is then is/here

Once the path has been processed, we verify that the returned page exists for the given module. If it does not, we try to handle the request by looking for a default page name for the module. The default page name, if defined exists at the magic data path /modules/$module/default_page.

The registered module, the page name, and the request remainder call all be accessed through I2CE_Pages's API.

Page Styles

Once we have a valid module and page name associated to a URL, we begin processing the page's styles. A page style can consist of three components:

• Another page style which this page style inherits the properties of
• A page class to associate to a page
• A nested array of arguments to pass the the page class constructor. These are merged into any inherited arguments by I2CE_Util::merge_recursive()

Templates

Each page instance is assigned a template which is an instance of I2CE_TemplateMeister, and usually an instance of the sub-class I2CE_Template.

The Template is essentially a wrapper class for a DOMDocument object with some useful convenience methods built in. Although the additional functionality provided by I2CE_TemplateMeister and I2CE_Template is initially very limited, it is greatly augmented by making use of fuzzy methods.

The page will display the DOM contained in the template as html after the page has finished processing.

Template Data

The most significant way the I2CE_Template case is augemented is to provide "Template Data." The module template-data provides the ability to assign arbitrary data to any node in the DOM. The data exists in categories, such as 'FORM' or 'OPTION' and applies to all sub-nodes of the given node. Each piece of data is assigned a name.

If the node is an given by specifying an id (rather than giving an explict instanceof DOMNode) the data will be held in a cache until a node with the given id is added to the template.

When looking for a piece of data assigned to a particular node, we start at the given node and walk up the DOM until the named data is found.

For each category of template data, a default bit of data may be assigned which applies for the whole DOM.

There are several modules which make explicit use of the template data structure.

Warning: The template data mechanism assumes that there is only one template in use per request. Be very careful if you are using multiple templates in one page each making use of template data.

Options

Closely related to the Display Data module is the Options module which saves template data in the category 'OPTIONS.' It process tags of the form:

<select id='some_id'/>

and if it finds an OPTION template data named 'some_id' it will append a <select> tag for each of these bits of data.

Form Data

A form can be set on any node and can be referenced as

<span type='form' name='form:field'/>

where you would substitute 'form' and 'field' as appropriate. If the 'form' is not specified it uses the default form, if any, set for the page.