This is a detailed design document for package News. This package is
an enhanced version of ACS3.4 News module.
This document includes the following:
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.
Top
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 parameter
A 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.
- news_is_admin_p
This proc takes two parameters
If the user is an admin for the newsgroup,
then 1 is returned. Otherwise, 0 is returned.
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 parameters
- user_id
- newsgroup_id, optional
This 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.
If the user is a site-wide admin, then "Post" is returned.
- news_newsgroup_id_list_view
This proc takes one parameter
This proc returns a list of newsgroup_id's this use has view priviledge of.
- news_newsgroup_id_list_post
This proc takes one parameter
This proc returns a list of newsgroup_id's this use has post or
suggest priviledge of.
- news_newsgroup_id_list_admin
This proc takes one parameter
This proc returns a list of newsgroup_id's this use administers.
If the user is a site-wide admin, then newsgroup_id of all
enabled newsgroups are returned.
- news_header
This proc takes two parameters
- title
- newsgroup_id, optional
If 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.
- news_footer
This proc takes one parameter
If 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.
- news_get_latest
This proc takes three parameters
- num_items, optional defaults to 1
- list_p, default to 0
- newsgroup_id, optional
The 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.
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:
- user_id
- group_id (optional)
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
- 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.
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
Depricated Procs
These procs are no longer being used.
Top
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.
Top
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.
Top
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.
Top
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. But
in many places like portal pages, /groups/.../news pages, there are links
pointing to /news/admin/post-new. For ad.com site, I have changed the links I
found to the correct location /news/post-new. But there might be other places
referfing to /admin/news/post-new, so I decided to created a post-new file
under /news/admin/news, and have it redirect to /news/post-new.
- /news/index.tcl
Inside one registered proc for /groups, there is a "cd /www/news" statement.
While the request processor knows to direct url "/news" to /packages/news/www,
this statement would fail without seeing a physical directory of /www/news. So
instead of removing all News module files, directories, I have to keep the
/news directory, and have an index.tcl file there which redirect to "/news".
- /intranet/ad-index.tcl
This is the only file outside /package/news that I have changed to list 10
most recent news items.
- Portals
I used /admin/portals page and edited the portals code for News.
Top
VIII. Revision History
