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

I was supposed to write up documentation for this about 3 years ago, but I stopped doing a lot of OpenACS work and didn't have time.

Recently I upgraded and themed a few OpenACS sites.

Here is what I do.

Install OpenACS 5.7 core.

Create a new package "mysite-subsite" with the package manager. Check of "implements subsite" and go to the package dependencies to specify that this package inherits from acs-subsite.

Copy openacs-default-theme to mysite-theme and find/replace the info files, and everything you can find that references openacs-default-theme. This should be automated, but it's not yet.

Ok go ahead and install those two packages, and go to mysite/admin/ and click Convert to dependent subsite type and choose your new subsite type.

Now go to the subsite parameters and change all of them to refer to your new theme package instead of openacs-default-theme.

Now you can put all your theme related code in mysite-theme and any other custom code into mysite-subsite.

This makes it VERY easy to customize the home page, or any ui elements, admin pages etc. If you don't customize a page, it'll default to the acs-subsite version. If you replace a page in mysite-subsite it'll use that one.

Now you can easily isolate all your changes in your own packages. No code needs to go under openacs/www/ or any core packages. In fact if you want to customize ANY package, create a new package of your own that inherits the templates from the Openacs core or optional package.

This basically changes everything about how you use OpenACS to make a custom web site.

You say "Copy openacs-default-theme to mysite-theme and find/replace the info files ..." and what I'm not understanding about that, is what is the goal of that? What do we want the info file to look like? When we copied the openacs-default-theme package files, what did the info file look like before change/find/replacing?

I have a chance to try this out nowish so I'm looking for a little more guidance in that particular area.

-Jim

I do not inherit templates for the theme package. The subsite derived package needs to inherit templates and needs to "extend" acs-subsite. This way you can put only the files that are different under your derived subsite package and use the default subsite templates where appropriate.

Since a theme package is just a master template and associated css, list and form templates, inheriting doesn't make sense for the theme.

I'm working on a script that makes a new openacs package which is a theme that can be applied to a subsite. I believe I'm at 60% before a bug shakedown of the script, this is after about 2 days, and so I expect maybe 2-3 more hack sessions before the script has generated its first working theme package.

In this thread, Dave Bauer refers to automation to make a theme package; this script is meant to fill that bill.

See the action:

git clone git://github.com/jwlynch/openacs-theme-create.git

-Jim

While trying to follow these directions, I got stuck at:

• go to mysite/admin/ and click Convert to dependent subsite type

At mysite/admin, there's a link for 'Create a new subsite' which allows one to choose the subsite package to mount, but nowhere do I see a 'Convert to dependent subsite'

Am I just getting stuck in the wording or should I be looking elsewhere? Pointers appreciated.

Jim,

Many thanks for the detailed directions!

I will use both cases described. Case 1: Try your script to duplicate a theme package for use with a new 'test' package. Case 2: I'm modifying an existing xowiki instance with the 'extra_css' xowiki parameter, but some changes were needed in the default-theme css files. Making changes directly to the openacs released files becomes difficult to maintain between subsites and releases.

(I surmise from your answer and by testing some tcl files under the subsite admin code that subsite-convert-type no longer works in 5.7)

if you end up having to remove the package, remember that this would destroy package-specific data, and this part may involve a lot of work: somehow you should backup that data and restore it, which might involve you writing a lot of scripts to do so.

Success using the directions for both cases. Notes below.

If the package already exists, after using "manage depends and provides" to extend the package, go back to the package parameters page and use "Write an XML package specification to the packages/travlr/travlr.info file" to update the .info file.

"Subsite-convert-type" mystery solved. After a package extending subsite is created, a link for this action shows up on the "Main Site" administration page after 'Create new subsite.' There's a message key missing error (though this can be corrected using the translator mode in developer support).

To mount the package as a new subsite, just use 'Create new subsite' from Main Site admin. The form only offers the OpenACS default themes, but this can be changed later in the subsite's parameters.

Your script, new-oacs-theme-pkg.tcl, worked without problems after modification to use the local tclsh.

The only fly in the ointment: failure of the theming templates to pass the title <property> to blank-master.

foobar.tcl
----------
ad_page_contract {
    Testing
 } {

 } -properties {
    title:onevalue
    context:onelist
}

set package_id [ad_conn package_id]
set title "Testing"
set context [list $title]

foobar.adp
----------
<master>
  <property name="title">@title;noquote@</property>
  <property name="context">@context;noquote@</property>

This returns the name of the package as the title, instead of "Testing." I have an instance of xowiki mounted under this package subsite as well. The wiki pages do pass the title properly even though they use the same plain-master and blank-master templates (seen when using ADP reveal with dev support toolbar).

If you look at blank-master.{tcl,adp} you will see the actual html start tag and end tag, and see how they put any head tag stuff that is requested by the slave page author (look at the .tcl to see how it's done, and look at the ad_page_contract on that page for how to use anything there.

If you were to make a whole new system, you could write the docs as you have seen there, to describe your system. If you were to add a piece to the existing system, you can of course add docs to the ad_page_contract invocation in blank-master.

Property problem drove me batty but now solved. In the past title was passed using the property 'title.' Now many properties are passed in an array named 'doc': so doc(title), doc(title_lang), doc(type), etc.. There's another array, body, referenced in /serviceRoot/www/blank-master.tcl.

Set doc(title), and any other keys for the doc array, in the .tcl file. Then reference the array 'doc' using a pass by reference syntax in the adp file.

foobar.tcl
----------
ad_page_contract {
  Testing
} {
} -properties {
    doc
    context
}

set package_id [ad_conn package_id]
set title "foobar"
set doc(title) $title
set context [list $title]
ad_return_template

foobar.adp
----------
<master>
<property name="context">@context@</property>
<property name="&doc">doc</property>

So &doc declares a variable 'doc' which gets its reference from the symbol, doc, between the property tags. Simple for many, perhaps, but it escaped me.

I read a post in these forums by someone who said a thorny OACS configuration had him 'in tears.' Many moons earlier, while traversing some Solaris/opensolaris forum, I read a similar, stronger sentiment: compiling code in Solaris could 'drive one suicidal.' I think, perhaps, that the personalities drawn to OACS and Solaris are alike: moths irresistably drawn by the promised power of these systems and then consumed by their complexity. I can certainly empathize.

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'?

Regards
Richard

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.

Regards
Richard

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?

Regards
Richard

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.

😟

Richard.

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.

Richard

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! 😊

Regards
Richard

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?

-Jim

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 &lt;html ...&gt; ... &lt;/html&gt;) 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.

Thanks!

-Jim
.

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.