SOAR_Manakin - SOAR Home
advertisement
BUILDING NEW INTERFACES FOR
SHOCKER OPEN ACCESS REPOSITORY
Sai Deng, Wichita State University Libraries
KLA-CULS Fall Conference 2010
SOAR
Manakin
interface @
WSU
Libraries
CUSTOMIZATIONS MADE
Header: Institution logo and banner
Footer: Text, links
Pages: Color scheme
Messages: Changed headings, news/messages
Navigation bar: Added “Share” section and “Information” Section
Static pages: Added “Help” files
Record view and bitstream display: Changed records summary
view label and bitstream link styles; changed “View” to
“View/Download” for bitstreams; switched bitstream label and field
data display order.
Structural changes: Disabled top left “login” button and “Search”
section on top of “Communities” in homepage
Font: Disabled font-sizing mechanism originally included
Additional aspects: Audio-visual streaming module, document
viewer, image zoomer (from @mire)…
Also experimented with community collapsing and expanding list,
themes for different communities and image collections. Disabled
these for the final interface due to various reasons.
TAKE A
SECOND
LOOK AT
THE
INTERFACE
ds-header
ds-div-head
ds-trail
content
sidebar
file_news_div_news
ds-share-option
ds-option-set
ds-paragrah
ds-search-option
aspect_artifactbrowser_Navigation_list_browse
ds-div-head
ds-option-set-head
Understand
page
structures
by looking
at element
ids and CSS
classes.
aspect_artifactbrowser_CommunityBrowser_div_comunity-browser
aspect_artifactbrowser_Navigation
_list_account_browse
ds-information-option
ds-footer
CREATE THE MANAKIN INTERFACE
Step 1: Find some documentations and presentations and
understand what Manakin is
Some resources to look at:
Some Manakin instances:
DSpace System Documentation: Manakin [XMLUI] Configuration and Customization
http://ir.uz.ac.zw/dspace/ch07.html
DSpace XMLUI-Manakin: https://wiki.duraspace.org/display/DSPACE/Manakin
NIS Camp: Developing Interfaces and Interactivity for DSpace with Manakin
http://nitlecamp.pbworks.com/f/manakin-workshop-slides.pdf
TDL training document: http://scott.phillips.name/wp-content/uploads/2009/05/tdlmanakin-training.pdf
Donohue, Tim. Making DSpace XMLUI Your Own
http://www.slideshare.net/tdonohue/making-dspace-xmlui-your-own
Gibson, Hilton. Asset Presentation http://ir.sun.ac.za/wiki/index.php/Asset_Presentation
Phillips, Scott. Manakin Developer's Guide.
http://drcdev.ohiolink.edu/handle/123456789/28
Texas A&M Repository http://repository.tamu.edu/
The Geologic Atlas of the United States http://repository.tamu.edu/handle/1969.1/2490
IDEALS @ UIUC https://www.ideals.illinois.edu/
ResearchSpace@Auckland http://researchspace.auckland.ac.nz/
Search “Who’s Using DSpace” and select “Manakin Themes” http://www.dspace.org/
Place to look for help:
DSpace community: DSpace Tech-list
WHAT IS MANAKIN?
XML-based DSpace user interface
Modular interface layer
Customizable on community, collection and item level
Built by Apache cocoon framework
Cocoon Pipeline model
(Figure from Manakin: A New Face for DSpace at:
http://www.dlib.org/dlib/november07/phillips/11phillips.html)
SOME MANAKIN CONCEPTS
Cocoon: a web development framework built around the concept of
pipeline, separation of concerns and a component-based architecture.
Sitemap: a set of XML files that configures the cocoon components.
Components: generators, transformers, serializers, matchers,
selectors, actions, readers
Pipeline defines components arrangement
Aspect: provides a set of coupled features for the system.
Theme: stylizes the content generated by Manakin.
DRI (Digital Repository Interface): schema governing the structure of
Manakin pages encoded in xml; has three top level elements: <meta>,
<body>, <options> contained inside <document>.
Aspect chain generates DRI document, theme stylizes the DRI document
and produces XHTML for display.
Concept definitions from “Manakin: Developer’s Guide” .
MANAKIN COMPONENT ARCHITECTURE/TIERS
Java/Cocoon development Tier
XML/XSL Theme Tier
Add or modify themes (structural changes)
HTML/CSS style Tier
Add or modify aspects (features)
Add or Modify themes (CSS changes)
Read “Manakin: Developer’s Guide” for details.
CREATE THE MANAKIN INTERFACE
Step 2: Navigate the file directories, locate the theme
templates and get to know how to make changes
Where are the theme templates?
(In Source version): [dspace-source]/dspace-xmlui/dspace-xmluiwebapp/src/main/webapp/themes
(In Release version, after run a maven build): [dspacesource]/dspace/target/dspace-1.6.2-build.dir/webapps/xmlui/themes/
At WSU Libraries:
DSpace system upgrade from 1.4.2 to 1.6.2 (1.5 only installed in a
test server);
Installed release version;
Source directory: [dspace-source]=/usr/local/src/dspace-1.6.2release
Running directory: [dspace]=/data/dspace
Where did we find the theme templates the first time:
data/dspace/webapps/xmlui/themes (in running DSpace)
Where did we copy the templates to: [dspacesource]/dspace/modules/xmlui/src/main/webapp/themes/
Theme customization needs to be done in the source directory.
XMLUI THEME OVERLAY
(From Donohue, Tim. Making DSpace XMLUI Your Own.
Available at http://www.slideshare.net/tdonohue/making-dspace-xmlui-your-own)
THEMES FILE STRUCTURE (@WSU L
IBRARIES)
Themes
themes.xmap
dri2xhtml.xsl
General-Handler.xsl
DIM-Handler.xsl
dri2xhtml
wsu/
localtheme
MODS-Handler.xsl
QDC-Handler.xsl
Reference
css
lib
structural.xsl
Kubrick
soarlogo.jpg
soarfooter.jpg
…
images
wsu/
localtheme
quickguide.htm
help.htm
…
static
lib
……
sitemap.xmap
wsu.xsl
images
…
sitemap.xmap
wsu.xsl
* wsu theme is based on Kubrick theme
HOW DOES THE THEME FIT INTO A BIGGER
PICTURE?
DRI to XHTML
Five steps in
processing aspect
content:
Generate the DRI
page (by aspects)
Add page metadata
Transform to XHTML
Localize the page
Serialize to the
browser
(Figure from TDL Manakin Training)
THEME SITEMAP
Configures cocoon components.
/themes/Reference/sitemap.xmap (Reference
theme sitemap)
/themes/Kubrick/sitemap.xmap (Kubrick theme
sitemap)
/themes/wsu/sitemap.xmap (Local theme
sitemap)
/themes/themes.xmap
General sitemap
ThemeMatcher
If matcher fails, default theme will be applied.
XSLT FILES
Convert DRI to XHTML.
/themes/dri2xhtml.xsl
/themes/dri2xhtml/structural.xsl
Bitstream display, file information
/themes/dri2xhtml/MODS-Handler.xsl
Items, collections, communities display
/themes/dri2xhtml/General-Handler.xsl
Structural components of a theme
/themes/dri2xhtml/DIM-Handler.xsl
Import other xsl files
MODS file
/themes/dri2xhtml/QDC-Handler.xsl
Qualified DC
ASPECTS
Aspects: search, browse, admin, e-person, submission…
Check DSpace wiki Manakin How To Guides for “how to create a
new aspect”;
For an example of overwriting the trail links, see the figure below:
(Figure from Donohue, Tim. Making DSpace XMLUI Your Own
http://www.slideshare.net/tdonohue/making-dspace-xmlui-your-own)
CREATE THE MANAKIN INTERFACE
Step 3: Decide on the template for testing
and/or modifying, identify some areas for
customization
Templates: Reference, Kubrick, Classic…
Decide on the parts which need customization:
Header, footer
Navigation bar
Homepage news/messages
Headings
Page structure, sections
Record display
…
TOOLS
Tools helping
in making CSS
changes and
identifying
page structure
and elements
Firefox
Firebug
IE 8
Developer
Tools
REBUILD DSPACE MANAKIN
Apache Maven and Ant
Commands to rebuild Manakin @WSU
Libraries:
cd /usr/local/src/dspace/dspace-1.6.2-release/dspace
mvn package
cd /usr/local/src/dspace/dspace-1.6.2release/dspace/target/dspace-1.6.2-build.dir
(ant -Dconfig=/data/dspace/config/dspace.cfg
init_configs)
ant -Dconfig=/data/dspace/config/dspace.cfg update
sudo /sbin/service tomcat5 restart
(Commands provided by Andy Speagle, Unix Administrator.)
CREATE THE MANAKIN INTERFACE
Step 4: Start create your local theme
Themes (*These theme print screens were taken after themes
were applied to different communities at a later testing stage at
WSU.)
Reference Theme
Classic Theme
CREATE THE LOCAL THEME
WSU theme is initially based on Reference
theme, then is changed to Kubrick theme (after
some internal feedback).
Create WSU theme based on Reference theme:
Copy themes folder to custom themes folder;
cd /data/dspace/webapps/xmlui/themes
cp –r themes /usr/local/src/dspace/dspace-1.6.2release/dspace/modules/xmlui/src/main/webapp/themes/
Create “wsu” theme folder (mkdir) under “themes”
based on Reference theme.
CREATE THE LOCAL THEME: MODIFY
XMLUI CONFIGURATION FILE
Modifiy XMLUI (Manakin) configuration file
Modify which theme should be applied to a particular URL
cd /usr/local/src/dspace/dspace-1.6.2-release/dspace/config
vi xmlui.xconf
<theme> attributes: name, id, regex, handle, path
Cascading: down to derivative directories
An example (<theme> section in xmlui.xconf):
<!-- test, Image gallery theme for pottery collections -->
<theme name="gallery" handle="10057/81" path="gallery/" />
<!-- test, Graduate School theme -->
<theme name="Gradschool" handle="10057/67"
path="Gradschool/"/>
<!-- WSU theme, local by default -->
<theme name="wsu" path="wsu/" regex=".*" />
CREATE THE LOCAL THEME: MODIFY
SITEMAP.XMAP
Modify local sitemap.xmap by changing “theme-path” and
“theme-name” to local ones.
For example:
<map:sitemap
xmlns:map="http://apache.org/cocoon/sitemap/1.0">
<map:pipelines>
<map:component-configurations>
<global-variables>
<theme-path>wsu</theme-path>
<theme-name>Wichita State University Libraries
theme</theme-name>
</global-variables>
</map:component-configurations>
…
</map:pipelines>
</map:sitemap>
CREATE THE LOCAL THEME: CUSTOMIZE
HEADER
Header: logo change
For reference theme test: change logo under images
folder and adjust css under lib folder;
cd \DSpace\dspace-1.6.2release\dspace\modules\xmlui\src\main\webapp\themes
\wsu\lib
vi style.css
div#ds-header a span#ds-header-logo {
…
background-image: url("../images/soarlogo.jpg");
}
For Kubrick theme, change kubrickheader and
kubrickfooter under lib/css folder and revise css as
well.
CREATE THE LOCAL THEME:
CUSTOMIZE HEADINGS AND MESSAGES
Heading text
cd
/usr/local/src/dspace/dspace-1.6.2release/dspace/modules/xmlui/src/main/webapp/i18n/
vi
messages.xml
Adjust heading styles in CSS.
Change messages text in messages.xml
Headings
Trail
message
Menu
header
Error
message
…
CREATE THE LOCAL THEME: CUSTOMIZE
FOOTER
Customize footer text and links
In Reference theme test, copy footer section from
structural.xsl to local.xsl and modify local.xsl.
For Kubrick theme, create local.xsl by modifying
Kubrick.xsl. Change footer text and add additional links to
local.xsl directly.
For example:
<xsl:template name="buildFooter">
<div id="footer">
…
<div id="ds-footer-links">
<a href="http://libraries.wichita.edu/">University Libraries</a>
<xsl:text> | </xsl:text>
<a href="http://www.wichita.edu/">Univeristy Home</a>
</div>
</div>…
</xsl:template>
CREATE THE LOCAL THEME: DISABLE
FONT-SIZING MECHANISM
Disable font-sizing mechanism.
“The font-sizing variable is the result of a linear function
applied to the character count of the heading text.”
It causes huge font display in some browsers and size
percentage for display needs to be adjusted in different
browsers.
Comment out font-sizing mechanism in structural.xsl
<!-- <xsl:template match="dri:div/dri:head" priority="3">
<xsl:variable name="head_count" select="count(ancestor::dri:div)"/> -->
<!-- with the help of the font-sizing variable, the font-size of our header
text is made continuously variable based on the character count -->
<!--<xsl:variable name="font-sizing" select="365 - $head_count * 160 string-length(current())"></xsl:variable>
…
</xsl:template> -->
CREATE THE LOCAL THEME: DISABLE
FONT-SIZING MECHANISM
Add the following section to local.xsl.
<!-- Overrides the default header -->
<xsl:template match="dri:div/dri:head" priority="3">
<xsl:variable name="head_count" select="count(ancestor::dri:div)"/>
<xsl:element name="h{$head_count}">
<xsl:call-template name="standardAttributes">
<xsl:with-param name="class">ds-div-head</xsl:with-param>
</xsl:call-template>
<xsl:apply-templates />
</xsl:element>
</xsl:template>
* Provided by DSpace Tech-list community.
Change body and heading text sizes to be fixed in
CSS files (when needed).
CREATE THE LOCAL THEME: ADD A
INFORMATION MENU FOR HELP FILES
Add custom code (adapted from UIUC’s code) to local.xsl to
provide an information block in the navigation menu.
If the search section is overwritten, copy “search” from
structural.xsl to local.xsl.
<xsl:template match="dri:options">
<div id="sidebar">
<h3 id="ds-search-option-head" class="ds-option-sethead"><i18n:text>xmlui.dri2xhtml.structural.search</i18n:text></h3>
…
<xsl:apply-templates />
<h3 class="ds-option-set-head">Information</h3>
<div id="ds-information-option" class="ds-option-set">
<ul class="ds-simple-list“>
<li><a>
<xsl:attribute name="href">
<xsl:text>quickguide.htm</xsl:text>
</xsl:attribute>
<i18n:text>Help</i18n:text>
</a></li>…
</ul>
</div>
CREATE THE LOCAL THEME: MORE
STRUCTURAL CHANGES
Disable top left “login” by modifying structual.xsl and commenting
out this section:
<!-- <xsl:choose>
<xsl:when
test="/dri:document/dri:meta/dri:userMeta/@authenticated = 'yes'">
<div id="ds-user-box">
….
</xsl:choose> -->
Remove front page search section (on top of the communities,
NOT the search box in the navigation menu)
Create a custom module folder:
/dspace/modules/xmlui/src/main/resources/aspects;
Copy ArtifactBrowser folder and its sitemap.xmap file from the sources
folder to the custom folder;
Comment out the following transformer in sitemap.xmap:
<map:transformer name=”FrontPageSearch”
src=”org.dspace.app.xmlui.aspect.artifactbrowser.FrontPageSearch” />
For details, refer to
http://ir.sun.ac.za/wiki/index.php/Asset_Presentation
CREATE THE LOCAL THEME:
CUSTOMIZE FRONT PAGE NEWS
Edit homepage main text at [DSpacesource]/dspace/config/news-xmlui.xml
XML DRI document
An Example:
<p>… Authors retain copyright to their own works
published/archived in SOAR (see <xref
target="http://webs.wichita.edu/inaudit/ch9_10.htm">Unive
rsity intellectual Property policy</xref>.) …</p>
For DRI information, go to “DRI Schema
Reference” at:
http://scm.dspace.org/svn/repo/dspace/tags/dspace1.5.2/dspace/docs/html.legacy/DRISchemaReference.html#DRI_in_Ma
nakin
CREATE THE LOCAL THEME: ADD
STATIC PAGES
Add static pages (help and about pages)
Create static webpages (check the structure and
markup of DSpace pages before starting the work);
Create “static” folder under local theme and Upload
the files to the “static” folder;
Modify static content section in local sitemap.xmap:
<map:match pattern="themes/*/**">
<map:read src="{2}"/>
</map:match>
<map:match pattern="*.htm">
<map:read src="static/{1}.htm" mime-type="text/html" />
</map:match>
CREATE THE LOCAL THEME: COLLAPSING AND
EXPANDING FEATURE FOR COMMUNITY LIST
Test on collapsing and expanding feature for community list
Documentation is at
https://wiki.duraspace.org/pages/viewpage.action?pageId=19006695
Some code can be found in Texas A&M’s IR site, check
http://repository.tamu.edu/handle/1969.1/2815
Implement with caution, extra customization may be needed
At WSU, add to local.xsl:
<xsl:template name="communitySummaryList-DIM">
<xsl:variable name="data"
select="./mets:dmdSec/mets:mdWrap/mets:xmlData/dim:dim"/>
<p class="ListPlus" style="display:none">[+]</p>
<p class="ListMinus">[-]</p>
…
</xsl:template>
Add jquery-1.3.2.min.js and menus.js to lib/;
Add the following lines to local sitemap.xmap for all browsers:
<map:parameter name="javascript#1" value="lib/jquery-1.3.2.min.js"/>
<map:parameter name="javascript#2" value="lib/menus.js"/>
Add css (from Texas A&M) to local.css:
p#expand_all_clicker,
p#collapse_all_clicker
…
CREATE THE LOCAL THEME: COLLAPSING AND
EXPANDING FEATURE FOR COMMUNITY LIST
Experiment at WSU
However we disabled this function because it stopped
statistics showing on the top level of the communities.
A TESTING RESULT: A COMMUNITY BASED ON
THE REFERENCE THEME
A TESTING RESULT: IMAGE GALLERY THEME
Image Gallery theme (http://dspace.nitle.org/handle/10090/12005)
“Includes a grid-view, popup metadata from grid view, and a
zoom-and-pan viewer on image view interface.”
See below for record view (CSS not fine adjusted) and zoom
effect
Not implemented to the final interface because we purchased
image zoom module from @mire.
A TESTING RESULT: GRADUATE SCHOOL
THEME
The Graduate School theme (based on Kubrick theme, use
Graduate School logo. Disabled in our final interface due to
confusion in branding.)
A TESTING RESULT: USE A DIFFERENT
BACKGROUND
Local theme with a darker background (based on Kubrick
theme)
CREATE THE LOCAL THEME: BROWSER TEST
Step 5: Initial Testing in different browsers
CSS customization and Browser test
Browser selector mechanism
Many browsers handle CSS in a more standard way
(e.g. Mozilla Firefox, Opera, Google Chrome…)
IE nightmare: IE8, IE7, IE6…
Many positioning problems (no big issues in other
browsers);
Define different stylesheets;
If encountering browser selector problems, use CSS
hacks (mainly IE hacks). For example:
color:brown\9; /* for all IE */
color:brown\0; /* IE8 only */
+color:red; /* IE7 only */ _
color:black; /* IE6 only */
FOCUS GROUP FEEDBACK
Step 6: Get feedback from the focus group
and admin office
Some feedback:
Make “title” and other labels in records summary
view more prominent;
Change “View” to “View/Download” in bitstream table
and make the link more obvious;
Change the order of bitstream table headers;
Change “DSpace” labels to “SOAR”;
“Send records to my Facebook”;
Add statistics number on the top level of the
communities;
Delete “[+]” in front of the communities when there is
only one level of community in homepage…
RECORD SUMMARY VIEW LABELS
Make record summary view labels more prominent.
Identified the element in MODS-Handler.xsl:
<!-- Generate the info about the item from the metadata section -->
<xsl:template match="mods:mods" mode="itemSummaryViewMODS">
<table class="ds-includeSet-table">
<tr class="ds-table-row odd">
<td><span class="bold"><i18n:text>xmlui.dri2xhtml.METS1.0.item-preview</i18n:text>:</span></td>…
</tr>
</table>
…
Add link style in CSS for “.ds-table a” and “span.bold”.
MESSAGES CHANGE
Changes made in messages.xml:
Adjust “show full item records” to “show Complete
item records” in record summary view;
Modify “All of DSpace” to “All of SOAR”;
Chang bitstream table lable “View” to
“View/Download”
<message key="xmlui.dri2xhtml.METS-1.0.item-filesview">View/Download</message>
Discuss adding various file type logos under
“Format” label in bitstream table (not
investigated due to time constrain).
BITSTREAM TABLE LABEL ORDER
Move “description” before “view” in bitstream table
Copy sections of code from General-Handler.xsl to wsu.xsl
and modify label and table cell content order accordingly
<!-- Generate the bitstream information from the file section -->
<xsl:template match="mets:fileGrp[@USE='CONTENT']">
….
<h2><i18n:text>xmlui.dri2xhtml.METS-1.0.item-files-head</i18n:text></h2>
<table class="ds-table file-list">
<tr class="ds-table-header-row">
<th><i18n:text>xmlui.dri2xhtml.METS-1.0.item-filesfile</i18n:text></th>…
<th><i18n:text>xmlui.dri2xhtml.METS-1.0.item-filesview</i18n:text></th>
</tr>…
</xsl:template>
<!-- Generate the bitstream information from the file section -->
<xsl:template match="mets:file">
<xsl:param name="context" select="."/>
<tr>…
<td>…</td>
…
</tr>…
</xsl:template>
STATISTICS NUMBER DISPLAY AND
EXPANDING MENU FOR COMMUNITY LIST
Add statistics numbers by changing configuration
file (dspace.cfg);
With the community collapsing and expanding
feature on, the statistics numbers do not show up
in the top community level and a “[+]” displays in
front of each community even when there is only
one level;
We disabled the collapsing and expanding menu.
If keeping it, more customization will need to be
done.
“SENT TO MY FACEBOOK”
Code provided by
Stuart Lewis
@Auckland
Code added to
structural.xsl (in
our case, local.xsl
since we modified
the sidebar menu)
For code and
potential
implementation
issues, see this
thread at
http://www.mailarchive.com/dspacetech@lists.sourceforge.n
et/msg12281.html
“SENT TO MY FACEBOOK”
Cocoon caching and browser selector problems
experienced at WSU
Force IE browsers to display the content correctly by
adding CSS hacks to the main CSS. See the previous
thread.
Send a link to
Facebook
SOME THOUGHTS ABOUT MANAKIN
Good things about Manakin:
Community and collection branding
Make it possible for department pages in DSpace to be consistent
to the department website (if preferred)
Make it possible for faculty collection pages in DSpace to be
consistent to the faculty website (if requested)
Special visual effect and structural layout for some collections (e.g.
images, maps)
Allow sharing of modular extensions and new features…
Some discussion on Manakin in DSpace Tech-list from the
design perspective:
Track the “Manakin questions” thread (e.g. http://www.mailarchive.com/dspace-tech@lists.sourceforge.net/msg12292.html)
Templates are not associated with individual pages;
Templating approach is more confusing than it is in other systems;
Structural.xsl is huge and hard to modify;
Program processing flow is not easy to follow;
Is DRI layer necessary?
Evaluation of Manakin needed…
SOME REFLECTIONS ON THE PROJECT
The upgrade of DSpace at WSU Libraries is a team work
of the IR Librarian, the Unix Administrator, the DSpace
Tech Support and the Metadata Librarian.
How can Manakin truly enhance an IR’s interfaces
without great effort and time spent?
How to best utilize the human resources when a developer
team is not available in a small or medium sized
institution?
The Metadata Librarian’s Manakin experience: sharp
learning curve, not too easy but rewarding
Always find inspirations and good practices from other
institutions;
Look for help from Systems people and DSpace
community.
PROJECT TEAM INFORMATION AND
ACKNOWLEDGEMENTS
Coordinator: Susan Matveyeva, WSU Libraries
Administrative Support: Kathy Downes, WSU Libraries
Metadata Catalog Librarian: Sai Deng, WSU Libraries
DSpace Tech Support: Baseer Khan, WSU Libraries
Unix Administrator: Andy Speagle, WSU Computing
Center
Thanks DSpace community developers who either wrote
the code or answered our Manakin questions: Hardy
Pottinger from UM, Tim Donohue & Bill Ingram from
UIUC, Stuart Lewis from Auckland and Hilton Gibson
from Stellenbosch…
