| Home > Admin Area > WebStyle Admin Guide |
This document describes how to change the look and feel of your CDS Invenio installation.
The most obvious modification you may want to do is the modification of CSS style sheet. You may also customize default images.
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.
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:
<body> tag)
<CFG_SITE_URL> and <CFG_SITE_SUPPORT_EMAIL>,
that will be replaced by https://cds.cern.ch and cds.support@cern.ch, the values that
you should have configured in your config.py file.
<lang>
<en>Book</en>
<fr>Livre</fr>
<de>Buch</de>
</lang>
will be replaced by "Book" if the user has chosen to display the English version of your site,
"Livre" in French or "Buch" in German.
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).
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:
tmpl_foo() function definition "as
is" into the above-cited example and then you would only modify
its HTML snippets. The important thing is to preserve the imports
(from invenio.config import CFG_SITE_LANG) as in the original
webstyle_templates.py file and to preserve the
leading whitespace Pythonic indentation.tmpl_foo()
functions do not contain any business logic in them, their only
purpose is to make the HTML presentation of data supplied to them.
But, should you need to carry out a little data transformation,
you can do it within the tmpl_foo() function itself,
thanks to the full Python power.tmpl_foo() functions across all Invenio
modules in a way that will completely change the presentation of
elements including their content, position and order on the
screen.sudo -u
apache /opt/invenio/bin/inveniocfg
--update-config-py. Then, after optionally running
bibreformat -a and webcoll -f (if you
want to debug search pages) and after having restarted your Apache
server (in every case), you will find in your browser that a
place-mark has been put next to every region of every page, and
that you can hover your mouse pointer over any region of the page
in order to discover which module/method/parameters have been used
to generate it. This is useful for debugging Python templates
and/or for understanding which part of code generates which HTML
snippet in the output.tmpl_foo() and tmpl_bar(), and
you are ugrading to a new release, you may at least briefly check
whether the function arguments are the same. A quick check of the
body would be helpful too, in case the new release fixed some
display-related problems in these functions.
'make install',
therefore giving you a chance to fix your templates before
upgrading. Just run 'make check-custom-templates' to
get the list of problems found with your templates. $ python /opt/invenio/lib/python/invenio/template.py
--check-custom-templates
Bibliographic metadata is formatted using BibFormat. Read the BibFormat documentation for more information.
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).
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 | | | '------------------------------------------' | +-----------------------------------------------+
| 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:
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:
CFG_WEBCOMMENT_ALLOW_COMMENTS and
CFG_WEBCOMMENT_ALLOW_REVIEWS variable in your config file).The contents of tabs are defined in the following ways:
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.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.tmpl_get_comments(..) in webcomment_templates.py. Other
functions in this file are also involved in the display.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).tmpl_filelist(..)
in websubmit_templates.py.The content of the mini panel is defined in the following ways:
tmpl_mini_review(..) inside webcomment_templates.pyHDACT. It can therefore be collection-specific.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:
detailedrecordtabsdetailedrecordboxdetailedrecordminipaneltop-left, top-right, bottom-left, bottom-rightdetailedrecordminipanel{actions,review,file}, detailedrecordshortreminderNote 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.
It is possible to create custom redirections to URLs within Invenio, by registering a given unique label to be used after path /goto/.
FIXME
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)