News Design Documentby Stefan Deusch
- User directory: /news/
- Tcl procedures: /tcl/news-procs.tcl
- Requirements document: /doc/news/requirements.html
- Data model: news-create.sql , news-sws.sql
II. IntroductionMost 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 ConsiderationsNews 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 AnalysisThe 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. DesignPublished 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
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. APIMuch 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 existing news item (not used)
- news.revision_activate: make a revision the active revision
- 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 DiscussionThe News application makes use of the existing 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:
- 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.
PermissionsWith 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
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.
- 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 InterfaceThe 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 site-wide
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
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)
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-SearchFollow the setup instruction in site-wide-search and read the design doc. You have to follow specifically these steps:
- download and install acs-interface from www.arsdigita.com/acs-repository/
- download and install site-wide-search from www.arsdigita.com/acs-repository/
- restart server
- run SQL setup script for site-wide-search, specifically sws-package-all.sql, by hand.
- cd into news/sql and source news-sws.sql
- mount site-wide-search, e.g. under /search - an instance must be mounted for each package you intend to have search functionality
- if you want to search your items immediately, you must compile
the index manually - otherwise it is scheduled to run every 2
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:
- drop news, and source news-sws-drop.sql
- source site-wide-search/sql/content-revision-sws-drop.sql
- source sws-package-all-drop.sql
X. General CommentsThis 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. ParametersThe 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 release 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 TestsYou 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.
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 one 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. AuthorsPlease mail suggestions or bug reports to Stefan Deusch
XV. Revision History
|Document Revision #||Action Taken, Notes||When?(mm/dd/yyyy)||By Whom?|
|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|