Previous | Up | Next |
Configuration files | Introduction | Database access |
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.
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.
global $PAGE
This hash contains various parameters related to the current page. Most are precomputed by the pre function.
The title
key of the
$PAGE variable holds the title of the
current page.
The options
key of the
$PAGE variable is a copy of the
array of options passed to the pre function by
the current page.
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.
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.
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.
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.
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"
.
Previous | Up | Next |
Configuration files | Introduction | Database access |
Documentation generated on Fri, 30 Jun 2006 10:31:36 +0200 by phpDocumentor 1.3.0RC3