DSpace 4.2 XMLUI Theming

DSpace 4.2 XMLUI
Theming
DSpace 4.2 Advanced Training by James Creel is licensed under a
Creative Commons Attribution 4.0 International License. Special
thanks to the DuraSpace Foundation and the Texas Digital Library
for making this course possible.

Theming Module Outline
• Creating a new theme
• Colors, Fonts, Images, and Layouts with CSS
• Presentation of Data with XSL
• Interactive Interfaces with JavaScript

Theming for the XMLUI
• Themes are applied in the [dspace-install-
dir]configxmlui.xconf configuration file
• Each theme is configured in its constituent sitemap.xmap
file
• Inside the xmlui webapp, you can find a themes directory
containing the themes…
• As with other configuration changes, the server must be
restarted to enact changes to how themes are applied.
• However, a currently applied theme may be edited on-the-fly
while Tomcat is running – but make sure you save your work
elsewhere so it is not erased when you redeploy!

Applying themes in the XMLUI
• Within your [dspace-data-
dir]/config/xmlui.xconf file, have a look at the
<themes> section.
• Use the handle attribute to apply to specific handles in your
repo.
• Apply another theme to your favorite collection (look into
your [tomcat]/webapps/xmlui/themes directory for
a few options)
• Restart Tomcat to see the effects.

Ideas for Customizing Themes
Easy Intermediate Challenging
Fonts Adding new elements Ordering elements
logically
Colors Adjusting element
presentation
AJAX
Images Interactive animations
Removing elements

Create a custom theme
• Navigate your file browser to the
C:Developmenttomcatwebappsxmluithemes
directory.
• Duplicate the Mirage directory to MiragePlus or some such.
Rename the primary stylesheet as well.
• Open the sitemap.xmap within your new theme directory
to see how it is configured
• To enable it in the xmlui.xconf, we will need to change the
<theme-path> element.

Customizing a Theme with CSS -
Topics
• Basics
• Colors
• Images
• Fonts
• Positioning and displaying elements in the Box Model

Basics
• Elements within the <body> of the HTML document may
possess id attributes and class attributes, e.g.
• <p class=“someclass” id=“myFavoritePTag>
• Any id attribute value should be unique to an element of the
page
• The class element may have repeated values

Basics
• Declarations consist of a property (such as “color”) and a value (such
as “blue”)
• Rules are applied with selectors
• p would select all <p> elements
• p.foo selects all <p class=“foo”> elements
• p#bar selects all <p id=“bar”> elements
• p,div selects all <p> elements and all <div> elements
• div p selects all <p> elements that are children of a <div> element
• Styles take the form of selector {declaration; declaration; … }
• Declarations will be inherited by or cascade to contained elements
where appropriate

Customizing a Theme with CSS –
Colors
• Set using the color attribute and background-color attribute
• Rendered using combinations of red, green and blue light
• Value may be expressed as a pre-set string, hexadecimal, or a trio of
integers
body
{
color:red; /*looks red */
}
h1
{
color:#00ff00; /*looks green */
}
p
{
color:rgb(0,0,255); /*looks blue*/
}

Customizing a Theme with CSS –
Images
• Set using the image and background-image attributes
• Images are referred to with values of the form url('URL') which
can be relative or a full URL, as in
body
{
background-image:url(‘local-image.gif’);
}
div
{
background-image:url(‘http://website.com/remote.gif’);
}

Fonts
• Apply to any element in which text might occur
• font-family attribute allows one to list the fonts in order of
preference
• font-style attribute allows vaules of normal, italic, and oblique
• font-size specifiable in pixels or points
• font attribute is shorthand allowing one to specify all info about a
font in one declaration (order matters)
body
{
font-family: arial;
font-size: 30px;
font-style: italic;
}

Positioning an element with CSS –
The Box Model
• All HTML elements are rendered as rectangles within the
ultimate rectangle, the document body.
• The box-model represents each element as four nested
concentric rectangles, from center outward:
• Content
• Padding
• Border
• Margin
(Image credit:
W3C)

Block vs. Inline elements
• Block elements - These elements will start by default on a new line and
be as wide as their container. They may contain inline elements.
• Headings
• Tables
• Lists
• Forms
• Divisions
• Paragraphs
• Inline elements - These elements will start on the current line in their
container and have the width of their own content. They may contain
data or other inline elements
• Anchors
• Spans
• Images
• Buttons
• Inputs
• Labels

the Position properties
• There’s been a proliferation of possibilities in new browsers,
but the classic values for this attribute are
• static – the default, rendering by the flow in the box model
• relative – relative to where it would be appearing
• absolute – relative to first non-static ancestor
• Fixed- always fixed at the same position in the browser window
• Then do the actual positioning with top and left attributes.
div.alwaysThere
{
position:fixed;
top: 10px;
left: 10px;
}

Example: Aligining the Checkboxes
on Submssion – Initial Questions
• Might the initial checkboxes look better to the left of their
help text instead of below?
• No problem with relative positioning and moving them around
a few pixels.
• The trick is selecting these checkboxes uniquely among other
elements throughout DSpace’s many pages
• We will want to appeal to an id attribute

Controlling Data Presentation with
XSL - Outline
• Introduction
• XSLT and XPath
• How DSpace applies XSL
• Examples
• Eliding elements
• Amending elements
• Ordering elements

Customizing a Theme’s XSL
• Change the order and contents of the generated
page
• Add anything available in the DRI
• Add new CSS and Javascript files

Customizing a Theme’s XSL
• Bring up one your favorite collections.
• Put the string “/DRI” in between the webapp name and
“handle” as in
• http://localhost:8080/xmlui/DRI/handle/123
456789/4
• The resultant XML is transformed with the i18n messages.
• Get an even earlier version of the XML with the ?XML
parmeter, as in
• http://localhost:8080/xmlui/handle/1234567
89/4?XML

XSL – XSLT and XPath
• XSLT – Composed of <template> elements that select XML elements to
style
• Sub elements of the template are used to write the transformation (i.e. the
output) and to pass the control of flow to other parts of the stylesheet
• At least one template had better select the whole document to get started –
in fact, XSLT does this for you with a hidden first call of <xsl:apply-
templates select="/"/> which selects the root node. Thenceforth,
templates are applied to elements in the order that they occur in the source
XML and get matched by a template.
• In general, use <xsl:template match=“xpath”> to transform the
source nodes matching the xpath
• Use <xsl:apply-templates select = “xpath”> within a
template to pass the flow of control to any templates matching the xpath in
the current context

XSL – XSLT
• Transformations can be made to occur conditionally with the
<xsl:if test=“boolean-expression”>
• Multiple choice is achieved with the <xsl:choose> tag,
which may contain one or more <xsl:when
test=“boolean-expression”> tags and optionally a
final <xsl:otherwise> tag
• Iteration over sets of elements is achieved with the
<xsl:for-each select=“xpath”> tag
• The boolean expressions may employ XSL functions and
operators – some useful ones:
• > and < - greater than and less than
• = and != - equality and inequality
• not(expression) - negation

XSL – XSLT and XPath
• XPath – The language of selectors in XSLT
• / selects the root and also delimits steps on the selection path
• // selects with further sub-selectors starting from anywhere
• . is the current node
• .. is the previous node
• @ precedes an attribute name
• node selects elements named “node”
• Predicates:
• Use the brackets [] on a sub-selector to limit its selection with an
expression
• Wildcards:
• Use the star * to select any and all nodes in the context of the
current step along the path
• Multiple Paths
• Use the bar | as an AND operator between two selectors

DSpace applies XSL with Apache
Cocoon
• Flow of control determined in sitemap.xmap, themes.xmap,
and aspects.xmap
• All requests begin to be processed at [xmlui]/sitemap.xmap
• URLs for static resources get returned as such
• XMLUI resources are processed in [xmlui]/themes/themes.xmap
which reads the xmlui.xconf to pick the theme and makes an
internal request to generate the DRI for the page
• sitemap.xmap calls aspects.xmap which matches the request for
the DRI and loads xmlui.xconf to determine the aspects.
• Each aspect has its own sitemap.xmap which modifies the DRI in its
turn
• Low level details at
http://cocoon.apache.org/2.1/userdocs/concepts/sitemap.html

XSL Theming Capabilities
• Eliding elements - Simply delete an element from an XSL
template to stop it appearing from your page. Or add
conditionals to your selectors to elide a subset of a group of
rendered elements.
• Moving elements – Re-order elements in an XSL template by
moving them or even splitting them into programmatically
chosen categories
• Amending elements – Add an attribute directly as a static
value or programmatically with the <attribute> XSL element.
Appearances can also be altered by changing text (or keys)
that are used as labels, etc.

XSL Theming – Amending
Metadata Value Presentation in the
Simple Item View
• A common use case: customizing the simple item view for a collection
• In the the duplicated Mirage theme, we can find the item view
templates in libxslaspectartifactbrowseritem-
view.xsl
• The metadata field rows are indicated by nice comments.
• Track down the “Author(s) row”, and precede the <span> elements with
a textual label of your choice. Optionally, give it a class or id and some
CSS.
• To get this to apply to just a specific collection, you will of course need
to duplicate the theme before applying the changes and map it to your
chosen collection in the xmlui.xconf.

Customizing a Theme with
Javascript - Outline
Everything that CSS can do plus…
• Animation
• DOM manipulation
• AJAX
Many of these functions are achieved most easily with a
supplementary library such as jQuery.

Examples: The Discovery
Search Page Widgets
• Add filters button to provide new options to the user
• Sorting widget that reissues the search request
• Find the magic in
[tomcat]webappsxmluistaticjsdiscoverysearch-
controls.js

Example: Autocomplete for
Subject keywords with VIAF
• The Virtual International Authority File is a collaborative name
authority hosted by OCLC
• VIAF includes personal names, corporate names, place names,
and names of works among others.
• VIAF offers a web service that allows querying for XML output
as well as text-input autocomplete

Autocomplete for Subject
keywords with VIAF (1) –
upgrade jQuery
• Navigate to your duplicated Mirage theme and find the
libxslcorepage-structure.xsl file
• Find the addJavascript template at line 667
• Change the text value of the jqueryVersion variable to
“1.11.1”
• This will be automatically read from Google’s library hosting
service -
https://developers.google.com/speed/libraries/devguide#jquery

supply the code
• Find the codes on the share at Developmentcode-samples
• Add the viaf-autocomplete.js file to Tomcat’s (not
[dspace-install-dir]’s!)
webappsxmluithemes[themename]libjs directory
• Add the viaf-autocomplete.css file to the
webappsxmluithtmes[themename]libcss
directory
• Add the new javascript and css to the theme’s sitemap.xmap.
• Restart Tomcat

Check the Functionality
• Enter the item submission workflow –
• On the second Describe page, we will find the subject keyword
text input that the JavaScript file is hard-coded to find

keywords with VIAF –
Reflections on Functionality
• dc.subject text values do not fully realize the potential of
linked open data
• The DC Terms schema gets closer, but not quite there yet
• Security concerns in the browser limit more robust access to
VIAF with Ajax.
• Safe browsers don’t permit cross-domain Ajax calls
• One could set up a local semantic-web service proxy

Topics To Explore Further
• Responsive design
• Paradigm for Mirage 2
• Interacting directly with the DSpace database
• One may, if necessary, issue queries directly to one’s database
through psql
• Caution is urged
• Coding Core DSpace
• Complete control over aspects as well as internal functionality
• However, if your changes don’t make it back into the next point
release, keeping your changes after an upgrade could be difficult
• Major challenges to rapid development:
• Build time
• Automated testing

DSpace 4.2 XMLUI Theming

Recomendados

Recomendados

Más contenido relacionado

La actualidad más candente

La actualidad más candente (19)

Destacado

Destacado (18)

Similar a DSpace 4.2 XMLUI Theming

Similar a DSpace 4.2 XMLUI Theming (20)

Más de DuraSpace

Más de DuraSpace (20)

Último

Último (20)

DSpace 4.2 XMLUI Theming

Notas del editor