| Table of Contents | ||||
|---|---|---|---|---|
|
...
Theme Tutorial: Getting Started with Manakin Themes
This quick guide is intended to walk you through the process of setting up your first Manakin theme. The first part will take you from the process for creating a blank new theme, configuring that theme, and finally installing it to apply to specific DSpace pages in order to set the stage for further development. The second part will cover some useful debugging and development methods as well as some common "gochas".
Part 1: Creating a new theme
Create a folder where the theme will be stored at in the themes directory.
Locate your local themes directory. In DSpace 1.5 it is located at
dspace-source/dspace-xmlui/dspace-xmlui-webapp/src/main/webbapp/themes/
If this is a fresh installation, you might have to create the themes directory inside webapp. Create a new directory inside themes and name it after your new theme. Remember the directory name; it will come in useful when configuring the pages that the theme will be applied to.
Create a sitemap file for the theme.
Once a directory is created to house the theme, the next step is to create the theme itself. The heart of a theme is a single Cocoon configuration filed called a sitemap that determines how the theme processes the DRI document passed to it from the aspect chain. Through the sitemap the theme can be configured to apply different transformations and add metadata to the DRI document, generate debug output and do various other things. Since creating a new sitemap from scratch requires good working knowledge of Cocoon and Manakin internals, a template sitemap is provided as a starting point.
The template is located in the
dspace-source/dspace-xmlui/dspace-xmlui-webbapp/src/main/webbapp/themes/template directory and includes a sitemap configured with the most common settings as well as the instructions on changing them. The template also comes with blank xsl and css files, referenced by the sitemap, to help you get started. Copy the contents of the template directory into your new theme.
Configure the sitemap
A theme's sitemap is responsible for performing the following tasks:
...
Your theme is now configured and you are almost ready to get started.
Installing the theme
Before you begin work on CSS or XSL changes, the newly created theme should also be installed. A theme is installed by adding an entry for it in the xmlui.xconf file, found in your DSpace config directory. Locate the <themes> block inside the xmlui.xconf and add an entry to your own theme there. The theme's location is specified by the path attribute while the set of DSpace pages it applies to can be specified in thee different ways:
...
Do note that only the first theme rule that matches a page request is used. For example, if you place the most general rule (like regex=".*") at the top, it will always be used instead of all others. In addition, theme rules do cascade unless overridden by another theme rule further down. Thus, a theme rule applied to a community will also apply to all of its sub-communities, collections and items. In general, you should place the most specific rules at the top of the themes block and the most general ones on the bottom to take full advantage of the cascading effects. The comments above the themes block in the xmlui.xconf explain the cascading rules further. Finally, Tomcat must be always be restarted for changes in xmlui.xconf to take effect.
Part 2: Theme Development
Since several different tasks fall under the purview of modifying the look and feel of a DSpace page, so we have established the concept of Tiers of Development. Tier 1 involves mainly stylistic changes: CSS, JavaScript, and other client-side modifications. Tier 2 deals with all the activities of Tier 1 and also includes extending the base XSL library with your own templates. Tier 3 involves writing new Aspect code in order to add new functionality to DSpace. This guide will deal with Tiers 1 and 2.
...
This allows you to import the existing XSL from your theme's stylesheet, copy the templates you wish to override into your XSL and make your changes. The modified template will take precedence, overriding the existing XSL code. A good resource for XSL-related issues is the Mulberry Tech XSL Forum, located at: http://www.mulberrytech.com/xsl/xsl-list/
. The mailing list's archives are open and searchable, and it's very likely that any XSL problem your encounter has been brought up before and resolved in a discussion thread.
Development Tips
This section will most likely be expanded as time goes on.
Debugging at various stages of the theme application pipeline
Theme development in Manakin does not explicitly require use any specific tools or IDEs. Both XSL and CSS can be read and edited through a plain-text editor like Notepad or vi. However, the use of a specialized editor can make development considerably easier, especially when trying to debug erroneous behavior. It is also useful to know the various stages that DSpace pages go through before they are rendered on screen and being able to look at the intermediate results of those stages. The Manakin theme application process can be illustrated with the following diagram:
Getting at the raw XML
At every point in the process you can look at the intermediate result to aid with development and debugging. The first thing you can look at is the raw DRI-encoded XML generated by the Aspect Chain. This is useful when writing XSL templates to match the target elements in the DRI source, and when trying to the debug the results of XSL transformations. There are two ways to get at the raw XML:
...
Knowing the raw DRI code behind a DSpace page is essential for XSL (Tier 2) development. It can be useful in figuring out which XSL template in the base library was used to generate a specific block of html and thus which template should be overridden to achieve the desired output. Similarly, it can be used when designing new templates. In addition to its usefulness as a reference, DRI XML can also be used for debugging purposes. If you have an XSL IDE that comes with a debugger (we use oXygen, but there are other alternatives), saving a copy of the DRI page and processing it step by step in a debugger can aid in solving some of the more elusive bugs.
Getting at the raw XHTML
Moving further down the pipeline, once the XSL templates have been applied and DRI has been converted into XHTML, CSS rules can be applied to the result in order to impart a specific look and feel to the theme. This is the point where Tier 1 development usually begins. When editing the CSS, Manakin theme development is much like any Web development project. You start out with XHTML, a blank CSS and possibly a design in mind, and work with the CSS until the results are satisfactory.
Getting at the raw XHTML output of the XSL processor is easy: all browsers allow the user to look at the page source and save a copy. While the underlying HTML varies for any given DSpace page, the top-level structures like body and header remain consistent. One technique is to go through DSpace page by page, look at the HTML, and create CSS rules as necessary. Alternatively, you can extend the Reference theme that contains CSS selectors for nearly all elements encountered in the HTML structures of Manakin DSpace.
Analyzing the final outcome
As is frequently the case, CSS can be as finicky and prone to bugs as XSL, if not more so. Though you usually tell whether a given CSS selector is being applied directly by simply looking at the rendered page, a CSS debugger can indispensable in figuring out more gnarly problems. These usually take the shape of browser plug-ins, for example Firebug for Mozilla and the Internet Explorer Developer Toolbar. Both allow you to see the computed styles, trace their source to a specific line in a style sheet, and the former also allows tweaking with the values on the fly.
Browser-specific style sheets
As mentioned earlier, the theme template, as well as the Reference theme both use of more than one CSS stylesheet. One, conventionally named style.css, is the primary style sheet, while others are used for adding tweaks when rendering the page in specific browsers. This is accomplished by the use of the "browser" selector and the "IncludePageMeta" trandformer in the theme's sitemap. The browser selector tests the user's browsing agent against the following values:
...
Here, the stylesheets that reset most elements to our own default values (reset.css) and apply the baseline styling (style.css) apply to all pages, regardless of browser used. Same principle applies to the JavaScript functions and theme path variables passed to the XSL. The browser selector then applies the appropriate set of CSS tweaks.
Multiple theme design paradigms
There is more than one way to design a theme. The most common (and most straightforward) technique is the one described in this tutorial: that is each theme is a standalone unit, contained in its own directory with its sitemap, xsl, css and supporting files. However, this does not have to be so. For example, in the case where a particular repository has several different themes applied to its communities and collections that vary in slight but significant ways, it is a good idea to have those themes reuse components between themselves.
...
| Code Block |
|---|
<map:select type="browser">
<map:when test="lynx">
<map:transform type="IncludePageMeta">
<map:parameter name="stylesheet.screen#1" value="../style.css"/>
<map:parameter name="stylesheet.screen#2" value="style-lynx.css"/>
<map:parameter name="theme.path" value="\{global:theme-path\}"/>
<map:parameter name="theme.name" value="\{global:theme-name\}"/>
</map:transform>
</map:when>
<map:otherwise>
<map:transform type="IncludePageMeta">
<map:parameter name="stylesheet.screen#1" value="../style.css"/>
<map:parameter name="theme.path" value="\{global:theme-path\}"/>
<map:parameter name="theme.name" value="\{global:theme-name\}"/>
</map:transform>
</map:otherwise>
</map:select>
<map:transform src="../main.xsl"/>
|
Dynamically switching out themes
A new feature in DSpace 1.5 is the ability to try out different themes on a particular page without having to mess with the xmlui.xconf file or needing to restart Tomcat. Two things need to be done in order to apply a theme to any page you are currently looking at.
- The following setting in dspace.cfg must be set to true: xmlui.theme.allowoverrides=true
- The "themepath" value should be appended to the end of the url, i.e. http://manakin-url/search?themepath=Theme1/ or http://manakin-url/search?themepath=CompundTheme/SubTheme1/
Processing an external XML document
Sometimes you will find it necessary to use another XML document for input in addition to the DRI. For example you might have a static block of HTML you want to include in your header or a block of GIS data to be used for building an interactive map application. As long as the external input is XML-based, you can use the XSL document() function. This function allows you to open an external XML file and treat it like any other node-set, i.e. document('thefile.xml'),which can then be used in any select statement as desired:
...
Then you just have to find the file on disk. If it's somewhere in the theme, you can use a path relative of the current xsl file, i.e. document('newsfeeds/thefile.xml'). If it's in a web-accessible location, you can use a url, i.e. document('http://www.place.org/thefile.xml').
Adding static pages
It is possible to add simple static pages to DSpace using Manakin. This is useful for adding "one-shot" pages like About and FAQs where creating a new aspect would be overkill. There are three ways to add a static page:
...
3. Tomcat/apache-based method. Outside of Manakin or DSpace you could reroute urls to static pages using Tomcat's web.xml or the Apache configuration. This method while easy doesn't allow you to have any of the dynamic content (such as who's loged in) available on the page.
Common Gotchas
Empty self-closed elements in XHTML
By convention, an empty XML element, that is an element with no text value, can be represented in two ways in XML syntax:
- open/close pair: <element></element>
- self-closed element: <element/>
Both are valid XML, although the latter is used more frequently for convenience. By extension this notation is also valid in XSL and XHTML, but problems do crop up in the latter. Some browsers will treat a self-closed div element as the div opening tag, for example, placing all the elements that follow it inside that div. This can cause a great deal of headache during CSS work as your page's body and footer might end up whole subsumed under the header. This can occur either accidentally (an element that usually holds a title, for example, can get collapsed into an empty tag if a title is missing) or intentionally (when using blank "spacer" divs to keep floated elements from collapsing their containing block). In either case, the problem can be solved by making sure that the element hold at least some text (like substituting "untitled" for an item with no title) or adding a non-breaking space to the element.
XSL comments
A very simple gocha that is bound to get any developer working with XML at least once is the single restriction XML places on its comments. In XML (and therefore XSL) syntax, comments as designated by the pair <!-- comments -->. The character sequence – (dash dash) cannot appear inside the XML comment section and its inclusion will throw an error. Some processors do not explicitly report the exact line where the offending character sequence occurs, instead pointing the developer to the beginning or the end of the entire comment block. In general, if you are getting a malformed XML error somewhere in the comment block, a simple string search for a double dash should fix the problem.
HTML entities
One of the more common entities used in HTML is the non-breaking white space, used to offset text and pad empty elements. While it is defined in XHTML as (as are about 250 other entities like © ® &rarr, etc.), the XSL processor will throw an error if those entities are used in the XSL code. The reason for this is that only the following five entities are explicitly defined in XML, mostly because the symbols are part of the syntax structure:
- & - &
- ' - '
- " - "
- > - >
- < - <
In order to insert other symbols into the HTML, use the ISO 8859-1 codes for those entities, i.e.   instead of and © instead of ©. A full list of entities and their corresponding codes can be found in section 24 of the W3C Recommendation for HTML4: http://www.w3.org/TR/html401/sgml/entities.html
Override rules for templates: priority, import precedence, and modes.
A word of caution in overriding templates. When an apply-template call is made for a particular element, the XSL processor looks for all the templates that could possibly match that element. If only a single template can match a particular element, then that template will be applied. As is frequently in the case, however, more than one template can match an element or a condition. For example the call <xsl:apply-template select="dri:list"/> can be matched by all of the following templates:
...
The last thing to point out here is the use of the "mode" attribute on templates. These are used to differentiate templates that apply to the exact same elements, usually to process the same element under different conditions. In order to match, a template's mode must correspond to the mode of the template call, so a call of the form <xsl:apply-template select="dri:list" mode="nested"/> will only match templates that have the same mode attribute, i.e. <xsl:template match="dri:list" mode="nested">. This pairing overrides all other templates, regardless of priority and import precedence, so it is generally advisable to preserve the modes in imported templates. If the modes are kept consisent, however, those templates are subject to the same disambiguation rules as templates with modes.
Positioning of theme declrations in the xmlui.xconf file
The order in which themes are listed in the xmlui.xconf file is important. When looking for a theme to apply to a DSpace page, the Theme Matcher will go through each theme declaration in order until it finds the first one that matches. If your theme is not getting applied to a specific community, collection or url, first make sure that the theme's declaration is not preceded by another, more general, one. It is generally a good idea to have the most specific matches come first (those for specific urls or handles attached to items), followed by the more general ones attached to collections and communities, with the most general "default" theme coming last.
Trailing slashes on theme locations
A simple but common gocha is forgetting to follow all theme path with a trailing forward slash. This comes into play in two places: xmlui.xconf theme declarations and the use of the themepath parameter when dynamically switching out themes in a browser.</html>