Configuring WB

Luca Fini (lfini@arcetri.astro.it). June 2005

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 teh WB auxiliary files. Let's assume it was called /var/www/http/BillBoards.

To define a new billboard you will simply create a directory into the billboard root. The name of the directory will be the name of the new billboard. Supposing you want a new billboard named News you will do:

> mkdir /var/www/http/BillBoards/News
Note: You can use any name for your billboards, except for names beginning with '.', which are reserved for special actions.

You must then ensure that the web server program has the right permissions to read, write and create files under the News directory. You must thus change the ownership of the directory to the user id that the web server is using when running. Standard Apache installations will often use the username apache (but this may be different on your web server: if you have followed installation directions, this should be the same owner owning the billboard root directory). Supposing it is actually apache:

> chown apache /var/www/http/BillBoards/News
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

Billboard customization is performed by putting an initialization file named wb.ini into the billboard directory. The initialization file contains redefinitions of the defafault values of many variables used by WB. You may have a look to the file wb.ini located in the billboard root which is there only as a template to help you to write your own initialization file (you can remove it, if you want).

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_headerindex_itemindex_footerdoc_headerdoc_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 name of a vocabulary file (E.g: italiano.voc) which must be in the billboard root. If the language you need is not defined, you might consider to write it by yourself (its a matter of half an hour of work) using existing ones as templates.

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.

Defining a new vocabulary

In order to support various languages all messages are gathered in "vocabulary files". If the language of your choice is not supported, you might consider writing a new vocabulary file for your own.

Vocabulary files are stored in the billboard root directory and are named: english.voc, italiano.voc, and so on. You may use one of those as template to write a new one (please, if you do so consider to send it to me to be added in the next distribution of WB).

Available vocabularies and values for each term in them can be shown by a special URL:

http://my.web.site/cgi-bin/wb.py?.voc