Chapter 2. Developer's guide

2.1. Static Pages Design Document

2.1.2. Introduction

This is the design document for the Static Pages package, which

  • allows users to make comments on a web site's static pages, and

  • loads the pages into the content repository so they are available to other packages.

The functions are described in detail in the requirements document.

Although this package enables commenting and searching, those services are actually performed by the General Comments and Site-wide Search packages, respectively.

2.1.3. Historical Considerations

The ACS 3.x version of Static Pages implemented a number of features (such as clickstream analysis and broken link searching) which, in the interest of modularity, have been excluded from this version of the package.

2.1.4. API

The two primary functions offered by the Tcl API for Static Pages are

  • sp_sync_cr_with_filesystem, which synchronized the content repository with the filesystem, adding, updating, and deleting content repository entries as necessary; and

  • sp_serve_html_page, which is registered with the request processor to serve static pages. Before serving a page, it checks to see if the user should be offered the opportunity to make comments on it, and creates the appropriate link if necessary.

The sp_sync_cr_with_filesystem proc is fairly general, taking a starting path in the filesystem, a root folder id in the content repository (corresponding to the starting path), and a regexp to identify what files should be considered.

The PL/SQL API is contained in the static_page package, which contains functions for creating and manipulating static pages.

2.1.5. Data Model Discussion

The Static Pages data model is simple: file contents are stored in BLOBs in the content repository, and two tables, static_pages and sp_folders, describe the basic file hierarchy (since this information is not easily extracted from the content repository API). A package_id is stored along with each entry in sp_folders so that an instance of Static Pages is able to distinguish its root folder from the root folders of other services that may be using Static Pages to mirror the filesystem in the content repository.

2.1.6. User Interface

There are two main user interface pages: www/admin/fs-scan (or www/admin/fs-scan-progress) and www/admin/commentability. www/admin/fs-scan simply performs sp_sync_cr_with_filesystem and reports the results. www/admin/commentability allows the administrator to change the commentability settings (by means of static_page.grant_permission and other functions in the PL/SQL API).

2.1.7. Future Improvements/Areas of Likely Change

There are a few useful features that will likely be added in later releases.

  • When a file is moved, the file sync procedure will think that one file has been deleted and another created. Therefore any comments made on the file before moving it are lost. One possible solution (proposed by Jeff Teeters) would be to add an HTML comment (containing the page id) to each file when it is first loaded into the system. The file could be identified in subsequent scans by the presence of the comment. However, modifying the static pages in the filesystem may raise other problems.

  • There is not presently any way to exclude pages from the site-wide search.

2.1.8. Authors

  • System creator: Brandoch Calef

  • System owner: Brandoch Calef

  • Documentation author: Brandoch Calef

2.1.9. Revision History

Document Revision #Action Taken, NotesWhen?By Whom?
0.1Creation2001/03/05Brandoch Calef

($Id: dev-guide.html,v 1.1.1.1 2001/04/20 20:51:23 donb Exp $)