News Design Document

by Stefan Deusch

I. Essentials

II. Introduction

Most Web services and almost all corporate sites have a company.com/news/ service. These can be used in a variety of ways, e.g. for advertising or dissemination of related news items. News items are such that they cease to be news after a while. When this happens, these news items should automatically disappear into the news archives without further administrator intervention. The News application supports site-wide news coverage - appropriate when one ACS installation is being used for a company - and subcommunity news coverage where several organizations are using the same ACS server

III. Historical Considerations

News applications previous to ACS 4 were less integrated into the site and had less functionality. This version scopes instances implicitly through use of the acs-permissioning system. The old news allowed to edit the items, the new one allows version control. The administrator can switch back to a historic version of a news item.

IV. Competitive Analysis

The News application is consistent with the functionality of similar systems on the Internet. It is built with ACS 4 and relies on the object oriented nature of ACS 4. It is best used in conjunction with other ACS applications such as general-comments, site-wide-search, and file storage.

V. Design

Published or archived news items are presented as entries in a hyperlinked list. Single news items are presented by taking advantage of the ACS Templating system. The default news template is in the file news.adp which takes as input. Publishers may wish to provide their own templates, however even more flexibility can be introduced by supplying the news body in HTML format. If someone submits a news body with inconsistent HTML tags, the News application attempts to close these tags in the preview page.

The news body can have a MIME format of "text/plain" or "text/html". Using HTML, the publisher can hyperlink images, audio- and video files into the publication body from other sites or from the local file storage module. This way, the news application does not need its own content management. For instance, one can download and install the ACS4 file-storage module from the acs-repository, upload some photographs in gif or jpeg format, and then link it into the HTML news body, somewhat like this: <img src="http://myserver.org/file-storage/download/Fig1.gif">

If someone submits a news body with inconsistent HTML tags, the News application attempts to close these tags in the preview page.

VI. API

Much of the API is covered in the news-create.sql file. The news package body holds all of the PL/SQL functions and procedures. The Tcl procedures are, see /tcl/news-procs.tcl file.

VII. Data Model Discussion

The News application makes use of the exisiting ACS Content Repository service. A news item consists of a row-entry in the table cr_item, where all of the meta-information that isn't already stored in acs_objects concerning these items is placed, one or several rows in the revision table cr_revisions, and a custom table, cr_news, which holds the remainder of the information necessary to describe a news item. cr_news items are children of cr_revision items. 
create table cr_news (
    news_id                     integer
                                constraint cr_news_id_fk references cr_revisions
                                constraint cr_news_pk primary key,
    -- include package_id to provide support for multiple instances
    package_id                  integer
                                constraint cr_news_package_id_nn not null,      
    -- regarding news item
    -- *** support for dates when items are displayed or archived ***
    -- unarchived news items have archive_date null
    archive_date                date,
    -- support for approval
    approval_user               integer
                                constraint cr_news_approval_user_fk
                                references users,
    approval_date               date,
    approval_ip                 varchar2(50)
);
Note that different package instances of the News application can be distinguished by the column 'package_id' (and not by the inherited context_id in acs_objects). We therefore need only a single cr_folder named 'news' to hold all news items.

The data model in the context of the content repository are further characterized by following:

A reminder to the column release_date is necessary here: Its granularity is only one day, i.e. the relase date is for instance 2001-01-01 00:00 (always at midnight). If someone wants to present a view of 'new items' since last login (which can be more than once since 00:00), one can use cr_news.approval_date for differentiating since this is time-stamped by sysdate.

Permissions

With the ACS4 permissions model, the news administrator need no longer coincide with the site administrator. This need only be the case right after installation. The News application has a hierarchical set of permissions which can be assigned to any party as needed. The news root privilege is news_admin which comprises news_create, news_delete, and news_read.

By default, the news_admin permission inherits from the site-wide admin. The news_read permission is assigned to the public so that all users, including non-registered users, have access to /news/. By default, the news_create permission is assigned to registered users. However, they can only submit a news items, but not approve it. Approval requires news_admin privilege or can be set to take place automatically by setting the parameter ApprovalPolicy to 'open'. The news privileges can be changed in /permissions/ by the administrator on the /news/admin/index page. The needs of an individual site, e.g. sharing the news administration duties among several individuals, are thus covered.

Legal Transactions

User Pages

News Administrator Pages

VIII. User Interface

The publicly accessible pages are in the root directory of the mounted instance. The administrative pages are in /news/admin/. No privilege check is needed in the news/admin/ directory.

The corresponding links for Administer and Create news item only appear for parties which possess the appropriate privileges. Viewers not authorized to view the index page (i.e. parties who were denied the news_read permission) are shown the the site-wide 'not-authorized' template.

The news gateway defaults to serving the parameter DisplayMax, see sec. XI below, number of news items or archived items. The rest of the items can be viewed with a centered paging link at the bottom of the page. The link archived items | live items appears if such exist.

The /admin/index page shows a table of the active revisions of each news item. News items can have the status of:

The /admin/index page has a dimensional slider to select items with the corresponding status. To each selected view, a SELECT box with allowable operations (on the items checked at their checkbox in the first column of the table), is shown. For example, bulk-archiving and deleting of published items can be effected in this way. For archived items, one can re-publish or delete them.

Note, that releasing/revoking can be done for an item individually as well, following the ID# link in the second column which leads to /admin/item. On that page, a new revision can be added. There is no UI to edit a revision; A new revision must be accompanied by a revision log string to describe the changes. The /admin/item administration page shows the audit history of an item in a similar format as that of the files shown in cvs.arsdigita.com. be added.

Function of the archive date: The archive status is either a date in the future after the release date or null for permanently live items.

IX. Making News Searchable with Site-Wide-Search

Follow the setup instruction in site-wide-search and read the design doc. You have to follow specifically these steps:
  1. download and install acs-interface from www.arsdigita.com/acs-repository/
  2. download and install site-wide-search from www.arsdigita.com/acs-repository/
  3. restart server
  4. run SQL setup script for site-wide-search, specifically sws-package-all.sql, by hand.
  5. cd into news/sql and source news-sws.sql
  6. mount site-wide-search, e.g. under /search - an instance must be mounted for each package you intend to have search functionality
  7. if you want to search your items immediately, you must compile the index manually - otherwise it is scheduled to run every 2 hours. 
         begin
  	sws_service.update_content_obj_type_info ('news');
  	sws_service.rebuild_index;
     end; 
     /

To drop an instance of the News application correctly, follow these steps:

  1. drop news, and source news-sws-drop.sql
  2. source site-wide-search/sql/content-revision-sws-drop.sql
  3. source sws-package-all-drop.sql
As can be seen from the function news__sws.sws_req_permission each searchable item requires an access permission. For users with the privilege 'news_admin', no permission (null) is required and all available revisions are searched as well. For all other users a 'news_read' permission is returned on the published revision, i.e. search results from the live revision (even though they might already be archived). The search results, shown in the mounted directory of site-wide-search, don't distinguish between 'live' and 'archived' items.

X. General Comments

This release allows general comments using the general-comments package. The policy of general comments is determined by the parameter SolicitCommentsP, see below. In order to work correctly, the general-comments package has to be installed and mounted first. Comments are only shown on the public pages, i.e. on /news/item.tcl. No comments are shown on the /news//admin/ pages. For administration of comments, one has to go into the site-wide general-comments package.

The most important integration of the comments facility is reflected in the news.delete procedure of the package news. Before the news item is deleted, all possible dependent comments including picture attachments are dropped.

XI. Parameters

The news application has three customizable parameters which have to be set for each package instance through the site-map manager.

XII. Acceptance Tests

You should test adding, viewing, editing, changing revisions, changing status and deleting a news item: Uploads of up to 10.000-character news items was tested successfully. HTML uploads appear correctly. However, some HTML tags are filtered site-wide against malicious spamming. The site-wide admin can turn them on/of at setting ACS Kernel parameters at ACS Kernel [set parameters].
Pure text uploads preserve their formatting from the textarea - a <pre> tag is wrapped around. That way the textarea for entering the news body is used as a formatting editor.

XIII. Future Improvements

XIV. Authors

Please mail suggestions or bug reports to Stefan Deusch

XV. Revision History

Document Revision # Action Taken, Notes When?(mm/dd/yyyy) By Whom?
0.1 Creation 12/20/2000 Stefan Deusch
0.2 First pass edit 12/24/2000 Josh Finkler
1.0 Alpha Release ready 1/24/2001 Stefan Deusch
1.1 Minor revisions, restructuring of sections 1/25/2001 Josh Finkler
1.2 Alpha release wrap up 1/25/2001 Stefan Deusch