Textantrieb | UText/1 | UText/1.2 Manual

cms add-in

The cms add-in module supports the generation of websites. It makes some content assumptions and provides some localization support.

Output Tags

These are the tags defined in this module. See Tags for details about each of them.

• i: html tag <i>
• b: html tag <b>
• em: html tag <em>
• sub: html tag <sub>
• sup: html tag <sup>
• ul: html tag <ul>
• ol: html tag <ol>
• li: html tag <li>
• br: html tag <br>
• hellip: html entity …
• mdash: html entity —
• ab: angle brackets
• cb: curly brackets
• nz: expand if non-zero length
• z: expand if zero length
• xml: xmlify
• header: header line
• meta: header meta name line
• url: external web link
• link: internal page link
• download: internal download link
• code: render code
• img: embed image
• tab: tabulator
• doctype: document type line
• d: standard date
• dl: long date
• ds: string date
• time: timestamp
• q: quotation marks
• more: hidden text
• file: resolve local file names
• n: internal link by name
• newsite: set the url of the website being generated
• newpage: set the name of the webpage being generated
• nav: website navigator
• navigators: load navigators data
• cref: item cross-references
• opentag: html open tag
• closetag: html close tag

Settings

This add-in module installs a setting provider named cms for changing the unit and class names used by some tags such as [n] or [nav]. The settings are the following:

• bound
• download class
• equivalent field
• expand tab
• external link class
• lang field
• navigation class
• navigator caption field
• navigator item page selector
• navigator item selector
• navigator next prefix
• navigator next suffix
• navigator page field
• navigator prev prefix
• navigator prev suffix
• navigator selector
• navigator title field
• page caption field
• page filename default extension
• page filename field
• page fulltitle field
• page selector post
• page selector pre
• page subtitle field
• page title field
• page unit name
• site unit name

For example, for [url] to set the html class ”www“ whenever an external link is output, instead of the default class name ”external“, one can use the following script instruction:

set external link class to www

Each setting is available as a Perl variable with a matching name without spaces and each word beginning with a capital letter. The above script instruction would be written in a Perl script as:

$cms::ExternalLinkClass = 'www';

Generic Methods

new_site

Every script that uses the cms module must call $ut->new_site(<url>); or the corresponding tag [newsite <url>] once for each generated website. Url indifferently with or without http://. The given url is used by the module currently just for expanding a download tag.

new_page

Every script that uses the cms module must call $ut->new_page(<unit name>); or the corresponding tag [newpage <unit name>] once for each generated webpage, so that when setting links the module knows the current location. This is used for setting relative paths to files and for classing an <a> tag as active or inactive.

get_text

The cms module contains translations for some few strings to get them translated according to the language that is currently set at run time.

A call to $ut->get_text('<string>') returns the translation of an English term in the current language.

You can call it with more than one string, then you get a list with each translation. For example:

($short,$long) = $ut->get_text('short','long');

to get the translation of the words ”short“ and ”long“ in the current $ut language and put them respectively into the variables $short and $long.

Currently supported strings are: active, ca, de, elink, en, es, hide, inactive, lang, long, more, next, pic_next, pic_prev, prev, short, show. Being ”lang“ the word to be shown when offering an equivalent page in other languages and ”en“, ”de“ etc. the names of the respective language. The strings ”pic_...“ are <img..> tags to be inserted in navigators to show the previous and next item, and ”elink“ is the legend of an external link.

load_navigators

This method must be called once on a UText object if navigators are to be used. See tag nav for more information.

Blog Support

This functionality is deprecated and might be removed in future versions. This blog support was used originally, before UText Script was implemented.

blog_generate

Usage: $ut->blog_generate(<relative directory>);

This function reads all UTL files contained in the source directory, generates for each source file a UTL file and saves it at the blog directory, and then parses each generated file, thus generating the blog structure. Parameters:

• The source directory is the given directory relative to the variable $blog_root_source.
• The generated files are saved at the given directory relative to the variable $blog_root_target.

The file generation for each blog item works this way:

• The source file is scanned for a time stamp, which is a line having the role defined by the variable $blog_role. If it does not have one, a time stamp is automatically added to the source file with the current time.
• The source file is copyied into the target file prepending the contents of the variable $blog_prolog.
• At the end of the generated file two item categories are appended: ~cat <year> and ~cat <year>-<month>, containing the year and the month of the time stamp.

blog_restrict_status

The blog items can have a role named ~status that specifies the editorial status of the item. A call to $ut->blog_restrict_status(<list of status>); causes the next call to blog_generate to apply only to the blog items that have one of the given status. An empty string corresponds to items without a status.

Example: $ut->blog_restrict_status('','review'); the next blog generation will include all posts that do not have any ~status line and all those that have a line ~status review, whereas $ut->blog_restrict('published'); will restrict the blog generation to the items containing a line ~status published.

getPostMetadata

The purpose of this function is to generate a localized line such as ”Posted on 05/30/09 at 06:30“ reflecting the time stamp of a particular blog item.

Usage: $ut->getPostMetadata(<timestamp>) returns the formated time stamp in the current language.

Use $ut->getPostMetadata(<timestamp>,{<option1>=><value1>, ...}) to set these options:

• lang=><language> to get the string in that particular language
• time=>short to get the time in short numerical format (default)
• time=>no returns just the date of the time stamp without time

$blog_root_source

Assign $UText::blog_root_source='<directory>'; once to define where the source blog files are located.

$blog_root_target

Use $UText::blog_root_target='<directory>'; to define where the generated blog files are to be saved.

$blog_role

This variable defines the name of the role in blog items that contains the time stamp.

If you put $UText::blog_role='timestamp'; then a line such as ~timestamp ... contains the time stamp.

$blog_prolog

The contains of this variable are put at the begining of each generated blog file. It can contain $blog and $id, the former being replaced with the blog directory it belongs to and the later being the unit name of the current item.

Example:

$UText::blog_prolog=<<'EOF';
=my_web
=$blog ~ website
=posts ~ content
=$id ~item
EOF

$blog_RESET

If you set $UText::blog_RESET=1; files for all post items are generated. If you set it to 0 (the default value) then each file is generated only if it does not already exist or if the source file is newer than the corresponding generated file.

Miscelaneous

getTime

The funtion getTime returns a date and time formatted according to RFC #822, which is used in RSS feeds. Example:

Tue, 18 Aug 2009 08:15:24 +0000

Syntax 1: getTime() — returns now

Syntax 2: getTime($filename) — returns the modification time of the given file

Syntax 3: getTime($time) — where the string $time is formatted as YYYY-MM-DD hh:mm:ss, returns the given time.

ELINK

The contents of the variable $UText::ELINK are prepended to the caption of an external link (tag [url]). This way you can define for example an external link icon by setting:

$UText::ELINK='<img src="[file link.gif]" alt="external link"/>';

Note: This property is for backwards compatibility only. The preferred way to set an external link icon is via css style sheet.