Homec4science
Diffusion invenio-infoscience (maint-1.0) Browse

R3600/modules/webstyle/doc/admin/webstyle-admin-guide.webdoc
7b3804d29a49maint-1.0

Last Change
Raw File

webstyle-admin-guide.webdoc
View Options

## -*- mode: html; coding: utf-8; -*-
## This file is part of CDS Invenio.
## Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008 CERN.
##
## CDS Invenio is free software; you can redistribute it and/or
## modify it under the terms of the GNU General Public License as
## published by the Free Software Foundation; either version 2 of the
## License, or (at your option) any later version.
##
## CDS Invenio is distributed in the hope that it will be useful, but
## WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
## General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with CDS Invenio; if not, write to the Free Software Foundation, Inc.,
## 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
<!-- WebDoc-Page-Title: WebStyle Admin Guide -->
<!-- WebDoc-Page-Navtrail: <a class="navtrail" href="<CFG_SITE_URL>/help/admin<lang:link/>">_(Admin Area)_</a> -->
<!-- WebDoc-Page-Revision: $Id$ -->
<h2>Contents</h2>
<ul style="list-style-type:None">
<li><strong>1. <a href="#overview_page_layout">Overview</a></strong>
<ul style="list-style-type:None">
<li>1.1&nbsp;&nbsp;<a href="#overview_css">CSS Style Sheet and Images</a></li>
<li>1.2&nbsp;&nbsp;<a href="#overview_page_layout">HTML Page Layout</a>
<ul style="list-style-type:None">
<li>1.2.1&nbsp;&nbsp;&nbsp;&nbsp;<a href="#overview_page_layout_stat">Layout of HTML Static Pages</a></li>
<li>1.2.2&nbsp;&nbsp;&nbsp;&nbsp;<a href="#overview_page_layout_dyn">Layout of Python Dynamic Pages</a></li>
</ul>
</li>
<li>1.3&nbsp;&nbsp;<a href="#overview_bib">Look of Bibliographic References</a></li>
<li>1.4&nbsp;&nbsp;<a href="#overview_spec_conf">Specific Configurations</a></li>
</ul>
</li>
<li><strong>2. <a href="#det_page">Detailed Record Pages</a></strong>
<ul style="list-style-type:None">
<li>2.1&nbsp;&nbsp;<a href="#det_page">Available tabs</a></li>
<li>2.2&nbsp;&nbsp;<a href="#det_show_hide_tabs">Showing/Hiding tabs</a></li>
<li>2.3&nbsp;&nbsp;<a href="#det_page_cust_cont_tabs">Customizing content of tabs</a></li>
<li>2.4&nbsp;&nbsp;<a href="#det_page_cust_look_tabs">Customizing look of tabs</a></li>
</ul>
</li>
</ul>
<h2><a name="overview">1. Overview</a></h2>
<p>This document describes how to change the look and feel of your CDS
Invenio installation.
<h3><a name="overview_css">1.1 CSS Style Sheet and Images</a></h3>
<p>The most obvious modification you may want to do is the
modification of <a href="<CFG_SITE_URL>/img/invenio.css">CSS style sheet</a>.
You may also customize default <a href="<CFG_SITE_URL>/img/">images</a>.</p>
<h3><a name="overview_page_layout">1.2 HTML Page Layout</a></h3>
<p>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.</p>
<p>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 <CFG_SITE_NAME>. Most
probably, you will only want to customize 'webstyle_templates.py',
which define the headers and footer of a page.</p>
<p>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.</p>
<h4><a name="overview_page_layout_stat">1.2.1 Layout of HTML Static Pages</a></h4>
<p>Static HTML pages are all located in the /opt/cds-invenio/lib/webdoc/
installation directory. These files are organized in 3 directories:</p>
<ul>
<li><b>help:</b> Help pages available to users of your website</li>
<li><b>admin:</b> Mostly guides for admin users</li>
<li><b>hacking:</b> Mostly guides for administrators and developers</li>
</ul>
<p>
These directories do not contain the <code>.html</code> files, but
<code>.webdoc</code> files. These '<em>WebDoc</em>' files are
basically HTML with the following main differences:
</p>
<ul>
<li>They only contain the body of your page (only content of the
<code>&lt;body&gt;</code> tag)
</li>
<li>You can make use of special tags such as
<code>&lt;CFG_SITE_URL&gt;</code> and <code>&lt;CFG_SITE_SUPPORT_EMAIL&gt;</code>,
that will be replaced by <CFG_SITE_URL> and <CFG_SITE_SUPPORT_EMAIL>, the values that
you should have configured in your <code>config.py</code> file.
</li>
<li>You can internationalize the content. For example:
<pre>
&lt;lang&gt;
&lt;en&gt;Book&lt;/en&gt;
&lt;fr&gt;Livre&lt;/fr&gt;
&lt;de&gt;Buch&lt;/de&gt;
&lt;/lang&gt;
</pre>
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.
</li>
</ul>
<p>Read the <a href="<CFG_SITE_URL>/help/hacking/webstyle-webdoc-syntax">WebDoc syntax guide</a> to learn more about details of the WebDoc syntax.</p>
<p>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: <b>they</b> will adapt themselves to your needs.</p>
<p>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 <code>/opt/cds-invenio/bin/webdoc --help</code> to learn more about it).</p>
<h4><a name="overview_page_layout_dyn">1.2.2 Layout of Python Dynamic Pages</a></h4>
<p>The dynamic Python-powered pages can be customized by making use of
CDS Invenio templating system that uses a notion of a template skin.
How this works?</p>
<p>When you edit <code>invenio-local.conf</code> during installation
or later during runtime (when during runtime, you have to
run <code>inveniocfg --update-config-py</code> after editing the conf
file), you may choose to use your own templates instead of the
provided default ones by editing
<code>CFG_WEBSTYLE_TEMPLATE_SKIN</code> variable. Let us say you
put <code>ithaca</code> there in order to use your
own <code>ithaca</code> style. Now, when you start Apache, then
instead of CDS Invenio's usual template files such
as <code>webbasket_templates.py</code> the system will look for file
named <code>webbasket_templates_ithaca.py</code> and will load the
template functions from there instead, provided that they exist.
(Otherwise it would fall back to the default ones.)</p>
<p>How do you create such an <code>ithaca</code> 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.</p>
<p>Let's show an example of how to modify the page footer. Create a
file named <code>webstyle_templates_ithaca.py</code> with the
following content:</p>
<blockquote>
<pre>
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 += """&lt;hr>This site has no footer.
&lt;/body>
&lt;/html>"""
return out
</pre>
</blockquote>
<p>After the file was created, restart Apache and lo, your new ithaca
style footer will be seen in action.</p>
<p>(A side comment: note that <code>tmpl_page_footer()</code> 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 <code>out = ""</code> statement
your GA script code:</p>
</blockquote>
<pre>
[...]
out += """&lt;script src="http://www.google-analytics.com/urchin.js"
type="text/javascript">
&lt;/script>
&lt;script type="text/javascript">
_uacct = "UA-1234567-8";
urchinTracker();
&lt;/script>"""
[...]
</pre>
</blockquote>
End of the side comment.)
<p>Some further remarks on this templating system:</p>
<ul>
<li>We have observed that in practice the HTML page designers were
ofter Python programmers, therefore we have adopted a
programmer-friendly templating system.</li>
<li>You have to know a bit of Python in order to use it. If you don't
know Python, do not worry, because you can basically copy and
paste the original <code>tmpl_foo()</code> 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
(<code>from invenio.config import CFG_SITE_LANG</code>) as in the original
<code>webstyle_templates.py</code> file and to preserve the
leading whitespace Pythonic indentation.</li>
<li>You do not have to learn "yet another templating language", you
can use the full power of Python. The <code>tmpl_foo()</code>
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 <code>tmpl_foo()</code> function itself,
thanks to the full Python power.</li>
<li>If you feel like doing so, you can modify all
the <code>tmpl_foo()</code> functions across all CDS Invenio
modules in a way that will completely change the presentation of
elements including their content, position and order on the
screen.</li>
<li>In practice, it is sufficient to modify the CSS and the
webstyle_templates_ithaca.py (and possibly
websearch_templates_ithaca.py) files to achieve most important
customizations.</li>
<li>If you would like to discover which method of which template
generate which region on the web page, you can switch on
the <tt>CFG_WEBSTYLE_INSPECT_TEMPLATES</tt> configuration variable
in your <tt>invenio-local.conf</tt> file and rerun <code>sudo -u
apache /opt/cds-invenio/bin/inveniocfg
--update-config-py</code>. Then, after optionally running
<code>bibreformat -a</code> and <code>webcoll -f</code> (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.</li>
<li>We expect to provide possibly more than one skin with the default
distribution, so if you have modified CDS Invenio look and feel in
an interesting way, please consider donating us your templates.</li>
<li>When upgrading from one CDS Invenio release to another, you may
find out that the default templates have changed in a way that
requires changes to your templates (such as an addition of
parameters to cover the new functionality). This is inevitable in
any templating system; unless you introduce new parameters, you
would not see them being printed. Therefore, if you have
modified <code>tmpl_foo()</code> and <code>tmpl_bar()</code>, 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.
<br/><br/>
In order to help you in this task, we provide a tool to check
incompatibilities between your customized templates and the default
templates.<br/>
This tool can be run before doing a <code>'make install'</code>,
therefore giving you a chance to fix your templates before
upgrading. Just run <code>'make check-custom-templates'</code> to
get the list of problems found with your templates. <br /><br />
You can also run this tool any time after the new default
templates have been installed, in order to ensure that
modifications you have done to your templates are valid. To do so
move to your CDS Invenio installation directory, and run: <br/>
<code>$ python /opt/cds-invenio/lib/python/invenio/template.py
--check-custom-templates</code>
</li>
</ul>
<h3><a name="overview_bib">1.3 Look of Bibliographic
References</a></h3>
<p>Bibliographic metadata is formatted using
<a href="bibformat-admin">BibFormat</a>. Read the
<a href="bibformat-admin-guide">BibFormat documentation</a>
for more information.</p>
<h3><a name="overview_spec_conf">1.4 Specific Configurations</a></h3>
<p>Note that the search interface pages may be modified to a large
extent in the <a href="websearch-admin">WebSearch Admin
Interface</a> by adding HTML portalboxes on various places on the page
(right top, before/after page title, before/after narrow by collection
boxes, etc).</p>
<h2><a name="det_page">2. Detailed Record Pages</a></h2>
<p>The web pages displaying the details of a record (such as
<a href="<CFG_SITE_URL>/record/1"><CFG_SITE_URL>/record/1</a>) do not only show metadata, but
also users' comments and reviews, statistics, etc. This information is
organized into tabs.</p>
<p>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.</p>
<p>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 <em>Information</em> tab is selected).</p>
<pre>
+--------------Detailed record page-------------+
| header |
|nav. breadcrumb |
| |
| .--------------------------------------. |
| .-|Info.|Ref.|Discussion.|Stats.|Fulltext|-. |
| | '--------------------------------------' | |
| | | |
| | content | |
| | | |
| '------------------------------------------' |
| |
| .---------------(Mini Panel)---------------. |
| | Mini | Mini | Mini | |
| | File | Review | Actions | |
| '------------------------------------------' |
+-----------------------------------------------+
</pre>
<h4><a name="det_page_avail_tabs">2.1 Available tabs</a></h4>
The following tabs are available:
<table border="1">
<tr>
<th>Name</th>
<th>Description</th>
<th>URL (eg. for record '10')</th>
</tr>
<tr>
<td>Information</td>
<td>Show the formatted metadata of the record</td>
<td><a href="<CFG_SITE_URL>/record/10"><CFG_SITE_URL>/record/10</a></td>
</tr>
<tr>
<td>References</td>
<td>Displays the references (bibliography) of the record</td>
<td><a href="<CFG_SITE_URL>/record/10/references"><CFG_SITE_URL>/record/10/references</a></td>
</tr>
<tr>
<td>Discussion</td>
<td>Displays the users' comments and reviews</td>
<td><a href="<CFG_SITE_URL>/record/10/comments"><CFG_SITE_URL>/record/10/comments</a><br/>
<a href="<CFG_SITE_URL>/record/10/reviews"><CFG_SITE_URL>/record/10/reviews</a></td>
</tr>
<tr>
<td>Usage Statistics</td>
<td>Statistics data and graph about file downloads/views</td>
<td><a href="<CFG_SITE_URL>/record/10/usage"><CFG_SITE_URL>/record/10/usage</a></td>
</tr>
<tr><td>Fulltext</td>
<td>Link(s) to fulltext file(s)</td>
<td><a href="<CFG_SITE_URL>/record/10/files"><CFG_SITE_URL>/record/10/files</a></td>
</tr>
</table>
<p>The mini panel is only displayed when the <em>Information</em> tab is
selected. It is divided into the following sections:</p>
<ul>
<li>Files : quick access to fulltext file(s)</li>
<li>Review : quick access to reviewing feature</li>
<li>Actions: quick access to several other features</li>
</ul>
<h4><a name="det_page_show_hide_tabs">2.2 Showing/Hiding tabs</a></h4>
<p>The <a href="websearch-admin">WebSearch admin web
interface</a> 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 <em>detailed record page options</em>. From there you can select which
tabs to show for that collection.</p>
<p>If you want to apply these settings to the subcollections, select
<em><input type="checkbox" checked="checked" disabled="disabled">Also apply to subcollections</input></em>
before you click on the
<input type="submit" value="Modify" class="formbutton" disabled="disabled"/>
button.</p>
<p>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.</p>
<p>Here are some behaviours you should expect when changing the tabs
configuration:</p>
<ul>
<li>Given that search results pages always link to <CFG_SITE_URL>/record/10,
and given the above comment about accessibility of tabs when they
are not displayed, the content of the <em>Information</em> will always be
show when clicking on <a href="#" class="moreinfo">detailed record</a> link in search results, even
if the <em>Information</em> tab is set not to be displayed.</li>
<li>If you select only 1 tab, none of the tabs will be displayed at the
top of the page. This also means that whatever tabs you have
selected, you users will always see the content of the 'Information'
tabs (see above behaviour).</li>
<li>If you select 0 tab, only the content of <em>Information</em> tab is shown.
None of the tabs, nor the border that usually surrounds the content
of the tabs, nor the minipanel are shown. You should choose this
option if you decide to drop the tabs metaphor for the detailed
record pages. You can then build your own user interface on this
almost blank page (See <a href="#det_page_cust_cont_tabs">Customizing content of tabs</a>).</li>
<li>Note that <em>Discussion</em> tab will not be shown if you have disabled
both the commenting and reviewing features in your installation
(<code>CFG_WEBCOMMENT_ALLOW_COMMENTS</code> and
<code>CFG_WEBCOMMENT_ALLOW_REVIEWS</code> variable in your config file).</li>
</ul>
<h4><a name="det_page_cust_cont_tabs">2.3 Customizing content of tabs</a></h4>
<p>The contents of tabs are defined in the following ways:</p>
<dl>
<dt><strong><em>Information</em> tab</strong></dt>
<dd>The content of this tab is defined by function
<code>tmpl_detailed_record_metadata(..)</code> in <code>websearch_templates.py</code>.
By default <code>tmpl_detailed_record_metadata</code> simply returns the result
of the formatting of the metadata by BibFormat using the "HD" output
format. It can therefore be collection-specific.</dd>
<dt><strong><em>References</em> tab</strong></dt>
<dd>The content of this tab is defined by function
<code>tmpl_detailed_record_references(..)</code> in <code>websearch_templates.py</code>.
By default <code>tmpl_detailed_record_metadata</code> 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.</dd>
<dt><strong><em>Discussion</em> tab</strong></dt>
<dd>The content of this tab is mainly defined by function
<code>tmpl_get_comments(..)</code> in <code>webcomment_templates.py</code>. Other
functions in this file are also involved in the display.</dd>
<dt><strong><em>Usage Statistics</em> tab</strong></dt>
<dd>The content of this tab is defined by function
<code>tmpl_detailed_record_statistics(..)</code> in <code>websearch_templates.py</code>.
If the returned content is empty, then the tabs will be disabled
(visible, but cannot be clicked).</dd>
<dt><strong><em>Fulltext</em> tab</strong></dt>
<dd>The content of this tab is defined by function <code>tmpl_filelist(..)</code>
in <code>websubmit_templates.py</code>.</dd>
</dl>
<br/>
<p>The content of the mini panel is defined in the following ways:</p>
<dl>
<dt><strong><em>Files</em></strong></dt>
<dd>The content of this section is defined by the output format
'HDFILE'. It can therefore be collection-specific.</dd>
<dt><strong><em>Review</em></strong></dt>
<dd>The content of this section is defined by function
<code>tmpl_mini_review(..)</code> inside <code>webcomment_templates.py</code></dd>
<dt><strong><em>Actions</em></strong></dt>
<dd>The content of this section is defined by the output format
<code>HDACT</code>. It can therefore be collection-specific.</dd>
</dl>
<h4><a name="det_page_cust_look_tabs">2.4 Customizing look of tabs</a></h4>
<p>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.</p>
<p>Have a look at the following classes in the CDS css stylesheet:</p>
<ul>
<li><code>detailedrecordtabs</code></li>
<li><code>detailedrecordbox</code></li>
<li><code>detailedrecordminipanel</code></li>
<li><code>top-left, top-right, bottom-left, bottom-right</code></li>
<li><code>detailedrecordminipanel{actions,review,file}, detailedrecordshortreminder</code></li>
</ul>
<p>Note that a tab might be greyed out (disabled) when its content is
empty. This is the case for the <em>References</em> tab (see <a href="#det_page_cust_cont_tabs">Customizing
content of tabs</a> -&gt; 'References tab') and the <em>Fulltext</em> tab (if no
file could be found for the record).<p>
<p>For more advanced modifications (like changing the HTML code of the
tabs), you can modify the <code>detailed_record_container(..)</code> and
<code>detailed_record_mini_panel(..)</code> functions inside your
<code>webstyle_templates.py</code> file.</p>
c4science · Help