Homec4science
Diffusion invenio-infoscience (master) Browse

R3600/modules/bibformat/doc/admin/bibformat-admin-guide.webdoc
51bfbcb9fa42master

Last Change
Raw File

bibformat-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:BibFormat 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="#shortIntro">Overview</a></strong>
<ul style="list-style-type:None">
<li>1.1&nbsp;&nbsp;<a href="#philosophy">How BibFormat works</a></li>
<li>1.2&nbsp;&nbsp;<a href="#tutorial">Short Tutorial</a></li>
<li>1.3&nbsp;&nbsp;<a href="#administerWebFile">Administer Through the Web Interface or Through the Configuration files</a></li>
</ul>
</li>
<li><strong>2. <a href="#outputFormats">Configure Output Formats</a></strong>
<ul style="list-style-type:None">
<li>2.1&nbsp;&nbsp;<a href="#addOutputFormat">Add an Output Format</a></li>
<li>2.2&nbsp;&nbsp;<a href="#removeOutputFormat">Remove an Output Format</a></li>
<li>2.3&nbsp;&nbsp;<a href="#rulesOutputFormat">Edit the Rules of an Output Format</a></li>
<li>2.4&nbsp;&nbsp;<a href="#attrsOutputFormat">Edit the Attributes of an Output Format</a></li>
<li>2.5&nbsp;&nbsp;<a href="#dependenciesOutputFormat">Check the Dependencies an Output Format</a></li>
<li>2.6&nbsp;&nbsp;<a href="#validityOutputFormat">Check the Validity an Output Format</a></li>
</ul>
</li>
<li><strong>3. <a href="#formatTemplates">Configure Format Templates</a></strong>
<ul style="list-style-type:None">
<li>3.1&nbsp;&nbsp;<a href="#addFormatTemplate">Add a Format Template</a></li>
<li>3.2&nbsp;&nbsp;<a href="#removeFormatTemplate">Remove a Format Template</a></li>
<li>3.3&nbsp;&nbsp;<a href="#codeFormatTemplate">Edit the Code of a Format Template</a>
<li>3.4&nbsp;&nbsp;<a href="#editFormatTemplate">Basic Editing</a></li>
<li>3.5&nbsp;&nbsp;<a href="#elementsInFormatTemplate">Use Format Elements</a></li>
<li>3.6&nbsp;&nbsp;<a href="#previewFormatTemplate">Preview a Format Template</a></li>
<li>3.7&nbsp;&nbsp;<a href="#internationalizationTemplate">Internationalization (i18n)</a></li>
<li>3.8&nbsp;&nbsp;<a href="#escapeFormatTemplate">Escaping special HTML/XML characters</a></li>
<li>3.9&nbsp;&nbsp;<a href="#attrsFormatTemplate">Edit the Attributes of a Format Template</a></li>
<li>3.10&nbsp;<a href="#dependenciesFormatTemplate">Check the Dependencies of a Format Template</a></li>
<li>3.11&nbsp;<a href="#validityFormatTemplate">Check the Validity a Format Template</a></li>
<li>3.12&nbsp;<a href="#xslFormatTemplate">XSL Format Templates</a></li>
</ul>
</li>
<li><strong>4. <a href="#FormatElements">Configure Format Elements</a></strong>
<ul style="list-style-type:None">
<li>4.1&nbsp;&nbsp;<a href="#addFormatElement">Add a Format Element</a></li>
<li>4.2&nbsp;&nbsp;<a href="#removeFormatElement">Remove a Format Element</a></li>
<li>4.3&nbsp;&nbsp;<a href="#codeFormatElement">Edit the Code of a Format Element</a></li>
<li>4.4&nbsp;&nbsp;<a href="#previewFormatElement">Preview a Format Element</a></li>
<li>4.5&nbsp;&nbsp;<a href="#internationalizationFormatElement">Internationalization (i18n)</a></li>
<li>4.6&nbsp;&nbsp;<a href="#escapeFormatElement">Escaping special HTML/XML characters</a></li>
<li>4.7&nbsp;&nbsp;<a href="#attrsFormatElement">Edit the Attributes of a Format Element</a></li>
<li>4.8&nbsp;&nbsp;<a href="#dependenciesFormatElement">Check the Dependencies of a Format Element</a></li>
<li>4.9&nbsp;&nbsp;<a href="#validityFormatElement">Check the Validity of a Format Element</a></li>
<li>4.10&nbsp;<a href="#browseDocFormatElement">Browse the Format Elements Documentation</a></li>
</ul>
</li>
<li><strong>5. <a href="#KBs">Configure Knowledge Bases</a></strong>
<ul style="list-style-type:None">
<li>5.1&nbsp;&nbsp;<a href="#addKB">Add a Knowledge Base</a></li>
<li>5.2&nbsp;&nbsp;<a href="#removeKB">Remove a Knowledge Base</a></li>
<li>5.3&nbsp;&nbsp;<a href="#addMappingKB">Add a Mapping</a></li>
<li>5.4&nbsp;&nbsp;<a href="#removeMappingKB">Remove a Mapping</a></li>
<li>5.5&nbsp;&nbsp;<a href="#editMappingKB">Edit a Mapping</a></li>
<li>5.6&nbsp;&nbsp;<a href="#attrsKB">Edit the Attributes of a Knowledge Base</a></li>
<li>5.7&nbsp;&nbsp;<a href="#validityKB">Check the Dependencies a Knowledge Base</a></li>
</ul style="list-style-type:None">
</li>
<li><strong>6. <a href="#BibReformat">Run BibReformat</a></strong>
<ul style="list-style-type:None">
<li>6.1&nbsp;&nbsp;<a href="#runBibReformat">Run BibReformat</a></li>
</ul>
</li>
<li><strong>7. <a href="#Appendix">Appendix</a></strong>
<ul style="list-style-type:None">
<li>7.1&nbsp;&nbsp;<a href="#marcNotation">MARC Notation in Formats</a></li>
<li>7.2&nbsp;&nbsp;<a href="#migration">Migrating from Previous BibFormat</a></li>
<li>7.3&nbsp;&nbsp;<a href="#integrationDreamweaver">Integrating BibFormat into Dreamweaver MX</a></li>
<li>7.4&nbsp;&nbsp;<a href="#faq">FAQ</a></li>
</ul>
</li>
</ul>
<style type="text/css">
<!--
.outputFormatBox {
font-weight: bold;
color: #990000;
background-color: #F4CBCC;
border: 2px dotted #FF0000;
}
.outputFormatBoxMain {
font-weight: bold;
color: #990000;
background-color: #F4CBCC;
border: 1px solid #FF0000;
padding: 4px;
}
.formatTemplateBox {
font-weight: bold;
color: #003300;
background-color: #DEFDBB;
border: 2px dotted #009900;
}
.formatTemplateBoxMain {
font-weight: bold;
color: #003300;
background-color: #DEFDBB;
border: 1px solid #009900;
padding: 5px;
}
.formatElementBox {
font-weight: bold;
color: #000066;
background-color: #CCFFFF;
border: 2px dotted #0066CC;
}
.formatElementBoxMain {
font-weight: bold;
color: #000066;
background-color: #CCFFFF;
border: 1px solid #0066CC;
padding: 5px;
}
-->
</style>
<h2><a name="shortIntro">1. Overview</a></h2>
<h3><a name="philosophy">1.1 How BibFormat Works</a></h3>
<p>BibFormat is in charge of formatting the bibliographic records that
are displayed to your users. It is called by the search engine when it has to
format a record.</p>
<p>As you might need different kind of formatting depending
on the type of record, but potentially have a huge amount of records in your database, you cannot specify
for each of them how they should look. Instead BibFormat uses a rule-based decision process
to decide how to format a record.<br/>
The best way to understand how BibFormat works is to have a look at
a typical workflow:</p>
<table width="90%" border="0" cellspacing="5" cellpadding="0">
<tr>
<td colspan="2"><span style="white-space: nowrap;">Step 1:</span></td>
</tr>
<tr valign="top">
<td>
<img src="<CFG_SITE_URL>/img/admin/bibformat-guide-url_bar.png" alt="http://cdsweb.cern.ch/search?recid=946417&amp;ln=en&amp;of=hd"/>
</td>
<td width="50%">When CDS Invenio has to display a record, it
asks BibFormat to format the record with the given output format
and language. For example here the requested output format is
<span class="outputFormatBox">hd</span>, which is a short code
for &quot;HTML Detailed&quot;. This means that somehow a user arrived on
the page of the record and asked for a detailed view of the
record.</td>
</tr>
<tr>
<td colspan="2"><hr/><span style="white-space: nowrap;">Step 2:</span></td>
</tr><tr valign="top">
<td><img src="<CFG_SITE_URL>/img/admin/bibformat-guide-bfo_hd_rules.png" alt="1. Use Template [Picture HTML Detailed] if tag [980__a] is equal to [PICTURE] 2. Use Template [Thesis HTML detailed] if tag [980__a] is equal to [THESIS] 3. By default use [Default HTML Detailed]"/>
<td>
Beside is a screenshot of the "hd" or "HTML Detailed" output format.
You can see that the output format does not specify how to format the record, but
contains a set of rules which define which template must be used.<br/>
The rules are evaluated from top to bottom.
Each rule defines a condition on a field of the record, and a format template to use to
format the record if the condition matches.
Let's say that the field 980__a of the record is equal to
&quot;Picture&quot;. Then first rules matches, and format template
<span class="formatTemplateBox">Picture HTML Detailed</span> is
used for formatting by BibFormat.<br/>
You can add, remove or edit output formats <a href="bibformatadmin.py/output_formats_manage">here</a></td>
</tr>
<tr>
<td colspan="2"><hr/><span style="white-space: nowrap;">Step 3:</span></td>
</tr>
<tr valign="top">
<td>
<div class="formatTemplateBoxMain"><code>
&lt;h1 align=&quot;center&quot;&gt;&lt;BFE_MAIN_TITLE/&gt;&lt;/h1&gt;<br />
&lt;p align=&quot;center&quot;&gt;<br />
<span class="formatElementBox">&lt;BFE_AUTHORS separator=&quot;; &quot;
link=&quot;yes&quot;/&gt;</span>&lt;br/&gt;<br />
&lt;BFE_DATE format=&quot;%d %B %Y&quot;&gt; .- &lt;BFE_NB_PAGES suffix=&quot;p&quot;&gt;<br />
&lt;/p&gt;</code></div></td>
<td>We see an extract of the Picture HTML Detailed format on the right,
as it is shown in the template editor. As you can see it
is mainly written using HTML. There are however some tags that
are not part of standard HTML. Those tags that starts with
<em>&lt;BFE_</em> are placeholders for the record values. For
example &lt;BFE_MAIN_TITLE/&gt; tells BibFormat to write the title
of the record. We call these tags &quot;elements&quot;. Some
elements have parameters. This is the case of the <span
class="formatElementBox">&lt;BFE_AUTHORS&gt; </span> element,
which can take <em>separator</em> and <em>link</em> as
parameters. The value of separator will be used to separate
authors' names and the link parameter tells if links to authors'
websites have to be created.
All elements are described in the <a href="bibformatadmin.py/format_elements_doc">elements documentation</a>.<br/>
You can add, remove or edit format templates <a href="bibformatadmin.py/format_templates_manage">here</a>.
<p>
In addition to this modified HTML language, BibFormat also supports XSL stylesheets as format templates.
Read the <a href="#xslFormatTemplate">XSL Format Templates</a> section to learn more about XSLT support for your format templates.
</p>
</td>
</tr>
<tr><td colspan="2"><hr/><span style="white-space: nowrap;">Step 4:</span></td></tr>
<tr valign="top">
<td><div class="formatElementBoxMain">
<code>def format(bfo, separator='; ', link='no'):<br />
&nbsp;&nbsp;&nbsp;&quot;&quot;&quot;<br />
&nbsp;&nbsp;&nbsp;Prints the list of authors for the record<br /><br />
&nbsp;&nbsp;&nbsp;@param separator a character to separate the authors<br />
&nbsp;&nbsp;&nbsp;@param link if 'yes' print HTML links to authors<br />
&nbsp;&nbsp;&nbsp;&quot;&quot;&quot;<br />
&nbsp;&nbsp;&nbsp;authors = bfo.fields(&quot;100__a&quot;)<br />
&nbsp;&nbsp;&nbsp;if link == 'yes':<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;authors = map(lambda x: '&lt;a href="'+CFG_SITE_URL+'/search?f=author&p='\<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
+ quote(x) +'"&gt;'+x+'&lt;/a&gt;', authors)<br />
&nbsp;&nbsp;&nbsp;return authors.split(separator)</code>
</div></td>
<td>A format element is written in Python. It acts as a bridge
between the record in the database and the format
template. Typically you will not have to write or read format
elements, just call them from the templates. Each element outputs
some text that is written in the template where it is called.<br/>
Developers can add new elements by creating a new file, naming it
with the name of element, and write a Python <code>format</code>
function that takes as parameters the parameters of the elements
plus a special one <code>bfo</code>. Regular Python code can be
used, including import of other modules.</td>
</tr>
</table>
<br />
<p>In summary BibFormat is called by specifying a record and an output
format, which relies on different templates to do the formatting, and
which themselves rely on different format elements. Only developers need to modify
the format elements layer.<p>
<table width="50%" border="0" align="center" cellpadding="0" cellspacing="2">
<tr align="center">
<td colspan="4"><div class="outputFormatBoxMain">Output Format</div></td>
</tr>
<tr align="center">
<td colspan="2"><div class="formatTemplateBoxMain">Template</div></td>
<td colspan="2"><div class="formatTemplateBoxMain">Template</div></td>
</tr>
<tr align="center">
<td><div class="formatElementBoxMain">Format Element</div></td>
<td><div class="formatElementBoxMain">Format Element</div></td>
<td><div class="formatElementBoxMain">Format Element</div></td>
<td><div class="formatElementBoxMain">Format Element</div></td>
</tr>
</table>
<p>You should now understand the philosophy behind BibFormat. </p>
<h3><a name="tutorial">1.2 Short Tutorial</a></h3>
<p> Let's try to create our own format.
This format will just print the title of a record.
</p>
<p>First go to the main <a href="bibformatadmin.py">BibFormat admin page</a>.
Then click on the "Manage Ouput Format" links. You will see the list of all output formats:</p>
<img src="<CFG_SITE_URL>/img/admin/bibformat-guide-bfo_manage.png" alt="Output formats management page"/>
<p>This is were you can delete, create or check output formats.
The menu at the top of the page let you go to other admininistration pages.<br/>
Click on the "Add New Output Format" button at the bottom of the page. You can then fill in some attributes
for the output format. Choose "title" as code, "Only Title" as name and "Prints only title" as description:</p>
<img src="<CFG_SITE_URL>/img/admin/bibformat-guide-bfo_attributes.png" alt="Screenshot of the Update Output Format Attributes page" />
<p>Leave other fields blank, and click on the button "Update Output format Attributes".<br/> You are then
redirected to the rules editor. Notice the menu at the top which let you close the editor, change the attributes again
and check the output format. However do not click on these links before saving your modification of rules!</p>
<img src="<CFG_SITE_URL>/img/admin/bibformat-guide-bfo_rules.png" alt="Output format menu" />
<p>As our format does not need to have a different behaviour depending on the record, we do not need to add new rules to the format. You just need to select a format template in the "By default use" list. However we first have to create our special format template that only print titles. So close the editor using the menu at the top of the page, and in the menu that just appeared instead, click on "Manage Format Templates". In a similar way to output formats, you see the list of format templates.</p>
<img src="<CFG_SITE_URL>/img/admin/bibformat-guide-bft_manage.png" alt="Format template management page" />
<p>
Click on the "Add New Format Template" button at the bottom of the page. As for the output format, fill in the attributes of the template with name "Title" and any relevant description.
</p>
<img src="<CFG_SITE_URL>/img/admin/bibformat-guide-bft_attributes.png" alt="update format template attributes"/>
<p>Click on the "Update Output Format Attributes" button. You are redirected to the template editor. The editor is divided in three parts. The upper left part contains the code of the template. The bottom part is a preview of the template. The part on the right side is a short remainder of the format elements you can use in you template. You can hide this documentation by clicking on "Hide Documentation".</p>
<img src="<CFG_SITE_URL>/img/admin/bibformat-guide-bft_editor2.png" alt="Format template editor" />
<p>The above screenshot shows the template code already filled in. It calls the <code>BFE_TITLE</code> element. If you do not know the name of the element you want to call, you can search for it using the embedded documentation search. You can try to add other elements into your template, or write some HTML formatting.</p>
<p>When you are satisfied with your template, click on the save button, close the editor and go back to the "Only titles" output format rules editor. There select the template you have just created in the "Use by default" menu and save the ouput format and you are done. </p>
<p>This tutorial does not cover all aspects of the management of formats (For example "Knowledge bases" or internationalization). It also does not show all the power of output formats, as the one we have created simply call a template. However you have seen enough to configure BibFormat trough the web interface. Read the sections below to learn more about it.</p>
<h3><a name="administerWebFile">1.3 Administer Through the Web Interface or Through the Configuration files</a></h3>
<p>BibFormat can be administered in two ways. The first way is to use the provided web interface. It should be the most
convenient way of doing for most users. The web interface is simple to use and provides great tools to manage your formats. Its only limitation concerns the format elements, which cannot be modified using it (But the web interface provide a dynamically generated documentation of your elements). <br/>
The other way to administer BibFormat is to directly modify the configuration files using your preferred text editor. This way of doing can bring much power to advanced users, but requires an access to the server's files. It also requires that the user double-check his modifications, or use the web interface to ensure the validity and correctness of his formats.</p>
<p>In this manual we will show both ways of doing. For each explication we show first how to do it through the web interface, then how to do it by manipulating the configuration files. Non-power users can stop reading as soon as they encounter the text "For developers and adventurers only".</p>
<p>We generally recommend to use the web interface, excepted for writing
format elements.</p>
<h2><a name="outputFormats">2. Output Formats</a></h2>
<p>As you potentially have a huge amount of
bibliographic records, you cannot specify manually for each of them
how it should be formatted. This is why you can define rules that will
allow BibFormat to understand which kind of formatting to apply to a given
record. You define this set of rules in what is called an "output
format".</p>
<p>You can have different output formats, each with its own characteristics.
For example you certainly want that when multiple bibliographic records are
displayed at the same time (as it happens in search results), only
short versions are shown to the user , while a detailed record is
preferable when a single record is displayed, whatever the type of the record.<br/>
You might also want to
let your users decide which kind of output they want. For example you
might need to display HTML for regular web browsing, but would also
give a BibTeX version of the bibliographic reference for direct
inclusion in a LaTeX document.</p>
<p>To summarize, an output format groups similar kind of formats, specifying which kind
of formatting has to be done, but not how it has to be done.</p>
<h3><a name="addOutputFormat">2.1 Add an Output Format</a></h3>
<p>To add a new output format, go to the <a href="bibformatadmin.py/output_formats_manage">Manage Output Formats</a> page and click on the "Add New Output Format" button at the bottom of the page. The format has been created. You can then specify the attributes of the output format. See <a href="#attrsOutputFormat">Edit the Attributes of an Output Format</a> to learn more about it.<p>
<strong>For developers and adventurers only:</strong>
<p>Alternatively you can directly add a new output format file into the
/etc/bibformat/outputs/ directory of your CDS Invenio installation, if you have
access to the server's files. Use the format extension .bfo for your file.</p>
<p>You should also check that user <code>www-data</code> has read/write access to the file,
if you want to be able to modify the rules through the web interface.</p>
<h3><a name="removeOutputFormat">2.2 Remove an Output Format</a></h3>
<p>To remove an output format, go to the <a href="bibformatadmin.py/output_formats_manage">Manage Output Formats</a> page and click on the "Delete" button facing the output format you want to delete. If you cannot click on the button (the button is not enabled), this means that you do not have sufficent priviledge to do so (Format is protected. Contact the administrator of the system).</p>
<strong>For developers and adventurers only:</strong>
<p>You can directly remove an output format from the /etc/bibformat/outputs/ directory of your CDS Invenio installation.
However you must make sure that it is removed from the tables <code>format</code> and <code>formatname</code> in the database, so that other modules know that it is not longer available.</p>
<h3><a name="rulesOutputFormat">2.3 Edit the Rules of an Output Format</a></h3>
<p>When you create a new output format, you can at first only specify the default template,
that is the one which is used when all rules fail. In the case of a basic output format,
this is enough. You can however add other rules, by clicking on the "Add New Rule" button.<br/>
Once you have added a rule, you can fill it with a condition, and a template that should be used
if the condition is true. For example the rule</p>
<img src="<CFG_SITE_URL>/img/admin/bibformat-guide-bfo_edit_rule.png" alt="Rule: Use template [Picture HTML Detailed] if field [980__a] is equal to [PICTURE]"/>
<p> will use template named "Picture HTML Detailed" if the field <code>980__a</code> of the record to format is equal to "Picture".
Note that text "PICTURE" will match any letter case like "picture" or "Picture".
Leading and trailing spaces are ignored too (" Picture " will match "PICTURE").
<br/><b>Tips:</b> you can use a regular expression as text. For example "PICT.*" will match "pictures"
and "PICTURE".</p>
<p><div style="float:right"><img src="<CFG_SITE_URL>/img/admin/bibformat-guide-bfo_edit_rule2.png" alt="Reorder rules using arrows"/></div>
The above configuration will use format template "Default HTML Detailed" if all above rules fail (in that case
if field 980__a is different from "PICTURE"). If you have more rules, you decide in which order the conditions are evaluated. You can reorder rules by clicking on the small arrows on the left of the rules.
</p>
<p>Note that when you are migrating your output formats from the old PHP BibFormat, you might not have translated all the formats to which your output formats refers. In that case you should use <code>defined in old BibFormat</code> option in the format templates menu, to make BibFormat understand that a match for this rule must trigger a call to the <i>Behaviour</i> of the old BibFormat. See section on <a href="#runSideBySide">Run old and new formats side by side</a> for more details on this.</p>
<strong>For developers and adventurers only:</strong>
<p>To write an output format, use the following syntax:<br/>
First you
define which field code you put as the conditon for the rule.
You suffix it with a column. Then on next lines, define the values of
the condition, followed by --- and then the filename of the template
to use:</p>
<pre>
tag 980__a:
PICTURE --- PICTURE_HTML_BRIEF.bft
PREPRINT --- PREPRINT_HTML_BRIEF.bft
PUBLICATION --- PUBLICATION_HTML_BRIEF.bft
</pre>
<p>
This means that if value of field 980__a is equal to PICTURE, then we
will use format template PICTURE_HTML_BRIEF.bft. Note that you must
use the filename of the template, not the name. Also note that spaces
at the end or beginning are not considered. On the following lines,
you can either put other conditions on tag 980__a, or add another tag on
which you want to put conditions.</p>
<p>At the end you can add a default condition:</p>
<pre>
default: PREPRINT_HTML_BRIEF.bft
</pre>
<p>which means that if no condition is matched, a format suitable for
Preprints will be used to format the current record.<p>
<p>The output format file could then look like this:</p>
<pre>
tag 980__a:
PICTURE --- PICTURE_HTML_BRIEF.bft
PREPRINT --- PREPRINT_HTML_BRIEF.bft
PUBLICATION --- PUBLICATION_HTML_BRIEF.bft
tag 8560_f:
.*@cern.ch --- SPECIAL_MEMBER_FORMATTING.bft
default: PREPRINT_HTML_BRIEF.bft
</pre>
<p> You can add as many rules as you want. Keep in mind that they are read
in the order they are defined, and that only first rule that
matches will be used.
Notice the condition on tag 8560_f: it uses a regular expression to
match any email address that ends with @cern.ch (the regular
expression must be understandable by Python)
</p>
<h3><a name="attrsOutputFormat">2.4 Edit the Attributes of an Output Format</a></h3>
<p>An output format has the following attributes:
<ul>
<li><code>code</code>: a short identifier that is used to identify the output format. It must be unique and contain a maximum of 6 letters. Note that the <b>code is not case sensitive</b> ("HB" is equal to "hb").</li>
<li><code>content type</code>: this is the content type of the format, specified in Mime. For example if you were to produce an Excel output, you could use <code>application/ms-excel</code> as content type. If a content type is specified, CDS Invenio will not print the usual header and footerfor the page, but will trigger a download in the client's browser when viewing the page (Unless the browser handles this content type).</li>
<li><code>name</code>: a generic name to display in the interface for this output format.</li>
<li>(*) <code>name</code>: internationalized names for the output format, used for displaying localized name in the search interface.</li>
<li><code>description</code>: an optional description for the output format.</li>
</ul></p>
<p><b>Please read this information regarding output format codes:</b>
There are some reserved codes that you should not use, or at least be aware of when choosing a code for your
output format. The table below summarizes these special words:
</p>
<p align="center">
<small>
<table width="40%" border="1">
<tr>
<th>Code</th><th>Purpose</th>
</tr><tr>
<td>HB</td><td>Used for displaying list of results of a search.</td>
</tr><tr>
<td>HD</td><td>Used when no format is specified when viewing a record.</td>
</tr><tr>
<td>HM</td><td>Used for Marc output. The format is special in the sense that it filters
fields to display according to the 'ot' GET parameter of the HTTP request.</td>
</tr><tr>
<td>Starting with letter 't'</td><td>Used for displaying the value of the field specified by the 'ot' GET parameter of the HTTP request.</td>
</tr><tr>
<td>Starting with 3 digits</td><td>Used for displaying the value of the field specified by the digits.</td>
</tr>
</table>
</small>
</p>
<strong>For developers and adventurers only:</strong>
<p>Excepted for the code, output format attributes cannot be changed in the output format file. These
attributes are saved in the database. As for the <code>code</code>, it is the name of the output format file,
without its <code>.bfo</code> extension. If you change this name, do not forget to propagate the modification in the database.</p>
<h3><a name="dependenciesOutputFormat">2.5 Check the Dependencies an Output Format</a></h3>
<p>To check the dependencies of an output format on format templates, format elements and tags,
go to the <a href="bibformatadmin.py/output_formats_manage">Manage Output Formats</a> page, click on
the output format you want to check, and then in the menu click on "Check Dependencies".</p>
<img src="<CFG_SITE_URL>/img/admin/bibformat-guide-bfo_check_deps.png" alt="Check Dependencies menu"/>
<p>The next page shows you:
<ul> <li>the format templates which might be called by the rules of the output format</li>
<li>the elements used in each of these templates</li>
<li>the Marc tags involved in these elements</li>
</ul>
Note that some Marc tags might be omitted.</p>
<h3><a name="validityOutputFormat">2.6 Check the Validity an Output Format</a></h3>
<p>To check the validity of an output format, simply go to the <a href="bibformatadmin.py/output_formats_manage">Manage Output Formats</a> page, and look at the column 'status' for the output format you want to check. If message "Ok" is there,
then no problem was found with the output format. If message 'Not Ok' is in the column, click on it to see
the problems that have been found for the output format.</p>
<h2><a name="formatTemplates">3. Format Templates</a></h2>
<p>A format template defines how a record should be formatted. For example it specifies which fields of the record are to be displayed, in which order and with which visual attributes. Basically the format template is written in HTML, so that it is easy for anyone to edit it. BibFormat also has support for XSLT for formatting. Read more <a href="#xslFormatTemplate">about XSL format templates here</a>.</p>
<h3><a name="addFormatTemplate">3.1 Add a Format Template</a></h3>
<p>To add a new format template, go to the <a href="bibformatadmin.py/format_templates_manage">Manage Format Templates</a> page and click on the "Add New Format Template" button at the bottom of the page. The format has been created. You can then specify the attributes of the format template, or ask to make a copy of an existing format.
See <a href="#attrsFormatTemplate">Edit the Attributes of a Format Template</a> to learn more about editing the attributes.<p>
<strong>For developers and adventurers only:</strong>
<p>Alternatively you can directly add a new format template file into the
/etc/bibformat/format_templates/ directory of your CDS Invenio installation, if you have
access to the server's files. Use the format extension .bft for your file.</p>
<p>You should also check that user <code>www-data</code> has read/write access to the file,
if you want to be able to modify the code and the attributes of the template through the web interface.</p>
<h3><a name="removeFormatTemplate">3.2 Remove a Format Template</a></h3>
<p>To remove a format template, go to the <a href="bibformatadmin.py/format_templates_manage">Manage Format Templates</a> page and click on the "Delete" button facing the format template you want to delete. If you cannot click on the button (the button is not enabled), this means that you do not have sufficent priviledge to do so (Format is protected. Contact the administrator of the system).</p>
<strong>For developers and adventurers only:</strong>
<p>You can directly remove the format template from the /etc/bibformat/format_templates/ directory of your CDS Invenio installation.</p>
<h3><a name="codeFormatTemplate">3.3 Edit the Code of a Format Template</a></h3>
<p>You can change the formatting of records by modifying the code of a template.
<p>To edit the code of a format template
go to the <a href="bibformatadmin.py/format_templates_manage">Manage Format Templates</a> page. Click on
the format template you want to edit to load the template editor.</p>
<p>The format template editor contains three panels. The left upper panel is the code editor. This is were
you write the code that specifies the formatting of a template. The right-most panel is a short documentation
on the "bricks" you can use in your format template code. The panel at the bottom of the page allows you to preview the template. </p>
<img src="<CFG_SITE_URL>/img/admin/bibformat-guide-bft_editor.png" alt="Template Editor Page"/>
<p>The following sections explain how to write the code that specifies the formatting.</p>
<h4><a name="editFormatTemplate">3.4 Basic Editing</a></h4>
<p>The first thing you have to know before editing the code is that everything you write in the
code editor is printed as such by BibFormat. Well almost everything (as you will discover later).</p>
<p>For example if you write "My Text", then for every record the output will be "My Text". Now let's say
you write "&lt;b&gt;My Text&lt;/b&gt;": the output will still be "&lt;b&gt;My Text&lt;/b&gt;", but as we display in a web browser, it will look like
"<b>My Text</b>" (The browser interprets the text inside tags &lt;b&gt;&lt;/b&gt; as "bold". Also note that the look may depend on the CSS style of your page).</p>
<p>Basically it means that you can write HTML to do the formatting. If you are not experienced with HTML you can use an HTML editor to create your layout, and the copy-paste the HTML code inside the template.</p>
<p>Do not forget to save your work by clicking on the save button before you leave the editor!</p>
<strong>For developers and adventurers only:</strong>
<p>
You can edit the code of a template using exactly the same syntax as in the web interface. The code of the template
is in the template file located in the /etc/bibformat/format_templates/ directory of your CDS Invenio installation. You just
have to take care of the attributes of the template, which are saved in the same file as the code. See <a href="#attrsFormatTemplate">Edit the Attributes of a Format Template</a> to learn more about it.
</p>
<h4><a name="elementsInFormatTemplate">3.5 Use Format Elements</a></h4>
<p>To add a dynamic behaviour to your format templates, that is display for example a different title
for each record or a different background color depending on the type of record, you can use the format elements.</p>
<p>Format elements are the smart bricks you can copy-paste in your code to get the attributes of template
that change depending on the record. A format element looks like a regular HTML tag. </p>
<p>For example, to print
the title of a record, you can write <code>&lt;BFE_TITLE /&gt;</code> in your template code where you want to diplay the title</p>
<p>Format elements can take values as parameters. This allows to customize the behaviour of an element. For example you can write <code>&lt;BFE_TITLE prefix="Title: " /&gt;</code>, and BibFormat will take care of printing the title for you, with prefix "Title: ". The difference between <code>Title: &lt;BFE_TITLE /&gt;</code> and <code>&lt;BFE_TITLE prefix="Title: " /&gt;</code> is that the first option will always write "Title: " while the second one will only print "Title: " if there exist a title for the record in the database. Of course there are chances that there is always a title for each record, but this can be useful for less common fields.</p>
<p>Some parameters are available for all elements. This is the case for the following ones:
<ul>
<li><code>prefix</code>: a prefix printed only if the record has a value for the element.</li>
<li><code>suffix</code>: a suffix printed only if the record has a value for the element.</li>
<li><code>default</code>: a default value printed if the record has no value for the element. In that case <code>prefix</code> and <code>suffix</code> are not printed.</li>
</ul>
</p>
<p>Some parameters are specific to elements. To get information on all available format elements you can read the <a href="bibformatadmin.py/format_elements_doc">Format Elements Documentation</a>, which is generated dynamically for all existing elements. it will show you what the element do and what parameters it can take.</p>
<p>While format elements looks like HTML tags, they differ in the followings ways from traditional ones:
<ul>
<li>A format element is a single tag: you cannot have <code>&lt;BFE_TITLE &gt;some text&lt;BFE_TITLE /&gt;</code> but only <code>&lt;BFE_TITLE /&gt;</code>.</li>
<li>The values of the parameters accept any characters, including &lt; and &gt;. The only limitation is that you cannot use the type of quotes that delimit that value: you can have for example <code>&lt;BFE_TITLE someParam="a lot of single quotes ' ' ' ' "/&gt;</code> or <code>&lt;BFE_TITLE someParam='a lot of double quotes " " " '/&gt;</code>, but not <code>&lt;BFE_TITLE someParam="a lot of same quotes as delimiter " " " "/&gt;</code>.</li>
<li>Format elements names always start with <code>BFE_</code>.</li>
<li>Format element can expand on multiple lines.</li>
</ul>
</p>
<p><b>Tips:</b> you can use the special element <code>&lt;BFE_FIELD tag="" /&gt;</code> to print the value
of any field of a record in your templates. This practice is however not
recommended because it would necessitate to revise all format
templates if you did change the meaning of the MARC code schema.</p>
<h4><a name="previewFormatTemplate">3.6 Preview a Format Template</a></h4>
<p>To preview a format template go to the <a href="bibformatadmin.py/format_templates_manage">Manage Format Templates</a> page and click on the format template you want to preview to open the template editor. The editor contains a preview panel at the bottom of the page.</p>
<img src="<CFG_SITE_URL>/img/admin/bibformat-guide-bft_preview.png" alt="Preview Panel"/>
<p>Simply click on " Reload Preview" button to preview the template (you do not need to save the code before previewing).<br/>
Use the "Language" menu to preview the template in a given language</p>
<p>You can fill in the "Search Pattern" field to preview a specific record. The search pattern uses exactly the same
syntax as the one used in the web interface. The only difference with the regular search engine is that only the first matching record is shown.</p>
<strong>For developers and adventurers only:</strong>
<p>If you do not want to use the web interface to edit the templates but still would like to get previews, you can open the preview frame of any format in a new window/tab. In this mode you get a preview of the template (if it is placed in the /etc/bibformat/format_templates/ directory of your CDS Invenio installation). The parameters of the preview are specified in the url: <ul>
<li><code>bft</code>: the filename of the format template to preview</li>
<li><code>ln</code>: the language to use for the preview</li>
<li><code>pattern_for_preview</code>: the search pattern to use for the preview</li>
</ul></p>
<h4><a name="internationalizationTemplate">3.7 Internationalization (i18n)</a></h4>
<p>You can add translations to your format templates. To do so enclose the text you want to localize
with tags corresponding to the two letters of the language. For example if we want to localize "title", write <code>&lt;en&gt;Title&lt;/en&gt;</code>. Repeat this for each language in which you want to make "title" available: <code>&lt;en&gt;Title&lt;/en&gt;&lt;fr&gt;Titre&lt;/fr&gt;&lt;de&gt;Titel&lt;/de&gt;</code>.
Finally enclose everything with <code>&lt;lang&gt; &lt;/lang&gt;</code> tags: <code>&lt;lang&gt;&lt;en&gt;Title&lt;/en&gt;&lt;fr&gt;Titre&lt;/fr&gt;&lt;de&gt;Titel&lt;/de&gt;&lt;/lang&gt;</code></p>
<p>For each &lt;lang&gt; group only the text in the user's language is displayed. If user's language is not
available in the &lt;lang&gt; group, your default CDS Invenio language is used.</p>
<h4><a name="escapeFormatTemplate">3.8 Escaping special HTML/XML characters</a></h4>
<p>By default, BibFormat escapes all values returned by format
elements. As a format template designer, you can assume in almost all
cases that the values you get from a format element will be escaped
for you. For special cases, you can set the parameter
<code>escape</code> of the element to '0' when calling it, to make
BibFormat understand that it must not escape the values of the
element, or to '1' to force the escaping. </p>
See the <a href="#listofescapingmodes">complete list of escaping modes</a>.
<p>
For example
<code>&lt;bfe_abstract /&gt;</code> will return:<br/>
<code>[...]We find that for spatially-flat cosmologies, background lensing</code><br/>
<code>clusters with reasonable mass-to-light ratios lying in the</code><br/>
<code>redshift range 0<span style="color:red;">&amp;lt;</span>1 are strongly excluded, [...]</code><br/><br/>
while <code>&lt;bfe_abstract escape="0"/&gt;</code> will return:<br/>
<code>[...]We find that for spatially-flat cosmologies, background lensing</code><br/>
<code>clusters with reasonable mass-to-light ratios lying in the</code><br/>
<code>redshift range 0<span style="color:red;">&lt;</span>1 are strongly excluded, [...]</code><br/><br/>
</p>
<p>In most cases, you will not set <code>escape</code> to 1, nor 0, but
just let the developer of the element take care of that for you.</p>
<p>Please note that values given in special parameters
<code>prefix</code>, <code>suffix</code>, <code>default</code> and
<code>nbMax</code> are never escaped, whatever the value of
<code>escape</code> is (but other parameters will). You have to take
care of that in your format template, as well as of all other values that
are not returned by the format elements.</p>
<h3><a name="attrsFormatTemplate">3.9 Edit the Attributes of a Format Template</a></h3>
<p>To edit the attributes of a format template
go to the <a href="bibformatadmin.py/format_templates_manage">Manage Format Templates</a> page, click on
the format template you want to edit, and then in the menu click on "Modify Template Attributes".</p>
<p>
A format template contains two attributes:
<ul>
<li><code>Name</code>: the name of the template</li>
<li><code>Description</code>: a short description of the template</li>
</ul>
<p>Note that changing these parameters has no impact on the formatting. Their purpose in only to
document the template.</p>
<p>If the name you have chosen already exists for another template, you name will be suffixed with an integer so that the name is unique.</p>
<p>You should also be aware that if you change the name of a format template, all output formats that were linking to this template will be changed to match the new name.</p>
<strong>For developers and adventurers only:</strong>
<p>You can change the attributes of a template by editing its file in the /etc/bibformat/format_templates/ directory of your CDS Invenio installation. The attributes must be enclosed with tags <code>&lt;name&gt; &lt;/name&gt;</code> and <code>&lt;description&gt; &lt;/description&gt;</code> and should ideally be placed at the beginning of the file.</p>
<p>Also note that the admin web interface tries to keep the name of the template in sync with the filename of the template. If the name is changed through the web interface, the filename of the template is changed, and all output formats that use this template are updated. You have to do update output formats manually if you change the filename of the template without the web interface.</p>
<h3><a name="dependenciesFormatTemplate">3.10 Check the Dependencies of a Format Template</a></h3>
<p>To check the dependencies of a format template
go to the <a href="bibformatadmin.py/format_template_manage">Manage Format Template</a> page, click on
the format template you want to check, and then in the menu click on "Check Dependencies".</p>
<img src="<CFG_SITE_URL>/img/admin/bibformat-guide-bfo_check_deps.png" alt="Check Dependencies menu"/>
<p>The next page shows you:
<ul> <li>The output formats that use this format template</li>
<li>the elements used in the template (and Marc tags use in these elements in parentheses)</li>
<li>A summary of all the Marc tags involved in the elements of the template</li>
</ul>
Note that some Marc tags might be omitted.</p>
<h3><a name="validityFormatTemplate">3.11 Check the Validity a Format Template</a></h3>
<p>To check the validity of a format template, simply go to the <a href="bibformatadmin.py/format_templates_manage">Manage Format Templates</a> page, and look at the column 'status' for the format template you want to check. If message "Ok" is there,
then no problem was found with the template. If message 'Not Ok' is in the column, click on it to see
the problems that have been found for the template.</p>
<h3><a name="xslFormatTemplate">3.12 XSL Format Templates</a></h3>
<p>In addition to the HTML-like syntax introduced in previous sections, BibFormat also
has support for server-side XSL transformation. Although you can do all the formatting using this custom HTML syntax, there are
cases where an XSL stylesheet might be preferred. XSLT is for example a natural choice
when you need to output complex XML, especially when your XML has a deep tree structure.
You might also prefer using XSLT if you already feel comfortable with XSL syntax.</p>
<p>XSL format templates are written using regular XSL. The template file has to be placed in the same folder
as regular format template files, and its file extension must be <code>.xsl</code>. The XSL template
are also visible through the web interface, as any regular format template file. However, some
functions like the "Dependencies checker" or the possibility to create a template or edit its attributes are not
available for the XSL templates.</p>
<p>In BibFormat XSL you have access to the following functions, provided you have declared <code>xmlns:fn="http://cdsweb.cern.ch/bibformat/fn"</code> in your stylesheet:</p>
<dl>
<dt><b><code>fn:modification_date(<i>recID</i>)</code></b></dt>
<dd>Returns the record modification date. Eg: <code>&lt;xsl:value-of select="fn:modification_date(445)"/&gt;</code> returns modification date of record 445</dd>
</dl>
<dl>
<dt><b><code>fn:creation_date(<i>recID</i>)</code></b></dt>
<dd>Returns the record creation date. Eg: <code>&lt;xsl:value-of select="fn:creation_date(445)"/&gt;</code> returns creation date of record 445</dd>
</dl>
<dl>
<dt><b><code>fn:eval_bibformat(<i>recID</i>, <i>bibformat_template_code</i>)</code></b></dt>
<dd>Returns the results of the evaluation of the format template code. Eg: <code>&lt;xsl:value-of select="fn:eval_bibformat(marc:controlfield[@tag='001'],'&amp;lt;BFE_SERVER_INFO var=&amp;quot;recurl&amp;quot;>')" /&gt;</code> returns the url of the current record. The parameter <code><i>bibformat_template_code</i></code> is regular code used inside BibFormat format templates, with <code>&lt;</code> escaped as <code>&amp;lt;</code> and <code>"</code>(quotes) escaped as <code>&amp;quot;</code></dd>
</dl>
<p>Finally, please note that you will need to install a supported XSLT parser in order
to format using XSL stylesheets.</p>
<h2><a name="FormatElements">4. Format Elements</a></h2>
<p>Format elements are the bricks used in format templates to provide dynamic content to the formatting process.
Their purpose is to allow non computer literate persons to easily integrate data from the records in the database into their templates. </p>
<p>Format elements are typically written in Python (there is an exception to that point which is dicussed in <a href="#addFormatElement">Add a Format Element</a>). This brings great flexibily and power to the formatting process. This however restricts the creation of format elements to developers.</p>
<h3><a name="addFormatElement">4.1 Add a Format Element</a></h3>
<p>The most typical way of adding a format element is to drop a <code>.py</code> file in the lib/python/invenio/bibformat_elements directory of your CDS Invenio installation. See <a href="#codeFormatElement">Edit the Code of a Format Element</a> to learn how to implement an element.</p>
<p>The most simple way to add a format element is to add a en entry in the "<a href="<CFG_SITE_URL>//admin/bibindex/bibindexadmin.py/field">Logical Fields</a>" management interface of the BibIndex module. When BibFormat cannot find the Python format element corresponding to a given name, it looks into this table for the name and prints the value of the field declared for this name. This lightweight way of doing is straightforward but does not allow complex handling of the data (it limits to printing the value of the field, or the values of the fields if multiple fields are declared under the same label).</p>
<h3><a name="removeFormatElement">4.2 Remove a Format Element</a></h3>
<p>To remove a Python format element simply remove the corresponding file from the lib/python/invenio/bibformat_elements directory of your CDS Invenio installation.</p>
<p>To remove a format element declared in the "<a href="<CFG_SITE_URL>//admin/bibindex/bibindexadmin.py/field">Logical Fields</a>" management interface of the BibIndex module simply remove the entry from the table.</p>
<h3><a name="codeFormatElement">4.3 Edit the Code of a Format Element</a></h3>
<p>This section only applies to Python format elements. Basic format elements declared in "<a href="<CFG_SITE_URL>//admin/bibindex/bibindexadmin.py/field">Logical Fields</a>" have non configurable behaviour.</p>
<p>A format element file is like any regular Python program. It has to implement a <code>format</code> function, which returns a <code>string</code> and takes at least <code>bfo</code> as first parameter (but can take as many others as needed).</p>
<p>Here is for example the code of the "bfe_title.py" element:
<pre>
def format(bfo, separator=" "):
"""
Prints the title of a record.
@param separator separator between the different titles
"""
titles = []
title = bfo.field('245__a')
title_remainder = bfo.field('245__b')
titles.append( title + title_remainder )
title = bfo.field('0248_a')
if len(title) > 0:
titles.append( title )
title = bfo.field('246__a')
if len(title) > 0:
titles.append( title )
title = bfo.field('246_1a')
if len(title) > 0:
titles.append( title )
return separator.join(titles)
</pre>
In format templates this element can be called like a function, using HTML syntax:<br/>
<code>&lt;BFE_TITLE separator="; "/&gt;</code><br/>
Notice that the call uses (almost) the filename of your element. To find out which element to use, BibFormat tries different filenames until the element is found: it tries to <ol>
<li>ignore the letter case</li>
<li>replace underscore with spaces</li>
<li>remove the BFE_ from the name</li>
</ol>
This means that even if the filename of your element is "my element.py", BibFormat can resolve the call &lt;BFE_MY_ELEMENT /&gt; in a format template. This also means that you must take care no to have two format elements filenames that only differ in term of the above parameters.
</p>
<p>The <code>string</code> returned by the <code>format</code> function corresponds to the value that is printed instead of the format element name in the format template.</p>
<p>The <code>bfo</code> object taken as parameter by <code>format</code> stands for BibFormatObject: it is an object that represents the context in which the formatting takes place. For example it allows to retrieve the value of a given field for the record that is being formatted, or the language of the user. We see the details of the BibFormatObject further below.</p>
<p>The <code>format</code> function of an element can take other parameters, as well as default values for these parameters. The idea is that these parameters are accessible from the format template when calling the elements, and allow to parametrize the behaviour of the format element.</p>
<p>It is very important to document your element: this allows to generate a documentation for the elements accessible to people writing format templates. It is the only way for them to know what your element do. The key points are:
<ul>
<li>Provide a docstring for the <code>format</code> function</li>
<li>For each of the parameters of the <code>format</code> function (except for <code>bfo</code>), provide a description using a Java-like doc syntax in the doc string:<br/> <code>@param my_param description for my param</code> (one line per parameter)</li>
<li>You can use one <code>@see</code> followed by a comma separated list of elements filenames to provide a reference to other elements of interests related to this one: <br/> <code>@see my_element1.py, my element2.py</code></li>
</ul>
</p>
<p>Typically you will need to get access to some fields of a record to display as output. There are two ways to this: you can access the <code>bfo</code> object given as parameter and use the provided (basic) accessors, or import a dedicated module and use its advanced functionalities.</p>
<p><b>Method 1: Use accessors of <code>bfo</code></b>:<br/>
<code>bfo</code> is an instance of the <code>BibFormatObject</code> class. The following methods are available:
<ul>
<li><code>get_record()</code>: Returns the record of this BibFormatObject instance as a BibRecord structure. Allows advanced access on the structure using <code>BibRecord</code>.</li>
<li><code>control_field(tag)</code>: Returns the value of control field given by MARC <code>tag</code>.</li>
<li><code>field(tag)</code>:Returns the value of the field corresponding to MARC <code>tag</code>. If the value does not exist, return empty string.</li>
<li><code>fields(tag)</code>: Returns the list of values corresonding to MARC <code>tag</code>.If tag has an undefined subcode (such as 999C5), the function returns a list of dictionaries, whoose keys are the subcodes and the values are the values of tag.subcode. If the tag has a subcode, simply returns list of values corresponding to tag.</li>
<li><code>kb(kb, string, default="")</code>: Returns the value of the <code>string</code> in the knowledge base <code>kb</code>. If kb does not exist or string does not exist in kb, returns <code>default</code> string.</li>
</ul>
You can also get access to other information through <code>bfo</code>, such as the language in which the formatting should occur with <code>bfo.lang</code>. To learn more
about the possibilities offered by the <code>bfo</code>, read the <a href="<CFG_SITE_URL>/help/hacking/bibformat-api">BibFormat APIs</a>
</p>
<p><b>Method 2: Use module <code>BibRecord</code></b>:<br/>
BibRecord is a module that provides advanced functionalities
regarding access to the field of a record
<code>bfo.get_record()</code> returns a structure that can be
understood by BibRecord's functions. Therefore you can import
the module's functions to get access to the fields you want.
</p>
<h3><a name="previewFormatElement">4.4 Preview a Format Element</a></h3>
<p>
You can play with a format element parameters and see the result
of the element directly in the
<a href="bibformatadmin.py/format_elements_doc">format elements documentation</a>:
for each element, under the section "See
also", click on "Test this element". You are redirected to a page
where you can enter a value for the parameters. A description is
associated with each parameter as well as an indication of the
default value of the parameter if you do not provide a custom
value. Click on the "Test!" button to see the result of the
element with your parameters.</p>
<h3><a name="internationalizationFormatElement">4.5 Internationalization (i18n)</a></h3>
<p>You can follow the standard internationalization procedure in
use accross CDS Invenio sources. For example the following code
will get you the translation for "Welcome" (assuming "Welcome" has
been translated):
<pre>
from invenio.messages import gettext_set_language
ln = bfo.ln
_ = gettext_set_language(ln)
translated_welcome = &#95;("Welcome")
</pre>
</p>
<p>Notice the access to <code>bfo.ln</code> to get access to the
current language of the user. For simpler translations or
behaviour depending on the language you can simply check the value
<code>bfo.ln</code> to return your custom text.</p>
<h3><a name="escapeFormatElement">4.6 Escaping special HTML/XML characters</a></h3>
<p>In most cases, that is cases where your
element does not return HTML output, you do not have to take any
particular action in order to escape values that you output: the
BibFormat engine will take care of escaping the returned value of the element
for you. In cases where you want to return text that should not
be escaped (for example when you return HTML links), you can make
the formatting engine know that it should not escape your
value. This is done by implementing the
<code>escape_values(bfo)</code> function in your element, that
will return (int) 0 when escape should not be done (or 1 when
escaping should be done):
<pre>def escape_values(bfo):
"""
Called by BibFormat in order to check if output of this element
should be escaped.
"""
return 0
</pre>
Note that the function is given a <code>bfo</code> object as
parameter, such that you can do additional testing if your element
should really return 1 or 0 (for very special cases).<br/> Also note
that the behavior defined by the <code>escape_values()</code> function
will be overriden by the <code>escape</code> parameter used in the
format template if it is specified.
</p>
<p> Finally, be cautious when you disable escaping: you will have
to take care of escaping values "manually" in your format element
code, in order to avoid non valid outputs or XSS
vulnerabilities. This can be done easily when using the
<code>field</code>, <code>fields</code> and
<code>controlfield</code> functions of bfo with <code>escape</code>
parameter:
<pre>
title = bfo.field('245__a', escape="1")
abstract = bfo.field('520__a', escape="2")
</pre>
<a name="listofescapingmodes" />
The <code>escape</code> parameter can be one of the following values:
<ul><li>0 - no escaping</li>
<li>1 - escape all HTML characters (escaped chars are shown as escaped)</li>
<li>2 - remove unsafe HTML tags to avoid XSS, but
keep basic one (such as &lt;br /&gt;)
This is particularly useful if you want to store HTML text in your
metadata but still want to escape some tags to prevent
XSS vulnerabilities. Note that this method is slower than
basic escaping of mode 1.<br/>
Escaped tags are removed.</li>
<li>3 - mix of mode 1 and mode 2. If field_value starts with &lt;!--HTML--&gt;,
then use mode 2. Else use mode 1.</li>
<li>4 - remove all HTML/XML tags </li>
<li>5 - same as 2, but allows more tags, like &lt;img></li>
<li>6 - same as 3, but allows more tags, like &lt;img></li>
</ul>
These modes are the same for <code>escape_values(bfo)</code> function.
<p>
You can also decide not to use the <code>escape</code> parameter and escape values
using any other Python function/library you want to use (such as <code>cgi.escape()</code>).
</p>
<h3><a name="attrsFormatElement">4.7 Edit the Attributes of a Format Element</a></h3>
<p>A format element has mainly four kinds of attributes: <ul>
<li>Name: it corresponds to the filename of the element.</li>
<li>Description: the description is in the <code>docstring</code> of the <code>format</code> function (excepted lines prefixed with <code>@param</code> and <code>@see</code>).</li>
<li>Parameters descriptions: for each parameter of the <code>format</code> function, a line beginning with <code>@param</code> <i>parameter_name</i> and followed by the description of the parameter is present in the <code>docstring</code> of the <code>format</code> function.</li>
<li>Reference to other elements: one line beginning with <code>@see</code> and followed by a list of comma-separated format elements filenames in the in the <code>docstring</code> of the <code>format</code> function provides a link to related elements.</li>
</ul>
</p>
<h3><a name="dependenciesFormatElement">4.8 Check the Dependencies of a Format Element</a></h3>
<p>There are two ways to check the dependencies of a format element. The simplest way is to go to the <a href="bibformatadmin.py/format_elements_doc">format elements documentation</a> and click on "Dependencies of this element" for the element you want to check.</p>
<p>The second method to check the dependencies of an element is through regular unix tools: for example <code>$ grep -r -i 'bfe_<i>your_element_name</i>' .</code> inside the format templates directory will tell you which templates call your element.</p>
<h3><a name="validityFormatElement">4.9 Check the Validity of a Format Element</a></h3>
<p>There are two ways to check the validity of an element. The simplest one is to go to the <a href="bibformatadmin.py/format_elements_doc">format elements documentation</a> and click on "Correctness of this element" for the element you want to check.</p>
<p>The second method to check the validity of an element is through regular Python methods: you can for example import the element in the interactive interpreter and feed it with test parameters. Notice that you will need to build a BibFormatObject instance to pass as <code>bfo</code> parameter to the <code>format</code> function of your element.</p>
<h3><a name="browseDocFormatElement">4.10 Browse the Format Elements Documentation</a></h3>
<p>Go to the <a href="bibformatadmin.py/format_elements_doc">format elements documentation</a>. There is a summary of all available format elements at the top of the page. You can click on an element to go to its detailed description in the second part of the page.</p>
<p>Each detailed documentation shows you:
<ul>
<li>A description of what the element does.</li>
<li>A list of all parameters you can use for this element.</li>
<li>For each parameter, a description and the default value when parameter is ommitted.</li>
<li>A link to a tool to track the dependencies of your element.</li>
<li>A link to a tool to check the correctness of your element.</li>
<li>A link to a tool to test your element with custom parameters.</li>
</ul></p>
<h2><a name="KBs">5. Knowledge Bases</a></h2>
<p>Knowledge bases are a way to define easily extendable repositories of mappings. Their use is various, but their main purpose is to get, given a value, the normalized version of this value. For example you may use a knowledge base to hold a list of all ways to abbreviate the name of a journal, and map these abbreviations to the full journal name. This would be useful to get a normalized journal name accross all of your records.</p>
<p>The knowledge base itself offers no method to do this normalization. It is limited to the archiving of this knowledge. To benefit from the normalization you need to use a format element which is knowledge-base-aware. The element will look by iteself into the knowledge base to format a record. In that way you can extend the formatting capabilities of this element without having to modify it.</p>
<h3><a name="addKB">5.1 Add a Knowledge Base</a></h3>
<p>To add a knowledge base go to the <a href="bibformatadmin.py/kb_manage">Manage Knowledge Bases</a> administration page.
At the bottom of the page click on the "Add New Knowledge Base" button. The knowledge base has been created and you are asked to fill in its attribute. See <a href="#attrsKB">Edit the Attributes of a Knowledge Base</a> to learn more about the attributes of knowledge bases.</p>
<h3><a name="removeKB">5.2 Remove a Knowledge Base</a></h3>
<p>To remove a knowledge base go to the <a href="bibformatadmin.py/kb_manage">Manage Knowledge Bases</a> administration page. Click on the "Delete" button facing the knowledge base you want to remove and confim. The knowledge base and all the mapping it includes are removed.</p>
<h3><a name="addMappingKB">5.3 Add a Mapping</a></h3>
<p>Go to the <a href="bibformatadmin.py/kb_manage">Manage Knowledge Bases</a> administration page and click on the knowledge base for which you want to add a mapping. Fill in the form of the "Add New Mapping" section on the left of the page with the new mapping, and click on "Add New Mapping". The mapping has been created. Alternatively you can create the mapping without its attributes, and fill them afterward (See <a href="#editMappingKB">Edit a Mapping</a>).<p/>
<h3><a name="removeMappingKB">5.4 Remove a Mapping</a></h3>
<p>Go to the <a href="bibformatadmin.py/kb_manage">Manage Knowledge Bases</a> administration page and click on the knowledge base for which you want to remove a mapping. Click on the "Delete" button facing the mapping you want to delete.
<h3><a name="editMappingKB">5.5 Edit a Mapping</a></h3>
<p>Go to the <a href="bibformatadmin.py/kb_manage">Manage Knowledge Bases</a> administration page and click on the knowledge base for which you want to edit a mapping. Locate the mapping in the list. You can click on the column headers to order the list by <i>Map From</i> or by <i>Map To</i> to help you find it. Once you have edited the mapping click on the corresponding "Save" button.
<h3><a name="attrsKB">5.6 Edit the Attributes of a Knowledge Base</a></h3>
Go to the <a href="bibformatadmin.py/kb_manage">Manage Knowledge Bases</a> administration page and click on the knowledge base you want to edit. In the top menu, click on "Knowledge Base Attributes". You can then give your knowledge base a name and a description. Finally click on the "Update Base Attributes" button.
<h3><a name="validityKB">5.7 Check the Dependencies a Knowledge Base</a></h3>
To check the dependencies of a knowledge base
go to the <a href="bibformatadmin.py/kb_manage">Manage Knowledge Bases</a> page, click on
the knowledge base you want to check, and then in the menu click on "Knowledge Base Dependencies".</p>
<p>The next page shows you the list of format elements that use this knowledge base.</p>
<p>Note that some format elements might be omitted.</p>
<h2><a name="BibReformat">6. Run BibReformat</a></h2>
<p>While records can be formatted on-the-fly using BibFormat, it is usually necessary to preformat the records
in order to decrease the load of your server. To do so, use the <code>bibreformat</code> command line tool.</p>
<h3><a name="runBibReformat">6.1 Run BibReformat</a></h3>
<p>The following options are available for running <code>bibreformat</code>:<p>
<blockquote>
<pre> Usage: bibreformat [options]
-u, --user=USER User name to submit the task as, password needed.
-h, --help Print this help.
-V, --version Print version information.
-v, --verbose=LEVEL Verbose level (0=min,1=normal,9=max).
-s, --sleeptime=SLEEP Time after which to repeat tasks (no)
-t, --time=DATE Moment for the task to be active (now).
-a, --all All records
-c, --collection Select records by collection
-f, --field Select records by field.
-p, --pattern Select records by pattern.
-o, --format Specify output format to be (re-)created. (default HB)
-n, --noprocess Count records to be processed only (no processing done)
Example: bibreformat -n Show how many records are to be bibreformated.
</pre>
</blockquote>
For example, to reformat all records in HB (=HTML brief) format, you'd launch:
<blockquote>
<pre>$ bibreformat -a -oHB
</pre>
</blockquote>
and you watch the progress of the process via <code>bibsched</code>.
<p>Note that BibReformat understands <code>-p</code>, <code>-f</code>,
and <code>-c</code> arguments that enable you to easily reformat only
the records you need. For example, to reformat the Pictures
collection, launch:
</p><blockquote>
<p>
<pre>$ bibreformat -cPictures -oHB
</pre>
</blockquote>
or to reformat HD (=HTML detailed) format for records #10 to #20, you
launch:
<blockquote>
<pre>$ bibreformat -p"recid:10-&gt;20" -oHD
</pre>
</blockquote>
<p>Last but not least, if you launch bibreformat without arguments:
</p><blockquote>
<pre>$ bibreformat
</pre>
</blockquote>
</p>
it will process all the records that have been modified since the last
run of BibReformat, as well as all newly inputted records. This is
suitable for running BibReformat in a periodical daemon mode via
BibSched. See our <a href="<CFG_SITE_URL>/help/admin/howto-run">HOWTO Run
Your CDS Invenio Installation</a> guide for more information.</p>
<h2><a name="Appendix">7. Appendix</a></h2>
<h3><a name="marcNotation">7.1 MARC Notation in Formats</a></h3>
<p>The notation for accessing fields of a record are quite flexible. You can use a syntax strict regarding MARC 21, but also
a shortcut syntax, or a syntax that can have a special meaning.</p>
<p>The MARC syntax is the following one:
<code>tag[indicator1][indicator2] [$ subfield]</code> where <code>tag</code> is 3 digits, <code>indicator1</code> and <code>indicator2</code> are 1 character each, and <code>subfield</code> is 1 letter.
</p>
<p>For example to get access to an abstract you can use the MARC notation <code>520 $a</code>. You can use this syntax in BibFormat. However you can also:
<ul>
<li>Omit any whitespace character (or use as many as you want)</li>
<li>Omit the <code>$</code> character (or use as many as you want)</li>
<li>Omit or use both indicators. You cannot specify only one indicator. If you need to use only one, use underscore <code>_</code> character for the other indicator.</li>
<li>Use percent '<code>%</code>' instead of any character to specify all ("don't care" or wildcard character) for that character. </li>
</ul></p>
<h3><a name="migration">7.2 Migrating from Previous BibFormat</a></h3>
<p>The new Python BibFormat formats are not backward compatible with the previous formats. New concepts and capabilities have been introduced and some have been dropped. If you have not modified the "Formats" or modified only a
little bit the "Behaviours" (or modified "Knowledge Bases"), then the transition will be painless and
automatic. Otherwise you will have to manually rewrite some of the
formats. This should however not be a big problem.</p>
<p>The first thing you should do is to read the <a href="#shortIntro">Five Minutes Introduction to BibFormat</a> to understand how the new BibFormat works. We also assume that you are familiar with the concepts of the old BibFormat. As the new formats separate the presentation from the business logic (i.e. the bindings to the database), it is not possible to automatically handle the translation. This is why you should at least be able to read and understand the formats that you want to migrate.</p>
<h4>Differences between old and new BibFormat</h4>
<p>
The most noticeable differences are:<br/>
<br/>
a) "Behaviours" have been renamed "Output formats".<br/>
b) "Formats" have been renamed "Format templates". They are now
written in HTML.<br/>
c) "User defined functions" have been dropped.<br/>
d) "Extraction rules" have been dropped.<br/>
e) "Link rules" have been dropped.<br/>
f) "File formats" have been dropped.<br/>
g) "Format elements" have been introduced. They are written in Python,
and can simulate c), d) and e).<br/>
h) Formats can be managed through web interface or through
human-readable config files.<br/>
i) Introduction of tools like validator and dependencies checker.<br/>
j) Better support for multi-language formatting.<br/>
</p>
<p>
Some of the advantages are:<br/>
<br/>
+ Management of formats is much clearer and easier (less concepts,
more tools).<br/>
+ Writing formats is easier to learn : less concepts
to learn, redesigned work-flow, use of existing well known and
well documented languages.<br/>
+ Editing formats is easier: You can use your preferred HTML editor such as
Emacs, Dreamweaver or Frontpage to modify templates, or any text
editor for output formats and format elements. You can also use the
simplified web administration interface.<br/>
+ Faster and more powerful templating system.<br/>
+ Separation of business logic (output formats, format elements)
and presentation layer (format templates). This makes the management
of formats simpler.<br/>
</p>
<p>
The disadvantages are:<br/>
<br/>
- No backward compatibility with old formats.<br/>
- Stricter separation of business logic and presentation layer:<br/>
no more use of statements such as if(), forall() inside templates,
and this requires more work to put logic inside format elements.<br/>
</p>
<h4>Migrating <i>behaviours</i> to <i>output formats</i></h4>
<p>Behaviours were previously stored in the database and did require to use the evaluation language to
provide the logic that choose which format to use for a record. They also let you enrich records
with some custom data. Now their use has been simplified and rectricted to equivalence tests on the value of a field
of the record to define the format template to use.</p>
<p>For example, the following behaviour:</p>
<table>
<tbody><tr align="center" bgcolor="#0000ff">
<td colspan="2"><font color="white"><b>CONDITIONS</b></font></td>
</tr>
<tr bgcolor="#33ccff">
<td align="center"><b>0</b></td>
<td width="95%"><b>$980.a="PICTURE"</b></td>
</tr>
<tr bgcolor="#ffffff">
<td bgcolor="#33ccff"><font size="2"><b>Action (0)</b></font></td>
<td>"&lt;record&gt;
<br />&nbsp;&lt;controlfield&nbsp;tag=\"001\"&gt;"&nbsp;$001&nbsp;"&lt;/controlfield&gt;
<br />&nbsp;&lt;datafield&nbsp;tag=\"FMT\"&nbsp;ind1=\"\"&nbsp;ind2=\"\"&gt;&nbsp;
<br />&nbsp;&lt;subfield&nbsp;code=\"f\"&gt;hb&lt;/subfield&gt;&nbsp;
<br />&nbsp;&lt;subfield&nbsp;code=\"g\"&gt;"&nbsp;
<br />xml_text(format("PICTURE_HTML_BRIEF"))
<br />"&nbsp;&lt;/subfield&gt;&nbsp;
<br />&nbsp;&lt;/datafield&gt;
<br />&lt;/record&gt;"</td>
</tr>
<tr align="center" bgcolor="#cccccc">
<td colspan="2">&nbsp;
</td>
</tr>
<tr bgcolor="#33ccff">
<td align="center"><b>100</b></td>
<td width="95%"><b>""=""</b></td>
</tr>
<tr bgcolor="#ffffff">
<td bgcolor="#33ccff"><font size="2"><b>Action (0)</b></font></td>
<td>"&lt;record&gt;
<br />&nbsp;&lt;controlfield&nbsp;tag=\"001\"&gt;"&nbsp;$001&nbsp;"&lt;/controlfield&gt;
<br />&nbsp;&lt;datafield&nbsp;tag=\"FMT\"&nbsp;ind1=\"\"&nbsp;ind2=\"\"&gt;&nbsp;
<br />&nbsp;&lt;subfield&nbsp;code=\"f\"&gt;hb&lt;/subfield&gt;&nbsp;
<br />&nbsp;&lt;subfield&nbsp;code=\"g\"&gt;"&nbsp;
<br />xml_text(format("DEFAULT_HTML_BRIEF"))
<br />"&nbsp;&lt;/subfield&gt;&nbsp;
<br />&nbsp;&lt;/datafield&gt;
<br />&lt;/record&gt;"</td>
</tr>
<tr align="center" bgcolor="#cccccc">
<td colspan="2">
&nbsp;
</td>
</tr>
</tbody>
<table>
<p>translates to the following output format (in textual configuration file):</p>
<p>
<code>
tag 980__a:<br/>
PICTURE --- Picture_HTML_brief.bft<br/>
default: Default_HTML_brief.bft<br/>
</code><p/>
<p>or visual representation through web interface:<br/>
<img src="<CFG_SITE_URL>/img/admin/bibformat-guide-bfo_hb_migrate.png" alt="Image representation of HB output format" />
</p>
<h4>Migrating <i>formats</i> to <i>format templates</i> and <i>format elements</i></h4>
<p>The migration of formats is the most difficult part of the migration. You will need to separate the presentation code (HTML) from the business code (iterations, tests and calls to the database). Here are some tips on how you can do this:</p>
<ul>
<li>If you want to save the time of unescaping all HTML characters and understanding how the layout should look like, just go with your web browser to a formatted version of the format in your CDS Invenio installation, and copy the source of the web page. Identify the parts of the HTML code which are specific to the current record, and replace them with a call to the corresponding format element.</li>
<li>If you have made small modifications to the old default provided formats, we suggest that you use the new provided ones and modify them according to your needs.</li>
</ul>
<h4>Migrating <i>UDFs</i> and <i>Link rules</i></h4>
<p><i>User Defined Functions</i> and <i>Link rules</i> have been dropped in the new BibFormat. These concepts have no reasons to be as they can be fully implemented in the <i>format elements</i>. For example the <code>AUTHOR_SEARCH</code> link rule can directly be implemented in the <code>Authors.bfe</code> element.</p>
<p>As for the UDFs, most of them are directly built-in functions of Python. Whenever a special function as to be implemented, it can be defined in a regular Python file and used in any element.</p>
<h4>The Migration Kit</h4>
<p>The migration kit is only available in older versions of Invenio.<br/>
To enable the migration kit in this release, you need to copy the required files from an older release.
</p>
<h4><a name="runSideBySide">Run old and new formats side by side</a></h4>
<p>This was possible by default only in older versions of Invenio.<br/>
To enable this functionality in this release, you need to copy the required files from an older release.
</p>
<h3><a name="integrationDreamweaver">7.3 Integrating BibFormat into Dreamweaver MX</a></h3>
<p>BibFormat templates have been thought to be editable in custom HTML editors. We propose in this section
a way to extend one particular editor, Dreamweaver.</p>
<h4>Make Dreamweaver Recognize Format Elements in Layout View</h4>
<p>To make Dreamweaver understand the format elements and display an icon for each of them in the layout editor, you must
edit a Dreamweaver configuration file named <code>Tags.xml</code> located inside /Configuration/ThirdPartyTags directory
of your Dreamweaver installation folder. At the end of this file, copy-paste the following lines:
<pre>
&lt;!-- BibFormat (CDS Invenio) --&gt;
&lt;tagspec tag_name="BIBFORMAT" start_string="&lt;BFE_" end_string="/&gt;" parse_attributes="false" detect_in_attribute="true" icon="bibformat.gif" icon_width="25" icon_height="16"&gt;&lt;/tagspec &gt;
&lt;tagspec tag_name="BIBFORMAT" start_string="&lt;bfe_" end_string="/&gt;" parse_attributes="false" detect_in_attribute="true" icon="bibformat.gif" icon_width="25" icon_height="16"&gt;&lt;/tagspec &gt;
</pre>
Also copy this icon <img src="<CFG_SITE_URL>/img/admin/bibformat-guide-bfe.gif" alt="bibformat.gif"/> in the same directory as <code>Tags.xml</code> (right-click on icon, or ctrl-click on one-button mouse, and "Save Image As..."). Make sure the downloaded image is named "<code>bibformat.gif</code>".
</p>
<p>Note that Dreamweaver might not recognize Format Elements when complex formatting is involved due to these elements.</p>
<h4>Add a Format Elements Floating Panel</h4>
<p>You can add a floating panel that will you to insert Format Elements in your document and read the documentation
of all available Format Elements.</p>
<p>The first step is to declare in which menu of Dreamweaver this floating panel is going to be available.
To do so, edit file "<code>Menu.xml</code>" located inside /Configuration/Menus of your Dreamweaver
application directory and copy-paste the following line in the menu you want
(typically inside tag <code>'menu'</code> with attribute <code>id='DWMenu_Window_Others')</code>:</p>
<pre>
&lt;menuitem name="BibFormat Elements" enabled="true" command="dw.toggleFloater('BibFormat_floater.html')" checked="dw.getFloaterVisibility('BibFormat_floater.html')" /&gt;
</pre>
</p>
<p>Once this is done, you can <a href="bibformatadmin.py/download_dreamweaver_floater">download the floating palette</a> (if file opens in your browser instead of downloading, right-click on icon, or ctrl-click on one-button mouse, and "Save Target As...") and move the dowloaded file "<code>BibFormat_floater.html</code>" (do not rename it) into /Configuration/Floaters directory of your Dreamweaver application folder.</p>
<p>To use the BibFormat floating panel, open Dreamweaver, and choose <code>Window &gt; Others &gt; BibFormat Elements</code>.</p>
<p>Whenever a new version of the palette is available, you can skip the edition of file "<code>Menu.xml</code>" and just replace the old "<code>BibFormat_floater</code>" file with the new one.</p>
<h3><a name="faq">7.4 FAQ</a></h3>
<h4>Why do we need output formats? Wouldn't format templates be sufficient?</h4>
<p>As you potentially have a lot of records, it is not conceivable to specify for each of them which
format template they should use. This is why this rule-based decision layer has been introduced.</p>
<h4>How can I protect a format?</h4>
<p>As a web user, you cannot protect a format. If you are administrator of the
system and have access to the format files, you can simply use the permission rights of your system, as BibFormat
is aware of it.</p>
<h4>Why cannot I edit/delete a format?</h4>
<p>The format file has certainly been protected by the administrator of the server. You must ask the
administrator to unprotect the file if you want to edit it.</p>
<h4>How can I add a format element from the web interface?</h4>
<p>Format elements cannot be added, removed or edited through the web interface. This limitation
has been introduced to limit the security risks caused by the upload of Pythonic files on the server. The only possibility to add a basic format element from the web interface is to add a en entry in the "<a href="<CFG_SITE_URL>//admin/bibindex/bibindexadmin.py/field">Logical Fields</a>" management interface of the BibIndex module (see <a href="#addFormatElement">Add a Format Element</a>)</p>
<h4>Why are some Marc codes omitted in the "Check Dependencies" pages?</h4>
<p>When you check the dependencies of a format, the page reminds you that
some use of Marc codes might not be indicated. This is because it is not
possible (or at least not trivial) to guess that the call to <code>field(str(5+4)+"80"+"__a")</code>
is equal to a call to <code>field("980__a")</code>. You should then not completely rely on this indication.</p>
<h4>How are displayed deleted record?</h4>
<p>By default, CDS Invenio displays a standard "The record has been deleted." message for all
output formats with a 'text/html' content type. Your output format, format templates and format elements
are bypassed by the engine.
However, for more advanced output formats, CDS Invenio
goes through the regular formatting process and let your formats do the job. This allows you to customize how a record should be displayed once it has been deleted.</p>
<h4>Why are some format elements omitted in the "Knowledge Base Dependencies" page?</h4>
<p>When you check the dependencies of a knowledge base, the page
reminds you that format elements using this knowledge base might not
be indicated. This is because it is not possible (or at least not
trivial) to guess that the call to
<code>kb(e.upper()+"journal"+"s")</code> in a format element is equal
to a call to <code>kb("Ejournals")</code>. You should then not
completely rely on this indication.</p>
<h4>Why are some format elements defined in field table omitted in the format element documentation?</h4>
<p>Some format elements defined in the "Logical Fields" management
interface of the BibIndex module (the basic format elements) are not
shown in the format elements documentation pages. We do not show such
an element if its name starts with a number. This is to reduce the
number of elements shown in the documentation as the logical fields
table contains a lot of not so useful fields to be used in
templates.</p>
<h4>How can I get access to repeatable subfields from inside a format element?</h4>
<p>Given that repeatable subfields are not frequent, the
<code>bfo.fields(..)</code> function has been implemented to return the most convenient structure for most cases, that is a '<em>list of strings</em>' (<b>Case 1</b> below) or '<em>list of dict of strings</em>' (<b>Case 2</b> below). For eg. with the following metadata:
<pre> 999C5 $a value_1a $b value_1b
999C5 $b value_2b
999C5 $b value_3b $b value_3b_bis
>> bfo.fields('999C5b') <b>(1)</b>
>> ['value_1b', 'value_2b', 'value_3b', 'value_3b_bis']
>> bfo.fields('999C5') <b>(2)</b>
>> [{'a':'value_1a', 'b':'value_1b'},
{'b':'value_2b'},
{'b':'value_3b'}]
</pre>
In this example <code>value3b_bis</code> is not shown for
<code>bfo.fields('999C5')</code> (<b>Case 2</b>). If it were to be taken into account, the
returned structure would have to be a '<em>list of dict of list of strings</em>', thus making for most cases
the access to the data a bit more complex.<br/>
In order to consider the repeatable subfields, use the additional <code>repeatable_subfields_p</code> parameter:
<pre> >> bfo.fields('999C5b', repeatable_subfields_p=True) <b>(1 bis)</b>
>> ['value_1b', 'value_2b', 'value_3b']
>> bfo.fields('999C5', repeatable_subfields_p=True) <b>(2 bis)</b>
>> [{'a':['value_1a'], 'b':['value_1b']},
{'b':['value_2b']},
{'b':['value_3b', 'value3b_bis']}]
</pre>
Another solution would be to access the BibRecord structure with
<code>bfo.getRecord()</code> and use the lower-level BibRecord module with this structure.
</p>
<br/>
c4science · Help