Introduction

Vdub CMS  is a content management system for VMS-based Web sites.

Vdub is a nickname for the VWcms (VMS Web-content management system) application.  The generic term content management system (CMS) is used to refer to software applications used to organize information in various environments.   In this case VWcms helps organise web sites on VMS systems.

Of course the documentation you are currently reading is composed and managed using VWcms!

Why another CMS?

Good question!$$TEASER$Good Question!$$ And why one built using a compiler rather than based on some scripting engine such as PHP?

If all you require is a functional infrastructure for site hosting or elementary shared authoring then Vdub is maybe what you are looking for. VWcms is not designed to be all things to all people, just much of what many may need. It would be expected site creators using VWcms would have a working knowlege of HTML and CSS, content editors/managers less so.

There are many free and commercial packages providing the essentials of a Web site.  These are constructed by professional graphic artists and designers and can provide a polished look and feel to a Web presence while saving a significant amount of effort for the site administrator. It is usually a relatively straight-forward exercise to adapt this sort of package to VWcms usage.

VWcms has been developed against recent versions of Firefox, Google Chrome, Microsoft Internet Explorer, Safari and Opera. As is often the case, much more time was spent getting MSIE (mostly) to behave as required than on all the others put together!

VWcms © 2008-$$TIME$%Y$$ Mark G. Daniel

This program comes with ABSOLUTELY NO WARRANTY.
This is free software, and you are welcome to redistribute it under the
conditions of the GNU GENERAL PUBLIC LICENSE, version 3, or any later version.
http://www.gnu.org/licenses/gpl.txt$$TEASER$GPL License$$

What's New?

$$NOPRINT$+$$$$RSS$feed=whatsnew$type=blog$description=What's new with VWcms!$level=-1$$

Announcements of new/changed functionality, etc., with VWcms.

$$BLOG$new$$

This information is available via  $$RSS$feed=whatsnew$subscribe$$  (see RSS Feed).

$$BLOG$level=-1$order=-$extract=512$$

For complete list of modified documentation see What's Changed?.

skip to editing

$$NOTOC$$$$GOTO$/vdub/Editing_Content$$

Q&A

$$BLOG$24 July 2011 21:15$goto=/vdub/Building_The_Site/Reader_Comment/Using_Q&A$$$$NOTOC$$

A question and answer challenge attempts to exclude automated spam generators by requiring additional input in the form of an answer to a question that is difficult for a machine to recognise as distinct from the other input and that often requires some domain knowledge or other understanding by a human.

reCAPTCHA

$$BLOG$18 July 2011 21:15$goto=/vdub/Building_The_Site/Reader_Comment/Using_reCAPTCHA$$$$NOTOC$$

A CAPTCHA is a program that can tell whether its user is a human or a computer. You've probably seen them - colorful images with distorted text at the bottom of Web registration forms. CAPTCHAs are used by many websites to prevent abuse from "bots," or automated programs usually written to generate spam. VWcms now supports the Google reCAPTCHA service for its three methods of information submission, $$$$COMMENT$$$$, $$$$FEEDBACK$$$$ and $$$$FEEDBACK$$$$.

Section Ellipsis

$$BLOG$11 May 2011 19:45$goto=/vdub/Editing_Content/VWcms_Edit$$$$NOTOC$$

VWcms Edit by default now copies and removes a section and its subordinate sections.  There have been other refinements and previous users should reread this section.

Insert Here^

$$BLOG$11 May 2011 19:30$goto=/vdub/Editing_Content/VWcms_Edit$$$$NOTOC$$

The VWcms Edit dialog now allows the name of a section to be inserted into the content ([Here^]) in addition to a link to a section ([Link^]).

Substitution

$$BLOG$04 May 2011 01:47$goto=/vdub/Building_The_Site/Substitution$$$$NOTOC$$

Substitution directives are now uniform between template and content (with a couple of notable exceptions).  A single section covering substitution has been consolidated from earlier (largely redundant) subsections from template and HTML content descriptions.

Website Packages

$$BLOG$10 April 2011 04:24$goto=/vdub/Configuration/Website_Packages$$$$NOTOC$$

There are many free and commercial packages constructed by professional graphic artists and designers that can provide a polished look and feel to a Web presence while saving a significant amount of effort for the site administrator. These are usually relatively straight-forward to adapt to VWcms usage.

PMDF Kludge

$$NOTOC$$$$BLOG$28 February 2011 22:58$$

PMDF is reported to have an issue with a mixed-case sender address passed directly via the VMS Callable Mail API.  This does not occur if a suitable mail transport is used to wrap the address.  The [PMDF-kludge] directive allows this to be provided.  See Site Directives.

Single-Button Blogging

$$NOTOC$$$$BLOG$Monday, 28 February 2011 18:11$$

The single-button blog entry!  See Blogging.

Tagging

$$NOTOC$$$$BLOG$Sunday, 11 April 2010 19:03$$

A tag in a site or blog is a label that explicitly categorises site content.  These can then be presented allowing a site user to select items of potential interest based on those categories.  See Tagging.

VWcms Configuration

$$BLOG$Sunday, 04 April 2010 22:52$$$$NOTOC$$

BE WARNED!  VWcms configuration has been radically altered.  It has moved from the use of logical names to define sites and some site characteristics to being globally configured using file-based directives.  See Global Configuration.

Regular Expressions

$$BLOG$Sunday, 04 April 2010 22:12$$$$NOTOC$$

VWcms conditional configuration and VWcms searching can now use regular expressions.

Form Processing

$$NOTOC$$$$BLOG$Sunday, 27 December 2009 02:37$$

The $$$$FORM$$$$ directive allows all of the familiar HTML form elements (text, radio and check boxes) to be used to solicit information from the reader and pass that back to the site via email, file or site-specific agent.  Elementary data validation is performed before before submission.  See Reader Form.

Comment Abuse

$$NOTOC$$$$BLOG$Tuesday, 01 December 2009 22:28$$

Abuse may be from humans being a nuisance or malicious, or from spambots creating unwanted activity and site pollution.

Though a notoriously difficult issue to address other than through moderation there are some configurable mechanisms available that attempt to minimise the possibility of site abuse and DOS.  All apply to Reader Comment and some to Reader Feedback.

See more detail at Spam Abuse.

Conditional Operators

$$NOTOC$$$$BLOG$Tuesday, 24 November 2009 22:32$$

While deploying some conditional content (and bug-fixing) Tim Sneddon concluded that the keyword match was insufficiently functional.  He then added code to provide string equality operators.  Thios has been integrated into the baseline VWcms. These are now described in Conditional Content.

RSS Feed

$$NOTOC$$$$BLOG$Sunday, 20 September 2009$$

"Really Simple Syndication" or "RDF Site Summary" is a means of providing timely and concise summaries of site content specifically for subscribers to that information.  The $$$$RSS$$$$ directive allows the equivalent of a $$$$SYNOPSIS$$$$ or $$$$BLOG$$$$ summary to be provided as an RSS Feed.

Conditional Content

$$NOTOC$$$$BLOG$Saturday, 12 September 2009$$

The $$$$IF$$$$ directive evaluates the request environment and then conditionally processes (and outputs) content between it and a matching $$$$ELSE$$$$ and/or $$$$ENDIF$$$$.  Conditionals may be nested, and can be used in both the site template and content.  Obviously it is intended to allow tailoring of that content.  One example might be the inclusion of a coversheet with a printed version.  See Conditional Content.

Breadcrumb Navigation

$$NOTOC$$$$BLOG$Sunday, 06 September 2009$$

The $$$$CRUMBS$$$$ directive provides a breadcumb style of navigation aid to compliment a CSS table of content.

Example What's New

$$NOTOC$$$$BLOG$Wednesday, 2 September 2009$$

This entry is really just a place-holder for the $$$$NOTOC$$$$ example referenced from Table of Content.

What's Changed?

$$NOPRINT$+$$$$RSS$feed=whatschanged$type=synopsis$description=What's changed in the VWcms documentation!$level=1$order=-$since=*$$

A complete list of modified sections and date of change with most recent shown first.

This information is available via  $$RSS$feed=whatschanged$subscribe$$  (see RSS Feed).

$$SYNOPSIS$level=1$order=-$since=*$$

skip to intro

$$NOTOC$$$$GOTO$/vdub/Introduction$$

Editing Content

VWcms  displays, edits and stores its content as HTML (XHTML in fact).

Each section shown in the table of content (to the left of this text) is composed and maintained as a relatively autonomous unit of information. The various sections of the site can be (hyper-) linked between, providing an alternate way to navigate through the content.

When logged-in as a site manager the Manage Site navigation item opens one of two supported HTML editors, TinyMCE or FCKeditor, at the section currently being viewed. The editor allows content composition using a WYSIWYG interface, much like a simple word processor. Among other capabilities these provide

Both editors can be concurrently supported with user selection available at the management interface.

The site management interface / edit window can repositioned in the browser window by clicking on the bar at the top of the interface (a move cursor is displayed) and then dragging to another position.  Clicking again releases the interface.  The [X] icon at the top right can be used to close the interface and return to site view mode.

VWcms management

Below the editor are a number of additional,  VWcms content selectors and buttons.

Within these controls are three important buttons:

Draft content is visible only to a logged-in manager.  It is used to modify site content to a satisfactory level before publishing it to the public site.  The draft persists over login-logout cycles and so may be used to retain in-progress modifications over the medium term before making them live.  Using $$_vwcmsbtn$Draft$$ appropriately often during changes helps guarantee against significant loss.

Once published any existing draft is not automatically deleted.  The draft remains available as an alert and for further modification until explictly deleted using the $$_vwcmsbtn$Discard$$ button.

Edit Changes

VWcms tracks editing changes to content and other site files and alerts the manager if the edit is about to be lost by navigating away from the editor  without saving  those changes.  Changes may be discarded by continuing.  Inadvertant loss can be avoided be by cancelling the alert, saving the changes appropriately and then recommencing the navigation.

Do not attempt to navigate backwards (using browser button or dialog) into an edit session.  It has been noted that commonly the edit session may have the appearance of containing the previous changes but when saved they are actually absent.  This appears to be a browser behaviour.

TinyMCE

TinyMCE is a very capable, open-source, JavaScript-driven HTML editor:

http://tinymce.moxiecode.com/

TinyMCE is copyright © MoxieCode Systems and released under LGPL.

Browser compatibility (extensive) is listed on the home page of the above site.

The editing capabilities available with TinyMCE are comprehensive and most will be familiar to anyone who has used word processing application(s).  A detailed explanation of TinyMCE, usage and management, is beyond the scope of VWcms documentation.  For detailed information or explanations of anything that seems less-than intuitive please consult the TinyMCE documentation wiki:

http://tinymce.moxiecode.com/documentation.php

An example of the editor interface is displayed below:

Some features of TinyMCE are disabled or have no effective behaviour when used within VWcms.

When leaving TinyMCE VWcms occasionally alerts, reporting that the content has changed (continue or not?)  This is due to TinyMCE checking the syntax of the content and making minor modifications (under-the-hood).  If the manager has made no explicit changes to content it is safe to continue without saving again.

FCKeditor

FCKeditor is a very capable, popular, open-source package:

http://www.fckeditor.net/

FCKeditor is copyright © 2003 - 2008 Frederico Caldeira Knabben and released under GPL.

Browser compatibility (extensive) is listed on the home page of the above site.

The editing capabilities available with FCKeditor are comprehensive and most will be familiar to anyone who has used word processing application(s).  A detailed explanation of FCKeditor, usage and management, is beyond the scope of VWcms documentation.  For detailed information or explanations of anything that seems less-than intuitive please consult the FCKeditor documentation wiki:

http://docs.fckeditor.net/FCKeditor_2.x/Users_Guide
http://docs.fckeditor.net

An example of the editor interface is displayed below:

Some features of FCKeditor are disabled or have no effective behaviour when used within VWcms.

When leaving FCKeditor VWcms occasionally alerts, reporting that the content has changed (continue or not?)  This is due to FCKeditor checking the syntax of the content and making minor modifications (under-the-hood).  If the manager has made no explicit changes to content it is safe to continue without saving again.

VWcms Edit

VWcms provides additional composition tools (amongst others) below the edit area:

All of the above insert at the current edit cursor.

Managing Sections

VWcms sites are divided into sections according to HTML headings.  An <h1> is a top-level section, <h2> second-level, <h3> third level.  Each of these can be part of a displayed table-of-content (the navigation menu to the left of this page).  <h4> generates an in-line heading separating parts of a single section (and generate an informational comment in the site-map).  Also see HTML Content. Section titles cannot contain a forward-slash (/).  A moment's thought about the way VWcms accesses subsections should underscore why. Forward-slashes are automatically converted to back-slashes (\).

Only a single $$$$CLIP$section-title$$$$ may exist and be copied, removed or inserted at any one time. A subsequently copied or removed section overwrites any existing clip.  Removing a clip deletes it completely.  Multiple concurrent clipped sections can be maintained by simple rename, the $$$$CLIP$section-title$$$$ into $$$$CLIP-1$section-title$$$$ for example, and then subsequently renamed back after intervening clip operations.

Remaining Tools

The remaining tools shown towards the bottom of the above image are discussed in Managing Content.

Plain Edit

VWcms provides a plain text editor in addition to the HTML editor.  The plain text editor is primarily used to compose and maintain the various other files used in compositing the site:

Each may be accessed using the file selector alongside the $$_vwcmsbtn$Edit-Plain$$ button.

Note the semi-colon delimited version number associated with each file.  More on this in Managing Content.

The adjacent $$_vwcmsbtn$Delete$$ button does exactly what the label implies - Caution!

The preceding search-and-replacement function is also described in Managing Content.

The $$_vwcmsbtn$Content$$ button returns the WYSIWYG content HTML editor.

Raw HTML Edit

The public content of the site (by default) is contained in the file _INDEX.HTML (note the leading underscore).

Similarly, the content of a draft is in file __INDEX.HTML (two underscores).

These are both available via the file selection dialog.

With a little experience and care significant structural changes can be made via this plain edit interface.  This is sometimes the easiest method for rearranging the sections of a site.  The plain-text editor offers (browser-dependent) cut, copy, paste and undo, and so can be used for most of such basic changes. Of course, it is always well advised to save a $$_vwcmsbtn$Draft$$ and then work on the __INDEX.HTML file until satisfied.

Managing Content

Below the content editing tools are a collection of file-oriented tools.  They are initially disabled (greyed-out) and require a file name to be selected (adjacent to the $$_VWcmsBtn$Edit-Plain$$ button) before becoming active.  This is deliberate to assist avoiding actions on unintended files.  Some tools are appropriate to some file types (e.g. textual) and not to others (e.g. images).  $$_VWcmsBtn$Delete$$ is applicable to all.

After the editing of content the next most common activity would be the management of the non-textual resources used within (e.g. images) and made available by (e.g. downloads) the site.  VWcms stores all content and resources in a single directory associated with the site.  Textual content is edited in-place.  All other resources must be uploaded to the site.  These are managed using the interface available from the $$_vwcmsbtn$Resources$$ button.

File Versions

As content and resource files are saved and uploaded new versions are created.  The semi-colon delimited number associated with the file increments with each save, with the highest version number being the most recent.  (Users of VMS will be familiar with this concept.)  For editable content it is possible to regress to earlier versions by selecting a version with a lower number.  The $$_vwcmsbtn$Tidy Up!$$ button removes multiple versions and resets the version number to ;1.

Care needs to be exercised to ensure that a file selected for search-and-replacement, editing or deletion is the actual version desired!

Search and Replace

The text input field to the left of the $$_vwcmsbtn$<Search$$ button can be used to check for instances of the supplied string in the currently selected file (adjacent to the $$_vwcmsbtn$Edit-Plain$$ button).  In conjunction with the $$_vwcmsbtn$Replace>$$ button and associated text field to the right it can be used to replace such instances with another string.  Again, this search-and-replace operates on the selected file.  The search and the replacement both operate on the raw text contained withing the selected file and so some care needs to be exercised when peforming general replacements (for example, not to replace HTML markup inadvertantly).

The HTML editors also support a search and replace which is confined to HTML content.  This can be performed on single section or by loading gthe entire _INDEX.HTML into the HTML editor on the entire site.

Edit

In addition to editing the content of the site it is possible to directly edit the content of a file.  Plain text editing is available for both site files and HTML files (allowing access to the raw HTML), and HTML editing for HTML files.  Some care needs to be exercised when using plain text editing on HTML!

Delete

Completely removes the selected file.  Caution!

Resources

The resources interface allows additional resources to be uploaded (e.g. images), viewed and deleted.

Each of the resource files used are listed showing size and modification date.  Graphics files have an iconised image below the resource name.  Clicking on this image increases it to full size.  When full-size, clicking reduces it to an icon.  Associated with each item is a link (¤¤¤) allowing direct browser access.

The $$_vwcmsbtn$Browse$$ dialog allows a file local to the browser system to be selected for upload.  The $$_vwcmsbtn$Upload$$ button places this file into the site directory.  The site directory can be used for site graphics and any other resource required or provided for download.

A file may be deleted by selecting the file name (adjacent to the $$_vwcmsbtn$Edit-Plain$$ button) and using the $$_vwcmsbtn$Delete$$ button.  Caution!

Archive & Tidy

The $$_vwcmsbtn$Archive Site$$ button creates an archive of all the files contained in the site directory.

By default this archive is a BACKUP saveset.

Setting site configuration directive [archive-zip] makes it a ZIP archive.

This is essentially a snapshot of the site at the time the archive was created.  The archive is placed in the subdirectory  [._ARCHIVE] of the site directory and named using a time-stamp.  The archive can be moved to another location and/or the content restored at some later date.

Do not use the archive facility indiscriminately.  It can consume significant disk-space.

The $$_vwcmsbtn$Tidy Up!$$ button removes all older versions of files.  This leaves just a single version of each the current files, preventing any sort of site content regression.  Version numbers on editable files are returned to ;1.  Tidying reduces the disk-space consumed.  It is generally a good policy to tidy after completing and publishing site modifications.

Building The Site

For working examples of VWcms concepts consult the relevant parts of the Vdub (this) site.

There are many sources for the essentials of a Web site, including free and commercial template packages.  These are constructed by professional graphic artists and designers and can provide a polished look and feel to a Web presence while saving a significant amount of effort for the site administrator.

For detail on adapting these to VWcms see the description in Website Packages.

There are two major components that contribute to the look and feel of a site

In addition there is the

Site Template

The template provides the "superstructure" of the site.  It determines the overall layout of the information on each page.  The content (HTML infromation of the site) is embedded inside this layout.  The template is essentially HTML with some embedded keywords delimited by two dollar symbols.  As an example, the keyword  $$$$CONTENT$$$$  causes the substitution of the content of the current section.  More detail on this in Template.

Style-Sheet

The style-sheet provides the detailed look-and-feel of each component in the site pages.  It contains Cascading Style Sheet version 2 (CSS2) directives.  Some are required-by and reserved for normal VWcms appearance, other for VWcms management (editing, etc.) behaviour.  Generally, site design requires at least a working knowledge of CSS2.  More on its role in Style-Sheet.

HTML Content

The HTML Content is provided via the HTML editor and the associated VWcms dialogs described in TinyMCE and FCKeditor, and VWcms Edit.

Print Template

The Print Template is generally a simplified version of the site template.  It does not contain the components supporting on-line, interactive access to the site, and provides the essential HTML content in a structure and format suitable for print media.  Similar recommendations for designing the main template apply to printing.

Composite Site

A composite VWcms site is one that spans multiple directories, uses shared templates and integrates tables-of-content. This allows multiple, independent site management domains to provide an effective, tightly-integrated single site.  Recommended for larger and more complex sites.

Substitution

Substitution of content for directive is a fundamental mechanism used in the building and dynamic nature of VWcms sites.

The HTML content is parsed by VWcms, with all text other than that surrounded by double dollar symbols (i.e. $$$$) output as-is.  Dollar-delimited strings are used as substitution directives, and in this sense a form of macro, representing content generated by VWcms and inserted in place of the directive.  Substitution directive names are case-insensitive, though generally shown upper-case to more easily distinguish them from surrounding content.  Some take optional parameters (case sensitivity is dependent on the parameter), each separated by a single delimiting dollar symbol (see examples).  To specify an empty parameter use the sequence $\$.

Substitution is supported in both template and HTML content, using exactly the same directives, with noted exceptions.

Common Directives

The following directives might be expected to be used in general content.

Name Function Parameter
$$$$AGO$$$$ How many minutes, hours, days, etc., ago the site or section was modified. (This section was last modified $$AGO$#$$.) "#" for section, "*" (default) for site
$$$$BACK$$$$ A (JavaScript-enabled) link to go to the previously viewed page. alternate text
$$$$BLOG$$$$ Allows blogging. See Blogging. parameters
$$$$CGI$$$$ Insert the value of the supplied parameter CGI variable. CGI variable name
$$$$COMMENT$$$$ Display and solicit reader comments.  See Reader Comment. parameters
$$$$CONTENT$$$$   The content of the specified section.  See Include Examples. section name/path
$$$$CRUMBS$$$$ Breadcrumb-style navigation aid.  See Table of Content.
parameters
$$$$FORM$$$$ Construct an HTML form.  See Reader Form. parameters
$$$$GOTO$$$$ Redirect to the specified URL. See Go & Gone To. URL
$$$$GONETO$$$$ Redirect to the specified URL. See Go & Gone To. URL
$$$$HIDE$$$$ No table-of-content entry, no site-map entry, not returned by searches, etc.  See Table of Content. none
$$$$HIT$$$$ Section (page) hit counter.  See Hit Counter. parameters
$$$$HTML$$$$ Insert raw HTML into the content.  See Raw HTML. parameter
$$$$INCLUDE$$$$ Include the contents of the supplied parameter in its own viewport.  See Include & Insert. CSS and URL**
$$$$INSERT$$$$ Insert the contents of the supplied parameter in-line with the content.  See Include & Insert.
CSS and URL**
$$$$LASTMOD$$$$  The date/time the site or section was last modified. This section last modified $$LASTMOD$#$$. "#" for section, "*" (default) for site; second parameter can be a time format string
$$$$NEXT$$$$  A link to the next section (if any).  alternate text
$$$$NOPRINT$$$$ Section is not printed.  See Print Template. "+" this and subordinate sections
$$$$NOTOC$$$$ No entry in the table-of-content but appears in the site-map and is returned by searches, etc.  See Table of Content. none
$$$$PRAGMA$$$$ Supply a pragmatic directive.  See Pragma. parameters
$$$$PREV$$$$  A link to the previous section (if any).  alternate text
$$$$QANDA$$$$ Supports a question and answer challenge.  See Using Q&A. parameters
$$$$RECAPTCHA$$$$ Supports the Google reCAPTCHA service.  See Using reCAPTCHA. parameters
$$$$SHOW$$$$ Show the parameter.  LANG to show the current language configuration directives.  Code module SHOWLOCAL.C allows local $$$$SHOW$$$$s to be provided. parameter
$$$$SYNOPSIS$$$$ Display a list of sections with extract. See Synopsis. parameter
$$$$TEASER$$$$ Adds a teaser (or informational comment) to the site map.  Does not appear in the content. text
$$$$TICKET$$$$ Issues a comment ticket.  See Spam Abuse. none
$$$$TIME$$$$  Display current date/time. See Time. parameter
$$$$TITLE$$$$ Display the current section title. See Section Title. parameters
$$$$USER$$$$ A logged-in username; empty otherwise. supplementary text

**See further explanation below.

Macro Directives

A site may configure substitution macros that can then be used to insert text within the site.  Macros are defined in the VWcms configuration file.  The [macro] configuration directive can be used multiple times to define each macro required.  Two types of macro are supported:

Substitution Insertion
A substitution macro, indicated by a ':' character, occurs when the page is read.  Subsequently changing the value of the macro in the configuration changes the substitution at read time. An insertion macro, indicated by a '=' character, occurs when the page is edited.  Any subsequent change in macro does not affect this instance.

The following are the directives from the Vdub documentation (this site) and are used in the following examples.

[macro]  example1:<b>This is EXAMPLE ONE macro!</b>
[macro]  example2:<b>This is EXAMPLE %s macro!</b>
[macro]  example3=<b>This is EXAMPLE THREE macro!</b>
[macro]  VWcmsBtn:<input class="manage_btn" style="font-size:66%%;margin:1px;" \
type="reset" value="%s" />

These directives are used with names beginning with a single underscore.

$$$$_example1$$$$ $$_example1$$

Macros can use the sequence %s to insert parameters when used.  Percent symbols must be escaped by doubling-up (i.e. %%).

$$$$_example2$TWO$$$$ $$_example2$TWO$$

This text of the example3 macro was inserted at edit time.

This is EXAMPLE THREE macro!

Note the error indication in the following example because the macro doesn't exist!

$$$$_example4$$$$ $$_example4$$

The buttons in use throughout the Vdub documentation are generated using a macro.

$$$$_VWcmsBtn$A Button!$$$$ $$_VWcmsBtn$A Button!$$

The VWcms Edit interface contains a convenient selector and button for inserting macros.

Specialised Directives

The following directives are not commonly used in content.

Name Function Parameter
$$$$ADVISE$$$$ Display informational, warning and error messages generated by the VWcms engine.  Should be one instance somewhere on the site template. none
$$$$CONTENT$$$$ The content of the current section. ** none
$$$$DRAFT$$$$ When managing the site and a draft is being viewed displays an advisory message. alternate message
$$$$LOGIN$$$$ Provide a login/logout dialog. alternate text
$$$$MANAGE$$$$ Provide a manage-site/view-site dialog. alternate text
$$$$RESULT$$$$ Display the results of a site search. none
$$$$RESULT$?$$$$ Display the keyword searched for. none
$$$$SITEMAP$$$$ Display a site-map as a nested, ordered list. none
$$$$TOC$$$$ Table of Content. See Table of Content. ** As shown to the left.
$$$$$$$$ Four dollar symbols output two dollar symbols (substitution-escape). none
$$$$! ... !$$$$ Text inside the directive is not output.  $$!(like this won't be!)!$$  Note the delimiting exclamation marks. none

**Site template only.

Alternate Text

Those directives that have an alternate text parameter generally provide visible text or a link in the content of the page.  These have a default string associated with them but allow an alternate to be specified.  This not only allows customisation of the various elements of the page but also allows for non-English language pages to be composed.  There are also a set of configuration directives beginning [lang_...] that can used.$$TEASER$non-English language$$

Alternate text, on appropriate substitution directives, may be used to specify graphical icons (images).  For example, the $$$$PREV$$$$ and the $$$$NEXT$$$$ directives, normally producing

<<PREV   NEXT>>

could be placed in the content as

$$$$PREV$<img src="/_vdub/arrow_left.gif" border="0" />$$$$
$$$$NEXT$<img src="/_vdub/arrow_right.gif" border="0" />$$$$

which would produce the content

$$PREV$<img src="/_vdub/arrow_left.png" border="0" />$$   $$NEXT$<img src="/_vdub/arrow_right.png" border="0" />$$

Detectable Errors

VWcms reports detectable errors in substitution directives and parameters.  The directive is highlighted on the page and the first reported in a status area. It also uses this area to report other conditions, such as warnings and informationals, in the case of Vdub documentation placed at the bottom of the page (using the $$$$ADVISE$$$$ directive).  This is an example of a misspelled directive.

$$ADVIZE$$

There are a number of deliberate errors included throughout the Vdub documentation to illustrate the function.

$$$$TIME$%d %b %999Y %H:%M$$$$=$$TIME$%d %b %999Y %H:%M$$

$$$$BOGUS$$$$=$$BOGUS$$

Template

This file is named _SITE.HTML (by convention) and contains standard HTML and VWcms directives delimited by double dollar symbols (i.e. $$$$).

The HTML is output directly and is used to format the composition of each page.

The substitution directives (e.g. $$$$CONTENT$$$$) insert other HTML (etc.) at that point in the output.

This template applies it's structure and format to all pages provided by the site.

Here is the template file used by the Vdub (this) site:

$$INCLUDE$height:300px;font-size:80%;$plain:///_site.html$$

Note a variety of substitution directives used throughout:

$$$$DRAFT$$$$
$$$$TITLE$$$$
$$$$TOC$$$$
$$$$PRINT$$$$
$$$$SEARCH$$$$
$$$$LOGIN$$$$
$$$$MANAGE$$$$

 These have been described in the previous section.

$$$$MANAGE$$$$

One of the most important directives, this provides a link for activating the site management and editing interface.

It is best placed in close proximity to $$$$LOGIN$$$$ and is not displayed unless the client is logged-in and capable of managing the site.

By default the management and editing interface is displayed where the $$$$CONTENT$$$$ directives is used.  However when this location is unsuitable it can be explicitly placed using the absolute=X,Y parameter, where X and Y are the window coordinates in pixels from the top left.  Such a directive might look like

$$$$MANAGER$absolute=100,100$$$$

$$$$ADVISE$$$$

Displays informational, warning and error messages generated by the VWcms engine.  There should be an instance of this directive somewhere on the site template so that conditions detected by VWcms (e.g. directive errors) can be observed by the site manager (in particular).

Structure

As the content of the site is framed inside the template structure it should be carefully planned.

When using a third-party package for the Web site the structure is already largely determined but needs to be understood by the VWcms administrator so that it can be appropriately adapted to the VWcms components.

The Vdub site template has a simple, five panel structure which should be obvious in the on-line page.

+-----------------------------------------------------------------------+
| header (title) |
+------------+----------------------------------------------------+-----+
| | | |
| | | |
| | | r |
| left | content | i |
| | | g |
| | | h |
| | | t |
| +----------------------------------------------------+ |
| | footer | |
| +----------------------------------------------------+ |
| | | |
+------------+ +-----+

Each of these has an associated style in the site-specific sheet.

Of course the above is just an example of one way (admitedly a common one) a site layout might be organised.  Using substitution directives the (X)HTML infrastructure can provide just about anything around the various VWcms components.

Table of Content

The $$$$TOC$$$$ directive provides a mechanism for navigating the site.

The default generates a plain-text list of all major sections of the document along with an expanded list of any subordinate sections of the currently open section.  This format is suitable for designs where there is significant vertical space, as with the left hand column of this page.  There are some variations available within the TOC.

Parameter(s) Description Example
number beginning with a non-zero digit a nested, expanding ordered list of sections $1
number ten or greater a fully-expanded, ordered list of section $10
any (non-digit) string a 'bullet' placed left of the section $&bull;&nbsp;
dollar-separated combination ordered list of sections with explicit 'bullet' $1$&bull;&nbsp;
image URL the image is placed to the left of the item http://host/this.png

$$$$HIDE$$$$

This directive on the first line of a section suppresses its entry in the table-of-content (along with any subordinate sections) and also does not appear in the site-map or is returned by searches, etc.  It can be directly accessed and referenced from elsewhere in the site.  The "Reader Feedback" section uses $$$$HIDE$$$$.

$$$$NOTOC$$$$

This directive on the first line of a section suppresses the entry in the table-of-content (along with subordinate sections) but is visible in the site-map and is returned by searches.  The blog entries referenced in the "What's New?" section each uses a $$$$NOTOC$$$$ directive to reduce table-of-content clutter.

$$$$TOC$CSS$$$$

Generates the dynamic table-of-content seen on this site, where subordinate items pop out to the right when the parent is hovered over.  This is implemented using only CSS (Cascading Style Sheets) and requires no JavaScript.  It is known to work successfully with later versions of FireFox (all Gecko-based browsers in fact), Google Chrome, Microsoft Internet Explorer (5.5, 6.0, 7.0; best with 8.0), Safari and Opera.  A synonym is $$$$TOC$CSS$POP$$$$.

This directive takes one or more optional parameters.  The width in "em" (current font size) may be specified for one or all of the heading items; the first is the first-level list, the second the second-level list, etc.  In this way a particularly large heading may be accomodated without overflow occuring.  The following example accomodates a 15em wide second level-heading:

$$$$TOC$CSS$10$15$10$$$$

$$$$TOC$CSS$DROP$$$$

This CSS-variant provides a format designed for across a page.  This style of site layout provides a number of major headings above the content, each of which drops into any subordinate content with additional table items shown as necessary.

The primary TOC always displays the top-level sections, with immediate subordinate sections dropping down and further subordinates opening to the right.  The drop TOC can take the same optional width parameters as the pop TOC.

This is a screenshot showing the "Building The Site" section

"Drop" Example

Although designed for the layout used in the Vdub (this) documentation and not optimal for using the $$$$TOC$CSS$DROP$$$$ format there is an example which provides a reasonable experience of how the across navigation operates with significant content.

Define the additional logical name

$ DEFINE /SYSTEM VWCMS_SITE_VDUB2 VWCMS_ROOT_VDUB:[VDUB]_INDEX.HTML

Add the following HTTPD$MAP rules (for WASD, equivalent mappings for other server environments will be needed) and load into the server

pass /_vdub2/* /vwcms_root_vdub/vdub2/*
map /vdub2/* /vwcms/vdub2/*

The alternate format should then be available via the URI

/vdub2/

How was this done?

The across example uses all the same resources and content as the Vdub site except for the site template.  This is _SITE2.HTML and is used by /vdbu2/ via conditional configuration.  In the Vdub __VWCMS.CONF configuration file is the conditional

[if-site] vdub2
[site-template] _site2.html
[if-end]

which directs VWcms to use the alternate template.

For additional information on conditional configuration see the source code module CONFIG.C

$$$$CRUMBS$$$$

This directive displays a breadcrumb-style navigation aid.  It can be used in both the template and content pages.

$$CRUMBS$$

The keyword parameter style=.. can be used to directly apply a CSS style to the enclosing <DIV>.

A keyword-less parameter may be used to define the separator.  For example

$$$$CRUMBS$ ---> $$$$

is rendered

$$CRUMBS$ ---> $$

and with an image separator

$$$$CRUMBS$<img src="./crumb.png" style="padding:0 7px 0 7px;">$$$$

using the specified graphic

$$CRUMBS$<img src="./crumb.png" style="padding:0 7px 0 7px;">$$

Search

The $$$$SEARCH$$$$ directive inserts a search-for dialog comprising a text input field and a submit button immediately adjacent to it.

The (on-screen) size of the text field can be specified as an optional dollar-delimited parameter, then an alternate label for the submit button as another option.  In this way the overall width of the search dialog can be adjusted according to the space available at the location.

As described in Icons and illustrated by the Vdub (this) documentation the search submit button can be replaced by an icon (image).

$$$$RESULT$$$$

This reserved section is used to report search results.  It can only be seen in the table of content when in site management mode.

Print

The VWcms print facility provides three levels.

$$$$PRINT$$$$ $$PRINT$$ print the current section (page)
$$$$PRINT$+$$$$ $$PRINT$+$$ print the current and any subordinate section (a chapter, of sorts)
$$$$PRINT$*$$$$ $$PRINT$*$$ print the entire site (preceded by a TOC/site-map)

As can be seen in the Vdub documentation each of these can be associated with an icon.  See Icons for further information.

Prefixing the level indicator with an underscore ($$$$PRINT$_*$$$$) suppresses the $$PRINT$_*$print$$ dialog.

Print Template

The print template is generally a simplified version of the site template.

It does not contain the components supporting on-line, interactive access to the site, and provides the essential HTML content in a structure and format suitable for print media.

The print template must contain a $$$$TOC$PRINT$$$$ immediately before the $$$$CONTENT$$$$ substitution directive.  This generates a table-of content suitable for a full-site print at the beginning of the document.

Content sections can use $$$$NOPRINT$$$$ on the first line to suppress printing.  With the parameter "+" (i.e. $$$$NOPRINT$+$$$$) subordinate sections are also not printed.

These elements can be seen in the one used by the Vdub (this) site:

$$INCLUDE$height:300px;font-size:80%;$plain:///_print.html$$

Pragma

Some things just cannot be accomplished without a pragmatic kludge!

The $$$$PRAGMA$$$$ directive allows these to be enabled.

$$$$PRAGMA$MSIE_INCLUDE_PERCENT$<integer>$$$$

MSIE appears incapable of correctly setting the width of $$$$INCLUDE$$$$ and $$$$INSERT$$$$ directives (perhaps it's just me).  This pragma sets the percentage of total page width that these inclusions should occupy.  For the site template used by Vdub this is 80%.  You can see it used in the site template.

Style-Sheet

The style-sheets contain the required Cascading Style Sheet (CSS) markup for the site.  There are two used to style the site.  The first contains all that is used to define VWcms for the current release.  The second is used by the site to define it's own styles and to provide any required customisation of existing VWcms styles.  Some knowlege of CSS is required to customise these!

It is recommended to modify only those in the site CSS!

This is the VWcms style-sheet containing all of the VWcms-specific markup; this is loaded first:

$$INCLUDE$height:200px;font-size:80%;$plain:///_vwcms.css$$

Here is the style-sheet used by the Vdub (this) site, this is loaded second:

$$INCLUDE$height:200px;font-size:80%;$plain:///_site.css$$

The same styles defined in the site sheet override those in the VWcms sheet.

HTML Content

**If you're not sure how you got "back here" when you expected to go on to "the next page" then read Go & Gone To.

The HTML content of the site is managed as a single HTML file and the content modified using an on-line HTML editor, as described in TinyMCE and FCKeditor.

The site is divided into sections according to HTML headings.  An <h1> is a top-level section, <h2> second-level, <h3> third level.  Each of these can be part of a displayed table-of-content (the navigation menu to the left of this page, or TOC).  <h4> generates an in-line heading separating parts of a single section. The heading numbers used as TOC can be changed from the default described above using the [site-depth] configuration directive.  Values of 2 to 5 are allowed.  If set to 4 then <h1>..<h4> are in the TOC and <h5>, <h6> are in-line headings, etc.  Unexpected document structure may be expected when changing this value after site design and composition!

These are substantially managed using VWcms Edit but can be manually added, removed or otherwise manipulated using the HTML or plain text editors (Plain Edit), or even at the command-line.

In fact a suitably organised HTML file could be uploaded from the $$_VWcmsBtn$Resources$$ interface and serve as the basis of the site content.

The HTML is output directly and is used to format the composition of each page.

The substitution directives (e.g. $$$$CONTENT$$$$) insert other HTML (etc.) at that point in the output.

Look and Feel

The look and feel of the content of the site is largely controlled by the associated stylesheet and the consistent structure imposed by the site template(s) on displayed and printed pages.  Under this paradigm the content manager should be more concerned with the content and integrity of the site than with the presentation.

Section Title

By default the $$$$TITLE$$$$ directive displays the section HTML heading.

In the case of this section, "$$TITLE$$" is from the <h3>Section Title</h3>.

A preferred title may be set for any section by placing the $$$$TITLE$title string$$$$ on the first line of that section.

By default $$$$TITLE$$$$ displays the title of the current section.  For both site template and content the directive can display the title of superior sections (e.g. its parent) or arbitrary levels in the section hierarchy.

To display the parent of a section use $$$$TITLE$+1$$$$ ("$$TITLE$+1$$"), the grandparent $$$$TITLE$+2$$$$ ("$$TITLE$+2$$"), etc.

To display an arbitrary title use $$$$TITLE$1$$$$ ("$$TITLE$1$$") for the top-most section, $$$$TITLE$2$$$$ ("$$TITLE$2$$") for the second-level section, etc.

If the requested section does not exist nothing is displayed.

Time

Directives substituting a time string (e.g. $$$$LASTMOD$$$$ and $$$$TIME$$$$) have a default format the same as displayed at the bottom of this page, and can take an optional, dollar-separated parameter, specifying an alternate strftime() format string, or "VMS", "VMS20", "VMS17" and "VMS11" to report times in a VMS format.

$$$$TIME$$$$ $$TIME$$
$$$$TIME$%d %b %Y %H:%M$$$$ $$TIME$%d %b %Y %H:%M$$
$$$$TIME$%A, %e %B %Y$$$$ $$TIME$%A, %e %B %Y$$
$$$$TIME$VMS$$$$ $$TIME$VMS$$
$$$$TIME$VMS20$$$$ $$TIME$VMS20$$ 
$$$$TIME$VMS17$$$$ $$TIME$VMS17$$
$$$$TIME$VMS11$$$$
$$TIME$VMS11$$ 

Go & Gone To

The $$$$GOTO$$$$ and $$$$GONETO$$$$ directives redirect the user to a specified URL.

Both can be used to redirect to other sections of the same site, other VWcms sites, or completely different sites.

The directive must be on the first line of the section.

$$$$GOTO$$$$

A section using $$$$GOTO$$$$ appears in the table-of-content and the site-map.

The next section, Go to Design illustrates this directive's behaviour.  Selected from either the link, or the table-of-content, or the site-map, it will redirect the user to the "Designing The Site" page.

$$$$GOTO$$$$ is particularly useful for building integrated composite sites from multiple VWcms sites.

$$$$GONETO$$$$

A section using $$$$GONETO$$$$ does not appear in the table-of-content or site-map.

It is used permanently to redirect a section which may have external references and which has changed its name or location.

NOTE ...

The next section after "Go to Design", Go & Gone 2 illustrates this directive's behaviour.  It cannot be seen on the site.  To see its behaviour change this section's URL from "Go and Gone To" to "Go & Gone 2" in the browser's location field and be redirected to the WASD site (dependent on Internet availability).  Only in site management edit mode can this section be seen.

If you click the  $$NEXT$$  (next button) from this page you will end up back at HTML Content.

To skip this jump backwards click here and go on to Include & Insert.

Go to building ...

$$GOTO$/vdub/Building_The_Site/HTML_Content$$

$$TEASER$Redirect to the WASD home page, illustrating the $\$GOTO$\$ directive$$

Go & Gone 2

$$GONETO$http://wasd.vsm.com.au/$$

Include & Insert

The $$$$INCLUDE$$$$ and $$$$INSERT$$$$ directives both display content from elsewhere than site HTML content.  That is, a mandatory parameter is the source of what is to be included/inserted.  These are an effective mechanism for including dynamic content from the same or different site.

This is quite a useful facility!

This basic include would place the home page of the site into a scrolling viewport within the current page.

$$$$INCLUDE$/$$$$

Inclusion / Insertion?

The basic difference between including and inserting content, is an inclusion is obvious, with a border and scrollbars as necessary.  With an insertion VWcms places the content in-line to the main content of the page.  It is much less obvious that it has been retrieved from elsewhere.

Parameters

Parameter    Description    Argument
height=   The height of the included content (default is full height).
  Any measurement acceptable to the CSS style height element (i.e. px and %)  Do not include a delimiting ';'.
refresh=   For a web URL refresh (reload) the content every this many seconds.  Due to browser sandboxing only works with a URL from the same host.
  integer
source=   The source of the inclusion.
  Any content described below.
style=   Inline style sheet.
  Any applicable CSS style elements.
width=   The width of the included content (default is full width).
  Any measurement acceptable to the CSS style height element (i.e. px and %)  Do not include a delimiting ';'.

Examples are provided in the next section ...

URL Content

URL content is any web address supported by the browser, such as

http://wasd.vsm.com.au/

and any source not an obvious URL is considered a local web resource

/wasd_root/src/

Note that insertion can only effectively be used for URLs from the same host.  Browser security sandboxing will severely constrain the presentation of URLs from other hosts.  The following will not work well.

$$$$INSERT$http://www.w3c.org/$$$$

Site Content

In addition to the content of the current section others from the VWcms site may be included and inserted into the current page.  This can be done using the $$$$CONTENT$$$$ directive and providing the section name/path as a parameter, or explicitly using the $$$$INSERT$$$$ or $$$$INCLUDE$$$$ directives described in this section. Inclusions of site content cannot be nested.

File Content

Local file-system content may be directly included and inserted into the current page.  Relative (to the site location) and absolute VMS file specifications can be used.  This allows files from anywhere in the file-system to be accessed provided the account executing VWcms has the appropriate read permission.

HTML File Content

The content of a file can be inserted unchanged into the text of a page.  Of course it should contain legitimate HTML (XHTML in fact).  Of course directly inserting HTML can disrupt the formating and layout or even disable the functioning of VWcms.  This example would insert the HTML contained in the file directly into the current page.

$$$$INSERT$height=250px$source=html:///web:[tables]one.html$$$$

Plain-Text File Content

HTML-significant characters can be escaped for presentation.  This effectively displays a file as plain-text. This example would include this site's (VWcms' documentation) template file (which is in fact HTML).

$$$$INCLUDE$height=250px$source=plain:///_site.txt$$$$

Spawned Content

If DCL spawning is enabled the URL scheme spawn:/// will execute a DCL command in the context of the scripting account.  Spawning content is a relatively latent and expensive operation.

Output of the following spawned command must be HTML.

$$$$INCLUDE$spawn:///show time$$$$

The URL scheme splain:/// executes the DCL command and renders the output as plain-text.

$$$$INSERT$splain:///show system$$$$

Spawned content must be enabled by the system administrator on a per-site basis.

Include Examples

$$$$INCLUDE$height=200px$source=/vdub/$$$$

Places a remote (network) URL into a scrolling window on the page.

$$INCLUDE$height=200px$source=/vdub/$$

$$$$INCLUDE$height=200px$source=plain:///_site.html$$$$

Places the content of a local file as plain text into a scrolling window.

$$INCLUDE$height=200px$source=plain:///_site.html$$

$$$$INSERT$width=80%$style=overflow:hidden;$source=/vdub/$$$$

Places a remote (network) URL in-line with the content of the page.

NOTE: This can only be used for URLs from the same host.  Browser security sandboxing will severely constrain the presentation of URLs from other hosts.

$$INSERT$width=80%$style=overflow:hidden;$source=/vdub/$$

$$$$INSERT$width=60em$height=20em$style=overflow:hidden;$source=plain:///_site.html$$$$

Places the content in-line with the content of the page.

$$INSERT$width=60em$height=20em$style=overflow:hidden;$source=plain:///_site.html$$

$$$$INCLUDE$http://www.w3c.org/$$$$

Just another external (hope this system is connected to the Internet) example.

$$INCLUDE$http://www.w3c.org/$$

$$$$INSERT$spawn:///show time$$$$

$$INSERT$spawn:///show time$$

$$$$INCLUDE$width=40em$height=20em$style=padding:1em;$source=splain:///show system$$$$

$$INCLUDE$width=50em$height=20em$style=padding:1em;$source=splain:///show system$$

$$IF$lnm=WASD_ROOT$lnm=WASD_ENABLE_SHOW$$And because this site appears to be empowered by WASD ...

(with the SHOW script enabled)

$$$$INSERT$source=/cgi-bin/show?show=system$refresh=5$$$$

$$INSERT$source=/cgi-bin/show?show=system$refresh=5$$$$ENDIF$$

$$$$INSERT$vwcms:///Building_The_Site/HTML_Content/Time$$$$

$$INSERT$vwcms:///Building_The_Site/HTML_Content/Time$$

$$$$CONTENT$Building_The_Site/HTML_Content/Time$$$$

$$CONTENT$Building_The_Site/HTML_Content/Time$$

$$$$INCLUDE$style=padding:1em;$source=vwcms:///Building_The_Site/HTML_Content/Time$$$$

$$INCLUDE$style=padding:1em;$source=vwcms:///Building_The_Site/HTML_Content/Time$$

Raw HTML

The HTML editor formats and reformats entered text according to its own requirements.  Occasionally this can make the management of some site-specific (HTML) construct frustrating.  The $$$$HTML$$$$ directive takes a parameter and processes it as if raw HTML.  Of course, as it is HTML, the user must supply all required markup, including line-breaks, etc.  Careful!  It should be XHTML.  And there are a multitude of ways to "break" the page!  As with regular HTML, generally white-space may be used as freely as desired.

The following example

$$$$HTML$<table style="border-color:black;border-style:dashed;
border-width:5px; padding:2em; margin-left:2em;">
<tr><td>Cell<br/>One</td><td>
&amp;</td><td> Cell
<p> Two </p><td></tr>
</table>$$$$

is rendered as

$$HTML$<table style="border-color:black;border-style:dashed;
border-width:5px; padding:2em; margin-left:2em;">
<tr><td>Cell<br/>One</td><td>&amp;</td><td> Cell
<p> Two </p><td></tr>
</table>$$

in this case removing the HTML editor's influence on the table layout.

The next example should be self-explanatory.

$$$$HTML$<div style="background-color:yellow;padding:1em;">$$$$

Opening and closing HTML elements may be in separate $$$$$$$$HTML$$$$$$$$ directives with intervening edited content.

$$$$HTML$</div>$$$$

$$HTML$<div style="background-color:yellow;padding:1em;">$$

Opening and closing HTML elements may be in separate $$$$HTML$$$$ directives with intervening edited content.

$$HTML$</div>$$

Hit Counter

The subsitution directive $$$$HIT$$$$ implements a section (page) hit counter.

This page has been accessed $$HIT$$ times since $$HIT$%$$$$TEASER$This page has been accessed lotsa times since it was created!$$

Hit counts are stored separately to content.  By default a file name is generated from the full section name.  The hit count file name can be specified as the first parameter to the directive.  Different sections have individual comment files (but by specifying the same name as parameter one on multiple pages the hit count files can be shared).

In the default case, the example hit counter above is in section

/Building_The_Site/Hit_Counter

and the associated comment file is

[.vdub]_Building_The_Site$Hit_Counter.HIT

Dollar symbols represent section forward-slashes.  The file name is made ODS-2 compliant if required.  It is stored in the site directory.  Renaming of a section requires renaming any associated hit count file.

If the first or second parameter is a percentage symbol (%) the $$$$HIT$$$$ directive provides the date and time when the hit counter was created (i.e. since).  A single percent symbol defaults to the standard VWcms time string (as in the above example).

This page has been accessed $$$$HIT$$$$ times since $$$$HIT$%$$$$

The percent symbol can be the start of a strftime() or other Time format string.

$$$$HIT$%A, %e %B %Y$$$$  would display  $$HIT$%A, %e %B %Y$$

Reader Comment

Reader comment may be solicited and displayed using the $$$$COMMENT$$$$ substitution directive.

JavaScript is required to view and make comments.

When included on a page two buttons are displayed. The first allows any existing comments to be viewed. It can be disabled (greyed-out) if none currently exist. The second allows any reader to compose and submit a new comment. This button may also be disabled if further comment has been closed.

The following displays some example comment and the comment submission dialog (and are moderated).

$$COMMENT$+$email=mark.daniel@wasd.vsm.com.au$name=Reader_Comment$$

As a general rule a comment directive would be placed at the end of a content section (bottom of the page).

Parameters

The comment directive is moderately complex and can take several parameters. All of the button label and dialog strings have reasonable defaults. If any of the parameters are supplied empty they use the associated default.

Parameter Description
! An exclamation point closes further comment.  This disables the $$_VWcmsBtn$Make Comment$$ button and further submissions are ignored.
^ A caret displays the comments when the page is first accessed.  By default the $$_VWcmsBtn$Show Comments$$ button needs to be used.
_ An underscore leading parameter renders the comment text in monospace (fixed) font.
: A full-colon makes comment strings that look like URLs into anchors (and therefore clickable).
@ The at sign results in the reader's host name being displayed both when soliciting and displaying the comment.
% A percentage symbol indicates a format string (see Time) used to format the comment time.
+ A plus sign indicates the comment must be moderated before being available for unobfuscated general viewing (provides optional email notification).
16x80 If the parameter begins with a digit it is used to specify the number of rows and the number of columns in the comment text area.  Rows and columns are separated by a non-digit (non-dollar) character.
email= Notification of comment submission for following email address(es).
fremail= Local string for default commentator email address.
from= Local string for default commentator identification.
hide= Label for the $$_VWcmsBtn$Hide Comments$$ button. 
make= Label for the $$_VWcmsBtn$Make a Comment$$ button.
name= Comment (file) name. When unspecified this is the full section name (including any parent).  Names are modified (see below).
nfp= Local string for "not for publication" notice.
origin= Sets the origin address ("From:") for the VWcms email message.
show= Label for the $$_VWcmsBtn$Show Comments$$ button.
submit= Label for the $$_VWcmsBtn$Submit Comment$$ button.

Each of the buttons can have an icon associated with it.  If one is graphical they all must be.  See Icons for additional information.

Moderation

Reader comments may be moderated before general viewing.  This is accomplished by obfuscating text until moderator approval. The example above includes one such comment.  Comment moderators should be notified by email so that approval (or otherwise) is implemented within a reasonable period.

The following example shows the directive for moderated comments with email notification, intially open for reading, and default button labels.

$$$$COMMENT$^$+$email=mark.daniel@wasd.vsm.com.au$$$$

A moderator must be a site manager.  Moderation is accomplished by logging-in and viewing the comment  section.  When logged-in checkboxes associated with each comment item variously allowing cutting the comment (removing it from view but not actually deleting it), approving the comment (for unobfuscated viewing), or un-cutting the comment (if previously cut).  An additional $$_VWcmsBtn$Moderate$$ button actions any checked items.

Email Notification

As suggested above, comment moderators should be notified by email so that moderation may occur expeditiously.  It is also possible to notify via email when a non-moderated comment is submitted.  Any email address acceptable to site VMS (callable) Mail may be specified.

$$$$COMMENT$email=mark.daniel@wasd.vsm.com.au$$$$

Comment Abuse

Though a notoriously difficult issue to address other than through moderation there are some configurable mechanisms available that attempt to minimise the possibility of comment abuse and DOS.

Comment Files

$$TEASER$Removing individual comments$$Comments are stored separately to content. By default a file name is generated from the full section name and all comments against the directive in that section (i.e. on that page) are stored in that file.  For whatever reason (name length, site preference, etc.) the comment file name can be specified in the comment directive. Different sections have individual comment files but by specifying the same name across multiple sections the comment files can be shared.

In the default case, the example comment directory above is in section

/Building_The_Site/Reader_Comment

and the associated comment file is

[.vdub]_Building_The_Site$Reader_Comment.CMT

Dollar symbols represent section forward-slashes.  It is stored in the site directory.  It is rendered ODS-2 compliant if necessary.  Renaming of a section requires renaming any associated comment file.

Individual comment files can be edited using the facilities of Managing Content and Plain Edit. Do not use an HTML editor.  Beware of "lost updates" (i.e. overwriting comments submitted during an edit).

The maximum size of an individual comment file is determined by configuration directive [comment-max-size] kbytes.

Spam Abuse

Comment/feedback/form submission abuse may be from humans being a nuisance or malicious, or from spambots creating unwanted activity and site pollution.

Although a notoriously difficult issue to address other than through moderation there are some configurable mechanisms available that attempt to minimise the possibility of site abuse and DOS.  All apply to Reader Comment and some to Reader Feedback and to Reader Form.

VWcms, not being a LAMP style application, probably has some immunity due to the relative obscurity of its interface.  However 'bots have had a lot of development time invested in them and are highly sophisticated applications.  There has been at least a couple of instances of probable spambot activity on the VWcms comment interface!  (Though it's difficult to tell human from spambot, and from human-assisted spambot.)

Q and A to Comment

A question and answer challenge attempts to exclude automated spam generation by requiring additional input that would be difficult for a machine to identify as such and produce an acceptable response for.

See Using Q&A.

reCAPTCHA to Comment

A CAPTCHA is a program that can tell whether its user is a human or a computer. You've probably seen them - colorful images with distorted text at the bottom of Web registration forms. CAPTCHAs are used by many websites to prevent abuse from "bots," or automated programs usually written to generate spam.

See Using reCAPTCHA.

Ticket to Comment

A ticket is a unique string, provided by VWcms, which must be included in the comment/feedback text by the user.  When a comment/feedback page contains a $$$$TICKET$$$$ directive VWcms requires the specified ticket in the comment/feedback text or it will be rejected.  This is an attempt to defeat spambot automation.

See Using Tickets.

User Agent

VWcms comment files store the request user-agent string.  These can be examined to determine if a 'bot has some identifying agent string characteristic and excluded from site access using the [reject-agent] and/or [comment-reject-agent] configuration directives.

This site may be of some assistance

http://www.botsvsbrowsers.com/

Text Strings

The comment or feedback (email) text can be examined for specific strings and rejected if present.  There are two variants with this.

[comment-reject-string] This directive accepts strings, one per line.  These strings are literals and may contain white-space.  If they are found in the text the comment/feedback is rejected.
[comment-reject-word] This directive accepts a series of white-space delimitted 'words'.  The comment/feedback text is processed to eliminate all non-alphabetic characters (to reduce obfuscation) and then these words are searched for in the text.  If found the comment/feedback is rejected.

Maximum Comment Size

Configuration directive [comment-max-chars] sets the maximum size of any single comment in bytes.

Maximum File Size

The total comment file size in kilobytes can be set using directive [comment-max-size].  (Reader comment only.)

Minimum Interval

Directive [comment-min-interval] sets the minimum interval in seconds between successive posts from the one host IP address.  (Reader comment only.)

Host Maximum

The maximum number of postings against any individual comment from any single host can be set using the [comment-host-max] directive.  (Reader comment only.)

Using Q&A

A question and answer challenge attempts to exclude automated spam generators by requiring additional input in the form of an answer to a question that is difficult for a machine to recognise as distinct from the other input and that often requires some domain knowledge or other understanding by a human.

VWcms supports Q&A for the three methods of information submission, $$$$COMMENT$$$$, $$$$FEEDBACK$$$$ and $$$$FORM$$$$.  Once configured (see below) all that is required is the inclusion of a $$$$QANDA$$$$ directive on a page prior to the submission form and the Q&A challenge will be added to the submit button.  This then must be completed correctly before the submission is accepted.

The following is a working example of the challenge dialog:

$$QANDA$these=vms$$$$form$action=store=*$$$$form$submit=example$=Submit Q&A Example$$

Configuration

The challenge questions and answers are configured as either a stand-alone file in the site directory or using the [qanda] directive in the VWcms configuration file.  Both contain a list with one question per line where the answers are delimited by an equate symbol; alternate acceptable answers are separated using a vertical bar.  Answer verification is case-insensitive.

The example above is generated using the file [.VDUB]_VMS.LIS with content shown below:

$$INCLUDE$padding:5px;font-size:80%;$plain:///_vms.lis$$

The format is exactly the same when using the VWcms configuration file.  The lines are just prefixed with the [qanda] directive.

To specify the use of a file the directive is

$$$$QANDA$these=VMS$$$$

To specify that the Q&A dialog occurs following the submit button

$$$$QANDA$after=submit$$$$

Using reCAPTCHA

reCAPTCHA is a Google service that helps avoid automated ('bot) spam submission.

A CAPTCHA is a program that can tell whether its user is a human or a computer. You've probably seen them - colorful images with distorted text at the bottom of Web registration forms. CAPTCHAs are used by many websites to prevent abuse from "bots," or automated programs usually written to generate spam. No computer program can read distorted text as well as humans can, so bots cannot navigate sites protected by CAPTCHAs.

http://en.wikipedia.org/wiki/reCAPTCHA
http://www.google.com/recaptcha

VWcms supports the reCAPTCHA service for its three methods of information submission, $$$$COMMENT$$$$, $$$$FEEDBACK$$$$ and $$$$FORM$$$$.  Once configured (see below) all that is required is the inclusion of a $$$$RECAPTCHA$$$$ directive with appropriate parameter(s) on a page prior to the submission form and the reCAPTCHA dialog** will be added to the submit button.  This then must be completed correctly before the submission is accepted.

[IMAGE]

**The default Google reCAPTCHA dialog mid-2011

For example $$$$RECAPTCHA$$$$ and its synonym $$$$RECAPTCHA$before=submit$$$$ on a page adds a reCAPTCHA dialog immediately before the submit button and $$$$RECAPTCHA$after=submit$$$$ adds the dialog immediately after the submit button.

Mailhide

Google also provides the Mailhide service which helps protect published email addresses by asking people to solve a reCAPTCHA before they can access the usable address.

http://www.google.com/recaptcha/mailhide/

The $$$$RECAPTCHA$mailhide=address$$$$ with optional parameter displays a link with an obscured address.

For example (non-functional), $$$$RECAPTCHA$mailhide=mark.daniel@wasd.vsm.com.au$$$$ provides $$HTML$<a href="" onclick="return false">...@wasd.vsm.com.au</a>$$ and $$$$RECPTCHA$mailhide=mark.daniel@wasd.vsm.com.au$display=Mark Daniel$$$$ provides $$HTML$<a href="" onclick="return false">Mark Daniel</a>$$.

Clicking on the link displays a pop-up dialog containing a reCAPTCHA that once solved displays another link with the visible and usable email address.

Configuration

reCAPTCHA requires a Google account and a set of keys.  Details can be found at the Google reCAPTCHA site.

VWcms must be provided with the site's public and private key (non-valid examples shown).

# VWCMS.CONF
[recaptcha-public-key]  6LeoO8JSABAAAMJagCq9KnILgSyjKpjvK6uKbwQx
[recaptcha-private-key] 6LeoO8JSABAAAKmKiD78I3I5fsZ6GRLA5F3Arcmy

Similarly Mailhide must be provided with public and private keys (non-valid examples shown).

# VWCMS.CONF
[recaptcha-mailhide-public-key]  012QFmC7cR9NSsMrNixjVSEA==
[recaptcha-mailhide-private-key] 3a0dc42089ec7c5f625004acb6db5616

reCAPTCHA can have theme and language customisation applied.

http://code.google.com/apis/recaptcha/docs/customization.html

The described options are configued using the [recaptcha-options] directive as in the following example.

# VWCMS.CONF
[recaptcha-options]  theme : 'white'

There are also [lang-recaptcha] messages that can be customised.

Using Tickets

A ticket is a unique, one-off, 15 character string, provided by VWcms, which must be manually copied and pasted by the user.  When a VWcms comment or feedback or form element contains a $$$$TICKET$$$$ directive VWcms requires the specified ticket somewhere in the comment/feedback/form text or it will be rejected.  Once a ticket is issued it remains valid until used (the once) or it expires (one hour).  This is a mechanism intended to help defeat spambots.

This is a ticket: $$TICKET$~$$

If you refresh the page you will notice it change.

It is intended to be cut-and-paste anywhere into the comment/feedback text.  When submitted VWcms searches the text for the ticket and if found accepts the comment/feedback, otherwise rejects it.  It then cuts the ticket from the text before final processing.

The following provides an example uage:

To have a comment accepted, cut-and-paste the highlighted
string into the comment (anywhere will do)!

$$$$TICKET$$$$

$$$$COMMENT$?$4x80$$$$

And is presented to the user as:

To have a comment accepted, cut-and-paste the highlighted string into the comment (anywhere will do)!

$$TICKET$~$$

$$COMMENT$~$?$4x80$$

Reader Feedback

Reader feedback may be solicited using the $$$$FEEDBACK$$$$ substitution directive.

This presents the reader with a dialog containing a text field allowing a return email address to be specified and a text field for feedback composition. The feedback is delivered using email.

Parameter Description
email= Destination email address(es) for the feedback. Any address acceptable to the site VMS system can be used.
from= Default string in the from email address field.
goto= Section (page) to go to after a successful send.
label1= Text to appear to the right of the email address field.
origin= Sets the origin address ("From:") for the email message.
submit= Text (or image) for the send (submit) button.
16x80 If the parameter begins with a digit it is used to specify the number of rows and the number of columns in the comment text area.  Rows and columns are separated by a non-digit (non-dollar) character.

The example Feedback section in this documentation uses

$$$$HIDE$$$$$$$$FEEDBACK$email=mark.daniel@wasd.vsm.com.au$goto=/vdub/Feedback/Thank_you$$$$

to provide the essentials of the feedback dialog.

The Feedback and the subordinate Thank you sections both use a leading $$$$HIDE$$$$ to reduce visiblity.

Email Abuse

Though a difficult issue to address there are some configurable mechanisms available that attempt to minimise the possibility of feedback abuse.

Reader Form

VWcms uses the $$$$FORM$$$$ directive to allow information to be solicited from the reader.

All of the familiar HTML form elements are available.

check box: $$FORM$#check=val_check$value=`one$two$three$$
radio button: $$FORM$#radio=val_radio$value=four$`five$six$$
selection list: $$FORM$#select=val_select$value=seven$eight$`nine$$
text field: $$FORM$#text=val_text$$
text area: $$FORM$#area=val_area$size=3x40$value=... and can include default values$$
submit button: $$FORM$#submit=val_submit$value=Submit VWcms Form$$
reset button: $$FORM$#reset$value=Reset Form Content$$

Submitted form content can be emailed, stored in a site file or post-processed by a site-supplied procedure; in any of plain-text, HTML, XML fragment or raw (POST body) formats.

$$$$FORM$$$$ Parameters

A form must begin with an action specifying an email, spawn or store parameter before subsequent elements may be used.  One form per section is supported.  Form elements may be placed independently within other HTML structure (e.g. tables, new lines, paragraphs) allowing specific form layout on the page.  Form action directives are best placed outside of (in front of) table structures.

Directive Description Parameter(s)
$$$$FORM$action=email=address$$$$ Begins a form and specifies the POSTed result will be emailed. Any email address that can be processed by the VWcms system (i.e. VMS, DECnet or SMTP).
$$$$FORM$action=spawn=name.COM$$$$ Begins a form and specifies the POSTed result will be processed by a procedure external to VWcms. The name of a DCL procedure located withing the site that will process the content.
$$$$FORM$action=store=name$$$$ Begins a form and specifies that the result will be appended to a file within the site. If the name is omitted a file name is derived from the section name.  If a name is specified that is used to generate the file name.
$$$$FORM$text=name$$$$ Displays a text input field (single line text). The optional parameters $size=integer$ can be used to specify the displayed length, and $value=string$ the default value.
$$$$FORM$area=name$$$$ Displays a text-area input field (multi-line text). The optional parameters $size=rows/cols$ can be used to specify the number of rows and columns in the text area, and $value=string$ the default value displayed.
$$$$FORM$check=name$$$$ Displays one or more check boxes. One of more values must be specified using the $value=...$ parameter.  All subsequent parameter are considered values, each separated by a dollar.  An optional parameter $align=vertical$ or $align=horizontal$ aligns the check box list.
$$$$FORM$radio=name$$$$ Displays a group of radio selectors. One of more values must be specified using the $value=...$ parameter.  All subsequent parameter are considered values, each separated by a dollar.  An optional parameter $align=vertical$ or $align=horizontal$ aligns the radio selector list.
$$$$FORM$select=name$$$$ Displays a selector list. One of more values must be specified using the $value=...$ parameter.  All subsequent parameter are considered values, each separated by a dollar.  An optional parameter $size=integer$ specifies the number of items displayed.
$$$$FORM$submit=name$$$$ Displays a submit button. The submit button initiates form processing.  The name of the button is available in form data allowing multiple buttons to be used.  An optional $value=...$ parameter allows the button label to be specified.
$$$$FORM$reset$$$$ Displays a reset button. Restores form content to that at page load.  An optional $value=...$ parameter allows the button label to be specified.
$$$$FORM$goto=section$$$$$ After successful submission goto this section. When a form is successfully submitted redirection to this section is performed.
$$$$FORM$set=label$$$$ Displays a form fieldset. Browser usually places a box around the form fields to aggregate them.  Set is terminated using a $$$$FORM$SET$$$$ or with a new set.
$$$$FORM$insert=parameter$$$$$ Insert some data into the form during submission. This inserts either a literal string into to submitted form data using $$$$FORM$insert="string"$$$$, or the value of a CGI variable using $$$$FORM$insert=variable-name$$$$.

Parameter Example

The form elements illustration displayed at the beginning of this section was created using the following $$$$FORM$$$$ parameters inside a table structure.

check box: $$$$FORM$check=val_check$value=`one$two$three$$$$
radio button: $$$$FORM$radio=val_radio$value=four$`five$six$$$$
selection list: $$$$FORM$select=val_select$value=seven$eight$`nine$$$$
text field: $$$$FORM$text=val_text$$$$
text area: $$$$FORM$area=val_area$size=3x40$value=... and can include default values$$$$
submit button: $$$$FORM$submit=val_submit$value=Submit VWcms Form$$$$
reset button: $$$$FORM$reset$value=Reset Form Content$$$$

Note that default items are checked or selected by prefixing them with a back-tick ( ` ), for example the one, five, and nine items.

A form field, and where applicable individual values, may be disabled by prefixing with an exclamation mark ( ! ).

check box: $$$$FORM$check=val_check$value=`one$!two$three$$$$

$$FORM$#check=val_check$value=`one$!two$three$$
text field: $$$$FORM$!text=val_text$$$$

$$FORM$#!text=val_text$$
submit button: $$$$FORM$!submit=val_submit$value=Submit VWcms Form$$$$

$$FORM$#!submit=val_submit$value=Submit VWcms Form$$

A form field can be made mandatory (see Form Processing) by prefixing with a plus symbol ( + ).

Form Processing

When a form is submitted the associated action with email, spawn or store parameter is processed.

Email

An email address may be specified as a VMS username, a DECnet node and username specification or an Internet Mail (SMTP) address.  The system on which VWcms is running must support the mail protocol used.  The request data is sent as the message body.

$$$$FORM$action=email=mark.daniel@wasd.vsm.com.au$$$$

The origin address ("From:") optionally can be specified using the origin=.. parameter.

$$$$FORM$action=email=mark.daniel@wasd.vsm.com.au$origin=VWcms at WASD$$$$

Spawn

Spawned form processing is specified as a DCL procedure located in the site's directory structure and hence only the procedure name needs to be provided.  Agent processing is reasonably specialised and reference to the FORM.C module is required.

$$$$FORM$action=spawn=example_form_spawn.com$$$$

Store

When a store parameter is processed the form data is appended to a file in the site directory.  This file can be accessed using the VWcms management interface or at the VMS command-line.  There are two variants to this parameter, one with a name and one without.  If a name is not supplied the file storing the form data is determined using the section name containing the form.  For example

$$$$FORM$action=store$$$$

in the section Building_The_Site/Reader_Form/Form_Processing (this one) is named

[.vdub]_Building_The_Site$Reader_Form$Form_Processing.FRM

The file name is made ODS-2 compliant if required.  If a name is specified that is used as the basis

$$$$FORM$action=store=an_example$$$$

and would become

[.vdub]_an_example.FRM

Form Data Format

Form data can be supplied as plain text, HTML, XML fragment or raw (POSTed body).

$$$$FORM$format=text$$$$
$$$$FORM$format=HTML$$$$
$$$$FORM$format=XML$$$$
$$$$FORM$format=raw$$$$

Form Validation

When a VWcms form is submitted certain implicit and explicit validations are performed.  Mandatory form elements (+) submitted must be present and if not the form is rejected.  Radio and check-box selections are compared to values supplied against the corresponding form field names and rejected if not one of those specified.  Text and text-area fields have [comment-reject-word] and [comment-reject-string] constraints applied.

Form Abuse

Though a difficult issue to address there are some configurable mechanisms available that attempt to minimise the possibility of form submission abuse.

Form Example

The following example is also used during bench-testing of VWcms.

$$form$action=store=*$$

Ticket (disabled): $$!TICKET$/!$$ (though is used during testing)
Form action: is to store the form data in a file (though in this case is overridden by the $$$$FORM$test$$$$ - see below)
Data format: $$FORM$format=$select=test_format$value=format=plain$format=HTML$format=XML$format=raw$$
**Text field: $$FORM$+text=a_text$$
Text area: $$FORM$area=an_area$value=This is a test!$$$$FORM$insert=example1$value="*** an inserted literal ***"$$
**Check-box: $$FORM$+check=a_checkbox$value=One$`Two$Three$$
Radio selector: $$FORM$set=set of radio buttons$$$$FORM$radio=a_radio$align=v$value=Four$`Five$<$&$!Six$$$$FORM$set$$
Selection list: $$form$select=select_from$size=3$=this$that$`&$!the$other$$
Submit button: $$FORM$insert=REQUEST_URI$value=cgi=REQUEST_URI$$$$FORM$submit=the_submit$=Example Form$$
Reset button: $$FORM$reset$value=Reset the Form!$$
**required field $$ADVISE$$
  $$FORM$test$$ $$FORM$goto=/vdub/Building_The_Site/Reader_Form/Form_Submitted$$ $$FORM$$

The above form is created using the following elements inside a table structure.  This is a little complicated and stripped of the table structure to make the form elements more obvious.  Each line corresponds to a row in the above table.  Note that some of these directive elements are for form testing purposes but included here for instructional purposes.

$$$$!TICKET$/!$$$$
$$$$FORM$action=email=mark.daniel@wasd.vsm.com.au$$$$
$$$$FORM$select=test_format$value=format=plain$format=HTML$format=XML$format=raw$$$$
$$$$FORM$+text=a_text$$$$
$$$$FORM$area=an_area$value=This is a test!$$$$$$$$FORM$insert=example1$value="*** an inserted literal ***"$$$$
$$$$FORM$+check=a_checkbox$value=One$`Two$Three$$$$
$$$$FORM$set=set of radio buttons$$$$$$$$FORM$radio=a_radio$align=v$value=Four$`Five$<$&$!Six$$$$$$$$FORM$set$$$$
$$$$FORM$select=select_from$size=3$=this$that$`&$!the$other$$$$
$$$$FORM$insert=REQUEST_URI$value=cgi=REQUEST_URI$$$$$$$$FORM$submit=the_submit$=Example Form$$$$
$$$$FORM$reset$value=Reset the Form!$$$$
$$$$ADVISE$$$$
$$$$FORM$test$$$$$$$$FORM$$$$

Form Development and Testing

Form development and testing is aided by some of the constructs demonstrated in the above form.  In particular $$$$FORM$test$$$$ which disables form POSTing and instead displays the generated data.  It must be used following all form elements.

Form Submitted

$$HIDE$$Thank you for submitting the requested information.

Synopsis

A VWcms $$TAG$synopsis$$ is a listing of site sections (pages) showing the title and an extract from the beginning of the section content.

There are four levels of synopsis

1 Lists the entire site (limited by parameters described below).
0 Lists everything at the directive level used. So an <H1> will synopsise all <H1>s. An <H2> will synposise all <H2>s until the next <H1> is encountered. Likewise, an <H3> will synopsise all <H3>s until the next <H2> or <H1> is encountered.
-1 Lists all immediate subordinate levels until the next peer level is encountered. So an <H1> will synposise all <H2> until the next <H1>, a <H2> all <H3>s until the next <H2>, while an <H3> will synopsise nothing.
-2 Will synopsise the subordinate of all immediate subordinates. In other words it only applies to <H1>s. A -2 will list all <H3>s until the next <H1> is encountered.

Parameters

The parameters are specified using the following keywords.

Parameter Description
empty= Optional message if synopsis is empty.
extract= The length of the synopsis (number of characters). Values from 64 to 1023 are allowed.
level= 1, 0, -1, -2 (see above)
list= The maximum number of items in the synopsis.
narrow Collapses the layout of the synopsis/blog listing intended for narrow columns.
order= "+" list is ascending date order (less recent at beginning) and "-" in descending order (more recent at beginning).
read= The text or icon used in the link to the synopsised section.
since= Lists only those section modified since the specified date or specified (negative) number of days, or "*" for all.
text= A formal synopsis (see below). A formal synopsis may contain a maximum of 2048 characters.

Example 1

This example displays a synopsis of the rest of the sections at the same level as this one (second).

$$$$SYNOPSIS$level=0$$$$

$$SYNOPSIS$level=0$$

Example 2

This example displays a synopsis of the subordinate sections of this one, this time with a maximum 512 character extract.

$$$$SYNOPSIS$level=-1$extract=512$$$$

$$SYNOPSIS$level=-1$extract=512$$

Change Synopsis

This example displays a synopsis the five most recently modified sections from the full site.

$$$$SYNOPSIS$level=1$order=-$list=5$since=*$$$$

$$SYNOPSIS$level=1$order=-$list=5$since=*$$

Blog Synopsis

A blog listing is just a special case of site synopsis.  Different defaults but all the synopsis parameters are available to blog listings.

Formal Synopsis

By default a synopsis is performed by extracting the leading text of any section.  It is also possible to provide a formal synopsis that is used when presenting a list of synopses as well as being shown at the top of the section when accessed.

$$$$SYNOPSIS$text=This is an example of a formal synopsis. It is used in the listing as well as presented in the section.$$$$

See Formal Example for how it can be rendered.

Example One

Wikipedia redirects synopsis to:

An abstract is a brief summary of a research article, thesis, review, conference proceeding or any in-depth analysis of a particular subject or discipline, and is often used to help the reader quickly ascertain the paper's purpose. When used, an abstract always appears at the beginning of a manuscript.

Example Two

This is a short example of a subordinate section for synopsis purposes.

Example Three

And Wiktionary describes synopsis as:

Etymology

From Late Latin synopsis, itself from Ancient Greek συνοψις (sunopsis) < συν (sun), with) + ὄψις (opsis), view)

Pronunciation

Noun

synopsis (plural synopses)

  1. A brief summary of the major points of a written work, either as prose or as a table; an abridgment or condensation of a work.
  2. (Orthodoxy) A prayer book for use by the laity of the church.

Synonyms

Formal Example

$$SYNOPSIS$text=This is an example of a formal synopsis. It is used in the listing as well as presented in the section.$$

By default a synopsis is performed by extracting the leading text of any section.  It is also possible to provide a formal synopsis that is used when presenting a list of synopses as well as being shown at the top of the section when accessed.

Blogging

The $$$$BLOG$$$$ substitution directive allows simple weblogs to be supported.

http://en.wikipedia.org/wiki/Blog

The VWcms blog facility should not be thought of as just a mechanism for airing opinions though.  It is much more versatile than that.  It is essentially a set of dated, related topics and so lends itself to "what's new?" style of information, etc.

When a section (page) begins  $$$$BLOG$day month year hour:minute$$$$  it is considered a weblog for that date and time.  The $$$$BLOG$$$$ directive with the current date/time is available from the management interface macro selector and $$_VWcmsBtn$Macro^$$ button. The date/time allows chronological ordering of the weblog entries.

An actual directive looks like

$$$$BLOG$2 March 2009 22:44$$$$

and when seen on the blog entry is rendered

$$BLOG$Monday, 02 March 2009 22:44$$

If the time components are excluded only the date of the entry is displayed

$$BLOG$Monday, 02 March 2009$$

These can be seen in the following blogging examples.

goto=section-name

Normally a blog [read] link will open the blog entry.  Where a blog is being used as a list of short advisory notes (as with the What's New? section) it may be a more useful to open an alternative location.  The $$$$BLOG$$$$ timestamp supports an optional goto parameter that allows just this.

$$$$BLOG$2 March 2009 22:44$goto=Building_The_Site/Blogging/Latest_Blog_Example$$$$

Single-Button Blogging

A blogger can initiate a new blog entry either by opening the site management interface, adding a new section and inserting the required  $$$$BLOG$date$$$$ directive, or on the blog page include a $$$$BLOG$new$$$$ entry which provides a single-button function to do all of the required steps to create the blog entry; the blogger then just completes the text entry and publishes.

This single button blog entry is only visible to a logged-in user capable of editing the site and looks like the following:

$$_VWcmsBtn$New Blog Entry$$ 

A blog topic must be entered.

Most Recent Blog

The most recent blog entry can be displayed as the content of any section using the directive $$$$BLOG$latest=<integer>$$$$ as the first line of the section.  The latest integer parameter performs the same function as level in blog and section synopsis.

For example, to make the home page of a site the most recent blog entry you would have the first line of the first section of the site contain

$$$$NOTOC$$$$$$$$BLOG$latest=1$$$$

The Latest Blog Example illustrates the use of this directive.

List of Recent Entries

The directive $$$$BLOG$list=integer$$$$, where integer is a number up to 99, generates a list of the integer most recent weblog entries. This list is generated from the entire site, even when multiple sets of blogs are maintained under independent parent sections. Each has the blog entry (section) title, the blog date/time, and a plain-text extract from the entry.

Note that these are presented in reverse-chronological order!

The following example shows a maximum of 6 of the most recent entries.

$$$$BLOG$level=-1$list=6$$$$

$$BLOG$level=-1$list=6$$

$$IF$manage$$You are seeing the following single-button blog dialog because you are logged-in and can edit the site!$$ENDIF$$

$$BLOG$new$$

Size of Extract

Values between 64 and 1023 are allowed.

$$$$BLOG$list=6$level=-1$extract=512$$$$

$$BLOG$list=6$level=-1$extract=512$$

Synopsis Special-Case

In fact a blog listing is just a special case of a $$TAG$synopsis$$ listing, with different defaults but with all the same parameters supported.

Read More

A directive  $$$$BLOG$list=6$level=-1$extract=512$read=more$$$$  would change it to [more]

And  $$$$BLOG$list=6$level=-1$extract=512$read=<img src="/_vdub/glasses.png" border="0">$$$$  to

See Icons for additional information.

Example One

$$BLOG$01 March 2009 07:21$$

This is the first example blog entry.

From Wikipedia ...

"A blog (a contraction of the term weblog) is a website, usually maintained by an individual with regular entries of commentary, descriptions of events, or other material such as graphics or video. Entries are commonly displayed in reverse-chronological order. "Blog" can also be used as a verb, meaning to maintain or add content to a blog."

All of the facilities of the WYSIWYG editor is available to the blogger.  In fact all of the VWcms facilities.

$$COMMENT$?$$

(just an example, further comment is ignored)

Example Two

$$BLOG$Monday, 02 March 2009$$

A second blog entry - not much to say.

(Note that this entry shows only a date.)

Example Three

$$BLOG$3 March 2009 20:26$$

A bit more history from Wikipedia ...

"The term "weblog" was coined by Jorn Barger[51] on 17 December 1997. The short form, "blog," was coined by Peter Merholz, who jokingly broke the word weblog into the phrase we blog in the sidebar of his blog Peterme.com in April or May 1999.[52][53][54] Shortly thereafter, Evan Williams at Pyra Labs used "blog" as both a noun and verb ("to blog," meaning "to edit one's weblog or to post to one's weblog") and devised the term "blogger" in connection with Pyra Labs' Blogger product, leading to the popularization of the terms."

Thus endeth the third example.

Latest Blog Example

$$NOTOC$$$$BLOG$latest=1$$

This is an example of a section (page) redirecting to the most recent $$$$BLOG$$$$ entry in the site.

Of course, that entry and this redirect will vary from Vdub release to Vdub release!

$$TEASER$Of course, clicking on this link will take you to the most recent blog entry, not to this section!$$

RSS Feed

"Really Simple Syndication" or "RDF Site Summary" is a means of providing timely and concise summaries of site content specifically for subscribers to that information.

http://en.wikipedia.org/wiki/RSS

The $$$$RSS$$$$ directive allows the equivalent of a $$$$SYNOPSIS$$$$ or $$$$BLOG$$$$ summary to be provided as an RSS feed. "What's New?" uses blog entries and an $$$$RSS$$$$ directive to provide a feed of the latest enhancements to VWcms.  "What's Changed?" provides a list of the more to less recent changes to all sections of the VWcms documentation.

VWcms RSS feeds are identified by a string and so each site can support multiple feeds with differing information contents.

Subscription

Using the $$$$RSS$$$$ directive with the feed and subscribe parameter provides a subscription link.

$$$$RSS$feed=whatsnew$subscribe$$$$

provides the  $$RSS$feed=whatsnew$subscribe$$  subscription link seen in the What's New? section.

The subscribe parameter takes an optional string providing an alternate subscription description or image.

$$$$RSS$feed=another$subscribe=Subscribe to "Another" Feed!$$$$

Feed Parameters

The feed is under the control of the site.  The only parameter provided by the client is the feed name.  If a feed by this name is not found the client receives an appropriate error.  Feed parameters are provided by site content.  An $$$$RSS$$$$ directive on the first line of any section (page) in the site (but obviously better placed in association with the feed content itself) provides those parameters.  It must consist of a leading, identifying feed name, then a feed type (synopsis or blog) and then any relevant parameters available with the $$$$SYNOPSIS$$$$ or $$$$BLOG$$$$ directives.

The What's New? section has an RSS feed specified as

$$$$RSS$feed=whatsnew$type=blog$description=What's new with VWcms!$level=-1$$$$

which provides immediately subordinate blog (dated) entries.

The What's Changed? section has a feed specified as

$$$$RSS$feed=whatschanged$type=synopsis$description=What's changed in the VWcms documentation!$level=1$order=-$since=*$$$$

which provides all sections in the VWcms documentation listed most to least recently modified.

Optional Parameters

The following parameters provide additional information to an RSS feed.

Parameter Description
description= More detail than the title can provide.
editor= Email address of the contact responsible for feed content.
language= Language for the feed (default is "en-us").
title= Short description of the feed.
ttl= Integer representing the number of minutes the feed should be cached before being refreshed.
webmaster= Email address of the techncial contact for the site.

Validate Feed

An additional and optional feature that may be provided is a validate feed link.

$$$$RSS$feed=whatsnew$validate$$$$

generates an  $$RSS$feed=whatsnew$validate$$  link.

The validate parameter takes an optional string providing an alternate description or image.

$$$$RSS$feed=another$validate=Validate "Another" Feed!$$$$

By default the W3C validator is used however an additional parameter

$$$$RSS$feed=whatsnew$validator=http://another.validator.org/this=%s$$$$

can be supplied to specify another service (note the "%s" that includes the feed URL at the appropriate point in the validator URL).

Tagging

A tag in a site or blog is a label that explicitly categorises site content.  These can then be presented allowing a site user to select items of potential interest based on those categories.

A word or short phrase within site content can be $$$$TAG$tagged$$$$ by enclosing it with an inline $$$$TAG$$$$ directive.  In this case the word $$TAG$tagged$$ has become a tag (as that one just has).  Tags should be as short as possible while still being meaningful.  Making tags that are excessively long will make the site-wide tag selection list or cloud cluttered and confusing.  Tagged words or phrases can contain markup (e.g. italics) but not embedded VWcms directives.  Tags are not case sensitive.

An alternative to inline tagging is to add a single $$$$TAG$$$$ directive containing all the terms to be used as tags for that section.

$$$$TAG$with=tags,tagged,categories,cloud,synopsis$$$$

The above directive does not appear in the site content.  Individual terms are comma-separated and white-space is not signficiant.

Tag Synopsis

The synopsis facility is used to list sections containing selected tags.

$$$$SYNOPSIS$tag=1$$$$

Tags are generally presented as a list or as a cloud.  When a tag is clicked on all relevant sections have a synopsis presented.  On this page these will appear here ...

$$SYNOPSIS$tag=1$$

Tag List

A list of the tags used on the current page can be generated using

$$$$TAG$list=$$$$

This will produce a list similar to the following:

$$TAG$list=$$

Tag Cloud

A listing displaying all tags used by a site can be produced using

$$$$TAG$cloud=simple$$$$

This will produce a list similar to the following

$$TAG$cloud=simple$$

Notice the terms will be sized in proportion to the number of instances site-wide.  The default factor is 3 but can be varied up to 5 by using the emphasis modifier, as in

$$$$TAG$cloud=simple;emphasis=5$$$$

Go To Tag

With tag clouds and lists an alternate display page may be specified using the $goto=section$ parameter.

$$$$TAG$cloud=simple$goto=Building_The_Site/Icons$$$$

$$! this commented-out section allows testing of the 'content cloud

$$TAG$with=tags,tagged,categories,cloud,synopsis$$

$$TAG$cloud=content;mincount=15;emphasis=5$$

!$$

Icons

All VWcms substitution directives that produce navigation or other prompts on a rendered page have a textual default.

For example, the navigation directives $$$$PREV$$$$, $$$$NEXT$$$$, $$$$BACK$$$$ and $$$$TOP$$$$ are by default rendered <<PREV, NEXT>>, ^BACK^ and TOP.

Of course, as can be seen from the Vdub (this) documentation, these may also be rendered as the icons (images) $$PREV$$ $$NEXT$$ $$BACK$$ and $$TOP$$.

There are two ways of accomplishing this.

Substitution Directive Parameter

In the content itself, where the directive takes an optional parameter specifying the text to be displayed.  This is a per-directive parameter and so any other instances remain unchanged.  Site-wide specification can be done using configuration directives (see below).

The $$$$PREV$$$$ navigation directive can be rendered  $$PREV$[Previous Page]$$  using  $$$$PREV$[Previous Page]$$$$.

And as the icon  $$PREV$<img src="/_vdub/arrow_left.png" border="0" />$$  using  $$$$PREV$<img src="/_vdub/arrow_left.png" border="0" />$$$$.

Note that the icon specification begins with "<img" and ends with " />".  The "src=" must be specified (somewhat obviously!).  Other image-related and general attributes may also be specified.

Configuration Directive

The site configuration file supports a number of [lang-..] directives. In the same way that these allow non-English language VWcms sites, they also allow the site-wide customisation of the strings associated with various directives.  As with substitution directive parameters while these can just be different strings, they can also specify icon images.

Note that many [lang-..] directives contain more than one string related to a functionality group.  So the previous, next, back and top navigation links are all grouped into the one.  If a language directive is specified all strings required must be specified.

In the Vdub site configuration directive file can be seen the navigation link language directive specifying the icons seen in the documentation.

[lang-navigate] \
<img src="/_vdub/arrow_left.png" border="0" />|\
<img src="/_vdub/arrow_right.png" border="0" />|\
<img src="/_vdub/arrow_down.png" border="0" align="top" />|\
<img src="/_vdub/arrow_up.png" border="0" />

Note the use of the continuation backslash character used to make the text more readable.

The section Non-English Language contains a table showing the default and current configuration file [lang-..] directives.  Note that not all [lang-..] directives support the specification of icons.

Directives Supporting Icons

The following substitution directives support icons.

Subs Directive Description Lang Directive
$$$$BACK$$$$ Navigate to the previous page visited (if any).
[lang-navigate]
$$$$BLOG$$$$
The blog recent entry read link.
[lang-blog]
$$$$COMMENT$$$$
The comment directive has four buttons and a string associated with it.  Each of the four buttons can be associated with an individual icon.  If any is an icon all must be.
[lang-comment]
$$$$LOGIN$$$$ Icons for the login and logout links. [lang-login]
$$$$MANAGE$$$$ Icons for the manage site and view site links. [lang-manage]
$$$$NEXT$$$$
Navigate to the next page (if any).
[lang-navigate]
$$$$PREV$$$$
Navigate to the previous page (if any).
[lang-navigate]
$$$$PRINT$$$$ Three buttons provide for the three levels of print available, current page, current page and any subordinates, and full site. [lang-print]
$$$$SEARCH$$$$
An icon for the search dialog button and an icon for the goto link in the results page.
[lang-search]
$$$$TOP$$$$ Navigate to the top of the page. [lang-navigate]

 

Title Attribute

The HTML title="text" attribute is rendered as a type of tool-tip by most modern browsers and can be used to provide additional information on an iconic (or other) link.  In the following example

<img src="/_vdub/glasses.png" title="Now can you see what happens?" />

is rendered as (place the mouse cursor over the image)

The title attribute is available using the text of substitution or configuration directive.  It is also accessable via the image edit function of the HTML editors.

Conditional Content

The $$$$IF$$$$ directive evaluates the request environment and then conditionally processes (and outputs) content between it and a matching $$$$ELSE$$$$ and/or $$$$ENDIF$$$$.  Conditionals may be nested, and can be used in both the site template and content.  Obviously it is intended to allow tailoring of that content.  One example might be the inclusion of a coversheet with a printed version.

$$$$IF$!print$$$$$$$$HIDE$$$$

Conditionals expressed in the template apply to the template and those in content apply to the currrent section of content only.  There is no global conditional scope.  The conditional above when placed on the first line of the section hides it if not printing.

$$$$IF$login$$$$
$$$$IF$login=mark daniel$$$$
This is some information specifically for MGD!
$$$$ELSE$$$$
General information for logged-in users.
$$$$ENDIF$$$$$$$$ENDIF$$$$

There are no fixed layout requirements for conditionals.  All on a single line or across multiple lines as applicable is fine.  Be aware unexpected white-space may be included in the document (most times to no consequence).

Evaluation

The $$$$IF$$$$ directive should be provided with a parameter.  Without a parameter it evaluates to false.

Parameter Content Description
cgi= name=keyword
If the named CGI variable exists and its value contains the specified keyword (string) then true.  If the CGI variable does not exist or does not contain the keyword then false.  In addition string comparison operators are available for testing CGI variables - see below.
lnm= name=keyword
If the specified logical name exists (case-sensitive) and its value contains the specified keyword (string) then true.  If the logical name does not exist or does not contain the keyword then false.  In addition string comparison operators are available - see below.
login none
If the current request is logged-in.
login= username If currently logged-in and it matches the supplied username.
manage none If currently in site management mode.
manage= "edit" If currently in site management edit mode.
print none If currently printing.
print= scope If currently printing the site ("ALL"), the current page "(PAGE") or the page plus subordinates ("PAGE+").
query= keyword if the query string begins with the specific keyword (e.g. login, tag).
rss none
If currently providing an RSS feed.
rss= feed If currently providing the specified RSS feed name.
search none If currently undertaking a keyword search.
0 none unconditionally false
1 none unconditionally true

A parameter can be prefixed by a "!" to logically negate the result; so "!0" is true and "!print" is false when printing.  Multiple parameters separated by '$' symbols (as is usual with multiple directive parameters), acting as a logical OR.  Hence if any one of mutliple parameters evaluates true then the entire conditional is true.  A parameter may be prefixed by ''&&" to make the result a logical AND with any preceding result.  No nesting of logical operations is supported.

The conditional

$$$$IF$cgi=http_user_agent=Opera$&&print$$$$

would be true only if printing via the Opera browser, whereas

$$$$IF$cgi=http_user_agent=Opera$cgi=http_user_agent=Mozilla$&&!print$$$$

would be true if using either Opera or a Mozilla (family) browser and not printing.

String Evaluation

The following operators provide more granular tests based on string comparison.  All are case-insensitive.

Operator Description Syntax
== Equality
$$$$IF$cgi=WWW_FORM_INDEX==10$$$$
<> or !=
Inequality $$$$IF$cgi=WWW_FORM_INDEX<>10$$$$
< Less than $$$$IF$cgi=WWW_FORM_INDEX<9$$$$
> Greater than $$$$IF$cgi=WWW_FORM_INDEX>11$$$$
<= Less than or equal to $$$$IF$cgi=WWW_FORM_INDEX<=9$$$$
>= Greater than or equal to $$$$IF$cgi=WWW_FORM_INDEX>=11$$$$
= Substring match.  It locates the specified substring in the CGI variable's value. $$$$IF$cgi=WWW_FORM_INDEX<=>11$$$$
^ Regular expression match.
See Regular Expressions.
$$$$IF$cgi=WWW_FORM_INDEX^fred|wilma$$$$

Dynamic Examples

The following examples use conditionals to tailor displayed content.  What you see will vary on browser in-use and other request characteristics.
$$IF$print$$
For example, you won't see this sentence except on the printed page!
$$ELSE$$
For example, you won't see this sentence on a printed page!
$$ENDIF$$

$$$$IF$cgi=http_user_agent=MSIE$$$$ results in $$IF$cgi=http_user_agent=MSIE$$ traditionally a significant standards disability (MSIE) $$ELSE$$ something most probably much more standards compliant (non-MSIE) $$ENDIF$$.  This is based on a user-agent of "$$CGI$http_user_agent$$".

$$$$IF$login$$$$ restricts content $$IF$login$$(or at least selected portions of it)$$ENDIF$$ to those who are currently logged-in.

$$$$IF$lnm=VWCMS_ROOT$$$$ tells us that your system $$IF$lnm=VWCMS_ROOT$$is$$ELSE$$is not$$ENDIF$$ currently using the VWCMS_ROOT logical name.

Reserved Sections

There are three reserved sections and titles.  There is one other similar used during site editing.  These do not appear in the table of content or site-map unless in management mode.

$$$$LOGIN$$$$

This section provides the content required to login.  When login is requested this section is substituted for the $$$$CONTENT$$$$ of the current section.  Although additional site specific information or instruction can be provided the essential HTML form requesting and submitting the login credentials must be preserved.

$$$$RESULT$$$$

When a keyword search has been submitted this section is used to report the result.

$$$$UNKNOWN$$$$

When a section is requested and not found this section is used to report the issue.

$$$$CLIP$section-title$$$$

This section exists after a site edit copies or removes a section.  It can then be re-inserted at another point in the document or subsequently completely removed (deleted) from the edit. Only one such clip can exist at a time; a subsequent copy or remove overwriting any existing clip.

Renaming an existing $$$$CLIP$section-title$$$$ to include an additional identifier, perhaps an obvious number as in $$$$CLIP-1$section-title$$$$, is one method for maintaining multiple concurrent clipped sections.  Renaming back to $$$$CLIP$section-title$$$$ allows that clip to then be reinserted or deleted.

$$$$anything-else$$$$

Any section name beginning with a double-dollar does not appear in the table-of-content unless managing the site.  For example, the section $$$$CHANGES$$$$ could be used to maintain a log of site changes obvious only to the site maintainer.

Installation

VWcms kits may be downloaded from

http://wasd.vsm.com.au/wasd/

or a mirror site.

VWcms installation comprises three main steps.  These are covered in detail in the following sections.

  1. VWcms kit build
  2. HTML editor
  3. Site creation and configuration

VWcms Root

Although not mandatory (VWcms sites may be located anywhere in file-system the server account has access) for convenience of resource mapping it is suggested that all VWcms site directories be located under a single root directory using a concealed logical name.  For example

$ DEFINE /SYSTEM /TRANSLATION=CONCEALED VWCMS_ROOT DKA0:[VWCMS.]

MIME Types

The following file types must be mapped to MIME types by the server:

File Type MIME Type
.CSS text/css
.HTML text/html
.JS text/JavaScript
.XML text/xml

Updating VWcms

An update of VWcms is very similar to an initial installation.  Just ensure that a backup of the site(s) is performed prior to update.   Then install the new kit.   Check the release notes for configuration changes, etc., that might need to be propagated to any existing sites.  Execute the startup procedure (primarily to INSTALL the new executable).

Updating HTML editor

When updating the release of the HTML editor remember that browsers cache Web content and the files comprising this are no different.  Of course a browser should be set to, and should, periodically revalidate its cache content.  However it's highly likely that unless a browser's cache is explicitly purged after an upgrade a mix of old and new components may produce unexpected and undesirable results!  Caution!

Release Notes

This site is currently using:  $$SHOW$VERSION$$

$$INCLUDE$height:30em;$plain:///vwcms_root_vdub:[000000]_release_notes.txt$$

Apache

VWcms is distributed as a ZIP archive.  In this example it is UNZIPped into the Apache tree.

$ SET DEFAULT APACHE$COMMON:[000000]
$ UNZIP <device>:[<directory>]VWCMS<nnn>.ZIP

and the optional object module archive

$ UNZIP <device>:[<directory>]VWCMS<nnn>-<arch>.ZIP

After this the VWcms executable must be compiled and linked

$ SET DEFAULT [.VWCMS]
$ @BUILD_VWCMS

or if the optional object module archive deployed merely linked

$ @BUILD_VWCMS LINK

and the executable placed into the scripting directory.  For an Alpha system this would be

$ COPY [.OBJ_AXP]VWCMS.EXE APACHE$COMMON:[CGI-BIN]

Then the VWcms environment itself needs to be started.  This defines required logicals and INSTALLs the image with required privileges.

$ @VWCMS_STARTUP.COM APACHE

Of course to make this a permanent part of the server environment it will be necessary to include this and other required logical names in system startup procedures.  This and the associated server configuration is described in Site Configuration.

OSU

VWcms is distributed as a ZIP archive.  In this example it is UNZIPped into the OSU tree.

$ SET DEFAULT WWW_ROOT:[000000]
$ UNZIP <device>:[<directory>]VWCMS<nnn>.ZIP

and the optional object module archive

$ UNZIP <device>:[<directory>]VWCMS<nnn>-<arch>.ZIP

After this the VWcms executable must be compiled and linked

$ SET DEFAULT [.VWCMS]
$ @BUILD_VWCMS

or if the optional object module archive deployed merely linked

$ @BUILD_VWCMS LINK

and the executable placed into the scripting directory.  For an Alpha system this would be

$ COPY [.OBJ_AXP]VWCMS.EXE WWW_ROOT:[BIN]

Then the VWcms environment itself needs to be started.  This defines required logicals and INSTALLs the image with required privileges.

$ @VWCMS_STARTUP.COM OSU

Of course to make this a permanent part of the server environment it will be necessary to include this and other required logical names in system startup procedures.  This and the associated server configuration is described in Site Configuration.

CSS Configuration

In WWW_ROOT:[SYSTEM]HTTP_SUFFIXES.CONF the CSS file suffix must be configured:

.NEXT .css text/css 8BIT 1.0

The server must be restarted following this change.

WASD

VWcms is distributed as a ZIP archive and can be UNZIPed onto either an ODS-2 or ODS5 volume.$$TEASER$The only web environment implemented expressly for VMS!$$

$ SET DEFAULT HT_ROOT:[SRC]
$ UNZIP <device>:[<directory>]VWCMS<nnn>.ZIP

and the optional object module archive

$ UNZIP <device>:[<directory>]VWCMS<nnn>-<arch>.ZIP

After this the VWcms executable must be compiled and linked

$ SET DEFAULT [.VWCMS]
$ @BUILD_VWCMS

or if the optional object module archive deployed merely linked

$ @BUILD_VWCMS LINK

and the executable placed into the scripting directory.  For an Alpha this would be

$ COPY [.OBJ_AXP]VWCMS.EXE CGI_EXE:

Then the VWcms environment itself needs to be started.  This defines required logicals and INSTALLs the image with required privileges.

$ @VWCMS_STARTUP.COM

Of course to make this a permanent part of the server environment it will be necessary to include this and other required logical names in system startup procedures.  This and the associated server configuration is described in Site Configuration.

CSS Configuration

In WASD_CONFIG_GLOBAL (WASD v10 or later) or HTTPD$CONFIG (v9.3 or earlier) the CSS file suffix must be configured:

[AddType]
...
.CSS text/css W3C Cascading Style Sheet
...

The server must be restarted following this change.

TinyMCE

TinyMCE is a very capable, open-source, JavaScript-driven HTML editor:

http://tinymce.moxiecode.com/

TinyMCE is copyright © MoxieCode Systems and released under LGPL.

TinyMCE is supported on ODS-2 and ODS-5 volumes (current at v3.5).

The editor must be mapped into server-space.  Which of the following rules and to which part of the physical file-system depends on site requirements.

Apache Configuration

alias /tinymce/ /dka0/tinymce/

OSU Configuration

pass /tinymce/* /dka0/tinymce/*

WASD Configuration

# HTTPD$MAP
pass /tinymce/* /dka0/tinymce/*

TinyMCE Configuration

TinyMCE itself largely can be configured in the [TinyMCE-init] section of the VWcms configuration file.

FCKeditor

FCKeditor can be downloaded from a link available at the home page:

http://www.fckeditor.net

FCKeditor is copyright © 2003 - 2008 Frederico Caldeira Knabben and released under GPL.

The default FCKeditor requires an ODS-5 volume due to the use of multiple periods in file names.  As of version 2.5 and 2.6 it also has embedded BOM sequences (unicode.org/faq/utf_bom.html#BOM) in some files that need to be removed (the utility STRIP_BOM_CR.C in the VWcms source code directory can do this). Of course these issues make it a more difficult package to work with than TinyMCE.

There is also a modified version suitable for immediate use with VWcms (unnecessary functionality removed) on an ODS-2 volume, available from the same download site as the VWcms kit.

The editor must be mapped into server-space.  Which of the following rules and to which part of the physical file-system depends on site requirements.

Apache Configuration

alias /fckeditor/ /dka0/fkceditor260/
#alias /fckeditor/ /dka0/fkceditor260_ods2/

OSU Configuration

pass /fckeditor/* /dka0/fkceditor260/*
#pass /fckeditor/* /dka0/fkceditor260_ods2/*

WASD Configuration

# HTTPD$MAP
pass /fckeditor/* /dka0/fkceditor260/* search=none
#pass /fckeditor/* /dka0/fkceditor260_ods2/* search=none

FCKeditor Configuration

FCKeditor is best tailored for local requirements using a JavaScript configuration script. For VWcms this is located in [.VDUB]_FCKEDITOR.JS and location specified using the VWcms configuration file.

[FCKeditor-init]
oFCKeditor.Config["CustomConfigurationsPath"] = "/_vdub/_fckeditor.js";

Configuration

Most configuration is performed on a per-site basis, with some that is applied globally.

VWcms configuration comprises these activities for each site:

  1. Allocation of a file-system area to contain the site content
  2. Adding the site to the VWCMS_CONFIG configuration file
  3. Adding mapping rules to the web server for this file-system area
  4. Tailoring the VWcms site configuration file
  5. Editing the site content

VWcms supports concurrent multiple sites differentiated by unique file-system locations, using global configuration and web server mapping.  The actual file-system location can be anywhere the server has access.

As suggested in Installation a concealed logical name for locating VWcms sites is the recommended approach.

$ DEFINE /SYSTEM /TRANSLATION=CONCEALED VWCMS_ROOT DKA0:[VWCMS.]

VWCMS$WATCH

The logical name VWCMS$WATCH provides some on-line insight into VWcms configuration and processing.

$ DEFINE /SYSTEM VWCMS$WATCH "*"

If translated to be an IP address it confines the behaviour to clients with that address.

$ DEFINE /SYSTEM VWCMS$WATCH "192.168.1.2"

Website Packages

There are many free and commercial packages providing the essentials of a website.  These are constructed by professional graphic artists and designers and can provide a polished look and feel to a Web presence while saving a significant amount of effort for the site administrator.

A simple Web search, such as for "website template package", can locate many such resources.

It is usually a relatively straight-forward exercise to adapt these templates to VWcms.  Such packages are often available as ZIP archives and contain files representing the site components.  One such example is shown below.

$ unzip -l EXAMPLE.ZIP
Archive:  VWCMS_ROOT:[000000]EXAMPLE.ZIP;1
  Length     Date   Time    Name
 --------    ----   ----    ----
    17107  02-06-11 21:34   license.txt
      306  02-06-11 21:34   images/img01.jpg
     6838  02-06-11 21:34   index.html
     5406  02-06-11 21:34   style.css
 --------                   -------
    29657                   4 files

These components need to be extracted into the area of the file system reserved for the site and then configured to conform to VWcms requirements.  The basic steps required are listed below.  Of course all templates will vary more or less in content and structure and require some thought, and possibly experimentation, to achieve the desired result.  It is recommended to get the basics of the site configured and edited before continuing with the finer detail.

  1. Map the proposed site into the server's web-space.
    # WASD_CONFIG_MAP pass /_example/* /vwcms_root/example/*
    map /example/* /vwcms/example/*
    map=once script+ /vwcms/* /cgi-bin/vwcms/*

    $ HTTPD/DO=MAP
  2. Check the structure of the archive, in particular if it contains a top-level directory.
    $ UNZIP -l <location>:EXAMPLE.ZIP
    
  3. If required, create a directory with protections appropriate to the server and make that the default.
    $ CREATE /DIRECTORY VWCMS_ROOT:[EXAMPLE] /PROT=W:RE $ SET DEFAULT VWCMS_ROOT:[EXAMPLE]
    
  4. Unzip the website package archive (then SET DEFAULT to the package subdirectory if required).
    $ UNZIP <location>:EXAMPLE.ZIP
    
  5. Copy the VWcms starter-kit content file and the style-sheet file from the VWcms kit.
    $ COPY WASD_ROOT:[SRC.VWCMS.STARTER]_INDEX.HTML *
    $ COPY WASD_ROOT:[SRC.VWCMS.STARTER]_VWCMS.CSS * 
  6. Ensure the protections for all files are adequate.
    $ SET PROTECTION=W:RE [...]*.*
    
  7. Generally the template content is in a file named INDEX.HTML.
    This site path should now be able to be accessed and the unmodified package content viewed.
    This also checks the path mapping.
  8. The INDEX.HTML must be made the site template file.
    $ RENAME INDEX.HTML _SITE.HTML 
  9. Map the site into VWcms configuration.
    # VWCMS_CONFIG
    [if-CGI-request_uri] /example/*
    [site-directory] VWCMS_ROOT:[EXAMPLE]
    [site-name] example
    [endif]
  10. Edit the _SITE.HTML template file.
    1. Add VWcms style-sheet link below existing style-sheet link. Modify other links as required.
      <link href="style.css" rel="stylesheet" type="text/css" />
      <link href="_vwcms.css" rel="stylesheet" type="text/css" />
    2. Substitute $$$$CONTENT$$$$ for the template content or in the desired location of the content.
    3. Similarly replace any template table-of-content with $$$$TOC$$$$ or place where desired.
    4. Add $$$$LOGIN$$$$ and $$$$MANAGE$$$$ directives somewhere convenient allowing the site to be edited and managed.
  11. Access the site and work out what you've missed  $$ROTATE$90$$:-)$$ROTATE$$
  12. Using VWcms populate the content of the site
  13. If $$$$PRINT$$$$ is used a template will need to be customised.
    $ COPY WASD_ROOT:[SRC.VWCMS.STARTER]_PRINT.HTML * /PROT=W:RE
    

Fundamental Directives

$$$$CONTENT$$$$  $$$$LOGIN$$$$  $$$$MANAGE$$$$  $$$$TOC$$$$

Common Directives

$$$$AGO$$$$  $$$$BACK$$$$  $$$$$LASTMOD$$$$  $NEXT$$$$  $$$$PREV$$$$  $$$$PRINT$$$$  $$$$TIME$$$$  $$$$TITLE$$$$

Global Configuration

Global Configuration File

The logical name VWCMS_CONFIG locates the system global configuration file.  For example

$ DEFINE /SYSTEM VWCMS_CONFIG VWCMS_ROOT:[000000]VWCMS.CONF

To make this permanent the name would need to be defined during system startup.  Do not have this located within the VWcms application directory tree or it may be lost at the next VWcms update. It is best located in the suggested VWcms sites root.

VWcms configuration occurs in two phases.  The global configuration file is loaded first, then any site configuration file.  By default site configuration files are _VWCMS.CONF located in the VWcms site directory.  Global directives cannot be used in a site configuration file.  Site directives can be used in the global configuration file where they can configure site characterstics globally, or per-site by selective application using conditional configuration.  If required these characteristics can then be overridden by a subsequently loaded site configuration file.  This approach allows the system adminstrator to set VWcms policy for the site in a way that cannot be overridden by VWcms site administrators who can and should be able to set configuration parameters for their own sites.

Conditional Directives

Much of the flexibility in configuring VWcms sites is derived from the conditional application of directives based on specific request characteristics as represented by CGI variables.  Condition testing is done via "*" wildcard match (matches any zero or more characters) or using regular expression matching (prefix the term with a ^ character).  For example, the regular expression

[if-CGI-server_name]  ^\.example\.net|example\.net
[  site-directory]  VWCMS_ROOT:[THE_EXAMPLE]
[  site-name]  example
[endif]

would match a request to any service at example.net and configure it with the enclosed directives.  The equivalent wildcard match 

[if-CGI-server_name]  *.example.net

would match www.example.net and sales.example.net and products.example.net but not example.net.

An equivalent configuration based on request path

[if-CGI-path_info]  /example/*
[  site-directory]  VWCMS_ROOT:[THE_EXAMPLE]
[  site-name]  example
[endif]

Conditionals may be nested and each must be terminated using an [if-end].

The following table describes the available conditional directives.

[if-CGI-variable_name]    This directive takes a single string parameter and matches it to the specific CGI variable name value.  An empty or non-existant variable tests false.  The directive [if-not-CGI-variable_name] tests if it does not match.
[if-LNM-logical_name]   This directive matches the specified logical name value.  The name is searched for using LNM$FILE_DEV.  A non-existant value tests false.  The directive [if-not-LNM-variable_name] tests if it does not match.
[if-site]   Once the site name is established using the [site-name] directive this directive performs a simple match.  The directive [if-not-site] test if it does not match.
[if-end]   All conditional directives must be matched by a closing end of conditional.  [endif] is a synonym.

These conditional directives are also available for site configuration.

Global Directives

These are used to determine overall site charactersictics, especially the location in the file system.  Global directives cannot be used in a site configuration file.  Directives are case-insensitive.

DirectiveDescriptionDefault
[site-config] alternate name and/or location for site configuration file _VWCMS.CONF
[site-content] alternate name and/or location of site content file _INDEX.HTML
[site-directory]
file-system location for site files (mandatory)
none
[site-domain]
if true then derive the site name from the request host domain name (e.g. both www.example.net and example.net would be "example" but sales.example.net would be "sales")
false
[site-name]
the site name is the leading path component (e.g. "vdub") and overrides [site-domain]
none
[site-origin] sets the origin address ("From:") for emails generated and sent by VWcms none
[site-root] if true VWcms is at the root of the site (see Root Site) false
[site-spawn] if true then allow spawned content (see Include & Insert)
false

Site Configuration

Site Directory

Although sites can be located anywhere the web server has access, as suggested in Installation a concealed logical name for locating VWcms sites is the recommended approach.

$ DEFINE /SYSTEM /TRANSLATION=CONCEALED VWCMS_ROOT DKA0:[VWCMS.]

Create an appropriately named site directory

$ CREATE /DIRECTORY VWCMS_ROOT:[THE_EXAMPLE]

ensuring required directory protections are set.

Site Content

There are many sites providing free and commercial packages containing the essentials of a Web site.  These relatively easily can be adapted for VWcms usage.  Following the general directions provided in Website Packages.

The alternative is to construct the site essentially from scratch.  Into the site directory the required seed files need to be copied.  Seed files contain the essential elements of a VWcms site infrastructure and although all can be created manually from scratch this is a quicker route to a basic site.

$ COPY [.STARTER]*.* VWCMS_ROOT:[THE_EXAMPLE]

Mapping Rules 1

The site's URL must be mapped into server space.

Apache
<Location /the_example/>
RewriteEngine  on
RewriteRule  /the_example/(.*)  /cgi-bin/vwcms/the_example/$1
</Location>
OSU map /the_example/* /vwcms/the_example/*
script /vwcms/* /htbin/vwcms/*
WASD map /the_example/* /vwcms/the_example/* map=once
script+ /vwcms/* /cgi-bin/vwcms/*

The script rule for OSU and WASD is only required the once per VWcms.

Mapping Rules 2

VWcms only provides content from the _INDEX.HTML primary content file.  For efficiency all other site resources (CSS, images, graphics, etc.) are provided directly by the Web server.  This requires it to be configured for where to obtain these files.  VWcms uses the site name prefixed by an underscore as the root of the resource path.  Using the above "The Example" site, a graphic resource would be requested using

/_the_example/an_image.png

Therefore for each site a rule must be present that maps this to the file-system location.

Apache alias "/_the_example/" "/vwcms_root/the_example/"
OSU pass /_the_example/* /vwcms_root/the_example/*
WASD pass /_the_example/* /vwcms_root/the_example/*

Of course this is in addition to other required mapping rules.

Configuration Directives

At this point the germinal site may be accessed using a path

/the_example/

Each site can have its own confguration file _VWCMS.CONF located with the other site files and uses specific site directives.

Site configuration can use the same conditional directives described for Global Configuration (but as mentioned, not the same configuration directives).

Site directives are described in Site Directives.

Site Directives

The following table provides all site configuration directives.  Directives are case-insensitive.

DirectiveDescriptionDefault
[archive-verify] setting this to true (1) performs SET VERIFY on archive DCL procedure SET NOVERIFY
[archive-zip] setting this to true (1) creates ZIP archives BACKUP
[comment-host-max] maximum number of comments originating from any one host (see Spam Abuse for these five items) none
[comment-max-size] maximum size of a comment file in kilobytes 64kB
[comment-max-chars] maximum size of any single comment 8kB
[comment-min-interval] minimum number of seconds between consecutive posts originating from any one host none
[comment-reject-agent] (new)line-separated strings found in the user-agent identification none
[comment-reject-string] (new)line-separated strings found in the comment text that reject a post none
[comment-reject-word] space-separated words (strings) found in the comment text that result in the reject of a post none
[downtime] disable the use of VWcms and provide the specified message to users as a simple announcement (see Downtime) none
[FCKeditor-init] JavaScript to initialise and configure FCKeditor  (see FCKeditor) none
[file-type-HTML] file extensions (types) for HTML .htm .html
[file-type-image] file extensions (types) for images/graphics .gif .jpg .jpeg .png
[file-type-text] file extensions (types) for plain text .conf .css .log .txt
[include-file] include a separate configuration file (maximum 2 deep) n/a
[lang-...] a number of directives for language-specific elements (see Non-English Language) compiled-in
[login-acme-doi] ACME Domain of Interpretation (DOI) VMS
[login-acme-no-restrict] ignore any login source restriction associated with the account (e.g. /NONETWORK) provided authentication is OK disabled
[login-alias] map one username into another before authentication (see Authorization) none
[login-credentials] comma-separated list of "user=password" entries as a crude, configuration-controlled authentication mechanism  (see Authorization) none
[login-idle] minutes session remains unused before forced re-login 60
[login-secret] string used as key for RC4 encryption of authentication credentials  (see Authorization) none
[login-source] source of authentication credentials  (see Authorization) none
[login-SSL] credentials (login) are only permitted using a secure (SSL) request disabled
[macro] a substitution directive for use in content (see Substitution) none
[ods] sets the file-naming convention to 2 or 5 site volume structure
[PMDF-kludge] if supplied applies the specified mail transport (e.g. IN%"") to the sender email address (for PMDF quirk) none
[read-only] a message such as "Site is read-only!" prevents VWcms from modifying the site writeable
[recaptcha-options] reCAPTCHA customisation options (see Using reCAPTCHA) none
[recaptcha-private-key] reCAPTCHA private key none
[recaptcha-public-key] reCAPTCHA public key none
[reject-agent] (new)line-separated strings found in the HTTP user-agent that are forbidden (403) to access the site (see Spam Abuse) none
[site-access] comma-separated list of (authenticated) users allowed to access the site  (see Authorization) all
[site-depth] an integer from 2 to 5 indicating how many levels of <Hn> are placed in the table-of-content (careful!) 3
[site-manage] comma-separated list of (authenticated) users allowed to manage the site  (see Authorization) none
[site-print] name of the print file _PRINT.HTML
[site-template] name of the template file _SITE.HTML
[TinyMCE-init] JavaScript to initialise and configured TinyMCE  (see TinyMCE) none
[unknown-302] redirection URL if a section is unknown (used in place of the $$$$UNKNOWN$$$$ section, see Root Site) none

It is also possible to conditionally apply site directives as described in Global Configuration.

Root Site

A root site is one that does not need to use the site name to access its content pages (though of course that will work as well).  It resides at the root of the site's content and supplies all content not explicitly supplied by the web server.  With this configuration it is essential for the web server to explicitly handle all requests other than those expected to be serviced by VWcms.  VWcms becomes the site's default mapping (also see [unknown-302] below).

In the following example the one.example.net site has two paths not handled by VWcms, /download/ and /docs/.  The example shows the global VWcms configuration file for the site and using WASD mapping rules (as described in Site Configuration).

# VWCMS_CONFIG
[if-CGI-server_name]  one.example.net
[site-directory] VWCMS_ROOT:[ONE]
[site-name] one
[site-root] true
[if-end]

The site name is still required because it is used to access site resource (e.g. images, etc.)  These are WASD mapping rules; other platforms will need to extrapolate.

# WASD_CONFIG_MAP (HTTPD$MAP)
pass /docs/* /vwcms_root/docs/*
pass /download/* /vwcms_root/download/*
# VWcms site resources
pass /_* /vwcms_root/one/*
# mapping for root site
map /*
/cgiplus-bin/vwcms/one/* map=once

All non-VWcms resources should be mapped before the site is mapped as the default.  These rules must occur before the rule that activates the VWcms script (which can be anwhere further on in the rules).  The standard rule should looks like

exec+ /cgiplus-bin/* /cgi-bin/*

[unknown-302]

When a section is requested that does not exist the standard VWcms behaviour is to present the $$$$UNKNOWN$$$$ section.  The Vdub site (this) displays a site map in this section.  The [unknown-302] directive allows this behaviour to be changed to redirect to an arbitrary URL.  A parameter beginning with a "/" (slash)

[unknown-302]  /vms/

would redirect to a local URI, while

[unknown-302]  http://www.openvms.org/

to an external site, and a leading "!" (an exclamation point)

[unknown-302]  !http://more.example.com

will insert the URI/URL following the "!" and then append the original request URI and redirect to that.

Using this directive a root site can actually be made to "fall though" to another arbitrary resource or resources.

Composite Site

A composite site is one that spans multiple directories, using shared templates and $$$$GOTO$$$$ to integrate the tables-of-content.

This allows multiple, independent site management domains to provide an effective, tightly-integrated single site.

The following describes such an example.

Primary Site

This site is the primary entry point for the web presence.

Among other content it has two sections, one titled "Sales" containing a $$$$GOTO$/sales/$$$$, and the other "Products" containing $$$$GOTO$/products/$$$$.  Each of these will redirect to the respective mapping.

Secondary Site "Sales"

This site provide a semi-independent collection of sales-related resources.

This and other secondary sites would contain a section titled "Home", or other appropriate term to identify the primary site, containing $$$$GOTO$/$$$$ to redirect to the home page.

A secondary site would generally use the primary configuration to supplement it's own configuration.  This allows a minimum of directives in the secondary with only the primary requiring configuration for integrated site requirements.  Secondary sites locate the primary configuration using the global configuration file.  For this example

# global
[site-directory]  VWCMS_ROOT:[SALES]
[site-config]  VWCMS_ROOT:[ACME]_VWCMS.CONF

Secondary sites use the site and print templates of the primary site.  This is accomplished using the following directives in secondary sites' site configuration files.

# site
[site-template]  VWCMS_ROOT:[ACME]_SITE.HTML
[site-print]  VWCMS_ROOT:[ACME]_PRINT.HTML

Secondary Site "Products"

This site provide another semi-independent collection of resources with the same configuration requirements as the first secondary.

Global Configuration

The following configuration assumes a VWcms root logical of VWCMS_ROOT.

[if-CGI-path_info]  /acme/*
[  site-directory]  VWCMS_ROOT:[ACME]
[if-end]
[if-CGI-path_info]  /sales/*
[  site-directory]  VWCMS_ROOT:[SALES]
[if-end]
[if-CGI-path_info]  /products/*
[  site-directory]  VWCMS_ROOT:[PRODUCTS]
[if-end]

Server Mapping

Of course each secondary site, as with each primary site supported, must have a mapping for the server to locate the respective resources.

For the above example and for the WASD package these would be

pass /_acme/* /vwcms_root/acme/*
map /acme/* /vwcms/acme/*
pass /_sales/* /vwcms_root/sales/*
map /sales/* /vwcms/sales/*
pass /_products/* /vwcms_root/products/*
map /products/* /vwcms/products/*

Site Directories

Although the above example shows the file-system location for the sites as peers there is no reason why a secondary site cannot be located as a subdirectory of the primary site.

Authorization

Authentication is the verification of a user's identity, usually through username/password credentials.

Authorization is the control of a given action based on that identity.

VWcms identifies a user by authenticating with username/password and then who are allowed to manage a site.  It is also possible to use authentication to control who views a site.

Authentication Source

VWcms can verify username/password credentials from these sources.  Only one may be used with any single site.

Secret

To enable authorization an encryption secret must be configured (with the exception of REMOTE_USER).  This is a string of at least 24 characters (the longer the better) containing alphanumerics and punctuation in any order.  The following is an example.

[login-secret]  f589b+j=&5gfjkl*H7Bkd-%ht?m,vZ@1hj]3Asrqm^b

A secret can be changed at any time (and perhaps periodically should be) with the proviso any current authentications will become invalid.

SSL Only

When authentication credentials are supplied in clear-text there is the potential for sniffing.  If the directive [login-SSL] is non-empty authentication is only accepted on a secure (https://) connection.   The directive can either be a message with that information or if https:// will automatically redirect the request to an SSL URL.

[login-SSL]  https://

Login Alias

This allows one username to be mapped to another before authentication.  An example might be using an email address or local mailbox name as the 'username' and mapping that to a VMS username before authenticating against the SYSUAF.

Alias mapping is performed in the configuration file. The format is one alias mapping per line. Mapping is performed using a case-insensitive match.

[login-alias]
Mark.Daniel/DANIEL
Fred.Bloggs/BLOGGS

If a match is not made and no mapping has occurred the default (drop-through) behaviour is to use the original user-supplied 'username' string and so in the above configuration both "Mark.Daniel" and "DANIEL" would authenticate against the DANIEL account, "Fred.Bloggs" and "BLOGGS" against BLOGGS.  Of course any other supplied username could also authenticate directly using the username. To prevent any other than an aliased username being used for authentication conclude the list with "*/-".

[login-alias]
Mark.Daniel/DANIEL
Fred.Bloggs/BLOGGS
*/-

In the above example only "Mark.Daniel" and "Freg.Bloggs" can be supplied to allow authentication.

REMOTE_USER Authentication

This authentication environment uses web server configured authorisation to supply the username.  When this is configured VWcms does not perform it's own authentication and a [login-secret] is not required.  If REMOTE_USER is configured and the web server does not provide authentication VWcms returns an error message.

Web server authorization is usually configured on a per-path basis.  Unless VWcms is configured for site access authorization (see below) a separate path ("site") is required to enable authorized access for site management.  One solution would be to provide general access using standard HTTP (http://) and site management through authorized secure HTTP (SSL, https://). Login aliasing cannot be applied to REMOTE_USER authentication.

Site Management Authorization

By default site management is disabled.  VWcms configuration must explicitly allow site management.  The asterisk parameter permits all who can authenticate against the site to manage the site.

    [site-manage]  * 

To restrict management to a subset of such users use a comma-separated list of such usernames.

    [site-manage]  curly,larry,moe

To explictly exclude one or more usernames from the larger group prefix with an exclamation point followed by a asterisk.

    [site-manage]  !shemp,*

For SYSUAF authenticated usernames site management may be controlled using a rights identifier.  Prefix the identifier name with a percentage symbol.  Multiple user names and rights identifier names may be mixed as required.

    [site-manage]  %stooges3

Site Access Authorization

To restrict site access to authenticated users use an asterisk as in the following example.

    [site-access]  *

To further restrict site access to a subset of authenticated usernames provide then in a comma-separated list.

    [site-access]  curly,larry,moe

To explictly exclude one or more usernames from the larger group prefix with an exclamation point followed by a asterisk.

    [site-access]  !shemp,*

Where site access must be authorised the only content that will be presented without it is from the login page.

As with site management, for SYSUAF authenticated usernames site access may be controlled using a rights identifier.

Mapping Changes for Authorised Site Access

(Not required when using REMOTE_USER authentication.)  With a conventional, open-access site the underlying Web server supplies non-content site resources (e.g. images, downloads, etc.).  When access to a site is limited to logged-in users VWcms itself must supply all resources (in order to control the access).  In this WASD example the previous rule, mapping the /_vdub/ resources into server-space, has been removed (commented-out).  It is replaced with rule that redirects the /_vdub/ path to /vdub/ allowing VWcms to serve the resources.

map /vdub/* /vwcms/vdub/*
#pass /_vdub/* /ht_root/src/vwcms/vdub/*
redirect /_vdub/* /vdub/*
script+ /vwcms/* /cgi-bin/vwcms/*

The VWcms file serving facility is provides only a basic service (no last-modified or other handling) and is not intended for general purpose, only for authorised site access.

When moving a site back and forth between open-access and authorization-access expect some interactions.  Do not flip back-and-forth arbitrarily.

$$TAG$$

Downtime

VWcms can provide a catch-all message configured on a per-system, global configuration or per-site configuration basis.

Defining a system logical name containing an explanatory message disables all VWcms instances on that system and provides the explanatory message to any request to VWcms.

$ DEFINE /SYSTEM VWCMS_DOWNTIME "VWcms will be available again next Monday."

If the global configuration file contains the directive

[downtime]  VWcms will be available again next Monday.

it similarly disables VWcms for all sites, while a site configuration file that contains the same directive disables that site only.

If the logical value or [downtime] begins with a dollar-delimited string then VWcms will treat that as a host name, host name wildcard or regular expression and perform a match against the client host (as represented by CGI variable REMOTE_HOST).  If it does not match then the downtime message is displayed and access denied.  If it matches then VWcms continues to process the request.  This allows the site to be accessed and perhaps worked from an administrator's host while denying general access.

For example

$ DEFINE /SYSTEM VWCMS_DOWNTIME "$192.168.1.*$VWcms will be available again next Monday."

would allow all hosts in the subnet access but deny any other, and

$ DEFINE /SYSTEM VWCMS_DOWNTIME -
"$^one.example.net|two.example.net$VWcms will be available again next Monday."

would allow hosts one and two access but deny any other.

Regular Expressions

Regular expressions (regex) provide a concise and flexible means for matching strings of text, such as particular characters, words, or patterns of characters.  A detailed tutorial on regular expressions is beyond the scope of this section.  It provides only a useful mnemonic for regex within VWcms.  Regular expressions can be used in conditional configuration matching, as well as in the VWcms search facility.  Just prefix the expression with a ^ character.

Description    Usage
match-self operator   ordinary characters, e.g. a b c A B C 1 2 3
match-any-character operator
  . (period)
concatenation operator
  juxtaposition
repetition operators
  * + ? {}
alternation operators
  |
list operators
  [...] [^...]
grouping operators
  (...)
back-reference  operator
  \digit
anchoring operators
  ^ $
backslash operator
  escape a meta-character, e.g. \ ^ . $ | [ (

The following operators are used to match one, or in conjunction with the repetition operators more, characters of the target string. These single and leading characters are reserved meta-characters and must be escaped using a leading backslash ("\") if required as a literal character in the matching pattern.

Expression    Purpose
^
  match the beginning of a line
. (period)
  match any character
$
  match the end of a line
|
  alternation (logical or)
[abc]
  match only a, b or c
l[^abc]
  match anything except a, b c
[a-z0-9]
  match any character in the range a to z or 0 to 9

Repetition operators control the extent, or number, of whatever the matching operators match. These are also reserved meta-characters and must be escaped using a leading backslash if required as a literal character.

Expression    Function
*
  match 0 or more times
+
  match 1 or more times
?
  match 0 or 1 time
{n}
  match exactly n times
{n,}
  match at least n times
{n,m}
  match at least n but not more than m times

Examples

^\.example\.net|example\.net   matches any host name containing the domain example.net
/one/.*|/two/.*
  matches paths beginning with /one/ or with /two/
/[0-9]/.*
  matches numeric paths (bit contrived)

Non-English Language

VWcms is designed with considerable scope for non-English language deployment.

Although the substitution directives all use English-language keywords that's about the total of the dependency.  All of the appropriate keywords allow alternate text to be specified as a parameter providng ad hoc, in place alternatives to the English-language defaults.

The directive  $$$$PREV$<< A la anterior$$$$  produces a  $$PREV$<< A la anterior$$  previous link!

Many of these defaults may also be specified in the configuration file using a set of [lang-..] configuration directives.

The same result as above (but throughout the entire site of course) could be obtained with

[lang-navigate] &lt;&lt;A la anterior|etc.|etc.|etc.

Note that many [lang-..] directives contain more than one string related to a functionality group.  So the previous, next, back and top navigation links are all grouped into the one.  If a language directive is specified all strings required must be specified.

The following table dynamically shows the default (for $$SHOW$VERSION$$) and the current language strings. If the default and current strings are identical (i.e. unchanged) the current is shown as double quotes (""). $$TEASER$Default and current language strings$$

$$SHOW$LANG$$

Note that when editing these in the configuration file long lines can be continued by using the backslash character (\) at the end of the to-be continued line.

Site Map

$$NOPRINT$$

A map of Vdub resources:

$$SITEMAP$$

Feedback

$$HIDE$$Although this is really an example of a feedback section the reader is welcome to use it to comment on VWcms.

Supply an email address if you would like a response!

$$FEEDBACK$email=mark.daniel@wasd.vsm.com.au$goto=/vdub/Feedback/Thank_you$$

Thank you

$$HIDE$$Thank you for your feedback.

If you left an email address we will attempt to respond soon.

$$UNKNOWN$$

$$TITLE$Unknown Section$$

Here is the site map:

$$SITEMAP$$

$$LOGIN$$

This facility is only for authorized use!

 
User: 
Password: 
 

$$RESULT$$

Search results for:   $$RESULT$?$$ 

$$RESULT$$

Note: regular expressions can be used when searching; prefix with a ^ character.