...
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.
...
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.
...
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:
- With regex pattern:
<theme name=" Theme's name" regex="community-list" path=" YourThemeDir /"/> - Directly with a handle:
<theme name=" Theme's name" handle="123456789/42" path=" YourThemeDir /"/> - Or both:
<theme name=" Theme's name" regex="browse-title^" handle="123456789/42" path=" YourThemeDir /"/>
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.
...
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:
...
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.
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.
...
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:
Wiki Markup {<xsl:apply-templates select="document('thefile.xml')" />}}
<xsl:for-each select="document('thefile.xml')/rootNode/subNode/etc/*" /><xsl:copy-of select="document('thefile.xml')" />
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').
...
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:template match="dri:list">
- <xsl:template match="dri:list1" priority="2">
- *<xsl:template match="dri:list.*)=0" priority="3">
...
simple matches < complex matches < explicit priority < importing templates
...
Since the question of what constitutes a complex vs. a simple match is processor-specific, the safest way to ensure desired behaviour is through explicit priorities. Thus, for empty lists in our example, all thee templates might match a given element, but the one designed to match the specific case wins because it is explicitly given a higher priority. If you look through the templates in dri2xhtml.xsl file itself, you will notice many templates bearing a priority attribute to disambigute cases where their match sets intersect.
...
A problem may arise, however, when these templates are imported into another stylesheet, as is the case in all themes overriding templates from the dri2xhtml base libray. Because templates belonging to the importing stylesheet have higher priority than those that are being imported (which is what allows the original templates to be overridden in the first place), this can produce unintended consequences when overriding only the simple and low-priority templates. Using our example above, we cannot just override the template than matches all lists if we also wish to preserve the original behavior, because it will always override the more specific ones simply by the virtue of having higher import priority. For this reason, when overriding simple templates for a particular element, always make sure that the templates dealing with the more esoteric conditions for that element are imported as well, even if you do not intent to change them.
...