Date: Thu, 28 Mar 2024 21:26:42 -0400 (EDT) Message-ID: <1466789083.29378.1711675602518@lyrasis1-roc-mp1> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_29377_514917228.1711675602518" ------=_Part_29377_514917228.1711675602518 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
The DSpace digital repository supports two user interfaces: one = based on JavaServer Pages (JSP) technologies and one based upon the Apache = Cocoon framework (XMLUI). This chapter describes those parameters which are= specific to the Manakin (XMLUI) interface based upon the Cocoon framework.=
For more information & diagrams
For a more detailed overview of XMLUI/Manakin, see the following resourc= es:
The XMLUI (aka Manakin) is built on Apache Cocoon framework. The= XMLUI uses Cocoon to provide a modular, extendable, tiered interface frame= work
The XMLUI essentially consists of three main tiers, in increasing order = of complexity:
These tiers are very important and powerful because of their modularity.= For example, based on your local expertise with these technologies, your i= nstitution may decide to only modify the XMLUI at the "Style Tier" (by just= modifying CSS & images in an existing theme). As you learn more about = themes & aspects, you may decide to slowly venture into the more comple= x "Theme Tier" and finally into the "Aspect Tier". Other institutions may d= etermine that all they really need to ever do is make "Style Tier" changes.=
Digging in a little deeper, there are three main XMLUI components that a= re unique to the XMLUI and used throughout the system. These main component= s are:
One of the harder things to initially grasp in the XMLUI is how a single= user's request (e.g. clicking on a link or button) flows through the entir= e system of enabled Aspects and Themes. Understanding this flow is also ver= y important as you work to build your own Aspects (or complex Themes), as i= t may allow you to more easily determine what is going on in the system.
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 t= he flow. More information about Cocoon Sitemaps is available at: http://cocoon.apache.org/2.1/userdocs/concept= s/sitemap.html
The following explanation provides a high level overview of how a reques= t 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 overvie= w, some details are likely left out, but the overarching flow is what is mo= st important.
sitemap.xmap
(locat=
ed at [xmlui]/sitemap.xmap
). This is the main entry point for =
all requests
[xmlui]/themes/the=
mes.xmap
file, which controls all the Themes.=20
themes.xmap
file will then load all "matching" themes =
which are configured in your [dspace]/config/xmlui.xconf
file =
(see #Themes bel=
ow).sitemap.xmap
file (located in its theme directory) is loaded and processed.=20
The theme's sitemap.xmap
is in charge of actually loadi=
ng 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 follow=
s:
<map= :generate type=3D"file" src=3D"cocoon://DRI/{1}"/>
sitemap.xmap<=
/code> (remember how we said that this sitemap is the main entry point for =
all requests).
[xmlui]/aspects/aspects.xmap
file to be loaded. As the name s=
uggests, this file obviously controls all the Aspects.=20
aspects.xmap
file will then load all enabled Aspects w=
hich are configured in your [dspace]/config/xmlui.xconf
file (=
see #Aspects be=
low).sitemap.xmap
is loaded &=
processed=20
dspa=
ce-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]/
xmlui.xconf
). Each aspect may add, remove or change conten=
t within the DRI document. After the final aspect is finished processing, t=
he DRI document is complete.=20
sitemap.xmap
(re=
member, this is the same location that triggered the loading of the Aspects=
in the first place).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.
Again, the above flow is a slightly simplified version of what is going = on underneath the XMLUI. As you can see, Cocoon Sitemaps are what control most of the XMLUI processing (and = the loading of the Aspects and Theme).
In an effort to save the programmer/administrator some time, the configu= ration table below is taken from 5.3.43. XMLUI Specific Configuration= em>.
Property: |
xmlui.supportedLocales |
Example Value: |
xmlui.supportedLocales =3D en, de |
Informational Note: |
A list of supported locales for Manakin. Mana= kin will look at a user's browser configuration for the first language that= appears in this list to make available to in the interface. This parameter= is a comma separated list of Locales. All types of Locales country, countr= y_language, country_language_variant. Note that if the appropriate files ar= e not present (i.e. Messages_XX_XX.xml) then Manakin will fall back through= to a more general language. |
Property: |
xmlui.force.ssl |
Example Value: |
xmlui.force.ssl =3D true |
Informational Note: |
Force all authenticated connections to use SS= L, only non-authenticated connections are allowed over plain http. If set t= o true, then you need to ensure that the 'dspace.hostname' paramet= er is set to the correctly. |
Property: |
xmlui.user.registration |
Example Value: |
xmlui.user.registration =3D true = |
Informational Note: |
Determine if new users should be allowed to r= egister. This parameter is useful in conjunction with Shibboleth where you = want to disallow registration because Shibboleth will automatically registe= r the user. Default value is true. |
Property: |
xmlui.user.editmetadata |
Example Value: |
xmlui.user.editmetadata =3D true = |
Informational Note: |
Determines if users should be able to edit th= eir own metadata. This parameter is useful in conjunction with Shibboleth w= here you want to disable the user's ability to edit their metadata because = it came from Shibboleth. Default value is true. |
Property: |
xmlui.user.assumelogin |
Example Value: |
xmlui.user.assumelogin =3D true <= /td> |
Informational Note: |
Determine if super administrators (those whom= are in the Administrators group) can login as another user from the "edit = eperson" page. This is useful for debugging problems in a running dspace in= stance, especially in the workflow process. The default value is false, i.e= ., no one may assume the login of another user. |
Property: |
xmlui.user.loginredirect |
Example Value: |
xmlui.user.loginredirect =3D /profile |
Informational Note: |
After a user has logged into the system, whic= h url should they be directed? Leave this parameter blank or undefined to d= irect users to the homepage, or /profile for the user's profile, o= r another reasonable choice is /submissions to see if the user has= any tasks awaiting their attention. The default is the repository home pag= e. |
Property: |
xmlui.theme.allowoverrides |
Example Value: |
xmlui.theme.allowoverrides =3D false= |
Informational Note: |
Allow the user to override which theme is use= d to display a particular page. When submitting a request add the HTTP para= meter "themepath" which corresponds to a particular theme, that specified t= heme will be used instead of the any other configured theme. Note that this= is a potential security hole allowing execution of unintended code on the = server, this option is only for development and debugging it should be turn= ed off for any production repository. The default value unless otherwise sp= ecified is "false". |
Property: |
xmlui.bundle.upload |
Example Value: |
xmlui.bundle.upload =3D ORIGINAL, METADAT= A, THUMBNAIL, LICENSE, CC_LICENSE |
Informational Note: |
Determine which bundles administrators and co= llection administrators may upload into an existing item through the admini= strative interface. If the user does not have the appropriate privileges (a= dd and write) on the bundle then that bundle will not be shown to the user = as an option. |
Property: |
xmlui.community-list.render.full = |
Example Value: |
xmlui.community-list.render.full =3D true= |
Informational Note: |
On the community-list page should all the met= adata about a community/collection be available to the theme. This paramete= r defaults to true, but if you are experiencing performance problems on the= community-list page you should experiment with turning this option off. |
Property: |
xmlui.community-list.cache |
Example Value: |
xmlui.community-list.cache =3D 12 hours= em> |
Informational Note: |
Normally, Manakin will fully verify any cache= pages before using a cache copy. This means that when the community-list p= age is viewed the database is queried for each community/collection to see = if their metadata has been modified. This can be expensive for repositories= with a large community tree. To help solve this problem you can set the ca= che to be assumed valued for a specific set of time. The downside of this i= s that new or editing communities/collections may not show up the website f= or a period of time. |
Property: |
xmlui.bistream.mods |
Example Value: |
xmlui.bistream.mods =3D true |
Informational Note: |
Optionally, you may configure Manakin to take= advantage of metadata stored as a bitstream. The MODS metadata file must b= e inside the "METADATA" bundle and named MODS.xml. If this option is set to= 'true' and the bitstream is present then it is made available to the theme= for display. |
Property: |
xmlui.bitstream.mets |
Example Value: |
xmlui.bitstream.mets =3D true |
Informational Note: |
Optionally, you may configure Manakin to take= advantage of metadata stored as a bitstream. The METS metadata file must b= e inside the "METADATA" bundle and named METS.xml. If this option is set to= "true" and the bitstream is present then it is made available to the theme= for display. |
Property: |
xmlui.google.analytics.key |
Example Value: |
xmlui.google.analytics.key =3D UA-XXXXXX-= X |
Informational Note: |
If you would like to use google analytics to = track general website statistics then use the following parameter to provid= e your analytics key. First sign up for an account at http://analytics.google.com, then create an entr= y for your repositories website. Google Analytics will give you a snipit of= javascript code to place on your site, inside that snip it is your Google = Analytics key usually found in the line: _uacct =3D "UA-XXXXXXX-X" Take thi= s key (just the UA-XXXXXX-X part) and place it here in this parameter. <= /td> |
Property: |
xmlui.controlpanel.activity.max <= /td> |
Example Value: |
xmlui.controlpanel.activity.max =3D 250= em> |
Informational Note: |
Assign how many page views will be recorded a= nd displayed in the control panel's activity viewer. The activity tab allow= s an administrator to debug problems in a running DSpace by understanding w= ho and how their DSpace is currently being used. The default value is 250.<= /p> |
Property: |
xmlui.controlpanel.activity.ipheader= |
Example Value: |
xmlui.controlpanel.activity.ipheader =3D = X-Forward-For |
Informational Note: |
Determine where the control panel's activity = viewer receives an events IP address from. If your DSpace is in a load bala= nced environment or otherwise behind a context-switch then you will need to= set the parameter to the HTTP parameter that records the original IP addre= ss. |
The Manakin user interface is composed of two distinct components: a= spects and themes. Manakin aspects are like extensions or plu= gins for Manakin; they are interactive components that modify existing feat= ures or provide new features for the digital repository. Manakin themes sty= lize the look-and-feel of the repository, community, or collection.
The repository administrator is able to define which aspects and themes = are installed for the particular repository by editing the [dspace]/con= fig/xmlui.xconf configuration file. The xmlui.xconf file cons= ists of two major sections: Aspects and Themes.
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 featur= es to the interface. For example, if the "submission" aspect were to be com= mented out or removed from the xmlui.xconf, then users would not b= e 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 u= sed to identify the Aspect, while the path determines the directory where t= he aspect's code is located. Here is the default aspect configuration:
<asp= ects> <aspect name=3D"Displaying Artifacts" path=3D"resource://aspects= /ViewArtifacts/" /> <aspect name=3D"Browsing Arti= facts" path=3D"resource://aspects/BrowseArtifacts/" /> <aspect name=3D"Searching Art= ifacts" path=3D"resource://aspects/SearchArtifacts/" /> <aspect name=3D"Administratio= n" path=3D"resource://aspects/Administrative/" /> <aspect name=3D"E-Person" pat= h=3D"resource://aspects/EPerson/" /> <aspect name=3D"Submission an= d Workflow" path=3D"resource://aspects/Submission/" /> <aspect name=3D"Statistics" path= =3D"resource://aspects/Statistics/" /> <aspect name=3D"Original Workflow"= path=3D"resource://aspects/Workflow/" /> </aspects>
A standard distribution of Manakin/DSpace includes eight "core" aspects:=
Following Aspects are optional
Following Aspects are deprecated and shouldn't be used anymore at all
The <themes> section defines a set of "rules" that determ= ine 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:
handle (either regex and/or handle is required<=
/em>)The handle attribute determines which community, collection, or item t=
he theme should apply to.
If you use the "handle" attribute, the effect is cascading, meaning if a r=
ule is established for a community then all collections and items within th=
at community will also have this theme apply to them as well. Here is an ex=
ample configuration:
<the= mes> <theme name=3D"Theme 1" handle=3D"123456789/23" path=3D"theme1/"= /> <theme name=3D"Theme 2" regex=3D"community-list"=09path=3D"theme= 2/"/> <theme name=3D"Reference Theme" regex=3D".*" path=3D"Reference/"= /> </themes>
In the example above three themes are configured: "Theme 1", "Them= e 2", and the "Reference Theme". The first rule specifies that "Theme 1" wi= ll apply to all communities, collections, or items that are contained under= the parent community "123456789/23". The next rule specifies any URL conta= ining 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.
The XMLUI user interface supports multiple languages through the use of = internationalization catalogues as defined by the Cocoon Inte= rnationalization Transformer. Each catalog contains the translation of = all user-displayed strings into a particular language or variant. Each cata= log is a single xml file whose name is based upon the language it is design= ated for, thus:
messages_language_country_variant.xml
messages_language_country.xml
messages_language.xml
messages.xml
The interface will automatically determine which file to select based up=
on the user's browser and system configuration. For example, if the user's =
browser is set to Australian English then first the system will check if
DSpace XMLUI supplies an English only translation of the interface, whic=
h can be found in the XMLUI web application ([dspace]/webapps/xmlui/i=
18n/messages.xml
), after you first build DSpace.
If you wish to add other translations to the system, or make customizati= ons to the existing messages.xml file, you can place them in the following = directory:
[dspace= -source]/dspace/modules/xmlui/src/main/webapp/i18n/
After rebuilding DSpace, any messages files placed in this directory wil= l be automatically included in the XMLUI web application (and files of the = same name will override any default files). By default this full directory = path may not exist (if not, just create it) or may be empty. You can place = any number of translation catalogues in this directory. To add additional t= ranslations, just add alternative versions of the messages.xml fil= e in specific language and country variants as needed for your installation= .
To set a language other than English as the default language for the rep= ository's interface, you can simply rename the translation catalogue for th= e new default language to "messages.xml".
Again, note that you will need to rebuild DSpace for these changes t= o take effect in your installed XMLUI web application!
For more information about the [dspace-source]/dspace/modules/ directory, and how it may be used to "overlay" (or customize) the defau=
lt XMLUI interface, classes and files, please see: Advanced Customisation
Manakin themes stylize the look-and-feel of the repository, community, o=
r collection and are distributed as self-contained packages. A Manakin/DSpa=
ce 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 s=
uch 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 n=
ew theme simply copy the theme template into your locally defined modules d=
irectory, [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>
<glo= bal-variables> <theme-path>[your theme's =09directory]</theme-path> <theme-name>[your theme's name]</theme-name> </global-variables>
Update both the theme's path to the directory name you created in step o=
ne. The theme's name is used only for documentation.
3) Add your=
CSS stylesheets
The base theme template will produce a repository interface without any st=
yle - just plain XHTML with no color or formatting. To make your theme usef=
ul you will need to supply a CSS Stylesheet that creates your desired look-=
and-feel. Add your new CSS stylesheets:
[your theme's directory]/lib/style.css (The base style sheet us= ed for all browsers)
[your theme's directory]/lib/style-ie.css (Specific stylesheet =
used for internet explorer)
4) Install theme and rebuild DSpace<=
/strong>
Next rebuild and deploy DSpace (replace <version> with the your curr=
ent release):
Rebuild the DSpace installation package by running the following com= mand from your [dspace-source]/dspace/ directory:
mvn pac= kage
Update all DSpace webapps to [dspace]/webapps by running th= e following command from your [dspace-source]/dspace/target/dspace-[ver= sion]-build.dir directory:
ant -Dc= onfig=3D[dspace]/config/dspace.cfg update
Deploy the the new webapps:
cp -R /= [dspace]/webapps/* /[tomcat]/webapps
The XMLUI "news" document is only shown on the root page of your reposit= ory. It was intended to provide the title and introductory message, but you= may use it for anything.
The news document is located at [dspace]/dspace/config/news-xmlui.xm= l. There is only one version; it is localized by inserting "i18n" call= outs into the text areas. It must be a complete and valid XML DRI document = (see Chapter 15).
Its (the News document) exact rendering in the XHTML UI depends, of cour= se, on the theme. The default content is designed to operate with the refer= ence themes, so when you modify it, be sure to preserve the tag structure a= nd e.g. the exact attributes of the first DIV tag. Also note that the text = is DRI, not HTML, so you must use only DRI tags, such as the XREF tag to co= nstruct a link.
Example 1: a single language:
<doc= ument> <body> <div id=3D"file.news.div.news" n=3D"news" rend=3D"primary"> <head> TITLE OF YOUR REPOSITORY HERE </head> <p> INTRO MESSAGE HERE Welcome to my wonderful repository etc etc ... A service of <xref target=3D"http://myuni.edu/">My Univer= sity</xref> </p> </div> </body> <options/> <meta> <userMeta/> <pageMeta/> <repositoryMeta/> </meta> </document>
Example 2: all text replaced by references to localizable message keys:<= /p>
<doc= ument> <body> <div id=3D"file.news.div.news" n=3D"news" rend=3D"primary"> <head><i18n:text>myuni.repo.title</i18n:text>&l= t;/head> <p> <i18n:text>myuni.repo.intro</i18n:text> <i18n:text>myuni.repo.a.service.of</i18n:text> <xref target=3D"http://myuni.edu/"><i18n:text>myuni= .name</i18n:text></xref> </p> </div> </body> <options/> <meta> <userMeta/> <pageMeta/> <repositoryMeta/> </meta> </document>
The XMLUI user interface supports the addition of globally static conten= t (as well as static content within individual themes).
Globally static content can be placed in the [dspace-source]/dspace/= modules/xmlui/src/main/webapp/static/ directory. By default this direc= tory only contains the default robots.txt file, which provides hel= pful site information to web spiders/crawlers. However, you may also add st= atic HTML (*.html) content to this directory, as needed for your i= nstallation.
Any static HTML content you add to this directory may also reference sta= tic content (e.g. CSS, Javascript, Images, etc.) from the same [dspace-= source]/dspace/modules/xmlui/src/main/webapp/static/ directory. You ma= y reference other static content from your static HTML files similar to the= following:
<lin= k href=3D"./static/mystyle.css" rel=3D"stylesheet" type=3D"text/css"/> <img src=3D"./static/images/static-image.gif" alt=3D"Static image in /= static/images/ directory"/> <img src=3D"./static/static-image.jpg" alt=3D"Static image in /static/= directory"/>
This feature allows you to harvest Items (both metadata and bitstreams) = from one DSpace to another DSpace or from one OAI-PMH/OAI-ORE server to a D= Space instance.
This section will give the necessary steps to set up the OAI-ORE/OAI-PMH= Harvester from the XMLUI (Manakin). This feature is currently not availabl= e in the JSPUI.
Setting up a Harvesting Collection:
http://dspace.url/oai/=
request
For example, you could use the Demo DSpace OAI-PMH provi=
der: "http://demo.dspace.org/oai/request"hdl_<handle-prefix>_<handle-suffix>. For example "hdl_10673_2" would refer to the Collection whose handle i=
s "10673/2" (on the DSpace Demo Server, this is the C=
ollection of Sample Items)
ListM=
etadataFormats
request to that OAI-PMH server. Typically this ha=
s the format: http://dspace.url/oa=
i/request?verb=3DListMetadataFormats
For example, you can see wh=
ich metadata formats are supported by the DSpace Demo Server by visiting: <=
a class=3D"external-link" href=3D"http://demo.dspace.org/oai/request?verb=
=3DListMetadataFormats" rel=3D"nofollow">http://demo.dspace.org/oai/request=
?verb=3DListMetadataFormatsAt this point the settings are saved and the menu changes to provide thr= ee options:
Import Now : performs a single harvest from the remote coll= ection into the local one. Success, notes, and errors encountered in the pr= ocess will be reflected in the "Last Harvest Result" entry. More detailed i= nformation is available in the DSpace log.
"Import Now" May Timeout for Large Har= vests
Note that the whole harvest cycle is executed within a single HTTP reque= st and will time out for large collections. For this reason, it is advisabl= e to use the automatic harvest scheduler set up either in XMLUI or = from the command line. If the scheduler is running, "Import Now" will handl= e the harvest task as a separate thread.
Setting up automatic harvesting in the Control Panel Screen.
dspace.c=
fg
using the harvester.harvestFrequency
parameter.Useful links with further information into XMLUI Development