Making DSpace 1.5 Your Own: Customizations via Overlays


Published on

Presentation given during the DSpace User Group Meeting at the Open Repositories 2009 conference in Atlanta, Georgia, USA on May 21, 2009.

Original version available at:

Published in: Technology, Education
No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Making DSpace 1.5 Your Own: Customizations via Overlays

  1. 1. MAKING DSPACE 1.5.X YOUR OWN CUSTOMIZATION VIA OVERLAYS Tim Donohue Research Programmer IDEALS University of Illinois DSUG @ Open Repositories 2009
  2. 2. DSpace 1.5.x Overview  Maven Build Architecture  DSpace “modules”  Application “Overlays”  XMLUI (aka. Manakin)  JSPUI  SWORD Interface  LNI (Lightweight Network Interface)  OAI-PMH Interface
  3. 3. Introducing Maven…  Apache Software Foundation  Java Project Build / Management Tool  Advantages:  Manages dependencies  Easier to manage/build many “modules”  Allows for basic application customizations via “overlays”  Disadvantages:  Yetanother XML config (many actually…)  Somewhat complex, if doing more than basic overlays
  4. 4. Maven v. Ant  DSpace 1.x-1.4 used Ant to build & install DSpace  DSpace 1.5 uses both Maven & Ant  Maven – Builds / Assembles DSpace “package”  Includesapplying “overlays” and pulling down all the necessary 3rd party dependencies  Ant – Installs or Updates your DSpace Installation directory ([dspace.dir] in dspace.cfg)
  5. 5. Ok, so what really is Maven? Build DSpace Here’s what I need… <dependencies/> mvn package pom.xml Maven local copies build Repository target JAR WAR dspace-1.5-build.dir Here you go… Dependencies!
  6. 6. Maven Concepts: An Overview  pom.xml (Project Object Model) config file  Standard directory layout src main java (Java Source Code) resources (Application Resources) webapp (Web Application Source) target (Build / Package Output)
  7. 7. DSpace 1.5.x Release Structure dspace-1.5 For those who only want to dspace make minor (non-Java) customizations bin config docs etc modules (Module Overlays) src (Maven Build Settings – no Java here…) pom.xml (Maven Project Object Model config)
  8. 8. DSpace 1.5.x “Modules” dspace-1.5 modules dspace src / main / resources jspui src / main / webapp …. (empty directories) lni modules oai …. sword xmlui Where’s the actual source code? src / main / java?
  9. 9. DSpace 1.5.x Source (SVN) dspace-1.5 dspace (Same as release version – see previous slides) dspace-api dspace-jspui dspace-lni Source code for DSpace “modules” dspace-oai In Release Version: dspace-sword Maven pulls down pre-compiled versions of dspace-xmlui these modules
  10. 10. DSpace 1.5.x Overlays • Overview of Overlays • How to take advantage of them
  11. 11. Customization via Overlays…  Overlay is Maven term (“Maven WAR Overlays”)  Simple way to override defaults with your own customizations and code  Allow you to more easily manage your customizations separate from DSpace core code  What can you “overlay”?  User interface look-and-feel (JSPUI, XMLUI Themes)  Language / terminology (messages.xml)  Java code to add functionality (XMLUI Aspect)  Although, this may be better built into a custom “module”
  12. 12. DSpace 1.5 + Maven = “Overlays” Build DSpace pom.xml Can you give me the JSPUI <dependencies/> Web application? dspace <build/> modules Maven jspui Repository messages Overlay JSPUI .properties jsp WAR Here you go… My JSPUI
  13. 13. Creating a Basic Overlay - JSPUI dspace Notice the Maven modules “standard directory layout” jspui src See “The Dspace Course” (S. Lewis & C. Yates) for more details on 1.5.x JSPUI customizations main java resources webapp (Replacement for “/jsp/local” ) jsp
  14. 14. Creating a Basic Overlay - XMLUI dspace webapp modules i18n messages.xml xmlui themes src My-Custom-Theme main css xsl images java sitemap.xmap resources webapp
  15. 15. Building/Installing an Overlay  Add your files to appropriate “/dspace/modules/” directory (see previous slides)  Rebuild DSpace: mvn package  Builds to [dspace-src]/dspace/target/  Update DSpace installation: ant update  Installs to [dspace.dir] (as specified in dspace.cfg)
  16. 16. Review: Why Overlays?  Essentially, they came along with move to Maven  You can manage your own customizations separate from DSpace source code  “/dspace/modules” subdirectories empty by default  JSPUI replacement for “/jsp/local” from pre-1.5  It is possible to overlay most *anything* (Java code, JSPs, XMLUI Aspects/Themes, sitemaps, etc.)
  17. 17. Overlays: things to watch out for…  We don’t recommend overlaying core APIs  Be very careful to merge in new code changes during your next upgrade  A local SVN code repository is helpful (“SVN vendor branch”) Image borrowed from:  It is recommended to only place overlays in [dspace-src]/dspace/modules/ (and subdirectories)
  18. 18. Quick XMLUI Review • Cocoon • DRI • Aspects • Themes
  19. 19. XMLUI Architecture Review  Built on Apache Cocoon  Modular, web-development framework  Pipeline based architecture  DRI (Digital Repository Interface) Schema  Structure based on TEI (light)  Metadata referenced in METS  Aspects and Themes  Aspects= functionality in system (Java or XSL)  Themes = style / look & feel (XSL, CSS, images)
  20. 20. Cocoon’s Pipeline Model Sitemaps are used by both XMLUI Aspects and Themes. Diagram Credit: Scott Phillips, Texas Digital Library
  21. 21. XMLUI Architecture Overview defines aspect chain & themes xmlui.xconf Diagram Credit: Scott Phillips, Texas Digital Library Notice the similarities to Cocoon Pipeline model…
  22. 22. Three “tiers” of customization…  Style Tier (CSS only)  Simple Themes: change basic look & feel  Theme Tier (XSL, CSS)  More Complex Themes: change page layout, what/how content is displayed  Aspect Tier (Java or XSL, sitemap)  Add new features via Java (and Cocoon)  Change XML (DRI) structure/hierarchy via XSL
  23. 23. Creating an XMLUI Theme • A few hints and tips on starting an XMLUI theme • Creating a theme via overlay
  24. 24. Create a new Theme via overlay dspace webapp modules i18n messages.xml xmlui themes src My-Custom-Theme main css xsl images java sitemap.xmap resources webapp
  25. 25. Tips on creating a theme  Start with an existing theme and tweak it  Use ?XML to view XML/DRI source document  Firebug ( for CSS/XHTML  Locate appropriate <xsl:template> in dri2xhtml  DIM-Handler.xsl = matches METS containing DIM  General-Handler.xsl = matches METS <fileSec>  MODS-Handler.xsl = matches METS containing MODS  QDC-Handler.xsl = matches METS containing QDC  structural.xsl = defines layout/page structure
  26. 26. Tips on creating a theme  Four metadata display “modes”  SummaryList = Summarized list of objects  (E.g.) Community/Collection listing, item browse/search  SummaryView = Summarized view of single object  (E.g.) Item homepage (summary metadata only)  DetailList = Detailed list of objects  Rarely used: (E.g.) “item appears in following collections”  DetailView = Detailed view of single object  (E.g.) Item “full record” page, collection/community pages
  27. 27. Homepage Structural Breakdown buildHeader dri:trail dri:options dri:body dri:list communitySummaryList-DIM (DIM-Handler.xsl) buildFooter
  28. 28. Item Page Structural Breakdown itemSummaryView-DIM (DIM-Handler.xsl) mets:filegrp (General-Handler.xsl) collectionDetailList-DIM (DIM-Handler.xsl)
  29. 29. Simple XMLUI Theme Overlay • Task: Modify file display to show a format icon • (E.g.) PDF icon is displayed next to PDF files
  30. 30. Review: Create a new Theme dspace webapp modules i18n messages.xml xmlui themes src My-Custom-Theme main css xsl images java sitemap.xmap resources webapp
  31. 31. Creating a new theme folder dspace/modules/xmlui/src/main/webapp themes Copy the default “Reference” theme into a new folder called “MyTheme” MyTheme sitemap.xmap images lib (CSS is stored here)
  32. 32. Adding File Format icons to theme /src/main/webapp Copy of “mets:file” template from General-Handler.xsl <xsl:template match=“mets:file”> themes … <xsl:call-template name="getFileFormatIcon"> MyTheme <xsl:with-param name="mimetype"> <xsl:value-of select="@MIMETYPE "/> </xsl:with-param> my-theme.xsl </xsl:call-template> … sitemap.xmap </xsl:template> <xsl:template name=“getFileFormatIcon”> images … pdf.png <xsl:when test=“$mimetype=‘application/pdf’"> <xsl:value-of select="$theme-path"/> <xsl:text>/images/pdf.png</xsl:text> lib </xsl:when> Snippet from getFileFormatIcon
  33. 33. Adding File Format icons to theme /src/main/webapp themes <map:sitemap> <map:pipelines> MyTheme <map:pipeline> … my-theme.xsl <map:transform src=“my-theme.xsl"/> … sitemap.xmap <map:serialize type="xhtml"/> </map:pipeline> images </map:pipelines> </map:sitemap> pdf.png lib
  34. 34. Enable your new theme… [dspace.dir] … <themes> config … <theme name="My New Theme" xmlui.xconf regex=".*" path="MyTheme/" /> … </themes> … Restart web server for changes to take effect Other sample theme settings: • regex=“^$” (Theme for homepage ONLY) • regex=“^browse$” (Theme for all global “Browse By” pages) • handle=“2142/2” (Theme for Community/Collection/Item)
  35. 35. File Format icon in new theme
  36. 36. Creating an XMLUI Aspect •A few (high-level) hints and tips on starting an XMLUI aspect
  37. 37. Options for adding custom Java via Overlay via Maven Module  Little more simplistic  Little more complex  Sitemap (XMLUI)  pom.xml & sitemap  Compiled in WAR (XMLUI)  Only one “module”  Compiled in JAR (UI) can use  Multiple “modules” can use via dependencies  Easier to share with others
  38. 38. Create a simple Aspect via overlay Good for simple aspects dspace modules java (Custom java source code) xmlui resources src aspects main MyAspect java sitemap.xmap resources My-aspect.xsl webapp
  39. 39. Aspect via a new Maven module For complex aspects or for easier sharing dspace modules java (Custom java source code) my-module resources src aspects main MyAspect java sitemap.xmap resources pom.xml
  40. 40. Aspect via a new Maven module dspace Very simple example of a valid pom.xml modules <project> <groupId>edu.myu.modules</groupId> <artifactId>my-aspect</artifactId> my-module <packaging>jar</packaging> <name>My Aspect’s API</name> src <version>1.0-SNAPSHOT</version> <dependencies>…</dependencies> </project> main java resources pom.xml More pom.xml details:
  41. 41. Add new Module as a Dependency dspace Add it to /dspace/modules/pom.xml so it is built alongside other modules modules <project> … my-module <modules> … <module>my-module</module> </modules> …. </project> pom.xml Also add it as a <dependency> in pom.xml of UI modules (XMLUI, JSPUI, etc) Rebuild DSpace for changes to take effect
  42. 42. Simple Aspect via Overlay • Modify Breadcrumb Trail to link to our Library’s Homepage • Do this at the “aspect” level so that it will apply across all of our XMLUI Themes • No Java…just XSLT Credit: Conal Tuohy, New Zealand Electronic Text Centre
  43. 43. Review: Simple Aspect via overlay dspace XSLT-only Aspect, so everything will go in /src/main/resources modules xmlui resources src aspects main MyAspect java sitemap.xmap resources My-aspect.xsl webapp
  44. 44. Aspect Overlay – Breadcrumb trail src/main/resources aspects <map:sitemap> <map:pipelines> Trail <map:pipeline> <map:generate/> sitemap.xmap <map:transform src="modify-trail.xsl"/> <map:serialize type="xml"/> </map:pipeline> modify-trail.xsl </map:pipelines> </map:sitemap> Remember: Aspects generate XML/DRI
  45. 45. Aspect Overlay – Breadcrumb trail src/main/resources <xsl:template match="*"> aspects <xsl:copy> <xsl:copy-of select="@*"/> Trail <xsl:apply-templates/> </xsl:copy> sitemap.xmap </xsl:template> <xsl:template match="dri:pageMeta"> modify-trail.xsl <xsl:copy> <xsl:copy-of select="@*"/> <dri:trail target=""> My Library </dri:trail> <xsl:apply-templates/> </xsl:copy> </xsl:template>
  46. 46. Enable your new aspect… [dspace.dir] … config <aspects> … xmlui.xconf <aspect name=“Trail” path=“resource://aspects/Trail/”/> </aspects> … Restart DSpace for changes to take effect
  47. 47. Simple aspect- based content Complex aspect- based content
  48. 48. Useful Resources (“Training Materials”) “The DSpace Course” (Stuart Lewis & Chris Yates): (Also linked to from under “Training Materials”) “Learning to Use Manakin” Tutorial (Scott Phillips): (Also linked to from under “Training Materials”)
  49. 49. Contact Info Tim Donohue University of Illinois DSpace Mailing Lists Technical Questions: Development Questions / Suggestions: This work is licensed under a Creative Commons Attribution- Noncommercial-Share Alike 3.0 United States License.