Making DSpace XMLUI Your Own


Published on

DSpace XMLUI (Manakin) Tutorial given at the DSpace User Group Meeting (DSUG) 2009 in Gothenburg, Sweden.

Published in: Technology

Making DSpace XMLUI Your Own

  1. 1. MAKING DSPACE XMLUI YOUR OWN CUSTOMIZATION VIA OVERLAYS Tim Donohue Research Programmer IDEALS University of Illinois DSUG 2009 – Gothenburg, Sweden
  2. 2. DSpace 1.5 & 1.6 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 & 1.6 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 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 “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 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 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 + 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. XML-UI Overview • Intro to Manakin / XMLUI • Tiered interface development Credit: Scott Phillips, Texas Digital Library + Texas A&M (Most of this content is borrowed heavily from Scott’s numerous Manakin tutorials)
  19. 19. XMLUI, Classic Theme
  20. 20. XMLUI, Reference Theme
  21. 21. XMLUI, Kubrick Theme
  22. 22. Why Choose XMLUI?  Module design – easier to extend  Multiple interfaces / views, per community, collection or item  Metadata in its native formats  No knowledge of Java/JSPs necessary Picture borrowed from:
  23. 23. XMLUI Architecture Overview  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)
  24. 24. Cocoon’s Pipeline Model Sitemaps are used by both XMLUI Aspects and Themes. Diagram Credit: Scott Phillips, Texas Digital Library
  25. 25. XMLUI Architecture Overview defines aspect chain & themes xmlui.xconf Diagram Credit: Scott Phillips, Texas Digital Library Notice the similarities to Cocoon Pipeline model…
  26. 26. Digital Repository Interface (DRI)  DRI is XML  Abstract representation of page in a repository  View from any page by appending ?XML or &XML onto URL
  27. 27. Aspects  Implement set of features across entire repository  Java or XSL  “Aspect Chain” (see below)  Each requires valid DRI document as input/output  Core Aspects in DSpace 1.5  ArtifactBrowser (browse / search)  E-Person (login / logout)  Submission (submit new items)  Administrative (admin and management tools)
  28. 28. Themes  Look and feel of repository  May apply to any of following:  item, collection, community, whole repository  Theme folders can include  XSL(restructure site)  CSS (add style)  Images  Other static resources?
  29. 29. Putting it all together : DRI doc
  30. 30. Putting it all together : Aspect 1
  31. 31. Putting it all together: Aspect 2
  32. 32. Putting it all together: Aspect 3
  33. 33. Putting it all together: Theme
  34. 34. 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
  35. 35.
  36. 36.
  37. 37.
  38. 38.
  39. 39. Creating an XMLUI Theme • A few hints and tips on starting an XMLUI theme • Creating a theme via overlay
  40. 40. 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
  41. 41. 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
  42. 42. 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
  43. 43. Homepage Structural Breakdown buildHeader dri:trail dri:options dri:body dri:list communitySummaryList-DIM (DIM-Handler.xsl) buildFooter
  44. 44. Item Page Structural Breakdown itemSummaryView-DIM (DIM-Handler.xsl) mets:filegrp (General-Handler.xsl) collectionDetailList-DIM (DIM-Handler.xsl)
  45. 45. Simple XMLUI Theme Overlay • Task: Modify file display to show a format icon • (E.g.) PDF icon is displayed next to PDF files
  46. 46. 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
  47. 47. 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)
  48. 48. 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
  49. 49. 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
  50. 50. 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)
  51. 51. File Format icon in new theme
  52. 52. Creating an XMLUI Aspect •A few (high-level) hints and tips on starting an XMLUI aspect
  53. 53. 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
  54. 54. 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
  55. 55. 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
  56. 56. 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:
  57. 57. 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
  58. 58. 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
  59. 59. 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
  60. 60. 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
  61. 61. 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>
  62. 62. 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
  63. 63. Simple aspect- based content Complex aspect- based content
  64. 64. DSpace Community • Where to go for more help… • How you can help
  65. 65. DSpace Resources  DSpace System Docs (/dspace/docs/)  DSpace Wiki:    Dspace Training Materials  > Resources > Training Materials  Mailing Lists  dspace-general : general announcements, q & a  dspace-tech : weird errors? upgrade issues?  dspace-devel : where the developers are…
  66. 66. Useful DSpace / XMLUI Tutorials “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”)
  67. 67. How you can help…  Help test : DSpace Testathon before new releases  Report bugs / Request new features : Add to bug/feature list on Jira   Help others, just like you : Answer questions on dspace-general or dspace-tech lists  Tec h-savvy? Fix bugs or add functionality :  Announce your work on dspace-tech 
  68. 68. Contact Info Tim Donohue (Before Nov. 2009) (As of Nov. 2009) University of Illinois DuraSpace 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.