Press Design Document

by Sarah Barwig, Stefan Deusch

I. Essentials

II. Introduction

Most Web services and almost all corporate sites have a "foobar.com in the news" page. This page typically offers a chronological list of articles appearing in newspapers, magazines, etc., in which the site or company is featured. This differs from our News application in that the site publisher is linking off to other publications and not trying to disseminate news himself. The Press application supports site-wide press coverage - appropriate when one ACS installation is being used for a company - and subcommunity press coverage, e.g. for a service like arfdigita.org where many organizations are using the same ACS instantiation. Anyone who has the administrator role in a user group can edit the press coverage for that group. Press items are displayed using a paging system. The module can be configured to display a set number of items on the main page, and will offer links to 'previous' and 'next' pages when these are available. The press administrator can revise a press item by adding a new revision. Because the application employs version control, the administrator can switch back to a historic version of a press item should the need arise.

III. Historical Considerations

The Press application was designed by looking at the presentation formats appearing on sites like www.scorecard.org and www.valinux.com and selecting those features we felt were most desirable. Our initial design was later modified to add pagination and access to an archive of expired articles based on feedback from client sites.

IV. Competitive Analysis

The Press application is consistent with the functionality of similar systems on the public internet.

V.Design Tradeoffs

By employing an application-specific templating system for this package, we offer site owners the benefit of simplified display customization on a per article basis. The templating system adds additional complexity to the Press application, especially with respect to displaying articles. Here, we have sacrificed usability for a more advanced feature set. The use of templates will minimally require the application administrators to learn and use HTML and to employ variables used by this templating system. We have automated the linking function of the press module in order to prevent the administrator having to learn ADP-programming.

VI. Data Model Discussion

The Press application makes heavy use of the exisiting ACS Content Repository service and its API, but not of its templating system. A press item consists of: The important template information is found in the table press_templates. 
create  table cr_press (
    press_id                    integer
                                constraint cr_press_id_fk references cr_revisions
                                constraint cr_press_pk primary key,
    -- include package_id to provide support for multiple instances
    package_id                  integer,
    -- constraint cr_press_package_id_nn not null,                      
    -- information about the publication where this press item appeared
    -- *** The journal name, the journal URL ***
    publication_name            varchar2(100)
                                constraint cr_press_publication_name_nn not null,
    publication_link            varchar2(200),
    -- *** the specific journal issue ***
    publication_date            date not null,
    publication_date_desc       varchar2(10),
    -- *** the article link, pages ***
    article_link                varchar2(400),
    article_pages               varchar2(40),
    article_abstract_html_p     varchar2(1) 
                                    constraint cp_article_abstract_html_p_ck
                                    check (article_abstract_html_p in ('t','f')),
    -- *** support for dates when items are displayed or archived ***
    -- unapproved release dates are null
    release_date                date,
    -- unscheduled archiving dates are null
    archive_date                date,
    -- support for approval, if ApprovalRequiredP == 1
    approval_user               integer
                                constraint cr_press_approval_user_fk
                                references users,
    approval_date               date,
    approval_ip                 varchar2(50),
    -- *** presentation information ***
    -- supply own press-specific templates (see table below) until
    -- template system is better organized and documented
    template_id                 integer default 1 
                                constraint cr_press_templ_id references press_templates 
);
Note that different package instances of 'press' can be distinguished by the column 'package_id' (and not by the inherited context_id in acs_objects).

Templating

The module provides a flexible templating system to support the wide range of formats needed for different sites and types of press coverage. Templates can be defined for different journals and styles. They can be mixed on the same site. A press item contains the followings information:

A press administrator can define named templates to control how these pieces of information are displayed. The templates are written as HTML fragments using the variables listed above, each of which is flanked by '@' signs (see below). These are the essential variables that must occur in any template. A sample template might be:

      <b>@publication_name@</b> - @article_name@ (@article_pages@)
      <dd>(@publication_date@) - "@article_abstract@"

This template would be expanded into:

Dog's Life - Planet of the Dogs (pp 50-52)
(January 1, 2100) - "They used to say that every dog has his day. Little did humans know that the collapse of their society at the beginning of this millennium would give rise to a new golden age of canine rule."

Hyperlinks to external publications and articles are inserted automatically and optionally tracked using the clickthrough module, currently under development in ACS4.

Permissions

With the ACS4 permissions model, the press administrator need no longer be identical to the site administrator. The application now has a hierarchical set of permissions which can be assigned to any party as needed. The press root privilege is press_admin which comprises press_create, press_delete, press_approve, and press_read.

By default, press_admin inherits from the site-wide admin. The press_read permission is assigned to the public so that all users, including non-registered users, have access to /press/. Currently, the press_create permission is unassigned by default and left commented out of the data model. Uncommenting it would assign the privilege to create a press item to the context of registered users, if this is a desired policy. Approval of uploaded items, however, is still reserved to the press_approve permission which is exclusively possessed by press_admin. Changing those permissions in /permissions/ enables the site-wide admin to tailor a permission hierarchy to the needs of an individual site, e.g. sharing the Press Administrator duties among more individuals, or enabling certain persons to create press items.

VII. Legal Transactions

User Pages

Press Administrator Pages

VIII. API

Much of the API is covered in the press-create.sql file. The package body press and package body press_revision hold many of the most interesting PL/SQL functions and procedures: Also of interest are the Tcl procedures which are largely wrappers for the PL/SQL functions and procedures and are located in the /tcl/press-procs.tcl file:

IX. User Interface

Users have a limited set of pages available to them. Administrator user pages are located in the /press/admin directory. The acs_privileges of press, along with the permissions on the admin directory, determine which parts of the pages are visible to which user types. Links for administer and create press item only appear for those parties possessesing the appropriate privileges. Users not authorized to view the index page - parties who were denied the press_read permission - receive a not-too-unfriendly "You are not allowed to see this page" message. The code looks like: 
# Display unauthorize privilege page if user is anauthorized
if { ![ad_permission_p [ad_conn package_id] press_read] } {
    ad_returnredirect unauthorized
    return
}

Press Administrator

The press gateway serves by default the DisplayMax number of press items or archived press items. The rest of the items can be viewed with a paging mechanism at the bottom of the page. The archived items | live items link appears, respectively, if such exist. Each item is rendered through its individual template, i.e. the index page can be heavily modified to match a site's appearance.

For users with the press_admin privilege, two links appear on the right side of the page, one to "administer" and one to "create a press item". The other pages are restricted to the press_admin, except the item-create** suite which is restricted to press_create.

The administer page shows a table of the active revisions of all press items. The active revision need not coincide with the live revision. Press items can have the status of:

Additionally, the archive status is shown if an item is approved. The archive status is either a fixed date in the future after the release date or null for permanently live items.

The administer page offers the option to archive, make permanent, or delete one or more items at once.

The one-item-admin page is accessed via links from the administer page. Revision administration is handled via one-item-admin page.

X. Parameters

The press application has three customizable parameters which must be set for each package instance.

DaysUntilArchive
how many days after being released until a press item goes into the archives
DisplayMax
how many items are shown on the index page (for live and archived items)
ClickThroughP
whether or not Hyperlinks should go through the click-through module

XI. Acceptance Tests

You should test adding, viewing, editing, changing revisions, changing status and deleting a press item:

XII. Future Improvements/Areas of Change

XIII. Revision History

Document Revision # Action Taken, Notes When?(mm/dd/yyyy) By Whom?
0.1 Creation 12/08/2000 Stefan Deusch
0.2 Proofreading 12/11/2000 Sarah Barwig
0.3 More proofreading 12/14/2000 Josh Finkler
0.4 Clarified PL/SQL functions 12/14/2000 Sarah Barwig
0.5 Light final edit 12/18/2000 Josh Finkler
0.6 Clarified UI and press_admin functions 01/11/2001 Sarah Barwig
0.7 Final pass edit 01/12/2001 Josh Finkler