User's Guide

This is the user's guide for diWEBlo v1.0 This document is technically oriented and assumes that you have read the introduction which details what this program is. Reading this document you will learn all the possible use of diWEBlo, far more than the simple use described in the introduction.

Table of Contents

1. General introduction

General introduction

2. Architecture of diWEBlo

diWEBlo is a CGI script written in the Perl language version 5.0 The program can run by itself, does not use any standard on non standard modules.

It reads text files and produces text files. It was designed to be used with HTML, but as a matter of fact nothing HTML specific is implemented in it.

diWEBlo gets CGI parameters, GET and POST parameters as well. The most important parameters are

Everything in diWEBlo IS case sensitive.

All other CGI parameters can be named arbitrarily and will be processed by diWEBlo, except a special one: diweblo. This parameter will be overwritten by diWEBlo to contain a reference text, like This page was generated by diWEBlo v1.0. You are encouraged to include a

<!--#diweblo diweblo-->
reference line in your HTML templates.

3. How diWEBlo works

1. diWEBlo first of all processes the CGI variables and puts them into an internal array.

2. diWEBlo reads the template file specified by the CGI parameter template or display. On format of template files read 4. Format of template files.

3. If the template has a Password field diWEBlo checks that the CGI input parameters also contain a variable named Password and the value of it matches the value of the password given in the template file. This password checking phase is skipped when the template name is given by the cgi parameter display as in this case no modification performed by diWEBlo, only a Web page is displayed with information which is on the Web anyway.

4. diWEBlo determines the name of the output file. This is done even when the edit page is to be displayed, because this name is used to determine the data file.

5. diWEBlo then reads the data file, if it exists. For each Web page there is a data file in a directory specified by the template field Data having the same name as the Web page and the extension .data.

6. Each field defined in the data file is checked against the CGI variable array, and in case a variable is not defined by CGI but is defined in the data file it is added to the CGI array.

7. If the process is to create a new file and not just displaying a Web page then diWEBlo saves the content of the CGI array to the data file.

8. On the other hand if the process does not generate a new file, only displays the edit web page it tries to get the HTML template for it from the template field Edit or if it does not exists from the file given by the template field EditFile.

9. If the HTML template is not defined when the program gets here (either because neither Edit nor EditFile is specified by the template or because diWEBlo is going to create a new file and not just to show an edit page) it gets the HTML template from the template field Template or from a file given by template field TemplateFile.

10. diWEBlo converts the HTML template to the final form inserting the actual values of the parameters to the appripriate places. diWEBlo takes the actual values from the array where the CGI variables were put and was merged with the values taken from the data file. This means that if the edit page does not include some parameter then it will not be deleted, but keep with the old value. This way you can create several template files each creating the same Web page, and therefore working with the same DATA file, but allowing different users to edit different values only.

11. Finally diWEBlo emits the result either to the screen or to the result file.

If any error occures during processing diWEBlo emits an error page to the browser.

4. Format of template files

The template files are text files. Each line contains a key, a colon and value till end of the line, like
key: value
When a value can not fit into a line a special separator is defined after the colon, and the value is represented in the following lines until the separator appears again. The separator starts with two dash characters. Example:
key: --This does not appear in the value
this is
a multiline
--This does not appear in the value
When the last character is a backslash on a line the line is joined to the next line.

5. HTML template formats

The HTML template file should obviously have HTML format. You can create it with any HTML processor. The parameters that are to be changed by diWEBlo should be referenced by special format HTML comments. HTML comments usually look like
<!-- this is a comment -->
The comments that have the format:
<!--#diweblo parametername-->
will be replaced by diWEBlo with the actual value of the parameter. There can be spaces between the words, so
<!-- #  diweblo  parametername     -->
works fine.

The word diweblo should be all lowercase.

6. Installing diWEBlo

diWEBlo is a CGI script written in the Perl language version 5.0 The program can run by itself, does not use any standard on non standard modules.

You can install it copying the Perl file into a directory that the Web server can access and execute. You probably will change the /usr/local/bin/perl path on the first line of the script to the Perl executable and edit the line

$template_directory = 'd:/InetPub/wwwroot/progs/perl/diweblo/';
to point to the directory where the template files are.

If your Web server complains about missing header lines or alikes then you probably have to change the line

$Status = 'HTTP/1.0 200 OK';
$Status = 'Status: 200 OK';
This is the case for Apache.

The program was tested with IIS3.0 and IIS4.0 under WindowsNT, but I would be surprised if it did not work under most UNIX operating systems. My favorite is Digital UNIX.

7. Author of the program

Péter Verhás

8. Legal

This software is provided on an "AS IS", basis, without warranty of any kind, including without limitation the warranties of merchantability, fitness for a particular purpose and non-infringement. The entire risk as to the quality and performance of the Software is borne by you. Should the Software prove defective, you and not the author assume the entire cost of any service and repair.

Any statement, assumption expressed or implied in this document, in any attached document, program source code, or in any other information source associated with this program, belong to the author, and might not reflect the views of anyone else.

The development of the program was sponsored by no one. I have done it in my free time at home using resources that I have legally purchased, including hardware and software.

You are free to use and distribute diWEBlo as far as your actions are in line with the GNU General Public License. I would also appreciate if you could include a reference text on one or more of the pages that you create on a site using diWEBlo. This can be done using the predefined parameter <!--#diweblo diweblo-->.

9. diWEBlo Pro

A professional version of diWEBlo is under development. The application is going to be developed by a company in case there is significant interest. The extra features planned: If you are interested drop me a mail. You are also welcome to request features.