Dynamic Content Processor - Documentation

1. Table of Contents

2. Introduction

The Tideland Dynamic Content Processor is a small CGI script written in Python which i configured so, that it will transparently convert the called content file into HTML. This is done by the definition of a serer action to call that CGI for every requested file with the extension .html.

This file doesn't contain standard HTML but contend written in the content description language. It will be processed and placed into a template.

3. Installation

3.1. File Installation

Most locations can be configured. Below just the standard installation is described.

Place the CGI script dcp.cgi into /cgi-bin/.
Place the library dcplib.py into /cgi-bin/.
Place the configuration dcpcfg.py into /cgi-bin/.
Place the images for the links into /images/.
Place the plugins into /plugin/.
Place the templates into /templates/.

You can change the directories setting them in the configuration library.

3.2. Hidden Processor Invocation

The hidden generator invocation needs the ability to configure web server action. This can be done inside the httpd.conf or with an .htaccess file in your document root. This second option will be the only one in typical provider environments.

The content of .htaccess looks like

AddType application/x-httpd-parse .dcp
Action application/x-httpd-parse "/cgi-bin/dcp.cgi?dcpFile="

AddType application/x-httpd-parse .html
Action application/x-httpd-parse "/cgi-bin/dcp.cgi?dcpFile="

This redirects any request to a file with the extension .dcp or .html to the configured CGI script with the given parameter. If you change the location or the name of the script, please also change the configuration above.

3.3. Configuration

The confiuration library contain the variables for the user specific configuration. There isn't much you have to change, but some variables will help you for your individual environment.

CFG_TEMPLATE_DIR       = "/templates/"
CFG_INCLUDE_DIR        = "/templates/"
CFG_PLUGIN_DIR         = "/plugin/"
CFG_IMAGES_DIR         = "images"
CFG_TIME_FORMAT        = "%d.%m.%Y %H:%M:%S"
CFG_ERROR_TEMPLATE     = "error.tmpl"
CFG_ERROR_TEMPLATE_TXT = "ERROR: Can't read template file '%s'!"
CFG_ERROR_INCLUDE_TXT  = "ERROR: Can't read include file '%s'!"
CFG_ERROR_CONTENT_TXT  = "ERROR: Can't read the content file!"
CFG_ERROR_PLUGIN_TXT   = "ERROR: Can't process plugin '%s'!"
CFG_LINK_IMAGE         = 1

CFG_DEFAULT_VARIABLES = {
    'dcpFile'     : 'index.html',
    'dcpTemplate' : 'yourtemplate.tmpl',
    'author'      : 'Your Name',
}

Those variables are:

CFG_TEMPLATE_DIR: The template directory, based upon .

CFG_INCLUDE_DIR: The include director for the template engine. Inside the content an absolute addresing is used.

CFG_PLUGIN_DIR: The plugin directory, based upon .

CFG_TIME_FORMAT: The format string for template variable dcpModificationTime.

CFG_ERROR_TEMPLATE: The name of the error template.

CFG_ERROR_TEMPLATE_TXT: The error text if a given template can't be found.

CFG_ERROR_INCLUDE_TXT: The error text if a given include can't be found.

CFG_ERROR_CONTENT_TXT: The error text if the content file can't be read. This can also be raised if the content isn't parsable.

CFG_ERROR_PLUGIN_TXT: The error text if the plugin can't be processed.

CFG_LINK_IMAGE: Switch for the image displayed in front of external links. 1 is true, the images will be shown, and 0 is false, the image will be suppressed.

CFG_DEFAULT_VARIABLES: These headers and their values will be added to the content. Their usage will be shown in the variables section.

4. Content

The content inside the .html files is written in a wiki-like language, headed by header definitions. This content is rendered and placed into the template by the CGI script.

Here's one example:

title: Home Page
menu: main

= This is a headline =

== This is a second level headline ==

And here I'm writing some text with **bold**, ''emphasized'' and __underlined__
text. {{Typewriter}} is also possible. I can also write bullet and numbered
lists, definition lists, pre-formatted and raw blocks.

4.1. Content Description Language

Due to the problems to describe the content description language in its own syntax, here are some examples you can see in the raw file. Headlines and paragraphs aren't described again.

4.1.1. Text Formatting

Paragraphs can contain bold, emphasized, underlined and typewriter text. The paragraph can also
contain a hard line break. Footnotes [1] are supported, too.

4.1.2. Lists

4.1.2.1. Bullet List

this
is
a
bullet
list

4.1.2.2. Numbered List

this
is
a
numbered
list

4.1.2.3. Definition List

item 1: definition 1
item 2: definition 2
item 3: definition 3

4.1.3. Blocks

4.1.3.1. Code

class MyClass:
    """
        I'm a python class.
    """

    def __init__(self):
        """
            This is the constructor.
        """

        print "MyClass instantiated ..."

4.1.3.2. Raw

Hello world!

4.1.3.3. Div

Fancy format!

4.1.4. Links

internal link
/index.html without text
this document
the samples section of this document
the top of this document
the bottom of this document
external link to Tideland
http://www.tideland.de without text
https://www.tideland.de secure (doesn't work, Tideland provides no https)
Tideland Software
ftp://ftp.tideland.de/pub/software/ without text
send a mail to the author
frank@mweb.de is the author's mail address

4.1.5. Images and Thumbnails

4.1.5.1. Image

Small Sample Image

4.1.5.2. Thumbnail

4.1.6. Includes

Includes use the same syntax as links. The included content will be processed in contrast to the include macro.

[include:/path/to/this/file.incl This will be shown if there's no file!]

5. Templates

Templates are just HTML files containing macros and variables. To include the rendered content, the content macro has to be used.

6. Macros

Macros are intended to add dynamic behaviour to the content and the templates. They control the content integration, includes and plugin execution. The syntax can be seen in the raw mode.

6.1. General

DCP macros follows the scheme @[a-zA-Z]+(<ARGS>). If this pattern matches to one of the built-in macros, it will be replaced by the result of the macros. Otherwise it will be replaced by ???.

6.2. Built-in Macros

content(): This macro places the content into the template. A filename can be passed as an argument to insert a named diffent content too.

include(): The include macro is used to include a file without processing.

execute(): If the core features of the DCP aren't enough you can extend it with plugins. These are very easy Python modules with the one method run(). The first argument is the name of the plugin, the remainder will be passed as argument to the plugin.

anchorTop() / anchorBottom() / anchor(): Placing anchors into the document so they can be used as targets for a quicker navigation. Take also a look at the links section.

cgienv(): Shows the value of CGI environment variables, like REMOTE_ADDR.

6.3. Writing Plugins

Plugins are realy simple to implement. They are simple Python modules with the one function run(args).

"""
    DCP Sample Plugin
"""

def run(args):
    if args:
        return "Args: %s" % args
    else:
        return "Hello world!"

Here are some samples of the output of this plugin:

Args: The quick brown fox jumps over the lazy dog.
Args: File /products/dcp/documentation.html with template tideland.tmpl.
Hello world!

7. Variables

The Dynamic Content Processor provides own variables and can work with external variables passed as headers or URL parameters. These variable control the behaviour of the generator or can be placed into the content or the template for display.

7.1. General

DCP variables follow the scheme $[a-zA-Z_]+. Only two of them are needed for the content generation. The first is dcpFile which is set automaticly through the action definiton (see above). The second is dcpTemplate which default is set inside the CGI script. dcpFile is the name of the content file, dcpTemplate the template where the content is placed in.

Individual templates can be set through the definition as a header inside the content or as URL parameter. The evaluaton order is parameter, then content file and at last the default.

A special variable is dcpRaw. It is intended to be used as URL parameter. It will control the raw content display. Also dcpNumbering controls the rendering as it places section numbers in front of the headlines.

All other variables are just for information purposes or to display the table of contents for inner page navigation.

If their's no variable matching to a string with the pattern above, it will be replaces by an empty string.

7.2. Built-in Variables

These are all the variables controlling the work of the Tideland Dynamic Content Processor or being filled through the system.

dcpFile: The name of content file, based on .
dcpTemplate: The name of the template file based on the template settings.
dcpModificationTime: The modification time of the content file, formatted based on the configuration settings.
dcpGenerator: Name and release of the DCP
dcpRaw: Flag for the raw display of the content file.
dcpNumbering: Flag for the numbering of the headers.
dcpTableOfContents: Generate a table of contents for inner document linking to the headers. Should be used together with dcpNumbering.

7.3. User Defined Variables

User can define their own variables, e.g. for the dynamic include of submenus depending on the current content. These variables have to be assigned inside the content header or as a parameter inside the URL.

7.4. Samples

7.4.1. Create a link pointing to the current file using a print template.

[link:/products/dcp/documentation.html?dcpTemplate=print.tmpl Print View]

7.4.2. Switching numbering for the current document on

dcpNumbering: on
title: Foobar

= First numbered title =

== Numbered subtitle ==

Back ...

Those little additional texts at the end of the page or document.

Last Blog Entries

Archive

Categories