Embed Size (px)
Citation preview
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]\config\xmlui.xconf configuration file
• Each theme is configured in its constituent sitemap.xmapfile
• 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:\Development\tomcat\webapps\xmlui\themes 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
Customizing a Theme with CSS -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
Customizing a Theme with CSS -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’);}
Customizing a Theme with CSS -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)
Positioning an element with CSS –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
Positioning an element with CSS –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/123456789/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/123456789/4?XML
Controlling Data Presentation with 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
Controlling Data Presentation with 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:whentest=“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
Controlling Data Presentation with 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.xmapwhich 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 lib\xsl\aspect\artifactbrowser\item-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 - OutlineEverything 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]\webapps\xmlui\static\js\discovery\search-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 lib\xsl\core\page-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
Autocomplete for Subject keywords with VIAF (2) –supply the code• Find the codes on the share at \Development\code-samples
• Add the viaf-autocomplete.js file to Tomcat’s (not[dspace-install-dir]’s!) webapps\xmlui\themes\[themename]\lib\js directory
• Add the viaf-autocomplete.css file to the webapps\xmlui\thtmes\[themename]\lib\cssdirectory
• Add the new javascript and css to the theme’s sitemap.xmap.
• Restart Tomcat
Autocomplete for Subject keywords with VIAF (3) –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
Autocomplete for Subject 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
