Customizations of existing packages is a diverse topic and many ways lead to Rome (so to speak). The following suggestions are based on my own experience and the discussions happening at Openacs.org http://openacs.org/forums/message-view?message%5fid=1101258 .
A couple of packages in OpenACS already have parameters to allow you to define the location of a certain include to use for pages. I will describe here the most important ones.
If you would like to have an existing page in a product package customized you can create a parameter on your own. You should ask yourself the question though, how often such a modification will happen in environments not unique to you. This is due to the fact that the parameters will be checked by the product owners and therefore drive you away from the core development and make upgrades more difficult.
In the acs-subsite package we have parameters to deal with login, registration and display of user information. The default files all reside in acs-subsite/lib directory and this where you should copy them from. This is where you most likely want to get some modifications as they are pretty core to each website:
- LoginTemplate: The login template is the include which is being displayed for the login page of the user. Most likely you would not want to ammend that except to give it a different layout, but you could e.g. provide a dropdown of quick urls where the users will go to after login
- UserNewTemplate: The new template is used during the registration process. This is where you can query additional fields about the user when they need to signup. It is also the place to add users automatically to groups or redirect to other URLs.
- UserInfoTemplate: Once you have given added new fields the information page about the user needs to be ammended as well to display this additional info.
- UserHomeTemplate: This is the template for the users home page (/pvt/home).
- EmailConfirmTemplate: This template is used for the confirmation of the users e-mail. It gives you the ability to have a special thank you for signup page which executes a lot more code than just confirming the E-Mail address of the user.
The following provides an overview of the most important parameters in OpenACS which you most likely want to customize.
- DefaultFormStyle: This is the default style for the forms on your site. Useful if you use custom CSS tags for the forms. With the latest changes to OpenACS the need for custom Form Styles should be significantly reduced though
- DefaultListStyle: This is the default style for the lists on your site. With the latest changes to OpenACS the need for custom List Styles should be significantly reduced though
- DefaultListFilterStyle: This is the default style for the list filters. This is pretty useful if you want to e,g have your filters be a drop down boxed menu instead of links. But you can achieve other things with it as well.
- DefaultMaster: The default master is the template which is being used on each page of this subsite. It should have been changed to /packages/service_name/templates/service_name in the [ layout setup ] .
- DefaultFormStyle: This is the default style for the forms to use in this subsite. This overwrites the parameter in acs-templating but can be overwritten by the definition in the form tag. With the latest changes to OpenACS the need for custom Form Styles should be significantly reduced though
- DefaultListStyle: This is the default style for the lists to use in this subsite. This overwrites the parameter in acs-templating but can be overwritten by the definition in the list tag. With the latest changes to OpenACS the need for custom List Styles should be significantly reduced though
- IndexRedirectUrl: A URL to redirect to instead of showing the subsite index page. Useful if you want to replace the index page with a page generated by portals, by edit-this-page, or to one of the applications installed at the subsite.
One additional method for customization of existing packages is to write callback implementations for callbacks defined in the packages.
A callback is a method which lets you execute custom code in a certain place. This is done by defining a callback hook in the location where the callback should be executed. That part is usually done for acs-core packages and adding a new callback requires a TIP. If you want to add callbacks to your own product packages, make sure to document them well and be very clear why you want to have the callback hook in a certain place.
Once the code is run all implementations of a callback are executed at the callback hook. Common callbacks are the callbacks for incoming e-mail processing, the search callbacks and the parameter change callbacks (which are executed when a parameter changes). For a list of callbacks in your system search for "callback::". This will also give you the list of implementations.
In case all the methods above fail we have to "subclass" packages. The idea here is to create a package that keeps your customizations of a product package, without you having to copy over all customizations manually.
The way to achieve this is first to create your custom package. Let's call it "service_name-forums" as we want to customize the forums package. Once the package is created the only thing you need to do right away is to write an index.vuh which makes an internal redirect to the forums package files.
set test test
(Matthew, please fill it in above).
In the event you want to "subclass" a singleton package which is usually mounted under only one mount point, there is one addition trick
Any file which resides in /www (so not /packages/.../www) will be served before querying the package. This means, that /www/register/login.tcl will be served before / instead of /packages/acs-subsite/www/register/login.tcl
Now let's assume you want to change /acs-admin/www/admin/become.tcl to make an additional permission check for special sysadmin privileges. The easiest way to do that is to create /www/acs-admin/admin/become.tcl and make your changes there.