Homec4science
Diffusion invenio-infoscience (maint-1.2) Browse

R3600/modules/webjournal/doc/admin/webjournal-admin-guide.webdoc
0ba3287c6292maint-1.2

Last Change
Raw File

webjournal-admin-guide.webdoc
View Options

## -*- mode: html; coding: utf-8; -*-
## This file is part of Invenio.
## Copyright (C) 2009, 2010, 2011 CERN.
##
## 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.
##
## 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 Invenio; if not, write to the Free Software Foundation, Inc.,
## 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
<!-- WebDoc-Page-Title: WebJournal 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="#introduction">Introduction</a></strong></li>
<li><strong>2. <a href="#addJournal">Add a Journal</a></strong></li>
<li><strong>3. <a href="#configureJournal">Configure a Journal</a></strong>
<li><strong>4. <a href="#journalSitemap">Sitemap of a Journal</a></strong>
<li><strong>5. <a href="#journalLayout">Edit the Layout of a Journal</a></strong>
<ul style="list-style-type:None">
<li>5.1&nbsp;&nbsp;<a href="#editJournalElement">Edit Format Elements - Best Practices</a></li>
</ul>
<ul style="list-style-type:None">
<li>5.2&nbsp;&nbsp;<a href="#editJournalAlertLayout">Alert layout - Best Practices</a></li>
</ul>
</li>
<li><strong>6. <a href="#addArticles">Submit Articles</a></strong>
<ul style="list-style-type:None">
<li>6.1&nbsp;&nbsp;<a href="#draftArticles">Draft/Unreleased/Offline Articles</a></li>
<li>6.2&nbsp;&nbsp;<a href="#draftPreview">Preview Unreleased Issues</a></li>
</ul>
</li>
<li><strong>7. <a href="#accessControl">Access Control</a></strong>
<ul style="list-style-type:None">
<li>7.1&nbsp;&nbsp;<a href="#accessControlSubmit">Articles Submission</a></li>
<li>7.1&nbsp;&nbsp;<a href="#accessControlIssue">Issue Control System</a></li>
</ul>
</li>
<li><strong>8. <a href="#troubleshoots">Troubleshoots</a></strong>
<ul style="list-style-type:None">
<li>8.1&nbsp;&nbsp;<a href="#updateCache">Update Cache</a></li>
<li>8.1&nbsp;&nbsp;<a href="#issueReleases">Manage Issue Releases</a></li>
</ul>
</li>
</ul>
<h2><a name="introduction">1. Introduction</a></h2>
<p>This guides shows how you can set up a new journal managed by the
WebJournal module of Invenio. You should first read the
<a href="webjournal-editor-guide">WebJournal Editor Guide</a> to get
an overview of the main concepts of this module
</p>
<h2><a name="addJournal">2. Add a Journal</a></h2>
<p>To add a journal, go to the WebJournal admin interface and click
&quot;Add new journal&quot;. Provide the name of your journal, and
edit the <a href="#configureJournal">configuration</a> of the
journal. Click &quot;Save&quot;.</p>
<p><a name="journalConfigurationWritePermission"><strong>Note that by
default your Apache user should not be able to save the
configuration</strong></a> since it should not have rights to write
to <code>/opt/invenio/etc/webjournal/</code>. To save the settings
you might want to manually save your configuration
to <code>/opt/invenio/etc/webjournal/<strong>yourJournalName</strong>/<strong>yourJournalName</strong>-config.xml</code> or give write permission to <code>/opt/invenio/etc/webjournal/</code></p>
<p>Usually adding a journal also requires to set up a dedicated
submission, give some access using WebAccess, and can optionally lead
to the creation of WebSearch collections (you can, but your don't have
to, map your journal categories to WebSearch collections. You can also
simply create a generic collection for all articles in all categories
of your journal, or don't create collections at all). See the section
dedicated to <a href="#addArticles">articles submission</a>.
</p>
<h2><a name="configureJournal">3. Configure a Journal</a></h2>
<p>You can either configure the journal from the admin web interface
or directly by editing the configuration file
(see <a href="#journalConfigurationWritePermission">above
note</a>).</p>
<p>The configuration consists in an XML file with the following
nodes:</p>
<ul>
<li>view
<ul>
<li><strong>niceName</strong>: The name of your journal as displayed on your journal pages</li>
<li><strong>niceURL</strong>: <em>(not yet used)</em></li>
<li>css
<ul>
<li><strong>screen</strong>: relative path to your journal CSS file.</li>
<li><strong>print</strong>: same as <strong>screen</strong>, but used when your users want to print your journal</li>
</ul>
</li>
<li>format_template
<ul>
<li><strong>index</strong>: format template of your journal <a href="#sitemapIndex">index page</a></li>
<li><strong>detailed</strong>: format template of your journal <a href="#sitemapDetailed">article page</a></li>
<li><strong>search</strong>: format template of your journal <a href="#sitemapSearch">search/archives page</a></li>
<li><strong>contact</strong>: format template of your journal <a href="#sitemapContact">contact page</a></li>
<li><strong>popup</strong>: format template of your journal <a href="#sitemapPopup">&quot;pop-up article&quot; page</a></li>
</ul>
</li>
</ul>
</li>
<li>model
<ul>
<li>record
<ul>
<li><strong>rule*</strong>: defines the categories of the journal, and the query matching articles of this category. Format: <code>categoryName, query</code>. The journal categories are not necessary mapped to Invenio collections (but they can be, for consistency)</li>
</ul>
</li>
</ul>
</li>
<li>controller
<ul><li><strong>issue_grouping</strong>: the default number of issues that are released together when grouping issue. Specify <code>1</code> if your release are not usually grouped.</li>
<li><strong>issues_per_year</strong>: number of expected issue per year. Help to anticipate next issue dates and number</li>
<li><strong>hide_unreleased_issues</strong>: if all unreleased issue should be hidden to readers, type "<code>all</code>" (recommended). If only future unreleased issues must be hidden to readers, type "<code>future</code>". If unreleased issues must always be accessible to everyone (even if displayed empty), use "<code>none</code>". Hidden issues are only visible to users who can access action "<code>cfgwebjournal</code>").</li>
<li>marc_tags
<ul>
<li><strong>issue_number</strong>: <em>(not yet used. Should correspond to field containing issue number. Now hardcoded to 773__n)</em></li>
<li><strong>order_number</strong>: <em>(not yet used. Should correspond to field containing article order. Now hardcoded to 773__c)</em></li>
</ul>
</li>
<li><strong>alert_sender</strong>: email displayed as sender when sending journal newsletter</li>
<li><strong>alert_recipients</strong>: default list of recipients emails (comma-separated) when sending journal newsletter</li>
<li><strong>languages</strong>: comma-separated list of languages enabled for this journal (you should have an article in <em>each</em> of these languages)</li>
<li>submission
:
<ul>
<li><strong>doctype</strong>: the doctype of the submission used to edit record. Used to provide journal editors a direct link to submission from an article</li>
<li><strong>identifier_element</strong>: the WebSubmit element name where the submission expects to get the report number of the article to edit.</li>
<li><strong>identifier_field</strong>: the MARC field on which the submission should rely to retrieve the article (identifier to use to prefill the <em>identifier_element</em> input field when using <code>CFG_SITE/submit/direct</code> URLs).</li>
</ul>
</li>
<li><strong>draft_keyword</strong>: keyword that will be removed from some fields of the records of the issue to be released: that is used to automatically "publish" records tagged as draft.</li>
<li><strong>first_issue</strong>: The first issue number to be ever published for this journal: this is only needed at the beginning, in order for WebJournal to know what should be the first issue number (Eg. if it starts in the middle of the year with a different number than <code>01</code>)</li>
<li><strong>draft_image_access_policy</strong>: '<code>allow</code>' or '<code>deny</code>' (default): if we should allow or not (default) access to images and files attached to an article even if this article is still part of a restricted collection: this allows to workaround the time required for an article to appear in a public collection after an issue has been released. Access is still forbidden if the article does not belong to a released issue, but at least default authorizations of the record do not apply.</li>
</ul>
</li>
</ul>
<p><em>* Means repeatable</em></p>
<h2><a name="journalSitemap">4. Sitemap of a Journal</a></h2>
<p>A journal typically contains the following sections, each generated using a different template (as defined in your journal configuration):</p>
<ul>
<li><strong><a name="sitemapIndex">Index</a></strong><br />
The main page of a journal, containing links to detailed articles. Correspond to a given journal, issue and category (by default the first category of the latest issue of the journal).<br />
Accessible at <code>http://yourSite/journal/<strong>yourJournalName</strong>/</code> or for a specific issue and/or category at <code>http://yourSite/journal/yourJournalName/<strong>year</strong>/<strong>number</strong>/<strong>category</strong></code><br />
When <code><strong>yourJournalName</strong></code> is not provided, the user is automatically redirected to the latest issue of your journal. If there are several journals available, he is offered a list of journals to choose from. When <strong>category</strong> is missing, the first category defined for your journal is used. When <code>/<strong>year</strong>/<strong>number</strong>/</code> are missing, the latest issue is chosen.</li>
<li><strong><a name="sitemapDetailed">Detailed</a></strong><br />
The page of a single article, in a given category, issue and journal.<br />
Accessible at <code>http://yourSite/journal/yourJournalName/year/number/category</code>/<strong>recID</strong></li>
<li><strong><a name="sitemapSearch">Search</a></strong><br />
Used for search or access to past issues of a journal<br />
Accessible at <code>http://yourSite/journal/</code>search?name=<code><strong>yourJournalName</strong></code></li>
<li><strong><a name="sitemapContact">Contact</a></strong><br />
Information about the journal<br />
Accessible at <code>http://yourSite/journal/</code>contact?name=<code><strong>yourJournalName</strong></code></li>
<li><strong><a name="sitemapPopup">Popup</a></strong><br />
Information about the journal<br />
Accessible at <code>http://yourSite/journal/</code>contact?name=<code><strong>yourJournalName</strong></code></li>
</ul>
<h2><a name="journalLayout">5. Edit the Layout of a Journal</a></h2>
<p>The WebJournal module relies on the BibFormat module to generate
its output. You should then already be familiar with its concepts
before reading further. In a few words, you edit the templates of a
journal using HTML, and use special tags for the dynamic parts
(navigation menu, article title, content, etc) of the layout.</p>
<p>The main differences between the use of BibFormat for journals
compared to BibFormat for the formatting of bibliographic records
are:</p>
<ul>
<li>Output formats are not used: format templates are directly
called based on your journal configuration (your
configuration <em>acts</em> like a basic output format)</li>
<li>A format template takes care of the full layout of your page: it
should therefore include the <code>tags
&lt;html&gt;</code>, <code>&lt;header&gt;</code>, <code>&lt;body&gt;</code>,
etc.</li>
<li>Format templates are saved
to <code>/opt/invenio/etc/bibformat/format_templates/webjournal/</code>.</li>
<li>In general, format elements (<em>in Python</em>) cannot rely on
the <code>bfo</code> parameter passed to their <code>format(bfo,
...)</code> function to access the articles metadata: format
elements are not only used in the context of a single
record/article, but can be used to format several records/articles
at the same time. A notable exception is in the case of template
used for the <code>article</code> page.</li>
</ul>
<h3><a name="editJournalElement">5.1 Editing Format Elements - Best practices</a></h3>
<p>As said above, WebJournal format elements are not used only to
format a single article/record: they are used as a generic way to
provide dynamic content to your journal, such as the main navigation
menu containing the categories defined for your journal, or a
dynamically updated weather forecast section. As a consequence you
should not use the <code>bfo</code> object of
the <code>format_element(bfo, ...)</code> function to access the
articles metadata, as it does not correspond to a record (see
exceptions further below). You can however use it to access knowledge
bases and user information.</p>
<p>In order to access the context of the page, you should use
the <code>parse_url_string(bfo.user_uri['uri'])</code> function, which
returns a dictionary with the keys and values:</p>
<ul>
<li><code>journal_name</code>: the name of the journal as shown in
the URLs, and generally used as parameter to other functions,
as <code>string</code></li>
<li><code>category</code>: the currently displayed category
as <code>string</code> <small>(Default: first category)</small></li>
<li><code>issue</code>: the issue number in the form
&quot;08/2007&quot; as <code>string</code> <small>(Default: current
issue)</small></li>
<li><code>issue_number</code> and <code>issue_year</code>: same
as <code>issue</code>, but split by component,
as <code>integer</code></li>
<li><code>recid</code>: the displayed article ID
as <code>integer</code> <small>(Default: <code>-1</code>)</small></li>
<li><code>verbose</code>: verbosity,
as <code>integer</code> <small>(Default: <code>0</code>)</small></li>
<li><code>ln</code>: the language that should be used to display the
page, as <code>string</code> <small>(Default: preferred language
or <code>CFG_SITE_LANG</code>)</small></li>
<li><code>archive_year</code>: the year selected on the
archive/search page, if any,
as <code>integer</code> <small>(Default: <code>None</code>)</small></li>
<li><code>archive_search</code>: the pattern used on the
archive/search page, as <code>string</code> <small>(Default:
empty <code>string</code>)</small></li>
</ul>
<pre style="border:1px dashed #888;background-color:#EEE">
from invenio.webjournal_utils import parse_url_string
def format_element(bfo):
args = parse_url_string(bfo.user_info['uri'])
journal_name = args['journal_name']
category = args['category']
ln = args['ln']
...
</pre>
<p>These values remain empty if they do not make sense in the
context. For example, the recid value will be empty when displaying an
index page: we are not displaying a specific article.</p>
<p><strong>Note</strong> the difference between <code>bfo.lang</code>
and the &quot;<code>ln</code>&quot; value returned
by <code>parse_url_string(..)</code>: the former represents the
user-chosen language on your Invenio installation, while the
latter is the more appropriate language to display the journal, based
on the languages defined in your journal configuration
file. Propagate <code>bfo.lang</code> through links, but display your
article/interface using the value returned
by <code>parse_url_string(..)</code>.</p>
<h4>Other WebJournal helper functions for format elements</h4>
<p>The <code>webjournal_utils.py</code> file contains several
functions that should help you work with the WebJournal module. Please
refer to this file for the list of available functions.</p>
<h3><a name="editJournalAlertLayout">5.2 Alert HTML layout - Best practices</a></h3>
<p>The HTML "alert" (or newsletter) is sent based on the homepage
("Index" format template) of the journal of a specific issue. In order
to maximize the chances for the newsletter to display correctly in the
recipients mail clients, the linked CSS files are embedded into the
source of the email. Because of the very varying level of support for
HTML in mail clients (including web-based ones) you should check that
the markup of your pages will be adequate for your targeted readers,
and simply the markup if necessary.</p>
<p>You can include some specific markup in your "index" format
template to define areas that should not be sent as part of the
newsletter. Use <code>&lt;!--START_NOT_FOR_ALERT--&gt;</code> to mark
the beginning of an area that should not be included in the
newsletter, and <code>&lt!--END_NOT_FOR_ALERT--&gt;</code> to mark the
end of such area.
<p>
<h2><a name="addArticles">6. Submit Articles</a></h2>
<p>Journal articles are nothing more than regular records having some
specific MARC fields. Hence they should be entered into the system
like any other record: provide a submission to your journal editors,
or input MARCXML using BibUpload. Have a look at
the <a href="<CFG_SITE_URL>/help/hacking/webjournal-record-metadata">metadata
requirements</a> of a WebJournal record.</p>
<h3><a name="draftArticles">6.1 Draft/Unreleased/Offline Articles</a></h3>
<p>
Since articles are just regular records, you should ensure that your
readers do not have access to these records before the issue they
belong to is released. Indeed, even though the articles can be hidden
from the journal interface (depending on the value of the
configuration variable <strong>hide_unreleased_issues</strong>), they
are still accessible from the standard Invenio interface (the CDS
Invenio search/browse interface is independent from the WebJournal
Module, as the WebJournal interface is independent from the CDS
Invenio search/browse interface)
</p>
<p>
In order to deal with unreleased articles, you can prepare a
submission that can change some field of a record to flag it as
"<em>draft</em>" or "<em>offline</em>" when necessary. These draft
records should go to a restricted "Drafts" collection that only
editors can see. Just before the issue is ready to be released, the
editor can remove the "Draft" flag from each article.</p>
<p>A suggested setting is to map each category of your journal to both
a public and a restricted WebSearch collections. For example, your
"sport" category may have a public "Sport" collection, and a
restricted "Restricted Sport" collection. Your submission would for
example flag/unflag the "Draft" by changing the collection
field <code>980__a</code> based on the parameter of the
submission: <code>980__a:myJournalSportDraft</code> &lt;-&gt;
<code>980__a:myJournalSport<strike>Draft</strike></code>.
</p>
<p>
One of the drawbacks of this solution is that each article has to be
manually "approved" <em>just before</em> releasing the issue. A
workaround is to set your journal configuration
variable <b>remove_keyword</b> to value "<code>DRAFT</code>":
that tells WebJournal to remove all occurrences of this keyword from
the articles when a new issue is released. You then no longer have to
take care of manually remove the "draft" flag from all these
articles.<br/> Note that this technique applies only to <em>all</em>
articles of the <em>released issue</em>, but that the following tags
are not affected by this
removal: <code>100</code>, <code>245</code>, <code>246</code>,
<code>520</code>, <code>590</code> and <code>700</code>. You should
therefore carefully choose your keyword so that it does not interfere
with other values of your record.
</p>
<h3><a name="draftPreview">6.2 Preview Unreleased Issues</a></h3>
<p>By tweaking the URL, you can access the desired journal issue. Even
if the unreleased issue is hidden to users, editors should be allowed
to access it (See <a href="#accessControlIssue">Issue Control
System</a> section).</p>
<h2><a name="accessControl">7. Access Control</a></h2>
<h3><a name="accessControlSubmit">7.1 Articles Submission</a></h3>
<p>Since submission is performed using WebSubmit, you can apply the
standard procedures to restrict submissions of records.</p>
<h3><a name="accessControlIssue">7.2 Issue Control System</a></h3>
<p>You can restrict access to the issue control system by using the
"<code>cfgwebjournal</code>" WebAccess action. This action takes the
journal name as parameter in order to restrict access to selected
journal(s) only. A second parameter "<code>with_editor_rights</code>"
must be set to "yes" in order for the authorized roles to edit apply
changes using the interface (including sending alerts, releasing
issues, etc.)<br/>
Note that this action also lets your editors change your journal
configuration file (unless the file is protected on disk, which is
recommended).
</p>
<h2><a name="troubleshoots">8. Troubleshoots</a></h2>
<h3><a name="updateCache">8.1 Update Cache</a></h3>
<p>
WebJournal makes heavy use of caches in order to optimize the serving
speed. Journal editors can regenerate the journal cache, but it does
not apply to old issues, or cache that has been generated by some
widgets. To clean the cache, remove the files
in <nobr><code>/opt/invenio/var/cache/webjournal/</code><b>yourjournal</b></nobr>.
Cached files starts with <code>issue_year</code>, followed by
the <code>category</code> so that it is easy to remove the caches for
a specific issue/section. Examples:
</p>
<pre>
$ rm /opt/invenio/var/cache/webjournal/AtlantisTimes/07_2009_*
$ rm /opt/invenio/var/cache/webjournal/AtlantisTimes/07_2009_index_News*
</pre>
<p>You might want to remove some other specific files created by some
widgets, for example:</p>
<pre>
$ rm /opt/invenio/var/cache/webjournal/AtlantisTimes/weather.html
</pre>
<h3><a name="issueReleases">8.2 Manage Issue Releases</a></h3>
<p>Issues are usually managed by the journal editors, using the web
interface. You might have to help your editors if they released an
issue by mistake, or created. Have a look at
the <a href="<CFG_SITE_URL>/help/hacking/webjournal-table-structure">WebJournal
Table Structure</a> hacking guide to find out how you can easily
update entries in the WebJournal tables.</p>
c4science · Help