|
|
|
Documentation for the Stale Content Management System (SMCS). Authored by Nigel Swinson and the Carrubbers webteam.
Nobody likes a website with stale content. If it is out of date, it is embarrasing, both for the user, the designer, and for the organisation that the website represents. Primarily it is the responsibility of the web designers to keep the content on a website uptodate, or to develop suitable systems that allow that responsibility to be delegated. The top level aims of the SCMS are:
Some content requires to be reguarily updated, every day/week/month/year due to it relating to a recurring event, while other data refers to a one off event that happens, and then ends. There is also data on the site that may not necessarily go out of date, but it should be "checked" at regular intervals to ensure that it stays up to date. These three styles of data have slightly different requirements as to how the data should be tagged.
If the content will go out of date regularily, it is helpful for the SCMS management interface to know how regularly it dates, on which day of the week/month/year it dates, and on which date the page was last checked. This information will allow us to work out when the next regular expiry boundary is and where we are now in relation to that expiry boundary. We can then check that against our last checked time to work out which boundary the current data applies to.
This data will also allow us to monitor what commitments are currently on the site. We can then analyse each in terms of risk and those systems that are consuming a high amount of bandwidth may be candidates for delagation outside the team through a web interface.
If the content is for a one off event, then we just want to be able to author the content, and let it come into and go out of date. The expiry criteria is now one absolute expiry time, and potentially one absolute time from which to start displaying the data. Then our job just comes down to an issue of "clearing out" or archiving the content once it has expired. The content itself will probably have already been hidden from view.
If the SCMS is being used just to ensure that content is checked regularily, then we just have to make sure that we eye-ball the page every so often. The data may not necessarily be out of date, but it might be so it would be worth checking to see just in case.
In order to achieve scalability, there could be several thousand web pages on a site, each of which could potentially contain content that could go out of date. Our first challenge is therefore to consider how to create a central place where all of the stale pages can be viewed. Clearly if we dynamically build a list of what is and is not stale when we visit the scms manager, then very quickly we will run out of processing power as we search our way through every page on the site. So there must be a central database for the site, containing a list of what pages are managed by the scms, which will tell us what needs to be updated on the site.
Our problem now breaks down into the issues of how we populate and view that central database. We could manually register pages with the scms, or run a script periodially to trawl through the site looking for pages we have tagged to be handled by the scms, but these options are either not scalable, or create barriers to the creative process of generating new content. What we really need is for the pages to automatically register themselves with the scms.
This ties in with the parallel goal of automatically expiring content on a page. If this is to be possible, there clearly has to be a dynamic server side processing element to the system. If we are to add new server side processing to the pages that contain volatile content, then we should be able to tie these two requirements together. Our server side processing engine of choice is of course PHP.
So if we have a php function in the scms that will add an entry to the database, then if we need to add a page to the scms, then all we have to do is to call that function from our page. That function can both register the page in the central database, and also return a suitable value to allow the server to decide how to render the page. The obvious choice for our function name is SCMS().
Rough idea for registering a page with the database
<html> <body> Some random conent <? // Include our SCMS library require_once(somewhere/scms.php); // This call registers this page with the // SCMS adding a db entry for this page SCMS(__FILE__); ?> Some other random content </body> </html>
On a note of caution, with this design, our SCMS() function is going to be called every time the page is viewed, so we must be very very careful to make sure SCMS() goes as fast as it possibly can, and defer any extra processing to the point at which the system is managed. This means that we should not do very much more than just add or modify the database record. If modifying the existing record is going to take too long due to the time required to search for the existing record, then we should just literally log the request and do as much processing as we need to do to tell the calling page whether the page is stale or not. Ideally, it should take less than 250ms to service the SCMS() request with a phpdbasedb database containing 300 records when run on the production server.
Should our SCMS() function fail in anyway, then it should catch all relevant errors and return with behaviour that suggests the content is currently valid. Practically speaking, this probably means we should set the error reporting level to zero and be very careful about error handling to ensure that we always return a value that will indicate to the caller that the content is valid.
In order to support the scalability that we require, our best option here is for SCMS() to take a single parameter which is an associative array, and return an associative array (or possibly FALSE). This allows us to expand the script by adding more values to the return value, or passing in more parameters in the input associative array to take advantage of advanced features. The SCMS() function will add an entry to the database with a key of the calling page, and column data of anything that was passed in through the SCMS() function.
The input array entries should be easily authorable as the user adds the SCMS() call, so entry names must all be easily written from memory, not requiring any tools or lookup process to work out if the names are spelt correctly or in the correct case. For this reason, the SCMS() system will accept the names of the associative entries in either case, or mixed case, and if an invalid name is entered it should provide suitable default behaviour, and the SCMS() system can record the fact that there is a syntax error on that page.
Many of the parameters to our function are going to be dates, and while it would be convenient for parsing if we were to use a timestamp in seconds, that will not be practical to author, so better to make it something that can flow from memory. Now we run into locale issues here, but given that the authors are British, and believe that day, month, year is the most logical way to lay out a date, that is the format we shall choose. To prevent confusion on dates like the 7/8/2002, we shall use a three character version of the month so that it is clear which section is the month, and which is the day. The format will be DD-MMM-YYYY where the month is given as the first three letters of the month, in either case or mixed case, and the day can be single digit, or double digit possibly one of which is a leading zero. ie
Given that the SCMS() function is going to be called from all over the site, if it goes "bonkers" then it is going to seriously impact much of the site. For this reason, we must make very very sure that under all circumstances, the SCMS() function:
Additionally the following may for suitable sections of the test harness:
Content is tagged by adding a PHP call to the SCMS() function in the source beside each of the sections of content that contains volatile content. There may be more than one call to SCMS on any given page, or just one call covering the page in general. Have a quick eyeball at the examples before reading all the gory details about the function itself.
A list of the valid associative array parameters follows. Please note that you must either specify Regular or Fixed, but not both. If both are set, then both will be ignored and the SCMS manager will show this as an error. If neither are set, then the content will always be displayed.
The description of the data that is to be managed by SCMS. Used for showing a description in the scms management console.
Default:
The location of this page, as seen by the web browser. This value will be used
to provide a link to the page to see the data that is managed by the SCMS by prepending the
name of the server. ie http://example.com/test.php/foo.bar would have Location
/test.php/foo.bar.
This may not
necessarily be unique, as there may be more than one call to SCMS() on one page.
The combination of the Location and the Description should always be unique. If the
description does not differ between two SCMS() calls on one page, then the second call
will blank over the first.
Default:
The content expires at regular intervals. The parameters that define those intervals, and when the data expires are held as an associative array as the data of this entry. The expiry schedule is based on the "cron" way of defining schedules.
The last time the page was checked for stale content. We could use the last modified time of the file, but this may be altered when a section of the page is updated, but the actual stale content is left alone. If this time is after the current time, but before the next regular boundary, then the content will be displayed. The times of the regular boundaries are evaluated from the other entries.
Default:
The day of the month when the current content expires. ie 14 would expire the content on the 14th of a month.
Default:
The day of the week when the current content expires. 0 = Sunday, 1 = Monday, 7 = Sunday. ie 3 would expire the content on a Wednesday.
Default:
The month when the current content expires, ie 5 would expire the content in May.
Default:
The year when the current content expires, ie 2003 would expire the content in the year 2003.
Default:
Default:
The content will be shown for a fixed period of time, then expired not to return. The parameters that define the bounds for when the content will be shown and hidden are held as an associative array as the data of this entry:
The date on which this content goes out of date.
Default:
The date on which this content becomes valid.
Default:
Default:
A list of the output associative array parameters follows. If SCMS() fails then it may return FALSE, but preferably if it can it should return an array which describes the content to currently be valid.
What the state of this page is. Options are:
Default:
The number of seconds until the content is valid. If the content is not yet valid, this will be positive. Once the content is valid, this will be a negative number.
Default:
The numbers of seconds until the content will expire. This will be positive if the content is yet to expire and negative if the content has already expired.
Default:
What follows are some examples to help you climb the fairly easy learning curve for using the SCMS.
This example will register the page in the database, but provide no extra information as to the expiry details for the page. This might be useful to indicate that the page contains content that will go stale, but at the time of authoring the developer either couldn't be bothered filling in the details, or did not know when the content would go out of date.
<?
require_once("scripts/php/scms/scms.php");
SCMS();
?>
Register a page, provide descriptive detail, and an expiry date. The page will not hide any content when the content goes out of date, but the manager will flag the page to indicate that the data is out of date.
<?
require_once("scripts/php/scms/scms.php");
$aSCMSArguments = array(
'Description' => 'Information about special event Christmas 2002',
'Fixed' => array('Expires' => '1-Jan-2003'));
SCMS($aSCMSArguments);
?>
Provide an expiry date and a valid from date. The content will only be shown when the page is viewed between the two dates.
<?
require_once("scripts/php/scms/scms.php");
$aSCMSArguments = array(
'Description' => 'Feedback section for special event Christmas 2002',
'Fixed' => array('Valid' => '25-Dec-2002'
'Expires' => '1-Feb-2003'));
$aSCMSResults = SCMS($aSCMSArguments);
if ($aSCMSResults['State'] == SCMS_STATE_VALID) {
?>
<p>Content that should only be displayed during the last week of December,
and the month of January.</p>
<?
}
?>
Data that goes out of date every week on a Monday, produce an "apology" if the data is out of date.
<?
require_once("scripts/php/scms/scms.php");
$aSCMSArguments = array(
'Description' => 'This weeks service times',
'Regular' => array('LastChecked' => '18-Sept-2002',
'ExpireWDay' => 0));
$aSCMSResults = SCMS($aSCMSArguments);
if ($aSCMSResults['State'] == SCMS_STATE_VALID) {
?>
<p>This weeks details.</p>
<?
} else {
?>
<p>We are sorry to say that current information is not available,
the system should be updated shortly, please try again later.</p>
<?
}
?>
Data that goes out of date every month on the 25th, produce an "apology" if the data is out of date.
<?
require_once("scripts/php/scms/scms.php");
$aSCMSArguments = array(
'Description' => 'This month\'s report',
'Regular' => array('LastChecked' => '18-Sept-2002',
'ExpireDay' => 25));
$aSCMSResults = SCMS($aSCMSArguments);
if ($aSCMSResults['State'] == SCMS_STATE_VALID) {
?>
<p>This month's report.</p>
<?
} else {
?>
<p>We are sorry to say that current information is not available,
the system should be updated shortly, please try again later.</p>
<?
}
?>
Data that needs to be checked in June every year to ensure that it is still valid. Show the content even if it hasn't been checked.
<?
require_once("scripts/php/scms/scms.php");
$aSCMSArguments = array(
'Description' => 'The current webmaster',
'Regular' => array('LastChecked' => '12-July-2003',
'ExpireMonth' => 6));
SCMS($aSCMSArguments);
?>
The SCMS() manager is likely to grow and expand over time, as we require more complex ways of viewing the data in our SCMS database. As a springboard, here are some ways we might want to view the content:
The SCMS manager can be slow if it wants to, as it will reside in the admin area, and therefore will only be seen and used by webteam members.
Last updated: 17 April 2008 02:15:13.
© 2008 Carrubbers Christian Centre | Registered Charity No. SC011455