Writing an ACS Module

part of the ArsDigita Community System by Tarik Alatovic
Note: As of ACS 3.3, this document is obsoleted by the ACS Package Manager

The Big Picture

An ACS module is a self-contained subsystem delivering a service visible to the end-user. From a programmer's point of view, it is a collection of sql table definitions supported by HTML interface generated by a scripting language such as Tcl. In order for a module to become a part of ArsDigita toolkit, it must implement common and reusable functions. Examples of modules in the ArsDigita toolkit are News, Bulletin Board, Address Book and Ecommerce.

Module Implementation Checklist

Module Architecture

Module Documentation

Every module should have its documentation in HTML format in the /doc directory (e.g. /doc/faq for faq module). This documentation is primarily intended for programmers and should be brief and technical as necesssary. It should list the features that this module provides, explain purpose of the module, possible uses and discuss design decisions. For good example of documentation, take a look at Chat Module Documentation.

Module Customization

A good, reusable module will be used in many ArsDigita installations and it may be required to perform a slightly different funcionality then the default one. A way to customize a module, so that it can be configured to support several different modes of operation is through usage of parameters. There are two levels at which the module can be customized: module and instance level.

Module Scoping

Standards for module scoping have been introduced in ArsDigita toolkit release 3.0. Before this release, very few modules supported scoping. For example, the address book module provided an address book instance for each user

ArsDigita standard defines three scopes: public, group and user.

Notice that scoping makes sense only for the modules supporting multiple instances, since scoping concept applies only to the instances of the module and not the module itself. In order to support scoping, your data model should include columns: scope, user_id and group_id in the table where module instances are defined. If user scope is not supported, then you don't need to have user_id column, and if group scope is not supported then you don't need to have group_id column. Here is the example of the faq data model, which supports scoping:
create table faqs (
	faq_id		integer primary key,
	-- name of the FAQ.
	faq_name	varchar(250) not null,
	-- group the viewing may be restricted to 
	group_id	integer references user_groups,
	-- permissions can be expanded to be more complex later
        scope		varchar(20),
        -- insure consistant state 
       	constraint faq_scope_check check ((scope='group' and group_id is not null) 
                                          or (scope='public' and group_id null))
);
Notice that faqs don't support user scope, so user_id is ommited and faq_scope_check restricts scope to public and group only.

Module Integration

If module supports multiple instances and scoping, you can decide to implement ACS interface for associating module with groups and users (i will refer to modules implementing this interface embeddable modules). Examples of embeddable modules are faq, news and address book module. Embeddable modules can be easily associated with groups through admin user group pages in /admin/ug. There are two steps in making an embeddable module: Finally, to see your embeddable module work, you should create a test group and associate module with that group through files in /admin/ug. For Novice Photographers group, faq module public pages will be located at /groups/novice-photographers/faq and faq module administration pages at /groups/admin/novice-photographers/faq. For more information on associating embeddable modules with user groups, take a look at User Groups Documentation.
tarik@arsdigita.com