Previous Up Next
Configuration files Introduction Database access
The framework

The framework

SWS general framework documentation

The framework

The first and foremost function of SWS is to provide functions to separate content from style. The two functions that manage this are described below, along with the relevant global variables.

The core API

Overview of pre()

This function does most of the work that SWS has to do. It needs two parameters, $title being the title of the page, and $options being a hash of options, with keys the option names and the values the corresponding option value. Note that you can leave out the options part if a page does not need specific options, which should be the case with the majority of the pages.

Here is what pre does:

  • First, it will try to resolve various links related to the current page: the link back to the index in the current directory, and an array of links to the other files in the pages directory (also known as the list of topics). These are stored in the $PAGE global variable.

  • Next, pre will load the specified theme. Specified means the theme specified by the options key theme, or the default theme specified in the site configuration file for the site in which the page is located, or failing that, the default theme specified in the global configuration file (in that order).

  • Then, it will load all extensions specified in the extensions options key. This key should be an array of extension names. Each is loaded as appropriate.

  • After that, it will try and insert this pages title in the database. For every page, SWS will remember its title so that the framework can generate a list of topics with human readable titles. Exceptions to the titles entered into the datbase are pages that set the error option key to a value that evaluates to true. This is intended for pages that are served in response to an HTTP error.

  • Pages can specify that they contain restricted content by setting the restricted option to a privilege that will suffice for access to the page. This access check is performed and a logon screen is presented (by calling the requireLogin function) if SWS determines that the current user does not have the required privilege.

  • If access was granted, or the page was not restricted, then finally the theme function preContent is called, which outputs the needed HTML to the user.

There are a few more options that a page can specify:

  • The changepw option. If this option is set then the current page is considered to be a password change page. The framework will then call the passwordChangeForm function in the currently loaded theme to display a password change form. If the password change was successful, the content of the page is shown.

  • The usedb option. This should be a name (or an array of names) of databases which the page will be using. The system will try to connect to these databases before anything is output to the client. This is especially handy when the user needs to be asked for the login credentials for the database (see the __ASK__ option in the database parameter file).

  • It is possible to provide a default set of options for a group of pages in a single directory by putting those options in a configuration file called .options in the same directory as the pages. Options specified by individual pages will have precedence over this per-directory default.

Note that most SWS functions that (implicityl) use $_SESSION variables, such as user authentication etc., rely on internal variables being set by this function. You should not call things like userLogin before having called pre. You can, however, call requireLogin in order to protect page content from unauthorized viewers.


$PAGE

global $PAGE

This hash contains various parameters related to the current page. Most are precomputed by the pre function.


$PAGE['title']

The title key of the $PAGE variable holds the title of the current page.


$PAGE['options']

The options key of the $PAGE variable is a copy of the array of options passed to the pre function by the current page.


$PAGE['index']

The index key of the $PAGE variable is an array consisting of two values, with $PAGE['index'][0] being the URL to the index page of the directory that the current page resides in, and $PAGE['index'][1] being the title of that index page.


$PAGE['topics']

The topics key of the $PAGE variable is a hash, with the keys of this hash being filenames of files that reside in the same directory as the current page. The values are the corresponding titles.


$PAGE['backlink']

The backlink key of the $PAGE variable is an array consisting of two values, just like the index key, with $PAGE['backlink'][0] being the URL of the page, and $PAGE['backlink'][1] being the title of the page. Unlike the page referenced in the index key, this is a link to the index page of the directory above the one that the current page resides in.


$PAGE['renderstart']

The renderstart key of the $PAGE variable contains the start time that the page was rendered, as returned by getmicrotime. This value can be used to determine the (approximate) total page rendering duration by calling getmicrotime() at the end of rendering the page and using strmicrotime to display the the resulting time difference.


$PAGE['theme']

The theme key of the $PAGE variable is itself an associative array. A theme can make use of this array itself. There are a few keys preset by the SWS framework. These are:

  • name, the name of the current theme.

  • url, an URL that a theme can use to refer to items in its own directory.

  • directory, the location of the theme directory in the filesystem.

So, to refer to an image that a theme uses, one can just do print $PAGE['theme']['url'] . "image.jpg".


Miscellaneous functions

Previous Up Next
Configuration files Introduction Database access

Documentation generated on Fri, 30 Jun 2006 10:31:36 +0200 by phpDocumentor 1.3.0RC3