Configuring WB

Luca Fini (lfini@arcetri.astro.it). September 2006

About Install Config Usage Copyright F.A.Q.

Defining a new billboard

In the following we will often refer to the billboard root directory. That's the directory you created at installation and where you put all the WB auxiliary files and directories. Let's assume it was called /var/www/http/BillBoards.

To define a new billboard you may point your browser to the billboard management page:

http://url.to.your.cgi/wb.py
to get the following:

Where you can select the "Create new billboard" operation.

Note: System administrator tasks (such as defining a new billboard) require that the user logging in is an "administrative user", i.e.: either admin or administrator, or root, so that the login id field is actually a menu of choices.

You must then choose a proper name for your billboard.

Note: You can use any name for your billboards, except for names beginning with either '.' or '_', which are reserved for special actions.

After successful creation, you will find a new subdirectory, named as the billboard name, in the billboard root directory. The created subdirectory will contain an initialization file named wb.ini copied from the default language directory.

Now your billboard is up and running and you might start to use it, but you might want to customize it a little bit to adapt it to your needs.

Billboard customization

In order to modify customizable items for your billboard you may use the link "configure billboard". This will open a page with the content of the billboard wb.ini filke which you can modify to suit your needs.

Most items are self explaining or their purpose may be undestood by reading comments in the file, a few items deserve some more discussion.

index_header,  index_item,  index_footer,  doc_header,  doc_footer
These variables may be used to customize the document index and the document display pages generated by WB. Each variable is an array of strings and each element will generate a line of HTML code after being processed as detailed below.

The document index will be generated as an HTML document as follows:

  1. Text generated by index_header.
  2. for each document, a block generated by index_item
  3. Text generated by index_footer.
The document display page, instead, is generated as:
  1. Text generated by doc_header.
  2. Document body
  3. List of links to attachments (if any)
  4. Text generated by doc_footer.
To generate text the definition strings are processed to apply string substitution so that some "variables" are substituted with their values.

E.g.: the default values of the five items are:

index_header = ['<h3>Index for billboard: <i>%(BBOARD)s</i></h3><blockquote><ul>']
index_item   = ['<p><li> %(DATE)s %(EXPIR)s',
                '<br><a href=%(HREF)s>%(TITLE)s</a>']
index_footer = ['</ul></blockquote>']
doc_header   = ['%(DATE)s %(EXPIR)s', '<h3>%(TITLE)s</h3>']
doc_footer   = []
As you may see the lines resemble HTML code except for the special symbols: %(VAR)s which indicate variable substitution, i.e.: the symbol in parentheses will be substituted with the value of the named variable.

Note: You need to know a little bit of Python syntax to write customization strings. Here's a very short resume: 1) Comment lines begin with "#"; 2) strings are enclosed in either double quote (") or single quote ('). When using double quotes, if you need to put a literal double quote character into the string you must escape it with backslash (E.g.: \"). The same happens when enclosing in single quote. 3) arrays are enclosed in brackets: [ ], elements in arrays are separated by commas; 4) it is safe to start a new line after a comma.

The following variables are defined and can be used for index generation:

Table 1: Variables to be used in substitutions
Where it can be used
Var name Meaning index
header		index
item		index
footer		doc
header		doc
footer		mail
body
AUTHORDocument author's name NO YES NO YES YES YES
BBOARDCurrent billboard name YES YES YES YES YES YES
DATEDocument date NO YES NO YES YES YES
EXPIRDocument expiration date1 NO YES NO YES YES YES
HREFURL pointing to document NO YES NO YES YES YES
IF_AUTHOR*Document author's string. Format is defined in author_fmt; empty, if no author specified NO YES NO YES YES YES
N_ITEMSNumber of items in list YES YES YES NO NO NO
TITLEDocument title NO YES NO YES YES YES
SEARCHHTML code to insert a search form. The content of the string is defined by variable search_fmt; It may be empty, if no search form is desired. YES NO YES NO NO NO
1. The expiration date is a string as follows: "(Expiration: dd/mm/yyyy)", and the word "Expiration" is generated by using the current language. The string is empty if no expiration date is defined for the given document.

Beware: if a variable is mispelled or not defined an error will result and no index will be displayed.

Testing the configuration file

After creating the configuration file you must ensure it doesn't contain syntax errors. You may do so by running python on it:
> python /var/www/http/BillBoards/News/wb.ini
No output should result.

Now you are ready to start putting documents into your billboard, or maybe to define a new billboard.

Refining billboard customization

More items can be found in the wb.ini file provided in the distribution. Comments should be enough to understand how to customize other items. You may be interested in:
allowed_users
A list of usernames who are authorized to add and modify documents in the billboard. Note that any access to the billboard for an opperation is subject to authentication against the server's password file. After the user is authenticated his/her username is checked against the allowed users list. Il the list is empty, all authenticated users will be allowed to perform operations on the billboard.

delete_expired
Specifies wether expired documents must be deleted or moved to a suitable directory. If true (any non zero integer value) the maintenance command will move expired documents (and related attachments) to the directory deleted under the billboard directory. Otherwise expired files will be deleted.

language
Language (possibly different from the default language) to be used for this billboard. The value is the two-letter standard country name (e.g.: 'us', 'uk', 'it'). It must correspond to a laguage directory in the billboard root such as: _lang_us, _lang_it, etc.
If the language you need is not defined, you might consider to write the vocabulary by yourself (its a matter of half an hour of work, see below).

mail_to
A list of e-mail adresses to which notification is mailed whenever something is changed in the billboard.

mail_new
The string used to generate the mail message text, used when a new document is added to the billboard. The string may contain variables to be substituted (see also Table 1 above).

mail_update
The string used to generate the mail message text, used when a document n the billboard is updated. The string may contain variables to be substituted (see also Table 1 above).

sort_order
Flags specifying how items in the document list should be sorted. It is a string containing a combination of words specifying the ordering rules:
date expir ascending descending
Words are separated by spaces in the string and may be written in any order. If conflicting words are specified one will prevail at random.

Supporting a new language

Available vocabularies and values for each term in them, can be shown by selecting the related command from the maintenance page.

In order to support various languages, language dependent items are contained in "language directories" in the billboard root. Subdirectories are named: _lang_it, _lang_us, end so on, and must contain the following files:

voc.ini Vocabulary file
about.html Brief introduction
config.html Configuration manual
copyright.html Copyright statement
help.html User help
install.html Installation notes
usage.html Administrator help
wbfaq.html F.A.Q

In order to support a new language you must create a proper directory; e.g.:

> python /var/www/http/BillBoards/_lang_uk
and copy into it the set of files from an existing language directory of your choice.

Then you must provide proper translations (please, if you do so consider to send them to me to be added in the next distribution of WB).

The most important file is voc.ini which contains messages displayed to the user.

After providing the transalted version you may select your preferred language as default by editing the file wb.py (different language can be selected for each billboard by editing the specific wb.ini).

Translating help files

If you want to translate help file, consider that only help.html will be necessary for the generic user, all other files are provided for the system administrator (may be you?) and you may decide to leave them as they are.