I. Introduction
Other docs of this package This is a detailed design document for package Enhanced News. This package is an enhanced version of ACS3.4 News module.
This document includes the following:
- Date model
- Tcl procedures
- User pages
- Newsgroup admin pages
- Site-wide admin pages
- Implementation Notes
- Revision history
II. Data Model
The original data model of the News module is used. More columns have been added for addtional features. An upgrade sql script (upgrade-from-newsmodule.sql) is available for upgrading from the News module.
-- /packages/news/news.sql -- -- A package to manage news postings/viewings -- -- A table to describe newsgroups create sequence newsgroup_id_sequence start with 1; create table newsgroups ( newsgroup_id integer constraint ng_newsgroup_id_pk primary key, -- if scope=all_users, this is the news for all newsgroups -- is scope=registered_users, this is the news for all registered users -- if scope=public, this is the news for the main newsgroup -- if scope=group, this is news associated with a group scope varchar(20) not null, group_id integer constraint ng_group_id_fk references user_groups, approval_policy varchar(20) default 'closed' constraint ng_approval_policy_nn not null constraint ng_approval_policy_ck check ( approval_policy in ('open', 'wait','closed')), -- group id of the admin group for this newsgroup -- if null, the administrators (role) of this group will be admins admingroup_id integer constraint ng_admingroup_id_fk references user_groups, enabled_p varchar(1) default 't' constraint ng_enabled_p_ck check(enabled_p in ('t', 'f')), -- if 't', then when a member suggests an item, admin group -- members will be notified via e-mail notify_admin_p varchar(1) default 'f' constraint ng_notify_admin_p_ck check(notify_admin_p in ('t', 'f')), constraint ng_scope_ck check ((scope='group' and group_id is not null) or (scope='public') or (scope='all_users') or (scope='registered_users')) ); create sequence news_item_id_sequence start with 100000; create table news_items ( news_item_id integer primary key, newsgroup_id integer constraint ni_newsgroup_id_fk references newsgroups not null, title varchar(200) constraint ni_title_nn not null, sub_title varchar(200), body clob not null, -- is the body in HTML or plain text (the default) html_p char(1) default 'f' constraint ni_html_p_ck check(html_p in ('t','f')), approval_state varchar(15) default 'unexamined' constraint ni_approval_state_ck check(approval_state in ('unexamined','approved', 'disapproved')), approval_date date, approval_user integer constraint ni_approval_user_fk references users(user_id), approval_ip_address varchar(50), release_date date constraint ni_release_date_nn not null, expiration_date date constraint ni_expiration_date_nn not null, creation_date date constraint ni_creation_date_nn not null, creation_user integer constraint ni_creation_user_nn not null constraint ni_creation_user_fk references users(user_id), creation_ip_address varchar(50) constraint ni_creation_ip_nn not null );
Each newsgroup has an entry in table newsgroups. A newsgroup has it's own scope, approval policy and admin group. If the scope is "group", then the members of the user group (as specified by column "group_id") will be the members of this news group. The members of the admin group (as specified by column "admin_group_id) are the admins for the newsgroup. If the admin_group_id is null, then the administrators of the user group ( column "group_id" ) will be the admins for the newsgroup.
Each news items has an entry in table news_items. An item will be displayed to readers when it's approved and the "release_date" become current. It will disappear into "expired items page" on and after the expiration_date. So an item can be in "expired" or "current" state depending upon whether the expiration_date has passed.
An news item is in "pending" state when it's just suggested and hasn't been approved, i.e. the approval_state is "unexamined". The item is in "Rejected" state when the admins disapprove it, i.e. the approval_state is "disapproval". When the approval_state has value "approved", the item is in "approved" state. This is the normal state and won't be marked specially on UI.
III. Tcl Procedures
All tcl procedures are defined in file "news-procs" under /packages/news. All procedures start with "news_".
New Procs
These procs are newly-written ones that don't exist in the News module.
- news_get_admins
This proc takes one parameterA list of user_ids of admins for the newsgroup (can either be members of the admin group, or the admin (role) of the newsgroup if admin_group_id is null)is returned.
- newsgroup_id
- news_is_admin_p
This proc takes two parametersIf the user is an admin for the newsgroup, then 1 is returned. Otherwise, 0 is returned.
- user_id
- newsgroup_id
If the user is a site-wide admin, then 1 is returned.
This proc should call "news_admins" to get a list of admin user_ids.
- news_get_user_priviledge
This proc takes two parametersThis proc returns the priviledge the user has to the newsgroup. The possible values are: "Post", "Suggest", "View" and "". If no newsgroup is passed in, then the highest priviledge the user has to all newsgroups is returned.
- user_id
- newsgroup_id, optional
If the user is a site-wide admin, then "Post" is returned.
- news_newsgroup_id_list_view
This proc takes one parameterThis proc returns a list of newsgroup_id's this use has view priviledge of.
- user_id
- news_newsgroup_id_list_post
This proc takes one parameterThis proc returns a list of newsgroup_id's this use has post or suggest priviledge of.
- user_id
- news_newsgroup_id_list_admin
This proc takes one parameterThis proc returns a list of newsgroup_id's this use administers.
- user_id
If the user is a site-wide admin, then newsgroup_id of all enabled newsgroups are returned.
- news_header
This proc takes two parametersIf no newsgroup_id is passed, then set it to the newsgroup_id of "public" newsgroup. Returns [ad_header $title] for now. But this is a good place for customization. If needed, every single news group can have it's own header.
- title
- newsgroup_id, optional
- news_footer
This proc takes one parameterIf no newsgroup_id is passed, then set it to the newsgroup_id of "public" newsgroup. Returns [ad_footer] for now. But this is a good place for customization. If needed, every single news group can have it's own footer.
- newsgroup_id, optional
- news_get_latest
This proc takes three parametersThe lastest $num_items news items for the newsgroup (as specified by the newsgroup_id) are returned as a Tcl string. If no newsgroup_id is passed in, then news items of all newsgroups are returned. If list_p is set to 1, then only release date and title is returned as list items.
- num_items, optional defaults to 1
- list_p, default to 0
- newsgroup_id, optional
Enhanced Procs
These procs are re-written ones that do exist in the News module but are enhanced. Note, the name, parameter and return type are kept the same as before and can be used the same way as before.
- news_newsgroup_id_list
This proc takes two parameters:Returns the list of newsgroup_ids for this user and group. If the user_id exists (i.e. non zero) then the list includes the registered_users. If group_id is set, then the newsgroup for the group is added (if it exists). if only the user_id is passed in, then return all newsgroup_id for the group she belongs to
- user_id
- group_id (optional)
- news_admin_authorize
This proc takes one parameter:Given news_item_id, this procedure will check whether the user can administer this news item. if news item doesn't exist, a warning page is served to the user. If successfull it will return user_id of the administrator.
- news_item_id
Existing Procs
These procs are taken from the News module without any changes (/tcl/news-defs.tcl). These procs kept for backward compatibility.
- news_new_stuff
- news_user_contributions
Parameteres:Returns list items, one for each news posting
- user_id
- purpose
Depricated Procs
These procs are no longer being used.
- news_item_comments
IV. User Pages
User pages are accessible to all users at url /news.
Main (index) page
This page lists all current and approved news items the user is entitled to see, grouped by newsgroups. This includes all news items of the newsgroups the user is a member of.
Each item contains the following information:
- release date
- title (hyperlinked to "display an item" page)
All items are sorted by release date and the latest one comes first. An item is displayed only if the release date is no later than today, and the expiration date is still a future date. Also the item has to be in approved status.
If the user viewing the page is entitled to post/suggest news items to ANY newsgroups, then a link to "Add an Item" is displayed at the top right corner. if the user viewing the page is also an admin, the a link to "Administer Newsgroup" (linked to newsgroup main admin page) is also displayed at the top right corner.
At the bottom, there is a link to "expired news items".
Expired News Items
This page is similar to the main index page, just display all expired items instead of current ones.
Display a News Item
The page displays the content of an news item.
No admin links are displayed in this page to change approval status, or to edit the item, even the logged in user is an admin. Because there is a page "admin an item" for this purpose.
Add a News Item
This page is the only place to add or suggest a news item, regardless of by whom (users or admins).
This page displays a form to take input from users about the new news item. Only the scope/groups she can post or suggest to are displayed in a select box.
After the form is submitted, the newsgroup of the new news item is checked. If the submitter has the priviledge of posting it, then approval_status is set to 'approved' and the submitter is returned with a message saying the news item will be displayed on the release date. If the submitter only has the priviledge of suggesting it, then the approval_status is set to 'unexamined' and the submmiter is returned with a proper message. Depending upon the "notify_admin_p" value for that newsgroup, an e-mail may be sent to all admins for that newsgroup.
V. Newsgroup Admin Pages
Admin pages are accessible to newsgroup admins and site-wide admins, at url /news/admin/.
Main (index) page
This page lists all newsgroups which have current news items in an ad_table, with information:
- scope (if group, then list group name)
- Total # of current (non-expired) items
- Link to "add an item" (an user page, not admin page) for this group
Then, at lower part, all current news items are displayed in lists grouped by scope/group name. Each news item contains the following:
- Release date
- Title (hyperlinked to "admin an item" page)
- Approval Status in red if pending or rejected
- A link to "edit an item" page
- A link to toggle approval status (between "approved" and "rejected")
At the bottom of the page, there are links to "admin expired news" page.
Admin Expired News
This page is similar to the main index page, but displays expired items. Each item has an edit link but no link to toggle the approval status.
Admin an item
Information like release date, expiration date, and approval status are listed at the top part. Also the link to toggle the approval status, link to edit the item are displayed.
Then Display the title, subtitle and body of the news item just as how it is showed to users in the user page.
Edit an item
Display all fields of an news item in a form. The fields are pre-populated with the existing values.
VI.Site-wide Admin Pages
Site-wide admin pages are accessible to site-wide admins only, at url /admin/news/.
Main (index) page
All newsgroups are listed, including the following info:
- scope (if group, then list group name)
- approval policy (with links to toggle it)
- enabled or not (with links to toggle it)
- admin group name (with links to add/edit it)
- whether e-mail admins when a member suggests an item (with links to toggle it)
At the botton part, provide a link to add a newsgroup
Add a Newsgroup
Display a form to take all the necessary information to add a newsgroup.
VII. Implementation Notes
- /admin/post-new
As part of the effort of cleaning file structures, I have consolidated many files. For example, there were three copies of post-new.tcl under /news, /news/admin and /admin/news. I now only have one copy of it under /news/www.VIII. Revision History
Document Revision # Action Taken, Notes When? By Whom? 0.1 Creation 12/12/2000 Lin Chen 1.0 Revision 12/29/2000 Lin Chen Kyle Nicholls