Veridian customization guide

Table of Contents

1. Veridian™ customisation
1.1. Configuration files
1.2. Macros
2. Functionality
2.1. Changing to single publication mode
2.2. Changing the document view style
2.3. Configuring the images generated by the imageserver
2.4. Adding a content type filter to the Advanced Search options
2.5. Adding a language selector
2.6. Improving search engine harvesting
3. Document structure
3.1. Making illustrations separate articles (newspaper documents only)
3.2. Making tables separate articles (newspaper documents only)
3.3. Displaying page headings in the document table of contents
4. Interface look and feel
4.1. Adding your organisation’s logo
4.2. Changing colours and fonts
5. Interface text
5.1. Changing the text appearing in the browser title bar
5.2. Changing the text on the home page
5.3. Changing the user interface to refer to “books” instead of “issues”, and “chapters” instead of “articles”


1. Veridian™ customisation

Veridian™ is set up with sensible defaults for most situations, but there are many ways to customise how a Veridian™ collection looks and works. This document lists some of these configuration possibilities.

1.1. Configuration files

Configuring a Veridian™ installation’s functionality and altering text and interface elements is done using the following files:

veridian/etc/runtime.cfg
veridian/macros/custom.dm

It is important that customisations are made to these files rather than the core Veridian files, so the core files can be upgraded automatically when patches are installed.

If your collection directory is not veridian (e.g. if it is dailynews), then all the paths to files given in this document should be changed to use your directory name instead, for example:

dailynews/etc/runtime.cfg
dailynews/macros/custom.dm

1.2. Macros

Veridian™ uses a macro system to generate the user interface elements. Macros are defined in files with a “.dm” extension, in the veridian/macros directory.

This is an example of a macro (called “samplemacro”):

_samplemacro_ {Sample text.}

2. Functionality

2.1. Changing to single publication mode

Veridian is set up to work with multiple publications by default. For collections that only contain one publication, the user interface can be simplified in various ways: there is no need for a publication filter in the Advanced Search options, no need for a “browse by title” page, and no need for a “browse by date” page over all publications. Additionally, there is no need for a “publication title” search result sort option, and no need for publication search result facets.

To switch the interface into single publication mode, change argdefault=1 to argdefault=0 in the following line in veridian/etc/runtime.cfg:

cgiarg shortname=mp argdefault=1      savedarginfo=mustnot    multiplevalue=false

2.2. Changing the document view style

The document view used for a Veridian collection is controlled by the documentlevelimagesview configuration option in the veridian/etc/runtime.cfg file.

  • To display all the document’s page images inside the PanoJS zoom and pan module, set this option to panojs
  • To display all the document’s page images as a realistic book, set this option to realisticbook
  • To have no view of all the document’s page images (the document table of contents will be displayed instead, and images will be viewed at logical section/page level), set this option to none

When the document-level zooming and panning module is turned off, it is still possible to have zooming and panning enabled at page-level. This is controlled by the setting the pagelevelimageview (page level images) configuration option to panojs

2.3. Configuring the images generated by the imageserver

Settings for the different types of image generated by the imageserver are controlled by options in the veridian/etc/runtime.cfg file:

logicalsectionimagecolours The number of colours in logical section images generated (e.g. on the “Clip Article” page).
logicalsectionimageextension The file type of the logical section images generated (e.g. on the “Clip Article” page) — possible values are jpg, gif and png
logicalsectionimagemaxwidth The maximum width (in pixels) of the logical section images generated (e.g. on the “Clip Article” page). Will take precedence over the logicalsectionimagescalefactor value.
logicalsectionimagescalefactor The scale factor (as a percentage) applied to the logical section images generated (e.g. on the “Clip Article” page). The logicalsectionimagemaxwidth option will take precedence over this if necessary (ie. if the result of scaling the image using the scale factor is larger than the maximum width set).
pageimagecolours The number of colours in page images generated (e.g. in the “zoom and pan” and “realistic book” views).
pageimageextension The file type of the page images generated (e.g. in the “zoom and pan” and “realistic book” views) — possible values are jpg, gif and png
pageimagemaxwidth The maximum width (in pixels) of the page images generated (e.g. in the “zoom and pan” and “realistic book” views). Will take precedence over the pageimagescalefactor value.
pageimagescalefactor The scale factor (as a percentage) applied to the page images generated (e.g. in the “zoom and pan” and “realistic book” views). The pageimagemaxwidth option will take precedence over this if necessary (ie. if the result of scaling the image using the scale factor is larger than the maximum width set).
pagetileimagecolours The number of colours in page tiles generated for the “zoom and pan” view.
pagetileimageextension The file type of the page tiles generated for the “zoom and pan” view — possible values are jpg, gif and png
snippetimagecolours The number of colours in search snippet images generated (ie. when the “Preview images” option is selected on the search page).
snippetimageextension The file type of the search snippet images generated (ie. when the “Preview images” option is selected on the search page) — possible values are jpg, gif and png
snippetimagemaxwidth The maximum width (in pixels) of the search snippet images generated (ie. when the “Preview images” option is selected on the search page). Will take precedence over the snippetimagescalefactor value.
snippetimagescalefactor The scale factor (as a percentage) applied to the search snippet images generated (ie. when the “Preview images” option is selected on the search page). The snippetimagemaxwidth option will take precedence over this if necessary (ie. if the result of scaling the image using the scale factor is larger than the maximum width set).

2.4. Adding a content type filter to the Advanced Search options

There is no content type filter in the Advanced Search options by default. This is because it depends on the types of document in the collection, and the content types encoded in the METS data.

If a content type filter is required, add a _searchcontroltyq_ macro to the veridian/macros/custom.dm file. If your collection contains newspapers, you might add something like the following:

package query

_searchcontroltyq_ [c=veridian] {
<input type=”checkbox” name=”tyq” value=”” _If_(“_core:doesmultivaluedcgiarginclude_(tyq,)” eq “1”,checked=”checked”) />All categories
<input type=”checkbox” name=”tyq” value=”ARTICLE” _If_(“_core:doesmultivaluedcgiarginclude_(tyq,ARTICLE)” eq “1” || “_args:cgiargtyq_” eq “”,checked=”checked”) />Articles
<input type=”checkbox” name=”tyq” value=”ADVERTISEMENT” _If_(“_core:doesmultivaluedcgiarginclude_(tyq,ADVERTISEMENT)” eq “1” || “_args:cgiargtyq_” eq “”,checked=”checked”) />Advertisements
<input type=”checkbox” name=”tyq” value=”ILLUSTRATION” _If_(“_core:doesmultivaluedcgiarginclude_(tyq,ILLUSTRATION)” eq “1” || “_args:cgiargtyq_” eq “”,checked=”checked”) />Illustrations
}

2.5. Adding a language selector

To add a language selector for switching the Veridian interface to a non-English language, modify the “languageoptions” entry in the veridian/etc/runtime.cfg file to list the desired languages. Current options are “english”, “german”, “spanish”, “russian” and “vietnamese” (please note that some of the translations are incomplete or out of date). For example:

languageoptions english german spanish russian vietnamese

2.6. Improving search engine harvesting

Veridian has some functionality to help search engine bots (such as the Google bot) harvest a Veridian collection efficiently and sensibly:

  • When a Veridian collection is built sitemap XML files are automatically generated in the veridian/web directory. These sitemap XML files list the most important pages for the search engine bots to harvest: the home page, the about page for each publication, the table of contents page for each document, and the article view for each article in the collection. If the web server configuration is correct then the sitemap XML files will be available at the root web path, e.g. http://*domain*/sitemap_index.xml.

  • When a search engine bot harvests an article page it is preferable that Veridian returns the article text instead of the normal image view that users will normally see. This means that the search engine bot will index the article text (so it will be searchable), but the search engine will still point users to the normal image view in its search results. To control which search bots this applies to, edit the veridian/etc/runtime.cfg file and edit the webcrawleragent entries, specifying a substring of the search engine bot “User Agent” string. By default this functionality applies to the Googlebot and bingbot harvesters.

  • By default Veridian will block search engine bots from accessing the imageserver, Veridian query pages and some Veridian user management pages. This is done through the robots.txt file in the veridian/web directory. If necessary, other Veridian pages can also be blocked by adding additional “Disallow” entries. The robots.txt file also references the sitemap XML index file, and attempts to restrict the crawl rate (to a maximum of one page per second).


3. Document structure

3.1. Making illustrations separate articles (newspaper documents only)

To make illustrations become articles in their own right, rather than being merged into their parent article, specify the -separate_illustrations option to MetsAltoPlugin in the veridian/etc/ingest.cfg file, then re-ingest the data.

3.2. Making tables separate articles (newspaper documents only)

To make tables become articles in their own right, rather than being merged into their parent article, specify the -separate_tables option to MetsAltoPlugin in the veridian/etc/ingest.cfg file, then re-ingest the data.

3.3. Displaying page headings in the document table of contents

By default, the sections in the document table of contents are displayed without any information about which page they appear on. To display page headings before the first section on each page, add the following content to the veridian/etc/runtime.cfg file:

format DocumentLogicalSectionTOCPageHeadings “<b>[Title]</b>”

4. Interface look and feel

4.1. Adding your organisation’s logo

First, save your new logo image into the veridian/web/images directory. It is suggested that this be no larger than 500 pixels wide by 80 pixels high.

Now add a _veridianheaderlogo_ macro referring to the new image to the veridian/macros/custom.dm file, for example:

package core

_veridianheaderlogo_ {<a href=”http://www.yourorganisation.com”><img src=”_httpimages_/logo.jpg” /></a>}

(This example assumes that the filename of your logo is logo.jpg).

4.2. Changing colours and fonts

  • To alter the banner background colour, add a _headerbgcolor_ macro containing the desired colour value for your collection to the veridian/macros/custom.dm file. For example:

    package core

    _headerbgcolor_ {#587CAF}

  • To alter the link colour, add _linkcolor_ and _hovercolor_ macros containing the desired colour values for your collection to the veridian/macros/custom.dm file, for example:

    package core

    _linkcolor_ {#587CAF}
    _hovercolor_ {#6D9DCC}

  • To change the body text colour, add a _textcolor_ macro containing the desired colour value for your collection to the veridian/macros/custom.dm file, for example:

    package core

    _textcolor_ {blue}

  • To change the body text font, add a _mainfont_ macro containing the desired font specification for your collection to the veridian/macros/custom.dm file, for example:

    package core

    _mainfont_ {Calibri, sans-serif}


5. Interface text

5.1. Changing the text appearing in the browser title bar

To change the text appearing in the browser title bar, add a _textcollectiontitle_ macro containing the desired text for your collection to the veridian/macros/custom.dm file, for example:

package core

_textcollectiontitle_ {My Veridian collection}

5.2. Changing the text on the home page

To change the text on the home page, add a _textwelcomemsg_ macro containing the desired text for your collection to the veridian/macros/custom.dm file, for example:

package home

_textwelcomemsg_ [c=veridian] {Welcome to my Veridian collection. This collection makes available…}

5.3. Changing the user interface to refer to “books” instead of “issues”, and “chapters” instead of “articles”

Add the following macros to the veridian/macros/custom.dm file:

package core

_textdocument_ [c=veridian] {_textbook_}
_textdocumenttc_ [c=veridian] {_textbooktc_}
_textdocuments_ [c=veridian] {_textbooks_}
_textdocumentstc_ [c=veridian] {_textbookstc_}
_textlogicalsection_ [c=veridian] {_textchapter_}
_textlogicalsectiontc_ [c=veridian] {_textchaptertc_}
_textlogicalsections_ [c=veridian] {_textchapters_}
_textlogicalsectionstc_ [c=veridian] {_textchapterstc_}