Page History

...

Before getting started, it's worth mentioning that this request flow is controlled via a series of Cocoon Sitemap files (named sitemap.xmap, themes.xmap and aspects.xmap). These Sitemap files are Cocoon's way of defining the flow. More information about Cocoon Sitemaps is available at: http://cocoon.apache.org/2.1/userdocs/concepts/sitemap.html^{Image Removed}

The following explanation provides a high level overview of how a request is processed, how a DRI document is generated (via Aspects), and then how it is transformed into XHTML (via Themes). As this is a high level overview, some details are likely left out, but the overarching flow is what is most important.

1. A user visits an XMLUI page (by clicking a link or button, etc)

2. Wiki Markup
   That request begins in the root Cocoon {{sitemap.xmap}} (located at {{\[xmlui\]/sitemap.xmap}}). This is the main entry point for *all requests*

   1. Within that sitemap, various URL path matching takes place. If the request is to download a document, that document is returned immediately.

   2. Wiki Markup
      However, in many cases, the request is for a page within the XMLUI. In this scenario, the root sitemap.xmap will load the {{\[xmlui\]/themes/themes.xmap}} file, which controls all the Themes.

      1. Wiki Markup
         The {{themes.xmap}} file will then load all "matching" themes which are configured in your {{\[dspace\]/config/xmlui.xconf}} file (see [#Themes] below).

      2. If more than one theme matches the current URL path, then the first match wins
      3. Once a matching theme is located, that theme's sitemap.xmap file (located in its theme directory) is loaded and processed.
         1. The theme's sitemap.xmap is in charge of actually loading the theme's XSLT, CSS, etc. However, before it does that, you'll notice it makes a call to generate the DRI document for the current page as follows:

            Code Block
            <map:generate type="file" src="cocoon://DRI/{1}"/>

         2. This DRI call generates a brand new, internal Cocoon request. This request is then processed back in the root sitemap.xmap (remember how we said that this sitemap is the main entry point for all requests).

3. Wiki Markup
   Back in the root sitemap, the "DRI/**" call is matched. This causes the {{\[xmlui\]/aspects/aspects.xmap}} file to be loaded. As the name suggests, this file obviously controls all the Aspects.

   1. Wiki Markup
      The {{aspects.xmap}} file will then load all enabled Aspects which are configured in your {{\[dspace\]/config/xmlui.xconf}} file (see [#Aspects] below).

   2. Each aspect is loaded in the order that it appears. However, multiple aspects may be loaded for the same URL path. Remember, aspects can build upon each other (we call this an "aspect chain") as they work together to generate the final DRI document.
   3. When an Aspect is loaded, its sitemap.xmap is loaded & processed

      • Wiki Markup
        NOTE: An aspect's sitemap.xmap is actually compiled into the {{dspace-xmlui-api.jar}} file. However, if you have a copy of DSpace source handy, it can be found in: {{\[dspace-src\]/dspace-xmlui/dspace-xmlui-api/src/main/resources/aspects/\[name-of-aspect\]/}}

   4. Each aspect is processed one-by-one (again in the order they are listed in xmlui.xconf). Each aspect may add, remove or change content within the DRI document. After the final aspect is finished processing, the DRI document is complete.
      • HINT: In the XMLUI you can always view the final DRI document by adding "?XML" or "&XML" on to the end of the current URL in your web browser.
4. Once the final DRI document is complete (all aspects are done processing), the flow will return back to your Theme's sitemap.xmap (remember, this is the same location that triggered the loading of the Aspects in the first place).
5. At this point, your Theme's sitemap.xmap will continue its processing. Generally speaking, most themes will then perform one or more XSLT transformations (to transform the final DRI document into XHTML). They also may load up one or more CSS files to help stylize the final XHTML.
6. Finally, once the Theme has completed its processing (remember, only one theme is ever processed for a single request), the final generated XHTML document is displayed to the user.

...

The <aspects> section defines the "Aspect Chain", or the linear set of aspects that are installed in the repository. For each aspect that is installed in the repository, the aspect makes available new features to the interface. For example, if the "submission" aspect were to be commented out or removed from the xmlui.xconf, then users would not be able to submit new items into the repository (even the links and language prompting users to submit items are removed). Each <aspect> element has two attributes, name and path. The name is used to identify the Aspect, while the path determines the directory where the aspect's code is located. Here is the default aspect configuration:

<aspects>
    <aspects>
    <aspect name="Displaying Artifacts" path="resource://aspects/ViewArtifacts/" />
        <aspect name="ArtifactBrowsing BrowserArtifacts" path="resource://aspects/ArtifactBrowserBrowseArtifacts/" />
        <aspect name="Searching Artifacts"    path="resource://aspects/SearchArtifacts/" />
        <aspect name="Administration"	 path="resource://aspects/Administrative/" />
               <aspect name="E-Person" path="resource://aspects/EPerson/"	 />
                <aspect name="Submission and Workflow" path="resource://aspects/Submission/" />
        <aspect name="Statistics" path="resource://aspects/Statistics/" />
        <aspect name="Original Workflow" path="resource://aspects/Workflow/" />
    </aspects>

A standard distribution of Manakin/DSpace includes four eight "core" aspects:

• Artifact Browser ViewArtifacts The Artifact Browser ViewArtifacts Aspect is responsible for browsing communities, collections, items and bitstreams, viewing an individual item and searching the repository.reposonsible for displaying individual item metadata.
• BrowseArtifacts The BrowseArtifacts Aspect is reponsible for displaying different browse options
• SearchArtifacts The SearchArtifacts Aspect displays the different search boxes. Shouldn't be activated together with DSpace Discovery.
• Administrative The Administrative Aspect is responsible for administrating DSpace, such as creating, modifying and removing all communities, collections, e-persons, groups, registries and authorizations.
• E-Person The E-Person Aspect is responsible for logging in, logging E-Person The E-Person Aspect is responsible for logging in, logging out, registering new users, dealing with forgotten passwords, editing profiles and changing passwords.
• Submission The Submission Aspect is responsible for submitting new items to DSpace, determining the workflow process and ingesting the new items into the DSpace repository.Administrative The Administrative Aspect is responsible for administrating DSpace, such as creating, modifying and removing all communities, collections, e-persons, groups, registries and authorizations.the DSpace repository.
• Statistics The Statistics Aspect is responsible for displaying statistics information.
• Workflow The Original Workflow Aspect is responsible for displaying workflow tasks. Shouldn't be activated with the new workflow called XMLWorkflow

Following Aspects are optional

• XMLWorkfflow This Aspect was added in DSpace 1.8 and is responsible for the new configurable workflow system. Shouldn't be activated together with the Workflow aspect.
• Discovery The Discovery Aspect replaces the standard search with faceted searching. It also takes care of the faceted browse options. Shouldn't be activated togather with SearchArtifacts.
• SwordClient The SwordClient aspect displays options that allow you to "push" DSpace content to another SWORD-server enabled system.
• XMLTest An aspect to assist developers in creating themes, as it displays different debugging options.

Following Aspects are deprecated and shouldn't be used anymore at all

• ArtifactBrowser This aspect has been split up into ViewArtifacts, BrowseArtifacts and SearchArtifacts in DSpace 1.7.0

Themes

The <themes> section defines a set of "rules" that determine where themes are installed in the repository. Each rule is processed in the order that it appears, and the first rule that matches determines the theme that is applied (so order is important). Each rule consists of a <theme> element with several possible attributes:

• name (always required)The name attribute is used to document the theme's name.
• path (always required)The path attribute determines where the theme is located relative to the themes/ directory and must either contain a trailing slash or point directly to the theme's sitemap.xmap file.
• regex (either regex and/or handle is required)The regex attribute determines which URLs the theme should apply to.
• handle (either regex and/or handle is required)The handle attribute determines which community, collection, or item the theme should apply to.
  If you use the "handle" attribute, the effect is cascading, meaning if a rule is established for a community then all collections and items within that community will also have this theme apply to them as well. Here is an example configuration:

  Code Block
  <themes> <theme name="Theme 1" handle="123456789/23" path="theme1/"/> <theme name="Theme 2" regex="community-list" path="theme2/"/> <theme name="Reference Theme" regex=".*" path="Reference/"/> </themes>

  In the example above three themes are configured: "Theme 1", "Theme 2", and the "Reference Theme". The first rule specifies that "Theme 1" will apply to all communities, collections, or items that are contained under the parent community "123456789/23". The next rule specifies any URL containing the string "community-list" will get "Theme 2". The final rule, using the regular expression ".", will match *anything, so all pages which have not matched one of the preceding rules will be matched to the Reference Theme.

...

Manakin themes stylize the look-and-feel of the repository, community, or collection and are distributed as self-contained packages. A Manakin/DSpace installation may have multiple themes installed and available to be used in different parts of the repository. The central component of a theme is the sitemap.xmap, which defines what resources are available to the theme such as XSL stylesheets, CSS stylesheets, images, or multimedia files.
*1) Create theme skeleton*
Most theme developers do not create a new theme from scratch; instead they start from the standard theme template, which defines a skeleton structure for a theme. The template is located at: _\[dspace-source\]/dspace-xmlui/dspace-xmlui-webbapp/src/main/webbapp/themes/template_. To start your new theme simply copy the theme template into your locally defined modules directory, _\[dspace-source\]/dspace/modules/xmlui/src/main/webbapp/themes/\[your theme's directory\]/_.
*2) Modify theme variables*
The next step is to modify the theme's parameters so that the theme knows where it is located. Open the _\[your theme's directory\]/sitemap.xmap_ and look for _<global-variables>_

    <global-variables>
        <theme-path>[your theme's 	directory]</theme-path>
        <theme-name>[your theme's name]</theme-name>
    </global-variables>

...

1. Wiki Markup
   Rebuild the DSpace installation package by running the following command from your _\[dspace-source\]/dspace/_ directory:

   Code Block
   mvn package

2. Wiki Markup
   Update all DSpace webapps to _\[dspace\]/webapps_ by running the following command from your _\[dspace-source\]/dspace/target/dspace-\[version\]-build.dir_ directory:

   Code Block
   ant -Dconfig=[dspace]/config/dspace.cfg update

3. Deploy the the new webapps:

   Code Block
   cp -R /[dspace]/webapps/* /[tomcat]/webapps

4. Restart Tomcat
   This will ensure the theme has been installed as described in the previous section "Configuring Themes and Aspects".

...

Any static HTML content you add to this directory may also reference static content (e.g. CSS, Javascript, Images, etc.) from the same _\[dspace-source\]/dspace/modules/xmlui/src/main/webapp/static/_ directory. You may reference other static content from your static HTML files similar to the following:

  <link href="./static/mystyle.css" rel="stylesheet" type="text/css"/>
  <img src="./static/images/static-image.gif" alt="Static image in /static/images/ directory"/>
  <img src="./static/static-image.jpg" alt="Static image in /static/ directory"/> 

Harvesting Items from XMLUI via OAI-ORE or OAI-PMH

...

1. Login to XMLUI and create a new collection.
2. Go to the tab named "Content Source" that appears next to "Edit Metadata" and "Assign Roles " in the collection edit screens.
3. The two "Content Source" options are "standard DSpace collection" (selected by default) and "collection harvests its content from an external source". Select "harvests from an external source" option and click Save.
4. A new set of menus appear to configure the harvesting settings:
   • "OAI Provider" is in the URL of the OAI-PMH provider that the content from this collection should be harvested from. The OAI-PMH provider deployed with DSpace typically has the format: http://dspace.url/oai/requestImage Removed For example, you could use the Demo DSpace OAI-PMH provider: "http://demo.dspace.org/oai/request"
   • "OAI Set Id" is the OAI-PMH setSpec of the collection you wish to harvest from. For DSpace, this Set ID has the format: hdl_<handle-prefix>_<handle-suffix>. For example "hdl_10673_2" would refer to the Collection whose handle is "10673/2" (on the DSpace Demo Server, this is the Collection of Sample Items)
   • "Metadata format" determines the format that the descriptive metadata will be harvested. The OAI-PMH server of the source DSpace instance may only support certain metadata formats. Select "DSpace Intermediate Metadata" if available (as this provides the richest metadata transfer) and "Simple Dublin Core" otherwise
     • To determine which metadata formats an OAI-PMH server supports, you can send a ListMetadataFormats request to that OAI-PMH server. Typically this has the format: http://dspace.url/oai/request?verb=ListMetadataFormatsImage Removed For example, you can see which metadata formats are supported by the DSpace Demo Server by visiting: http://demo.dspace.org/oai/request?verb=ListMetadataFormats^{Image Removed}
   • Click the "Test Settings" button to verify the settings supplied in the previous steps. This will usually let you know if anything is missing or does not validate correctly. If you receive an error, you will need to fix the settings before continuing
5. The list of radio buttons labeled "Content being harvested" allows you to select the level of harvest. These harvesting options include:
   • Harvest Metadata Only - will only harvest item metadata from the source DSpace (or any OAI-PMH source)
   • Harvest metadata and references to bitstreams (requires ORE support) - will harvest item metadata and create links to files/bitstreams (stored remotely) from the source DSpace (requires OAI-ORE)
   • Harvest metadata and bitstreams (requires ORE support) - performs a full local replication. Harvests both item metadata and files/bitstreams (requires OAI-ORE).
6. Select the appropriate option based on your needs, and click Save

...