## News Design Document

by Stefan Deusch

### I. Essentials

- User directory: /news/
- TCL procedures: /tcl/news-procs.tcl
- Requirements document: /doc/news/requirements.html
- Data model: news-create.sql , news-sws.sql

### II. Introduction

Most Web services and almost all corporate sites have a comany.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

-     @publish_title@

-     @publish_body@

-     @creator_link@

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.

- news.new: creates a new news item
- news.delete: deletes a news item
- news.make_permanent: removes archival date from items
- news.archive: archives items with a default date of now
- news.set_approve: approves or revoked submitted items (for use when the general public can submit news items). Approving means setting the publish date.
- news.status: returns info as to permanent, when it will archive, when it will be released
- news.revision_add: add a new revision to an existing news item
- news.revision_delete: delete a revision from an exisiting news item (not used)
- news.revision_activate: make a revision the active revision

The TCL procedures are, see /tcl/news-procs.tcl file.

- news_items_archive: archives items at a certain date
- news_items_make_permanent: removes archival date from items
- news_items_delete: deletes news items

### 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 futher characterized by following:

- The items are assigned to the folder 'news' in the content repository.
- The PL/SQL API provides procedures and functions to create, delete, approve, archive, query, release, or revise a news item.
- A new revision generates an entry in cr_news and cr_revisions in parallel and updates the live_revision in cr_items.
- The release date is stored in the publish_date column of cr_revisions,
- The archive_date is supplemented by cr_news.

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

- View published news item list: index?view=active
- View archived news item list: index?view=archive
- View one news item: revision
- Preview one news item before publishing/approving: preview

#### News Administrator Pages

- View one news item with administrative information: admin/revision
- Administer news items: admin/index
- Administer one news item: admin/item
- Add/suggest a new news item: item-create
- Edit existing news coverage by adding a revision: admin/revision-add
- Archive existing news coverage: admin/process?action=archive
- Make permanent existing news coverage: admin/process?action=make_permanent
- Approve existing news coverage: admin/approve
- De-activate existing news coverage: admin/revoke
- Delete existing news coverage: admin/process?action=delete
- Set one revision the active one: admin/revision-set-active

### 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:

- unapproved (only if a non-news-admin uploaded something), the news_admin is approved automatically
- approved and awaiting release
- published (= approved and live)
- archived

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 inlcuding 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.

- ActiveDays...number of days between relase and archival
- DisplayMax ... how many items are shown on the index page (valid for live and archived items)
- ApprovalPolicy...[open|wait] if open, submitted items are approved immediately, wait means approval by the administrator.
- ShowSearchInterfaceP...[0,1] whether we show a 'Search Box' for searching news items with site-wide-search (must be installed).
- SolicitCommentsP...[1,0] whether we allow comments on a news item or not

### XII. Acceptance Tests

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

- Go to /news/ and click on the Administer link.
- Add a news item
- Verify that the item shows up on the admin side and the user side with the correct number of days left for display.
- Verify that the new revision is active, and that it is displayed on the user side.
- On the admin side, archive the item.
- Ensure that the user now sees it as an archived item.
- On the admin side, make the item permanent.
- Ensure that the user now sees it as a live item.
- Delete the 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

- Use e-mail notification on submission and release, such as supplied by ACS Notification in PL/SQL only.
- Allow for more MIME types, especially Microsoft Word, and use the corresponding Intermedia filter to render as HTML.
- Add news categorization to the data model that allows to order news articles by categories without creating new application instances (e.g. sports, education, health, literature, music , politics, ...) - this also needs a UI to create categories and a mapping table.

### 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