Documentation In Progress
This chapter of the Bedework 3.8 Documentation is in the process of being updated.
This section is a resource for web designers who would like to customize the look and layout of the Bedework calendar web clients. No programming experience is assumed, though a basic understanding of how web applications work is helpful.
A generic theme is provided with each web application in the quickstart release. The public client's MainCampus calendar suite comes with a number of themes to get you started. Fonts, colors, and most layout specifics are defined with CSS.
Examples of how members of the Bedework community have implemented themes can be viewed by selecting from our listing on the Bedework website, “Who's using Bedework?”: http://www.bedework.org/bedework/update.do?artcenterkey=35
Changing headers, footers, colors, and fonts can be accomplished with an understanding of XHTML and CSS. Changing global layout or presentation behavior requires an understanding of XML and XSL (xslt and xpath, in particular).
Because the calendar front-end uses XSLT to transform XML, you must use valid XML markup for all templates. Skins that produce HTML must be written using XHTML (regardless of the final output). Skins without valid markup will fail to transform.
In the quickstart directory, the theme files for the xml-based web applications are found in the following directories:
If you rebuild the application (you will want to do this to create a production release), the skins are copied into:
The quickstart distribution comes with the themes already in place and ready to use.
Once deployed (as they are in the quickstart), the skins can be manipulated directly inside the JBoss ROOT.war directory for quickest development; be aware however that on a rebuild the source files will overwrite the JBoss files, so it is safest to edit in the source folder and copy files into the JBoss directories as you go. You may also choose to place your theme files on a separate web server. (Note: the destination folder into which the theme files are copied during a build is defined by the ...resources.dir property in the cal.properties config file.)
The locations of the theme directories are defined in the file
which should be copied to your user home directory or to another location as described in Configuring Bedework.
In production, however, the <browserResourceRoot> must be served over https for secure web sites to avoid mixed content errors. To build a production release, change the values of <appRoot> and < browserResourceRoot> to the name of the server hosting the resources, and add https: to the <browserResourceRoot> for those web clients you will provide over SSL (e.g. personal, submissions, and admin web clients).
The <appRoot> takes the following value:
which for the quickstart is
The appRoot is modified at run time for portals and calendar suites. If we are running under a portal the approot has .portalPlatform appended. For example, if the portal platform is uPortal2 the user client appRoot defined above becomes
In addition, we append the calendar suite name for public clients (all calendar suites and the feeder application). So if the calendar suite is MainCampus we have
or for the portlet
The public web client appRoot directories have the following structure:
The personal, admin, and submissions web clients use a slightly different structure for resource files and language strings. All templates in these clients are found in the default.xsl file for a particular skin. These will be refactored in upcoming releases to match the current structure of the public clients. Behaviors are otherwise the same among all the xsl clients.
When a Bedework web application is requested, the server goes through a process of stylesheet discovery in three steps: selecting the locale, selecting the browser type, and finally selecting the skin.
The top-level directories of the appRoot define locales. The default locale is default. You may add directories here using a locale name such as en_US or fr_CA. Browsers provide Bedework with a locale; if a directory is found with a name that matches the locale provided by the browser, Bedework will use the skins found there. Otherwise, the default locale directory will be used.
For a locale to be supported by Bedework it must be included in the list of supported locales in the Admin Client. For example, if you wish to support fr_CA, visit http://localhost:8080/caladmin → System tab → Manage system preferences, and add fr_CA to the list of supported locales.
The next level down defines the browser type. Bedework looks first for a folder whose name is associated with the user-agent of the visiting browser. If found, Bedework will use that folder to deliver the skin. If not found, Bedework will use the default directory seen here. Currently, the acceptable folder names are:
Bedework can be forced to use a specific browser type and skin and can have multiple skins per browser type. See Actions & Parameters for more information about this.
This code is somewhat archaic, and PDA user-agent sniffing is out-of-date; to use the PDA directory found in the quickstart release, you can explicitly request it by adding the request parameter browserTypeSticky=PDA. browserTypeSticky=default will reset this to the default path.
Once the locale and browser type paths have been selected, the server will select the xsl skin used for transforming Bedework's XML. If no skin is explicitly requested, the server will fall back to default.xsl. A skin can be directly requested using the request parameter skinName=someskin or skinNameSticky=someskin. See Actions & Parameters for more information about this.
In the public client, the default.xsl skin includes the global.xsl file for global variables, the strings.xsl file for internationalized language strings, and the root xsl file of the theme that will be used by default. Here is the example from default.xsl of the MainCampus calendar suite:
In the personal, submissions, and admin client, default.xsl includes strings.xsl. The rest of the xsl logic is self-contained.
Skins are only loaded at first reference and are then cached. The skins can be explicitly flushed using the refreshXslt=yes query parameter (see Actions and Parameters below). Most themes shipped with Bedework have a Refresh XSLT link in the footer of the web client. (You will probably want to disable this link prior to production.)
The discovered 'real' path is cached with the 'idealized' path as the key so that subsequent lookups for the same path will proceed without the discovery phase.
As a first step towards internationalizing Bedework, nearly all English strings have been pulled from the xsl templates that produce the personal, public, admin, and submission web clients.
The public client locale directories contain two files, strings.xsl and localeSettings.xsl. These two files contain the replacement text and settings for the language associated with the current locale. The themes reference the current locale's strings and localeSettings files. The strings should be translated to the default language you wish to use for your site. If you wish to support other languages in the same client, create a locale directory and place a translated strings and localeSettings files into it.
Each default.xsl includes the strings file from its locale directory. Each otherwise includes default/default/globals.xsl file and the theme of its choice. Here is an example of what the fr_CA default.xsl would look like for the MainCampus calendar suite:
The public themes consist of a collection of xsl skins that contain a series of xsl templates. The theme directories are found in
In the MainCampus/themes directory, you'll find Bedework default theme bedeworkTheme. The root xsl file is called bedework.xsl. Likewise, in the iphoneTheme, the root xsl file is called iphone.xsl.
If you have a good grasp of XHTML and CSS, you can modify the graphics, colors, and general feel of a skin by editing one of the examples and copying the changes into its associated resources directory in JBoss. Skins are cached in memory, so to update a skin you must refresh the stylesheet by appending your query string with refreshXslt=somestring. For example:
Bedework's default theme is based on work at Duke and Yale Universities. The theme includes a number of features that can be configured in themeSettings.xsl. These include:
Events can be colored by category in the public web client if you choose. This is currently accomplished by customizing a template in the stylesheet.
For example, to color events in the calendar grid of the bwclassicTheme, search for the template that looks like this (approx. line 170 of themes/bwclassicTheme/eventGrids.xsl):
Uncomment the category tests and add your own logic for setting the event colors. The values such as bwltpurple are css classes that will be applied to each event in the grid or list, and are found in bedework/deployment/resources/xsl/default/default/subColors.css
This file gets deployed to the bedework-common directory and is referenced by the public web client.
You can use this approach to color events in other ways or use your own custom classes.
In future versions of Bedework, we will refactor the personal, admin, and submissions clients to use the same structure as the public themes. For now, theming for these clients involves modifying the appRoot/default/default/default.xsl files and default.css files.
Typical of web applications, Bedework receives HTTP requests and returns responses based on the page or action requested and the parameters sent in the query string. Look at the following URL:
Bedework is built in the Apache Struts MVC framework, and as such does not reference "web pages" through URLs directly. setViewPeriod.do in the URL above calls a Java "action" that returns a response based on the query string "date=20101121". This URL tells the personal calendar to set the current view to November 21, 2010.
Parameters can be strung together with ?'s and &'s on a query string like so:
Request processing in Bedework is divided into two parts: a normal action that may change the state of the application, and a render action that returns the resulting state for display. This is required, among other things, for Bedework to run as a portlet.
For each normal action that is called, Bedework will automatically redirect to the appropriate render action. Normal actions take a .do extension. Render actions have an .rdo extension.
As the developer of a skin, you will be primarily concerned with normal actions, and it is these that will be presented in the XSL stylesheets for users to click. All actions and parameters described below are normal actions.
All actions used by the Bedework web clients are defined in the client's struts-config.xml file. For example, the public and personal web clients are described in
and all actions used by the Bedework admin web client are described in
For detailed information about all actions and parameters used in Bedework, please see the API reference found from the Bedework Wiki.
The following parameters provide control over stylesheets. They can be added to any Bedework URL and combined with any other parameter.
setappvar=key(value) - Pass a key/value pair into the XML output.
skinName=name - Set the skin to name during for the request
skinNameSticky=name - Set the skin to name for the rest of the session (or until another skin is called).
where name is the file name of an XSLT document at the bottom of the locale/browserType path, leaving off the .xsl extension.For example:
If skinName is unspecified, Bedework uses the default skin. The URL to select "shiny.xsl" might look like this: http://hostname/cal/setup.do?skinNameSticky=shiny
browserType=default, MSIE, Netscape, Netscape4, Mozilla, PDA, other - Set browser folder during request
browserTypeSticky=default, MSIE, ... - Set browser folder for the remainder of the session (or until another browserType is called).
If unspecified, Bedework uses the folder that most closely matches the user-agent of the requesting browser. If not found, the "default" folder will be used. The example above would use the Mozilla folder for an incoming Mozilla browser. You may also create your own folder and call it explicitly, though Bedework cannot automatically associate it with a user-agent.
XSL skins are cached once per user session to improve performance. If you make a change to your skin, you need to pass this parameter to reload it. anystring can be any value; we typically set it to yes. Example:
This parameter turns off the XSLT filter and returns raw xml in the response. You can look at the xml by selecting "view source" from your browser. This feature is very important when designing skins because it allows you to reference the exact XML you are trying to transform. anystring can be any value; we typically set it to yes. Example:
In Bedework, you can effectively look at the XML in two ways:
In a user client (guest or personal) append noxslt=yes to the query string and view the page source. For example:
There is a link in the footer of each web client that reads “show XML” which adds this parameter to the query string for the current page. When manipulating the XSLT, this is the easiest way to understand the underlying XML that is being transformed.
Look at the JSP pages which produce the XML output. These can be found in:
where client is webclient, webadmin, websubmit, or feeder.
Each “page” of an XML response takes the following form:
In most cases, the skins look first at the pageName found in the incoming XML and branch to an appropriate XSL template based on that. Look to the default template (the first in the stylesheets, matching on “/”) to see a listing of all incoming “pages” and their associated XSL templates. For example of this branching, look in
Bedework uses Apache Xalan as its XSLT processor, and processes XSLT version 1.0 and Xpath version 1.0. Bedework uses the standard Xalan libraries without extensions. The XSLT language is reasonably simple, and if you are familiar with basic programming or scripting, you will have little difficulty reading it.
The key to understanding how the transformations take place, however, is to look at the underlying XML (by switching off the transform in Bedework using the “noxslt=yes” parameter and viewing the page source) and recognizing how XPath expressions are used to locate the xml nodes for transformation.
As noted above, a good place to begin understanding how the XML is transformed is
XSLT & XPath Quick Reference (PDF): http://www.mulberrytech.com/quickref/XSLT_1quickref-v2.pdf
XPath Specification: http://www.w3c.org/TR/xpath
XSLT Specification: http://www.w3c.org/Style/XSL/