Theming in OpenACS
Created by Gustaf Neumann, last modified by Paul Babin 14 Oct 2021, at 04:01 PM
OpenACS provides theming functionality, i.e. the customization of the site layout through so-called theme packages with customized CSS and HTML layout.
Each subsite in OpenACS can have its own theme.
By default, the "Openacs-Default-Theme" is activated when installing OpenACS. The "Openacs-Default-Theme" package contains a "tabbed" navigation theme and a "plain" navigation theme (without tabs in main navigation).
OpenACS comes now with a new theme package, the "Openacs-Bootstrap3-Theme" Package, which is based on the Twitter Bootstrap Library. This new package is used on the openacs.org site and available form the openacs repository. The package (and the description below) requires at least OpenACS 5.9.0. In the following section you find some hints on how to use and customize this theme and how the theming can be customized in newer versions of OpenACS.
Step-by-Step Installation of a Theme Package
Installing theme packages and switching between themes can be easily done in a few steps:
- Obtain the theme package (e.g. from CVS or github) and install it under the package directory. You can as well "install from the respository", which makes step 2 below unnecessary.
- Go to /acs-admin/install and install the package
- Navigate to the subsite whose theme you would like to change and go to the "Configure"-Page. If you only have the default subsite set up, this is located at /admin/configure. Choose the theme you want. Click Ok. You should see the new theme now.
Note that a theme package can contain a number of different themes. For instance, the "Openacs-Default-Theme" Package contains a "tabbed" and a "plain" theme; the "Openacs-Bootstrap3-Theme" Package contains a "tabbed" theme in OpenACS style and a "tabbed" theme in turquoise color. - DONE!
Understanding the Basic Settings of Theme Packages
Where are the themes of a theme package defined?
Open /packages/openacs-bootstrap3-theme/tcl/apm-callback-procs.tcl in your editor. You see that 2 themes are defined here (subsite::new_subsite_theme), with all relevant parameters including css and js files and definition of template files.
You could add another subsite theme here. In order to get it listed on the "Configure"-Page of your subsite, you need to de-install and re-install the Theme Package.
The Theming Parameters allow you to specify, how elements of your page such as forms or lists should be rendered. If the resource which you have defned in your theme is not found, the default is taken from /packages/acs-templating/resources/ as a fallback.
The Theming Parameters
Have a look at the parameter page of your subsite. If you only have the default subsite set up, this is located at /shared/parameters.
In the "Theming"-Section of the subsite parameter page, you find the parameters which you have defined in the apm-callback-procs.tcl file of your theme package. You can modify the parameters here, however it is recommended that you define them in the apm-callback-procs. Why? If you switch the theme or re-install it, the settings of the parameter page are lost!
DefaultDimensionalStyle
- Defines layout of the filter options in a dimensional list. You can find an example at the Download Page of the OpenACS Website.
DefaultFormStyle
- Defines the layout of form templates
DefaultListStyle
- Defines the layout of list templates
DefaultMaster
- Defines the general page layout. The master usually sets the framing for the page layout and places elements such as header, navigation, content area, footer.
ResourceDir
- The directory, from which the resources of acs-templating are loaded. The resources include the template files for dimensionals, forms, lists, masters, templates, widgets. If not set, or the required resource is not found, the default is taken from /packages/acs-templating/resources/.
If for instance, the ResourceDir is set to /packages/openacs-bootstrap3-theme/resources, and you have a dimensional template defined in "Openacs-Bootstrap3-Theme" Package, you only need to specify the name of the -dimensional_template without giving the entire path.
StreamingHead
- Master used for streaming content
ThemeCSS
- List of CSS files used in the theme
ThemeJS
- List of Javascript files used in the theme
ThemeKey
- Key of theme.
Additional Tools to Layout in a Theme Package
Widgets
Starting with OpenACS 5.9, so-called widgets can be defined. <widget> is very similar to <include>, but uses widget specific name resolution based on themes. If the theme package contains resources/widgets/$specifiedName it is used from there. Otherwise it behaves exactly like <include> (without the resources/templates/theming).
In the "Openacs-Bootstrap3-Theme" Package, widgets are defined e.g. for the main navigation bar and the login area.
Templates
Sometimes, you might want a specific page or include to have a special design or layout which differs from the standard layout defined in that package. For instance, you might want to give the notification widget a new look&feel. You could go to the notification package and edit the correspondend tcl/adp files there. However, when upgrading the package, you always would have to merge your local changes with the upgraded files.
Starting with OpenACS 5.9, you can customize your local templates in your Theme Package. These files "overrule" the tcl/adp files in the corresponding packages. This makes it easier for you to keep the overview of all your layout changes, and also to upgrade your packages with less effort.
How does it work?
Let's take the example from above: you want to change the lokk&feel of the notification widget. The tcl/adp files are situated in /packages/notifications/lib/notification-widget.tcl and /packages/notifications/lib/notification-widget.adp.
Go to the "Openacs-Bootstrap3-Theme" Package. You see a folder resources/templates. Now construct a folder structure in the templates folder, just like this: resources/templates/notifications/lib and create the 2 files notification-widget.tcl/adp. Change the layout as desired.
DONE!
The "Openacs-Bootstrap3-Theme" Package contains a few such template files by default; feel free to change or complement them.
Understanding the Openacs-Bootstrap3-Theme Package
Different master files
The "Openacs-Bootstrap3-Theme" Package comes with a set of master files, which are shortly explained here.
- The "base master" is the plain-master.tcl/adp. It defines the general page layout.
- The tabbed-master.tcl/adp is the addition for a tabbed navigation, i.e. navigation tabs in the header bar which are defined in the parameter page. Tabs can be defined for admins (AdminNavbarTabsList), for members (MembersViewNavbarTabsList), for users (UserNavbarTabsList). You can check if you want the applications to be shown as tabs in the navigation bar.
- The tabbed-master-turquois.tcl/adp is similar tp the tabbed-master.tcl/adp. The difference is in the logo image defined in the .tcl file. In the OpenACS website, it is currently applied in the subsite for the .LRN project.
- The plain-streaming-head.tcl/adp, tabbed-streaming-head.tcl/adp, and tabbed-streaming-head-turquois.tcl/adp files are the corresponding master files for streaming content.
Color css
"Openacs-Bootstrap3-Theme" Package contains a "tabbed" theme in OpenACS style and a "tabbed" theme in turquoise color. The color stylesheets are defined in the apm-callback-procs.tcl file and located at /packages/openacs-bootstrap3-theme/www/resources/css/color/. This makes it very easy to change the color design of the theme. You could either modify one of the color stylesheets "blue.css" or "turquois.css"; or you could add your own color stylesheet and link it in the apm-callback-procs.tcl-file. In the latter case, you should de-activate and re-activate the theme in the "Configure"-Page (see above) to activate the setting.
Twitter Bootstrap
As the name of the package suggests, the "Openacs-Bootstrap3-Theme" Package makes use of the Twitter Bootstrap Library in version 3. The Twitter Bootstrap Library is a HTML, CSS and JAVASCRIPT library for frontend development which is based on a mobile first, responsive approach to web design.
Much has been written about this library. However, here are a few links which should help you to make yourself familiar with the Library in case you are new to Bootstrap:
- http://getbootstrap.com/getting-started/: Really helpful to get familiar with the notation specialties.
- https://en.wikipedia.org/wiki/Bootstrap_(front-end_framework): Some background information
- https://github.com/twbs/bootstrap: Bootstrap on GitHub
- https://jelvix.com/blog/bootstrap-vs-material: Compare Bootstrap with Google's Material Design
Designing your own Theme
The following guideline helps you to create your own theme. The easiest approach to develop your own theme is to build up on an existing one. For instance, you could modify the "Openacs-Bootstrap3-Theme" Package as a starting point.
- Make a local copy of the "Openacs-Bootstrap3-Theme" Package
- Rename the package.
- Take particular care of the .info file. Rename all the places where you find "openacs-bootstrap3-theme", and give a unique package key.
- Take particular care of the tcl/apm-callback-procs.tcl file. The subsites defined here through subsite::new_subsite_theme need to have a unique key, so give all the subsites you create here a unique key. Also, take care of the namespace.
- Before starting to modify the package, it is best to try to install and de-install the package on a test instance to make sure that you have all the naming right.
- Now feel free to modify the design as you like.
Themes in .LRN
When installing .LRN, the theme-zen is installed and activated by default.
.LRN comes now with a new theme package, the "Dotlrn-Bootstrap3-Theme" Package (as of July 2016, it is in proof-of-concept state!).
The "Dotlrn-Bootstrap3-Theme" Package builds on the "Openacs-Bootstrap3-Theme" Package and depends on both the "Openacs-Bootstrap3-Theme" Package and the "Theme-Zen" Package.
The Theming specifics described above also apply to .LRN theming, but additionally you should consider the following points:
Portal Pages Design
The Design of a Portal Page is defined on 3 levels:
- The subsite theme (which can be chosen on the "Configure"- Page, as described above)
- The page layout: It defines whether the page has, for instance, a 1-column, 2-column or 3-column layout. In the "Dotlrn-Bootstrap3-Theme" Package, the layouts are defined at lib/layouts.
- The portlet theme: It defines the look&feel of the single portlet. In the "Dotlrn-Bootstrap3-Theme" Package, the themes are defined at lib/themes.
Since every portal which is created, stores the portlet theme ID in the database, and since every portal page that is created, stores the page layout ID in the database, changing a theme in .LRN requires an upgrade of the affected database tables. This is done by the tcl/theme-procs.tcl/xql in the "Dotlrn-Bootstrap3-Theme" Package.
!!!!!! Attention: If you switch to the .LRN-bootstrap3-theme, all the portal pages are updated to the bootstrap3 layout !!!!!!
Installing and De-Installing the "Dotlrn-Bootstrap3-Theme" Package
If the "Dotlrn-Bootstrap3-Theme" Package is de-installed, the above described portal pages design falls back to the theme-zen design. This should make sure that the portal pages are always provided with a working layout.
