Forum OpenACS Q&A: Re: Current state of theming in OpenACS (without .LRN)

I've read through all this very carefully but there's something I'm still not clear about.

Is it possible to create a custom theme for the default 'Main Site' instance of subsite, without having to mount another subsite?

What I mean is, the instructions seem to require that you either create a new subsite package and mount it as a new subsite, or that you uninstall, modify, and re-install a subsite that already exists. Can you do this for the default 'Main Site'?

Alternatively, should you just mount a new subsite as per Dave's instructions, and then delete the original default subsite called 'Main Site'?


Posted by Dave Bauer on
You can theme any subsite including the main subsite by setting the theme
parameters of the subsite instance.

You can convert the main subsite into a dependent subsite package type, if
you need to modify the behavior of the subsite but not to just change the
master template and css.

Ok, after experimenting all is now clear.

In Dave's instructions there is a step in which you 'Convert' an existing subsite to a new type - the type that you have just created the package to define.

The option will appear under 'Main Site Administration' at ./admin/ once your new subsite 'type' has been installed. This would seem to be analogous to sub-classing the acs-subsite package, and once a new sub-class is installed and available, the option to change an existing subsite to be of this new type is presented.

The word 'dependent' appears in the above instructions, which confused me when initially reading through. The option to select is actually:

"Convert to Descendent Subsite type".

Descendent in this context makes more sense.

I hope this helps someone.


Thanks Dave, I posted my second message before seeing your reply, which makes things much much clearer.

Because the thread title mentions re-theming, it looked as if you had to create a 'descendent subsite type' to activate a new theme.

This makes much more sense now.

The need to customise styling and templates is obvious to me, but it would help to understand an example use case of why people might typically need to make code customisations to acs-subsite?

(On the question of language, is it 'dependent subsite' or is it 'descendent subsite' as in the message key for the 'Convert to Descendent Subsite type' option? Only words, but potentially confusing.)

Does this facility allow for encapsulated customisation of any OpenACS package that implements subsite? So if you wanted to add custom code to xowiki for example, could you create a new package that extends acs-subsite and inherits from xowiki?


I am trying to extend Xowiki as an example of encapsulating customisations of css and templates, but I cannot seem to figure this out.

I have created a new package 'Customised Xowiki', OpenACS Core = No, Singleton = No, Implements Subsite = No, Inherits Templates = Yes.

I have mounted an instance of this application, gone to 'Dependencies and Provides', added xowiki version 0.144 to Services Extended by this package. What I get as a result is a working, empty xowiki that uses the standard xowiki templates and style sheets.

I have added a new style sheet in ./www/resources/ and put a modified view-default.adp in the ./www/ of my custom package directory, but the request processor is still delivering the original xowiki template and styles. I expected the RP to fall-back to the standard xowiki files only if I had not provided replacements

What am I doing wrong?


Posted by Dave Bauer on
Check out the URL of the css files that are used.

They most likely look like


So in this case the request processor is looking directly under the xowiki package

In general packages should not be providing a lot of css ad it should be consistent at the site/subsite theme level.

In your case what you need to do it either

Add a new css file that loads after the xowiki css file and overrides those styles.
Modify xowiki to allow somehow specifying an alternate css file (or maybe this feature is a setting already?)


Thanks for the reply. Yes the request processor is looking at /resources/xowiki/ which I was expecting not to happen having extended the package.

Is what I did supposed to work? I mean, would it work with other packages - did I attempt the right thing?

I am still slightly foggy on exactly what should be done for each use case.

So in summary:

1) To create a new theme where you can specify your own versions of the master templates, css and adp/tcl pages, make a duplicate of openacs-default-theme, modify, point subsite parameters and go!

2) To create a descendant package that inherits from and extends acs-subsite, create a new package using the package manager according to DaveB's instructions earlier in this thread (though I'm now not clear exactly why you'd ever need or want to do this).

3) To create a customised/re-styled version of any OpenACS package, create a new package using the package manager that extends the application you want to customise (i.e. forums) and inherits templates from it. I thought that this would allow me to put css and adp/tcl pairs into the new package directory that would be served up in preference where they exist, but when I experimented using xowiki it didn't happen. I am therefore not clear why you'd ever want to do this either.



Posted by Dave Bauer on
The request processor doesn't understand the last part that you have here:

3) To create a customised/re-styled version of any OpenACS package, create a new package using the package manager that extends the application you want to customise (i.e. forums) and inherits templates from it. I thought that this would allow me to put css and adp/tcl pairs into the new package directory that would be served up in preference where they exist, but when I experimented using xowiki it didn't happen. I am therefore not clear why you'd ever want to do this either.

It can not rewrite the content of the script/link tags that xowiki puts into the package. Xowiki does a lot of templating and other things that don't quite fit into the rest of OpenACS. For example.

Your package can use a local master template for all that packages pages and add the required css/js etc in that master which then goes up to the subsite master template.

You could also just put template::head calls in the individual pages (probably xowiki is doing something like this). You'd need to extend/override the code in xowiki that is setting the path to the css file. Again, maybe there is a setting for that.

The request processor only looks in the package dependency tree for regular requests under www for tcl/adp pages. The resources filter does not (its supposed to be simple and quick and not do any database or permission hits.)

I haven't run into this issue yet myself, I usually set all the CSS at the subsite level so its consistent across all the packages under the subsite.

......aha! Which explains the use-case for option 2. So to have styles that apply to all child nodes of a subsite node, you have to extend acs-subsite, otherwise, if you only do step 1, your custom theme applies universally.

Finally got it.

So the conclusion to that is that for customising themes, every site should really be under a subsite node which is a child of the default 'main-site' subsite node.

Thanks for explaining.


Posted by Dave Bauer on
Hmmm, you should not need an extra subsite package _under_ the main subsite unless that is a specific organization you need for your application.

For theming all you need is to apply the themes correct styles and master template in the package parameters for the main subsite. In this case there is no need to create a descendant acs-subsite package type at all.

You only need a descendant package type if you want to modify the behavior.

In either case, there isn't any reason to put your content under a second subsite.

You can either

1) Edit the parameters in the Main Subsite to point to the resources in the appropriate theme location. This has always been the case, the theme packages are just a way to encapsulate the styles and master templates in one place.

2) Edit the parameters as mentioned in #1 and convert the main subsite to a descendant package type if you want to modify the behavior of the subsite. Every web site I work on now uses this technique since the default openacs UI for acs-subsite is less than ideal, and certainly is not specific enough to meet most custom applications requirements.

Ah, yes. Ok. Thank you very much Dave.

So if you want to change the underlying queries in support of modified or changed tcl pages, converting a subsite into a descendant package type would enable you to do this. It would also allow you to export your customisations as a package so that in future you could install it on top of a default OpenACS, conveniently adding back your own customisations.

Initially I couldn't think of why you'd want to modify the behaviour of acs-subsite beyond changing the templates.

If you want to customise an existing application then I guess the best way is to create a new package, and copy the code from the one you want to modify! :-)


Posted by Jim Lynch on

Several things combine to form this whole theming thing:

1, subsites have these parameters that let you set where the subsite should look for the css and the whole template for every page

2. if you make your own package you want to add theming to, it can extend subsite, then you will notice it has some parameters, that look a lot like subsite parameters. Then, you would copy openacs-default-theme and point the theming parameters at your copy; editing the files inside the copy will only affect your package and its children.

3. if you want a subtree of your site to look different than the parent of that subtree, you can put a subsite there and adjust the theming parameters.

4. if you want the whole site to look different, you can either alter files in openacs-default-theme to suit, or you can make a copy of openacs-default-theme and adjust the main site's theming parameters so they point at your new theme and then edit the files in the copy.

In my case, I notice the site-node map which can tie domain names to subsites, and also notice that if I do a site that way, I might want to theme it separately, so my app extends subsite, and it has its copy of openacs-default-theme.

Posted by Jim Lynch on

I noticed a couple things about openacs-default-theme...

First, in tcl/apm-callback-procs.tcl, the func in there called openacs_default_theme::install::after_install and at the ehd it sets some default settings. When I xopy the package, these settings cause the defaults to point at the copied package.

Second, openacs-default-theme (and all its copies) doesn't have a complete copy of the theme, for example blank-master and some stuff related to lists and forms.

Should I create a new theme package, which is the one copied by my script, which has all the files in the theme, and does not have the default settings when the package is installed?

Any other comments you might have on this?


Hi Jim,

1. In your copy of openacs-default-theme, rename the function to something like my_new_theme::install::after_install and find/replace this function throughout the package copy. There are also some calls within this function that need to be updated before installing the package.

2. blank-master should only exist in one place for the whole instance, so its absence in the theme is by design. Your own templates combine with the blank-master. See openacs-default-theme for an example. If you want to branch the css files for lists and forms, places them in my_new_theme/www/resources/styles and add the path in your ThemeCSS theme package parameters. Alternate form templates can be placed in the theme and referred to in the formtemplate tag as style=/path/to/template.

Yes, once you have copied and updated openacs-default-theme, you will definitely want to install this new package.

If you need an example of a customised theme package, let me know.


Posted by Jim Lynch on
Heya Ryan!

the script I wrote is already doing (1), and also making sure package key, pretty name and pretty plural are unique within the openacs instance. It uses an xml parser (tdom) on the .info file, and it reads that file, finds the stuff that matches the old package name (likely and currently only openacs-default-theme) and replaces it in the tdom tree, which I then write back out.

Please check it out, a reference to the git repo is in this thread somewhere. I have tested packages copied by my script, and they are working fine; the default setter in the callback being a minor inconvenience and I want input to see if other people think it's not so minor.

About (2), on blank-master, I was thinking that since it contains the outer stuff (doctype and <html ...> ... </html>) one could be motivated to alter it as newer versions of html may require different things, and I may be motivated to preserve the original.

Yes! I would love to see a theme! I am also interested in documenting the existing css classes in a refcard-like format.




Thank you very much. That is exactly the explanation I needed.


Posted by Jim Lynch on
You're welcome; I wanted to go out one level and cover the material and do so in a way that would let you do whatever you wanted
Posted by Dave Bauer on
For CSS I suggest throwing out everything except the forms and list CSS.

Use something like (there are plenty of other HTML5/CSS frameworks). I did this on my latest theme and its great!

Posted by Dave Bauer on
For acs-subsite, basically I put the entire web site under acs-subsite.

For example, for a simple web application, I'd put all the custom user interaction under my new subsite package and extend or override any subsite features to make them simpler or more specific for my application.

OR for a complex web site, I might have many subsites all with different descendant subsite types. In this case each sub-application has its own set of users etc so using a subsite makes sense. Again everything is put into the subsite derived package.

I generally don't use any existing application packages as they all contain too many assumptions or are just a huge set of switches which makes it very difficult to meet precise demanding user requirements. I just build all new data collection forms and displays and lists using the existing core features. It is kind of hard to explain in a forum post :) This mainly is due to the extremely unique requirements of my remaining OpenACS users.