Theme Tutorial: Getting Started with Manakin Themes

...

The sitemap that comes with the theme template is configured to place references to one or two CSS stylesheets (depending on the browser) into the pageMeta and to use the theme's local XSL to perform the conversion. Generation, localization and serialization are handled as well. In fact, at first, the only change you have to make to your new theme is to set its new location at the very top of the sitemap file:

    <map:component-configurations>
        <global-variables>
            <theme-path>YourThemeDir</theme-path>
            <theme-name>The theme's name/description (not required)</theme-name>
        </global-variables>
    </map:component-configurations>

...

It is highly recommended that the user be familiar with CSS styling language prior to working with the styling aspects of theme creation and modification, and the basics of the XSL transformation language before working with the XSL stylesheets directly. A good starter set of tutorials on all things web related is available at the World Wide Web Consortium's site at:

• http://www.w3schools.com/^{Image Removed}
• http://www.w3schools.com/html/default.asp^{Image Removed}for HTML
• http://www.w3schools.com/css/default.asp^{Image Removed}for CSS
• http://www.w3schools.com/xml/default.asp^{Image Removed}for XML
• http://www.w3schools.com/xsl/default.asp^{Image Removed}for XSLT

Another resource for CSS work is also available from Zen Garden, a site containing an extensive list of stylesheet examples with complete access to the source code. It is located at: http://www.csszengarden.com/^{Image Removed} . Although you will most likely want to create your own theme, Zen Garden provides a good set of examples of things that can be accomplished with CSS alone, and can serve as a starting point or inspiration for a theme.

...

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/^{Image Removed} . 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.

...

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:

!<a href=!onetheme.jpg!"/>

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:

...

Once an agent has been matched (or the default case selected), the IncludePageMeta transformer is called with one or more parameters:

    <map:transform type="IncludePageMeta">
        <map:parameter name="stylesheet.screen#1" value="style.css"/>
        <map:parameter name="stylesheet.screen#3" value="style-ie6.css"/>
        <map:parameter name="stylesheet.screen#2" value="style-ie.css"/>
        ...
    </map:transform>

The syntax of the paramer statement is as follows. The format for a parameter name must follow the form:

    <element>.<qualifier>.<language>#order

The qualifier, language, and order are all optional components. The order component is an integer and is needed to ensure that parameter names are unique. Since Cocoon's parameters are Hashes duplicate names are not allowed. The order syntax allows the sitemap programmer to specify an order in which these metadata values should appear in the output document. The example above will introduce the following metadata elements into the DRI document:

    <pageMeta>
        <metadata element="stylesheet" qualifier="screen">style.css</metadata>
        <metadata element="stylesheet" qualifier="screen">style-ie.css</metadata>
        <metadata element="stylesheet" qualifier="screen">style-ie6.css</metadata>
        ...
    </pageMeta>

In the final DRI document these elements will be placed under pageMeta, which is where the default XSL library knows to look for them. If you follow the syntax and add more parameters to the IncludePageMeta transformer, the XSL will process the new values as well and add the appropriate lines to the HTML output. There is no limit to how complex or specific you want your browser matches to be, nor do they have to be limited to CSS stylesheet declarations. Furthermore, you can break up the declarations between several IncludePageMeta transformers for extra efficiency. The sitemap example below, taken from the Texas A&M Repository theme, demonstrates such a case.

    <!-- Add general page metadata -->
    <map:transform type="IncludePageMeta">
        <map:parameter name="stylesheet.screen#1" value="lib/css/reset.css"/>
        <map:parameter name="stylesheet.screen#2" value="lib/css/style.css"/>
        <map:parameter name="javascript#1" value="lib/jquery-1.2.min.js"/>
        <map:parameter name="javascript#2" value="lib/tamu-menus.js"/>
        <map:parameter name="theme.path" value="{global:theme-path}"/>
        <map:parameter name="theme.name" value="{global:theme-name}"/>
    </map:transform>
    &lt;!-- Add browser-specific stuff -->
    <map:select type="browser">
        <map:when test="explorer6">
            <map:transform type="IncludePageMeta">
                <map:parameter name="stylesheet.screen#1" value="lib/css/style-ie6.css"/>
            </map:transform>
        </map:when>
        <map:when test="explorer7">
            <map:transform type="IncludePageMeta">
                <map:parameter name="stylesheet.screen#1" value="lib/css/style-ie7.css"/>
            </map:transform>
        </map:when>
        <map:when test="safari2">
            <map:transform type="IncludePageMeta">
                <map:parameter name="stylesheet.screen#1" value="lib/css/style-safari2.css"/>
            </map:transform>
        </map:when>
        <map:when test="safari3">
            <map:transform type="IncludePageMeta">
                <map:parameter name="stylesheet.screen#1" value="lib/css/style-safari3.css"/>
            </map:transform>
        </map:when>
    </map:select>

...

In general, there is nothing preventing you from separating all the sub-themes into their own top-level directories, while still reusing components between them. Just as most themes import dri2xhtml.xsl, so can all themes use each other's XSL, CSS, images, and other supporting files. However, doing so creates strong coupling between themes that is not visible at a glance. If one of the themes is changed or removed, the effect will quietly propagate to other themes, potentially causing problems. Combining like themes together is a good alternative.

!<a href=!twotheme.jpg!"/>

Compound themes consist of a primary theme that defines all the main features and behaviors and any number of sub-themes that live in the same directory, using the primary theme's resources and overriding them as needed. This allows for reuse of resources and also works to keep all related themes together in one place.

As always every theme should have a sitemap. A subtheme's sitemap is really no different from a stand-alone theme: it declares the theme path and name, points to the theme's resources (relative of the sitemap's location) and invokes various transformers like XSL and i18n to process the page. Unlike a stand-alone theme, a subtheme also has at its disposal all the resources of its parent theme that it can use. For example, a subtheme can add special-case rendering for some situations, while relying on the parent theme for all others.

    <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"/>

...

1. XSL-based method. You can override the main body template and then add a check for the url of the page you want to add. The current page's url is always present in the DRI pageMeta section as request.URI. If the current page url is one you designated for your static page, then instead of rendering the body of the DRI page normally, you can have XSL insert different content. This content can either be placed in the code of the XSL template or imported from an external source using the document() function. This method is useful if the number of extra pages you want to include is relatively small and they are not edited frequently.

    <!-- Overriding the main body template -->
    <xsl:template match="dri:body">
        &lt;div id="ds-body">
            &lt;!-- Check for the custom pages -->
            <xsl:choose>
                <xsl:when test="/dri:document/dri:meta/dri:pageMeta/dri:metadata[@element='request'][@qualifier='URI']='about'">
                    &lt;div>
                        &lt;h1>About us</h1>
                        &lt;p>Lorem Ipsum dolor si amet</p>
                    &lt;/div>
                </xsl:when>
                <xsl:when test="/dri:document/dri:meta/dri:pageMeta/dri:metadata[@element='request'][@qualifier='URI']='faq'">
                    <xsl:copy-of select="document('faq.xml')" />
                </xsl:when>
                &lt;!-- Otherwise use default handling of body -->
                <xsl:otherwise>
                    <xsl:apply-templates />
                </xsl:otherwise>
            </xsl:choose>
        &lt;/div>
    </xsl:template>

...

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.

...

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:

• & - &amp;
• ' - &apos;'
• " - &quot;"
• > - &gt;>
• < - &lt;<
  In order to insert other symbols into the HTML, use the ISO 8859-1 codes for those entities, i.e. &#160;   instead of &nbsp; and &#169;   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^{Image Removed}

Override rules for templates: priority, import precedence, and modes.

...