CERN Accelerating science

WebStyle Admin Guide

Contents

1. Overview

This document describes how to change the look and feel of your CDS Invenio installation.

1.1 CSS Style Sheet and Images

The most obvious modification you may want to do is the modification of CSS style sheet. You may also customize default images.

1.2 HTML Page Layout

The customization of the general page look and feel is currently different depending on whether you customize HTML-like static pages or dynamic Python pages.

Dynamic HTML pages are used to build the 'interactive' parts of the website, such as the search and browse pages, as well as the admin pages. The content of these pages is defined at run time, depending on the users parameters. You can modify them to provide a totally different experience to your users when browsing CERN Document Server. Most probably, you will only want to customize 'webstyle_templates.py', which define the headers and footer of a page.

Static HTML pages are used for basic pages that do not embed dynamic content, such as this guide. They help reducing the load of the server and speed up pages serving. As you will see, even HTML static pages can still contain some values defined at run time, but these are reduced to the minimum compared to dynamic pages. Most probably you will not want to modify these pages, since the small amount of dynamic content they have allow these pages to inherit from the customizations you have made elsewhere, such as in the CSS, and the page header and footer.

1.2.1 Layout of HTML Static Pages

Static HTML pages are all located in the /opt/invenio/lib/webdoc/ installation directory. These files are organized in 3 directories:

These directories do not contain the .html files, but .webdoc files. These 'WebDoc' files are basically HTML with the following main differences:

Read the WebDoc syntax guide to learn more about details of the WebDoc syntax.

The advantage of not using raw HTML for these static pages is that they can for example reuse the header and footer that you have defined for dynamic pages, and make use of the variables you have defined in your invenio.conf file. In that way you should not need to adapt them to your needs: they will adapt themselves to your needs.

Any modification should be immediatly visible when looking at the pages from the web: the pages are built "dynamically" and then cached. If you want to force the cache of the pages, use the WebDoc CLI (type /opt/invenio/bin/webdoc --help to learn more about it).

1.2.2 Layout of Python Dynamic Pages

The dynamic Python-powered pages can be customized by making use of Invenio templating system that uses a notion of a template skin. How this works?

When you edit invenio-local.conf during installation or later during runtime (when during runtime, you have to run inveniocfg --update-config-py after editing the conf file), you may choose to use your own templates instead of the provided default ones by editing CFG_WEBSTYLE_TEMPLATE_SKIN variable. Let us say you put ithaca there in order to use your own ithaca style. Now, when you start Apache, then instead of Invenio's usual template files such as webbasket_templates.py the system will look for file named webbasket_templates_ithaca.py and will load the template functions from there instead, provided that they exist. (Otherwise it would fall back to the default ones.)

How do you create such an ithaca style templates file? We do not use one of many existing templating frameworks in Python but a very simple programmer-friendly templating system that enables you to use the full power of Python to inherit from the default templates the output generating functions you want to reuse and to write anew only the functions you would like to modify.

Let's show an example of how to modify the page footer. Create a file named webstyle_templates_ithaca.py with the following content:

from invenio.config import CFG_SITE_LANG
from invenio.webstyle_templates import Template as DefaultTemplate

class Template(DefaultTemplate):
    """Ithaca style templates."""

    def tmpl_pagefooter(self, req=None, ln=CFG_SITE_LANG, lastupdated=None,
                        pagefooteradd=""):
        """
        Ithaca style page footer.  See the default function for
        the meaning of parameters.
        """
        out = ""
        out += """<hr>This site has no footer.
                  </body>
                  </html>"""
        return out

After the file was created, restart Apache and lo, your new ithaca style footer will be seen in action.

(A side comment: note that tmpl_page_footer() is an ideal place to put any local code you may want to execute at the end of web request processing when the main page content was just served to the user. As an example, if you are using Google Analytics, you may want to put just after the above out = "" statement your GA script code:

        [...]
        out += """
<script type="text/javascript">

  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'UA-XXXXX-X']);
  _gaq.push(['_trackPageview']);

  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();

</script>
"""
End of the side comment.)

Some further remarks on this templating system:

1.3 Look of Bibliographic References

Bibliographic metadata is formatted using BibFormat. Read the BibFormat documentation for more information.

1.4 Specific Configurations

Note that the search interface pages may be modified to a large extent in the WebSearch Admin Interface by adding HTML portalboxes on various places on the page (right top, before/after page title, before/after narrow by collection boxes, etc).

2. Detailed Record Pages

The web pages displaying the details of a record (such as https://cds.cern.ch/record/1) do not only show metadata, but also users' comments and reviews, statistics, etc. This information is organized into tabs.

The content of these tabs can be customized on a collection basis. It is also possible to show/hide tabs depending on the displayed collection.

The detailed record pages also feature a mini panel at the bottom of the page that links to popular functions (The mini panel is only displayed when Information tab is selected).


  +--------------Detailed record page-------------+
  |                    header                     |
  |nav. breadcrumb                                |
  |                                               |
  |   .--------------------------------------.    |
  | .-|Info.|Ref.|Discussion.|Stats.|Files |-.  |
  | | '--------------------------------------' |  |
  | |                                          |  |
  | |                  content                 |  |
  | |                                          |  |
  | '------------------------------------------'  |
  |                                               |
  | .---------------(Mini Panel)---------------.  |
  | |   Mini    |      Mini     |    Mini      |  |
  | |   File    |     Review    |   Actions    |  |
  | '------------------------------------------'  |
  +-----------------------------------------------+

2.1 Available tabs

The following tabs are available:
Name Description URL (eg. for record '10')
Information Show the formatted metadata of the record https://cds.cern.ch/record/10
References Displays the references (bibliography) of the record https://cds.cern.ch/record/10/references
Discussion Displays the users' comments and reviews https://cds.cern.ch/record/10/comments
https://cds.cern.ch/record/10/reviews
Usage Statistics Statistics data and graph about file downloads/views https://cds.cern.ch/record/10/usage
Files Link(s) to full-text and associated file(s) https://cds.cern.ch/record/10/files

The mini panel is only displayed when the Information tab is selected. It is divided into the following sections:

2.2 Showing/Hiding tabs

The WebSearch admin web interface lets you decide for each collection which tabs are to be displayed. Choose a collection to edit in the collection tree and go to its detailed record page options. From there you can select which tabs to show for that collection.

If you want to apply these settings to the subcollections, select Also apply to subcollections before you click on the button.

Note that these settings only affect the tabs, not the content of the tabs: even if a tab is not displayed, it is still possible to access its content using its usual url. This is useful if you decide to completely change the detailed record pages, dropping the tab-metaphor (eg. for a side bar) but still want to access the comments, reviews, etc pages.

Here are some behaviours you should expect when changing the tabs configuration:

2.3 Customizing content of tabs

The contents of tabs are defined in the following ways:

Information tab
The content of this tab is defined by function tmpl_detailed_record_metadata(..) in websearch_templates.py. By default tmpl_detailed_record_metadata simply returns the result of the formatting of the metadata by BibFormat using the "HD" output format. It can therefore be collection-specific.
References tab
The content of this tab is defined by function tmpl_detailed_record_references(..) in websearch_templates.py. By default tmpl_detailed_record_metadata simply returns the result of the formatting of the metadata by BibFormat using the "HDREF" output format. If the result returned by BibFormat is empty, the tab is disabled (visible, but not clickable). It can therefore be collection-specific.
Discussion tab
The content of this tab is mainly defined by function tmpl_get_comments(..) in webcomment_templates.py. Other functions in this file are also involved in the display.
Usage Statistics tab
The content of this tab is defined by function tmpl_detailed_record_statistics(..) in websearch_templates.py. If the returned content is empty, then the tabs will be disabled (visible, but cannot be clicked).
Files tab
The content of this tab is defined by function tmpl_filelist(..) in websubmit_templates.py.

The content of the mini panel is defined in the following ways:

Files
The content of this section is defined by the output format 'HDFILE'. It can therefore be collection-specific.
Review
The content of this section is defined by function tmpl_mini_review(..) inside webcomment_templates.py
Actions
The content of this section is defined by the output format HDACT. It can therefore be collection-specific.

2.4 Customizing look of tabs

You can customize how tabs look like, as well change the look of the border that surrounds the content of tabs. The mini panel can similarly be customized.

Have a look at the following classes in the CDS css stylesheet:

Note that a tab might be greyed out (disabled) when its content is empty. This is the case for the References tab (see Customizing content of tabs -> 'References tab') and the Files tab (if no file could be found for the record).

For more advanced modifications (like changing the HTML code of the tabs), you can modify the detailed_record_container(..) and detailed_record_mini_panel(..) functions inside your webstyle_templates.py file.

Custom Redirections

It is possible to create custom redirections to URLs within Invenio, by registering a given unique label to be used after path /goto/.

FIXME

Command Line Interface

Usage: gotoadmin [options]

Options:
  -h, --help            show this help message and exit

  Plugin Administration Options:
    --list-plugins      List available GOTO plugins and their documentation
    --list-broken-plugins
                        List broken GOTO plugins

  Redirection Manipultation Options:
    -r LABEL, --register-redirection=LABEL
                        Register a redirection with the provided LABEL
    -u LABEL, --update-redirection=LABEL
                        Update the redirection specified by the provided LABEL
    -g LABEL, --get-redirection=LABEL
                        Get all information about a redirection specified by
                        LABEL
    -d LABEL, --drop-redirection=LABEL
                        Drop an existing redirection specified by LABEL

  Specific Options:
    -P PLUGIN, --plugin=PLUGIN
                        Specify the plugin to use when registering or updating
                        a redirection
    -j PARAMETERS, --json-parameters=PARAMETERS
                        Specify the parameters to provide to the plugin
                        (serialized in JSON)
    -p PARAM=VALUE, --parameter=PARAM=VALUE
                        Specify a single PARAM=VALUE parameter to be provided
                        to the plugin (alternative to the JSON serialization)