Page History
Mirage Theme Configuration and Customization
Table of Contents | ||||||
---|---|---|---|---|---|---|
|
Introduction
Mirage is a new XMLUI theme, added in DSpace 1.7 by @mire. The code was mainly developed by Art Lowel. The main benefits of Mirage are:
Excerpt | ||
---|---|---|
| ||
@mire contribution of new theme to support easier development and branding.Provides the following: (1) Mirage, a basic theme that contains the templates that need customization most often in the UI. (2) A Restructured dri2xhtml base templates for easing locating specific XSLT templates. |
Mirage XMLUI Theme
...
- Clean new look and feel.
- Increased browser compatibility. The whole theme renders perfectly in today's modern browsers (Internet Explorer 7 and higher, Firefox, Safari, Chrome, ...)
- Easier to customize.
- Enhanced Performance
Configuration Parameters
Property | Name Default Value | Type | Description | solr.log.server | ${dspace.baseUrl}/solr/statistics | String | Is used by the SolrLogger Client class to connect to the Solr server over http and perform updates and queries. In most cases, this can (and should) be set to localhost (or 127.0.0.1).
---|
Code Block |
---|
wget http://127.0.0.1/solr/statistics/select?q=*:* |
Assuming you get an HTTP 200 OK response, then you should set solr.log.server
to the '/statistics' URL of 'http://127.0.0.1/solr/statistics' (essentially removing the "/select?q=:" query off the end of the responding URL.)
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="706ff77d-79de-483d-a11a-b0bd3bc2751d"><ac:plain-text-body><![CDATA[
solr.spiderips.urls
Code Block |
---|
http://iplists.com/google.txt, \
http://iplists.com/inktomi.txt, \
http://iplists.com/lycos.txt, \
http://iplists.com/infoseek.txt, \
http://iplists.com/altavista.txt, \
http://iplists.com/excite.txt, \
http://iplists.com/misc.txt, \
http://iplists.com/non_engines.txt
|
String
]]></ac:plain-text-body></ac:structured-macro>
The "stats-util" command can be used to force an update of spider files, regenerate "isBot" fields on indexed events, and delete spiders from the index. For usage, run:
Code Block |
---|
dspace stats-util -h
|
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="27338682-a8d1-4004-a716-5a5186f79aa0"><ac:plain-text-body><![CDATA[from your [dspace]/bin directory
]]></ac:plain-text-body></ac:structured-macro>
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="95342ec1-9b18-4d93-ad9e-9bb611c9cfda"><ac:plain-text-body><![CDATA[
solr.dbfile
${dspace.dir}/config/GeoLiteCity.dat
String
The following referes to the GeoLiteCity database file utilized by the LocationUtils to calculate the location of client requests based on IP address. During the Ant build process (both fresh_install and update) this file will be downloaded from [http://www.maxmind.com/app/geolitecity] if a new version has been published or it is absent from your [dspace]/config directory.
]]></ac:plain-text-body></ac:structured-macro>
solr.resolver.timeout
200
Integer
Timeout in milliseconds for DNS resolution of origin hosts/IPs. Setting this value too high may result in solr exhausting your connection pool.
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="b889b4ba-25d2-4c3b-80b3-b091faabe1b6"><ac:plain-text-body><![CDATA[
useProxies
true
boolean
Will cause Statistics loging to look for X-Forward URI to detect clients IP that have accessed it through a Proxy service. Allows detection of client IP when accessing DSpace. [Note: This setting is found in the DSpace Logging sesction of dspace.cfg]
]]></ac:plain-text-body></ac:structured-macro>
statistics.item.authorization.admin
true
boolean
Enables access control restriction on DSpace Statistics pages, Restrictions are based on access rights to Community, Collection and Item Pages. This will require the user to sign on to see that statistics. Setting the statistics to "false" will make them publicly available.
solr.statistics.logBots
true
boolean
If false, and IP is detected as a spider, the event is not logged.
If true, the event will be logged with the "isBot" field set to true.
(see solr.statistics.query.filter.* for query filter options)
solr.statistics.query.filter.spiderIp
false
boolean
If true, statistics queries will filter out spider IPs -- use with caution, as this often results in extremely long query strings.
:
xmlui.theme.mirage.item-list.emphasis
Example Value:
xmlui.theme.mirage.item-list.emphasis = metadata
Informational Note:
Determines which style should be used to display item lists. Allowed values:
- metadata: includes item abstracts in the listing and is suited for scientific articles.
- file: immediately shows you whether files are attached to the items, by displaying a large thumbnail icon for each of the items.
metadata is the default value.
Property:
xmlui.theme.enableConcatenation
Example Value:
xmlui.theme.enableConcatenation = false
Informational Note:
Allows to enable concatenation for .js and .css files. Enhances performance when enabled by lowering the number of files that needs to be sent to the client per page request (as multiple files will be concatenated together and sent as one file). Value can be true or false. False by default.
Property:
xmlui.theme.enableMinification
Example Value:
xmlui.theme.enableMinification = false
Informational Note:
Allows to enable minification for .js and .css files. Enhances performance when enabled by removing unnecessary whitespaces and other characters, thus reducing the size of files to be sent. Value can be true or false. False by default
solr.statistics.query.filter.isBot
true
boolean
If true, statistics queries will filter out events flagged with the "isBot" field. This is the recommended method of filtering spiders from statistics.
Technical Features
Look & Feel
...
- Based on the new restructured dri2xhtml base templates. Templates in the theme, overriding the new base templates, are located in the same folder hierarchy to ensure full transparancytransparency.
- Automated browser feature detection for improved browser compatibility.
- In other themes, user agent detection is used to identify which browser version your user is using. Based on the result of this detection, the theme would use a different cascaded style sheet (CSS) to render a compatible page for the visitor. This approach has 2 major issues:
- User agent detection isn't very reliable
- Maintaining these different CSS files is a maintenance nightmare for developers, especially when using features from newer browsers.
- Mirage applies two novel techniques to resolve these issues
- For compatibility with older Internet Explorer browsers, conditional comments give the body tag a class corresponding to the version of IE
- modernizr is used to detect which css features are available in the user's browser. This way you can target all browsers that support a certain feature using css classes, and rules affecting the same element can be put together in the same place for all browsers.
- In other themes, user agent detection is used to identify which browser version your user is using. Based on the result of this detection, the theme would use a different cascaded style sheet (CSS) to render a compatible page for the visitor. This approach has 2 major issues:
- CSS files are now split up according to function instead of browser. style.css will now fit most needs for customization. Following additional CSS files are included, but will rarely need to be changed:
- reset.css ensures that browser-specific initializations are being reset.
- base.css contains a few base styles
- helper.css contains helper classes to deal with specific functionality.
- handheld.css and print.css enable you to define styles for handheld devices and printing of pages.
- jQuery and jQueryUI are included by default. To avoid conflicts the authority control javascript has been rewritten to use jQuery instead of Prototype and Script.aculo.us.
...
- Concatenation and Minification techniques for css and js files.
- The IncludePageMeta has been extended to generate URL's to the concatenated version of all css files using the same media tag.
- The ConcatenationReader has been created to return concatenated and minified versions of the css and js files.
- Once js and css files have been minified and concatenated, they are being properly cached. As a result, the minification and concatenation operations only need to happen once, and do not include performance overhead.
- Caution: when minification is enabled, all code-comments will be removed. This could be a problem for comments containing copyright notices, so for files with those comments you should disable minification by adding '?nominify' after the url e.g.
<map:parameter name="javascript" value="lib/js/jquery-ui-1.8.5.custom.min.js?nominify"/> - Disabled by default, these features need to be enabled in the configuration using the properties 'xmlui.theme.enableConcatenation' and 'xmlui.theme.enableMinification'
- These features can be enabled for other themes as well, but will require an alteration of the theme's sitemap.
- Javascript references are included at the bottom of the page instead of the top. This optimizes page load times in general.
Troubleshooting
Errors using HTTPS
DSpace 1.7.0 ships with a hardcoded http:// link for JQuery, causing problems for users running 1.7.0 Mirage on HTTPS. While awaiting the implementation of this fix in an upcoming release, you can solve in the following file: lib/core/page-structure.xsl, addJavascript template. In this file, you will need to replace
Code Block |
---|
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"> </script>
|
with
Code Block |
---|
<script type="text/javascript">
<xsl:text disable-output-escaping="yes">var JsHost = (("https:" == document.location.protocol) ? "https://" : "http://");
document.write(unescape("%3Cscript src='" + JsHost + "ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js' type='text/javascript'%3E%3C/script%3E"));</xsl:text>
</script>
|
Thanks Peter Dietz for providing this fix. Note: This issue is resolved in 1.7.1