W2ML Specification (Draft)

This version:
11 December 2008 draft
Editors:
Marc Mongenet <marc@mongenet.ch>

W2ML stands for Web 2 Markup Language or Writable Web Markup Language. W2ML is an open dataformat for writable web pages. It is an XML based markup language that extends XHTML™ with content management features, including WYSIWYG edition of page elements. W2ML is server-side processed, and, on the web client side, it uses only open standards like ECMAScript and the DOM™.

Table of content

W2ML in documents

W2ML is an application of XML 1.0. W2ML is designed to be used with XHTML™ in W2ML+XHTML documents, but any XML vocabulary (like MathML, SVG…) may also be used with W2ML. W2ML is designed to extend other markup languages, not to create pure W2ML documents: so no DTD, nor XML Schema, nor Relax NG schema exists for W2ML.

W2ML namespace

W2ML markup (i.e. elements and attributes) is mixed with other XML vocabularies using the XML namespaces mechanism. The W2ML namespace is identified by this URI reference: http://w2ml.org/2005/w2ml. W2ML attributes do not need to be qualified to be recognized as W2ML when they are on W2ML elements.

The examples in this documentation imply the namespace declaration xmlns:w2="http://w2ml.org/2005/w2ml" which means that the w2 prefix is used here to qualify W2ML markup.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:w2="http://w2ml.org/2005/w2ml"
      w2:base="site:///pub/"
      xml:lang="en" lang="en">
 <w2:include src="doc1.w2ml"/>
</html>

MIME type

The MIME type for W2ML documents is application/x-w2ml+xml (x- because the MIME type is unregistred; +xml because W2ML is an XML based media type). Note that this is the MIME type of a W2ML document to be processed. The output produced by processing a W2ML document is not a W2ML document, but generally an (X)HTML document of MIME type configured by the web server.

W2ML processor

HTTP client
HTTP request (X)HTML document
HTTP server
W2ML processor
W2ML+XHTML document

Client-server architecture

An HTTP client, generally a web browser used by a visitor, sends an HTTP request to a W2ML-enabled HTTP server, i.e. an HTTP server that is able to process W2ML documents. On the server, W2ML documents are parsed and processed by a W2ML processor, then the result is serialized to the HTTP client. If the W2ML processor modifies a W2ML document in the process, then it also saves the modified document on the server.

Parsing

W2ML parsing

The W2ML processor can only parse well-formed XML 1.0 documents. It does not recover from well-formedness constraint violations because they are fatal in XML. The processor is not a validating XML processor, but it may log on the server violations of this specification.

Request parameters

All request parameters (in URI query string, in HTTP POST request, and in cookies, in this order) are automatically parsed. If a parameter appears several times (for instance in the URI and in a cookie), then the first parsed parameter takes precedence (so any parameter can be overridden by URI hand-editing). Parameter names beginning with w2ml are reserved.

Processing

Internal DOM's

When the processor parses a W2ML document, it works internally on two DOMs (Document Object Model): the inDOM and the outDOM.

inDOM
It is the input DOM, the only one containing W2ML markup. It is built by parsing W2ML documents, then it is processed to produce the outDOM. The inDOM may be modified by its own markup, in this case it is saved on the server after processing.
outDOM
It is the output DOM. It contains no W2ML markup and typically represents an XHTML document. It is built and modified by markup in the inDOM. It is serialized to the requesting HTTP client.

inDOM processing

All DOM nodes (elements, attributes, entity references, text, CDATA, processing instructions…) except W2ML elements, W2ML attributes, and comments, are automatically copied from the inDOM to the outDOM. It means that if the inDOM comes from a pure XHTML document, then it is automatically copied to the outDOM. Formatting inside tags may not be preserved. Known HTML character entity references may be converted into characters. Characters may be converted to another character encoding.

Inclusion

With inclusion markup it is possible to include several W2ML documents to build the inDOM. When an XML document is included, its parsing builds a subtree of the inDOM. The W2ML processor has a built-in protection against infinite recursive inclusions of the same document.

Locking

The W2ML processor automatically performs the necessary locking of W2ML documents in case of concurrent accesses.

outDOM serialization

After processing, the outDOM is serialized to the HTTP client. Note that parts of the outDOM may be serialized to other destinations during processing; it is achieved using the output element.

The outDOM is serialized in XML, excepted if an HTML DTD is detected (for instance, the public identifier begins with -//W3C//DTD HTML): in this case it is output in SGML. Note that namespace prefixes are dropped in SGML. If an XHTML DTD is detected, then the serialization follows the HTML compatibility guidelines of XHTML.

XHTML serialization example

This well-formed XML document has an XHTML DTD:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html lang="en" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
 <head><title>Test</title></head>
 <body>
  <p><img src="http://example.com/i.gif" alt="example"/></p>
 </body>
</html>

The W2ML processor serializes it in XML syntax (following HTML-compatibility guidelines) to the HTTP client:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html lang="en" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
 <head><title>Test</title></head>
 <body>
  <p><img src="http://example.com/i.gif" alt="example" /></p>
 </body>
</html>
HTML serialization example

This well-formed XML document has an HTML DTD:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
 <head><title>Test</title></head>
 <body>
  <p><img src="http://example.com/i.gif" alt="example"/></p>
 </body>
</html>

The W2ML processor serializes it in SGML syntax (HTML-compatible) to the HTTP client:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
 <head><title>Test</title></head>
 <body>
  <p><img src="http://example.com/i.gif" alt=example></p>
 </body>
</html>

inDOM serialization

If the inDOM was modified by processing, then it is saved on the server. The inDOM is always serialized in XML. If the inDOM includes several documents, then only modified documents are saved.

Error handling

The result of the processing of each W2ML element and attribute is described in this specification. Unknown W2ML elements and attributes are ignored. The content of unknown W2ML elements is processed, except if prevented by its attributes. Recognized W2ML attributes on unknown W2ML elements are processed.

URI schemes

The W2ML processor may support various standard and custom URI schemes to identify resources. URI and relative URI references may be used to identify resources, and URI path resolution rules as described in RFC 3986 are used. To resolve relative URI references, the base URI is deduced from the URI of the document, except if configured otherwise by the base attribute.

Custom site scheme

To identify local resources of the served web site, the W2ML processor implements and uses the site scheme. The root of the website is identified by the site:/// URI.

On a file based HTTP server, the site:/// URI identifies the website root (home page). For instance, http://www.example.com/ is mapped to site:///, and http://www.example.com/file.w2ml is mapped to site:///file.w2ml. It means that a relative site URI references beginning with / starts path resolution from the website root, not the filesystem root. Additionnaly, it is not possible to go above the website root using ../ path components.

The mapping between site URIs and local resources uses the same mechanism than the mapping used to map URI of client requests. This is similar to virtual inclusion with Server Side Includes.

Custom exe scheme

The exe scheme may be implemented by the W2ML processor to include software generated resources. The exe scheme identifies the standard output of an executable run by the W2ML processor. The shell is not used to invoke command nor to parse arg1 arg2 argN.

The working directory of command is the base if it corresponds to a directory (for bases of site and file schemes). Otherwise it is implementation defined (for instance for bases of http scheme). No base is deduced from exe scheme and the inherited is used in documents included with exe scheme.

The scheme format is: exe:command arg1 arg2 argN.
command is searched in the path environment of the processor and executed. arg1 arg2 argN are arguments for command. Inclusion markup provides alternatives means to pass arguments to command. It also provides a way to pass data to the standard input of command.

ExampleDescription
exe:date look for the date command in path and execute it
exe:echo -n hello look for the echo command in the path and execute it with 2 arguments: -n, and hello.
exe:/bin/ls execute /bin/ls
exe:mycmd/myexe look for mycmd/myexe in the working directory and execute it

file scheme

The W2ML processor may implement the file scheme. Unlike the site scheme, the file scheme may identify any file on the filesystem, including files above the site root. For instance if the site root is the /var/WWW/ directory, then the file:///var/ URI identify the directory above the site root.

Other schemes

The W2ML processor may implement other schemes, like http. It may also implement various security policy restricting usable schemes and paths.

W2ML markup

When the W2ML processor processes W2ML markup, it performs the processing specified in this document.

Markup rank

W2ML generic attributes may be processed before or after other attributes, before or after the element itself, and before or after the element content and its children. They can also configure the processing of the element. The content of W2ML elements can be processed before or after the element itself, or not at all. So, the order of processing of W2ML attributes, the element, and its content, is significant.

Note that in XML, and so in W2ML, the order of attributes in start tags is not significant. In this specification, the rank gives the order of processing of attributes and elements. The rank 0 is the rank of processing of element content.

W2ML elements

ElementRankDescription
Generic
g - generic element
Time
year 0 write year
month 0 write month
day 0 write day
ampm 0 write AM or PM
hour 0 write hour
minute 0 write minute
second 0 write second
tz 0 write time zone
time 0 write time
sleep 0 sleep for time duration
Inclusion
include -1 include resource
outclude -1 include resource out of content
backclude -1 include back outcluded content
Output
output -p; 6 select output
Users and groups
user -14 declare or define user
name -14 define name
password -14 define password
group -14 declare or define group
Self-modifying
counter -1 count
del -1 delete itself
res 6 replace itself by its result
once 6 process element once
next 6 process element next time
undo -15; 10 undo modifications
File operations
fdel -1 delete file
fcopy -1 copy file
fren -1 rename file
fsave -1 save as file
Conditional
ok -1 if ok
ko -1 if not ok
Data
v 0 write variable
Markup
a -p attribute of parent

Generic W2ML attributes

Generic W2ML attributes can be added to XHTML and W2ML elements with explicit restrictions for some attributes.

AttributeRankDescription
URI
base -6 configure base URI
Text
tfirst 1 keep or cut first characters
tlast 2 keep or cut last characters
twidth 3 fill text up to width
tfiller -6 configure twidth filler text
timg 4 text to image
timg2 -6 configure timg suffix
Time
tz -6 configure time zone for time elements
timeof -6 configure time source of time elements
Users and groups
login -11 login
ac -10 access control
group -10 group for access control
user -10 user for access control
req -10 request parameter for access control
internal -10 internal variable for access control
match -10 regex for req or internal access control
nmatch -10 regex for req or internal access control
Filtering-9
seli -5 configure selection of ID with filtering
sele -5 configure selection of element with filtering
seles -5 configure selection of elements with filtering
selt -5 configure selection of tags with filtering
sela -5 configure selection of attributes with filtering
reji -5 configure rejection of ID with filtering
reje -5 configure rejection of element with filtering
rejes -5 configure rejection of elements with filtering
rejt -5 configure rejection of tags with filtering
reja -5 configure rejection of attributes with filtering
Self-modification
once -14; 9 process attributes once
next 8 process attributes next time
timesuspe -13 time suspend element
timesuspt -12 time suspend tag
Edition-2
ed -2; 6 editor
edrun -6 configure editor running mode
onedconflict -6 configure editor resource for conflicts
Template-3
template -15; 5; 10 template declaration
instance -15; 5 template instance declaration
new -3; 7 declare template destination
del -3; 7 declare deletable element
from -3; 6; 7 point to template source
to -3; 6; 7 point to template destination
Debugging
log -6 configure log level

Configuration attributes

Some W2ML attributes change the configuration, i.e. a processing setting. The configuration is inherited by attributes of a higher rank, by the element, and by the content of the element, i.e. its child elements and their attributes. The configuration may be modified again by child elements. A configuration is reverted to its old value when the element processing is completed; i.e. after its content and all its attributes have been processed. When no configuration can be inherited, a default configuration is used.

Generic element

ElementDescriptionExample
g The generic element.

This element performs no processing by itself. It is mostly useful with generic W2ML attributes.

W2ML in
Hello <w2:g>world</w2:g>!
HTML out
Hello world!
in client
Hello world!

URI markup

Generic URI attributes

AttributeDescriptionExample
base="URI"
rank="-6"
default=""
configure URI as the base to resolve relative URI references.

Configuring the base with this attribute overrides base deduction from document URI, notably in case of inclusion.

The URI must be absolute. An empty attribute value means that the base is deduced from the document URI.

W2ML in
 <div w2:base="site:///test/">
  ...
 </div>

Text markup

Generic text attributes

Generic text attributes modify the outDOM. They modify the text produced by the processing of their element and its content. If their element and its content processing produced elements, then the structure of elements is not modified: only the text between elements is modified. The timg attribute also replaces text by new elements.

AttributeDescriptionExample
tfirst="I"
rank=1
Keep or delete the first |I| characters of outDOM.

I is an integer number.

If I is not negative, then only the first I characters are kept. If I is negative, then the first -I characters are deleted (no character deleted for tfirst="-0").

W2ML in
<w2:g tfirst="3">12345</w2:g>
<w2:g tfirst="-3">12345</w2:g>
HTML out
123
45
in client
123 45
tlast="I"
rank=2
Keep or delete the last |I| characters of outDOM.

I is an integer number.

If I is not negative, then only the last I characters are kept. If I is negative, then the last -I characters are deleted (no character deleted for tlast="-0").

W2ML in
<em w2:tlast="3">12345</em>
<em w2:tlast="-3">12345</em>
HTML out
<em>345</em>
<em>12</em>
in client
345 12
twidth="I"
rank=3
Fill outDOM text so that its width is I.

I is an integer number.

The string configured by tfiller is repeated until the number of characters in the outDOM text is |I|. If I is positive, then the text is filled at its beginning, otherwise at its end. If |I| is smaller or equal to the number of characters already present, then nothing is done.

W2ML in
<w2:g tfiller="x"
      twidth="5">123</w2:g>
<w2:g tfiller="ab"
      twidth="-6">123</w2:g>
<w2:g tfiller="x"
      twidth="-2">123</w2:g>
HTML out
xx123
123aba
123
in client
xx123 123aba 123
tfiller="S"
rank=-6
default=" "
Configure filler string for twidth.

S must be a non-empty string of characters.

This attribute configures S as the filler string used by the twidth attribute. The default filler string is a single non-breaking space.

timg="URI"
rank=4
Transform text to image: each character, except blanks, is replaced by an image.

URI is a base URI.

URI gives the base location of image resources (typically a directory containing PNG or GIF files), each resource containing a glyph. Resources must be named after the Unicode code point of the character in uppercase hexadecimal digits, prefixed with 0 if necessary to be four digits long: 0041 for 'A', 00E9 for 'é', 20AC for '€'… A suffix can be configured with the timg2 attribute.

It should be noted that the URI is not used by the W2ML processor. The URI is copied as is in the outDOM, concatenated with the code point and the suffix, to give the resource location to the HTTP client. Typically, it is implemented with the HTML img element, and the URI goes into the src attribute.

W2ML in
<w2:g timg="fonts/"
      timg2=".png">Hi !</w2:g>
HTML out
<img alt="H" src="fonts/0048.png"
><img alt="i" src="fonts/0069.png"
> <img alt="!" src="fonts/0021.png"
>
in client
Hi !
timg2="S"
rank=-6
default=""
Configure suffix of timg.

S is the end of an URI.

The default suffix is empty.

Time markup

Generic time attributes

Generic time attributes configure time elements processing.

AttributeDescriptionExample
tz="zone"
rank=-6
default="local"
Configure time zone.

Supported zone values:

  • local: local time zone of the processor;
  • utc, UTC, gmt or GMT: universal time (UTC, also known as GMT).
W2ML in
<w2:g tz="utc">
 <w2:hour/>:<w2:minute/>
</w2:g>
HTML out
 3:15
in client
3:15
timeof="source"
rank=-6
default="request"
Configure time source.

Supported source values:

  • request: time at request reception;
  • modification: last modification time, i.e. resource modification time of last modified resource included and processed in the inDOM, or request time if the inDOM has been modified by processing;
  • doc modification: last modification time of the document containing this attribute, or request time if the document has been modified by processing;
  • clock: time when the timeof attribute is processed, using a high-resolution clock if available.
W2ML in
<w2:g timeof="modification">
 Last modified:
 <w2:hour/>:<w2:minute/>.
</w2:g>
HTML out
 Last modified:
 13:4.
in client
Last modified: 13:4.

Time elements

Time elements write time in the outDOM.

ElementDescriptionExample
year
empty
Write year in the outDOM. W2ML in
<w2:year/>
HTML out
2005
in client
2005
month
empty
Write month in the outDOM. W2ML in
<w2:month/>
HTML out
3
in client
3
AttributeDescription
fmt="format"
default="digit"
Supported format values:
  • digit: Months go from 1 to 12.
  • abbr: Months go from Jan to Dec (locale dependent).
  • name: Months go from January to December (locale dependent).
day
empty
Write day in the outDOM. W2ML in
<w2:day fmt="abbr"/>
HTML out
Sun
in client
Sun
AttributeDescription
fmt="format"
default="digit"
Supported format values:
  • digit: Days go from 1 to 31.
  • abbr: Days go from Sun to Sat (locale dependent).
  • name: Days go from Sunday to Saturday (locale dependent).
ampm
empty
Write morning or afternoon symbol (locale dependent) in the outDOM. W2ML in
<w2:ampm/>
HTML out
AM
in client
AM
hour
empty
Write hour in the outDOM. W2ML in
<w2:hour/>
<w2:hour fmt="12"/>
HTML out
13
1
in client
13 1
AttributeDescription
fmt="format"
default="24"
Supported format values:
  • 24: Hours go from 0 to 23.
  • 12: Hours go from 1 to 12.
minute
empty
Write minute (0 to 59) in the outDOM. W2ML in
<w2:minute/>
HTML out
3
in client
3
second
empty
Write second (0 to 59) in the outDOM. W2ML in
<w2:second/>
HTML out
3
in client
3
tz
empty
Write time zone in the outDOM. W2ML in
<w2:tz/>
<w2:tz fmt="num"/>
HTML out
CET
+0100
in client
CET +0100
AttributeDescription
fmt="format"
default="abbr"
Supported format values:
  • abbr: Output time zone name or abbreviation.
  • num: Output time zone as hour offset from GMT.
time
empty
Write time in the outDOM. W2ML in
<w2:time/><br/>
<w2:time fmt="rfc822"/>
HTML out
Wed Jan 31 01:33:06 2007<br />
Wed, 31 Jan 2007 01:33:06 +0100
in client
Wed Jan 31 01:33:06 2007
Wed, 31 Jan 2007 01:33:06 +0100
AttributeDescription
fmt="format"
default="local"
Supported format values:
  • local: Output date and time in local format (locale dependent).
  • rfc822: Output time in an RFC 822 compliant format (as amended by RFC 1123).
sleep Sleep.

Sleep duration is given by the concatenation of element's text nodes. The duration format is a natural number followed by the u (microsecond), s (second), m (minute), h (hour) or d (day) letter.

W2ML in
<w2:sleep>3</w2:sleep>
HTML out

in client

Inclusion markup

Inclusion markup includes resources. If the resource type is W2ML, then it is parsed to build a subtree of the inDOM, and processed. Configuration is inherited by subtrees. If the subtree is modified, then it is saved in the included resource.

Inclusion elements

ElementDescriptionExample
include Include resource.

If inclusion fails, then the content of the include element is processed as fallback, otherwise it is not processed. Recursive inclusion and processing of the same resource fails.

If the URI scheme supports parameters, (for instance the exe scheme) then if include has got output child elements directing to arg or stdin, then output child elements are processed before inclusion. See exe scheme examples.

W2ML in
…bla.
<w2:include src="doc.w2ml">
 Inclusion failed
</w2:include>
Bla…
doc.w2ml
<w2:g xmlns:w2=
 "http://w2ml.org/2005/w2ml">
 <em>Included document.</em>
</w2:g>
HTML out
…bla.
 <em>Included document.</em>
Bla…
in client
…bla. Included document. Bla…
AttributeDescription
src="URI"
required
Source of inclusion.

URI is the URI of the resource to include. If the URI is empty, then the document includes itself (which is a forbidden recursive inclusion if it is included as W2ML).

type="type"
default= "application/­x-w2ml+xml"
Type of included resource.

Supported type values:

  • application/x-w2ml+xml: The included resource is parsed and processed as a W2ML document;
  • text/plain: The included resource is not parsed; it is used as text data.
outclude Include resource out of content.

The content of outclude is not immediately processed: the backclude element must be used in the included document (or a document included by the included document) to process it. It means that the content of outclude is normally processed as if it were the content of a backclude element in an included document. So, an outclude/backclude pair of elements includes a document "out of" or "around" the content of outclude.

A document included by outclude can itself use outclude. It works as if each outclude pushes its content on a stack and each backclude looks for content to process deeper in the stack.

Recursive inclusion of the same resource fails.

If the URI scheme supports parameters, then, if they are output child elements directing to arg or stdin, they are processed before inclusion.

inDOM
…bla.
<w2:outclude
 src="border.w2ml">
 <em>Outcluded</em> content.
</w2:outclude>
Bla…
border.w2ml
<p style="border:1ex ridge"
 xmlns:w2=
  "http://w2ml.org/2005/w2ml">
 <w2:backclude/>
</p>
HTML out
…bla.
<p style="border:1ex ridge">
 <em>Outcluded</em> content.
</p>
Bla…
in client
…bla.

Outcluded content.

Bla…
AttributeDescription
src="URI"
required
Source of inclusion.

URI is the URI of the resource to include.

backclude Include back content of outclude.

The content of the nearest outclude element ancestor that is not already included by an ancestor backclude is included and processed.

The content of the backclude element is processed when there is no content to include back, otherwise it is ignored.

Note that the recursive inclusion prohibition makes recursive backclusion impossible. But it is possible to use several sibling backclude elements in the same document, and they all include and process the content of the same outclude element.

exe scheme examples

Example with all parameters in the exe scheme:

W2ML in
Here is the content of the directory:
<pre>
<w2:include src="exe:ls -l" type="text/plain"/>
</pre>
HTML out
Here is the content of the directory:
<pre>
-rw-rw----  1 user www-data   3084 Aug 14 03:49 index.w2ml
-rw-rw----  1 user www-data   1290 Apr 30  2006 ex.w2ml
</pre>
in client
Here is the content of the directory:
-rw-rw----  1 user www-data   3084 Aug 14 03:49 index.w2ml
-rw-rw----  1 user www-data   1290 Apr 30  2006 ex.w2ml

The same result can be achieved by using separate parameters:

W2ML in
Here is the content of the directory:
<pre>
<w2:include src="exe:ls" type="text/plain"/>
<w2:output to="arg">-l</w2:output>
</pre>

Output markup

The outDOM may be serialized to other destinations than the HTTP client.

Output elements

ElementDescriptionExample
output Select outDOM output destination.
AttributeDescription
to="dest" Output to unique destination.

Supported dest values:

  • new: Output to new resource (new file). Require dst attribute.
  • append: Output to end of resource. Require dst attribute.
  • null: no output;
  • stdin: Output to standard input of exe resource. To be used no more than once, only as a child of an element including a resource with the exe scheme.
  • arg: Output to argument of exe resource. To be used only as a child of an element including a resource with the exe scheme. For each output to arg a new argument is added to the argument vector of the exe resource.

When the output is finished, the part of the outDOM that has been output is removed from the outDOM.

W2ML in
<w2:output to="new"
           dst="log">
 Text to new log file
</w2:output>
HTML out
 Text to new log file
output to log file
Text to new log file
in client
add="dest" Add output destination.

Supported output dest values are the same as for the to attribute.

W2ML in
<w2:output add="new"
           dst="log">
	   fmt="html">
Text to new<br/>log file
</w2:output>
HTML out
Text to new<br />log file
output to log file
Text to new<br>log file
in client
Text to new
log file
dst="URI" URI of output destination.

This attribute may only be used for output destinations requiring an URI.

The use of href instead of dst is deprecated.

fmt="format"
default=""
Output format.

Supported format values:

  • "": Output in XHTML or HTML syntax depending on outDOM output rules.
  • "xhtml": Output tags in XHTML-compatible syntax.
  • "html": Output tags in HTML-compatible syntax.
  • "text": Output text only.

Users and groups

When a W2ML document is processed, the visitor is always automatically given a (default) name by the W2ML processor. Through login, the visitor may be given another (default) name. Users and groups markup defines users (with a user name and password) and groups. A user can be in one or several groups, and a group can be in other groups. Edition, deletion, execution and other rights can be given or withdrawn to user and group names on a per element basis.

Login request parameters

Login request parameters are supported to provide a way for visitors to log in or out. When the request processing begins, the following request parameters are automatically parsed and used by the processor:

NameMeaning
w2mlusr user name
w2mlpwd user password
w2mllog logout if value is out, otherwise ignored

Predefined users

The request parameters are used by the processor to perform an automatic login when the request processing starts. For the automatic login, only hardcoded predefined users are used. During document processing, login can be redone with users and groups defined in a W2ML document by the login attribute. It is possible to add predefined users to defined groups.

Predefined users
User namew2mllog parameter w2mlusr parameter w2mlpwd parameter Name given to…
w2mllogout out any any logged out visitors
w2mlanon - none any anonymous visitors
w2mlwrong - illegal any visitors using a predefined user name with w2mlusr
w2mlnolog - present any unauthentified visitors (who may be given another name by the login attribute)
w2mlunknown - unknown any visitors with unknown name (set by the login attribute)
w2mlnopwd - known wrong visitors with wrong password (set by the login attribute)
user - known correct visitors with correct name and password (set by the login attribute for successful login)

Generic users and groups attributes

AttributeDescriptionExample
login="URI"
rank=-11
Load users and groups definitions and perform visitor login.

This attribute includes the W2ML document identified by URI and processes only users and groups elements, ignoring all other markup. Notably, generic attributes on users and groups elements are not processed. If URI is empty, then login includes its own document.

Login works like configuration: it is valid in the element and is inherited by its content, which can overrride it with other login attributes.

Once users and groups definitions are processed, login checks values of the w2mllog, w2mlusr and w2mlpwd request parameters. If a user is defined with the same user name and password, the visitor is given this user name, and the w2mlusr and w2mlpwd parameters are automatically saved in a cookie to provide them automatically to other documents of the site. If login fails, then the visitor is given a predefined user name. The user name, predefined or not, may be in one or several groups.

<html w2:login="passwd.w2ml">
…
</html>

Users and groups elements

When not included by a login attribute, these elements have no effect, like the g element. So a document with users and groups elements can be viewed and edited without defining users and groups. When included by a login attribute, users and groups elements are processed and define users and groups. Each user and group may only be defined once.

It should be noted that these elements may be freely interspersed with other elements. For instance XHTML table elements may be used to provide a more manageable layout.

Users and groups elements
ElementDescriptionExample
user Define or only declare a user.

If it contains a name element, then it declares and defines a user, otherwise it only declares the user which name is equal to the concatenation of its inDOM text.

If this element has a name element, then it may also contains a password element. Otherwise, it may not.

If this element is in, or contains, a group element, then the user is added to the group. A user element should not contain another user element.

<w2:user>
 <w2:name>Joe</w2:name>
 <w2:password>123</w2:password>
</w2:user>

<w2:group>
 <w2:name>admin</w2:name>
 <w2:user>Joe</w2:user>
</w2:group>

<w2:user>
 <w2:name>Tom</w2:name>
 <w2:group>admin</w2:group>
</w2:user>

name Contain a user or group name.

The inDOM text of this element is concatenated to a user or group name.

This element should not be out of user and group elements.

password Contain a user password.

The inDOM text of this element is concatenated to the user password. If this element is not present, then the user can log in without password.

This element should not be out of user element.

group Define or only declare a group.

If it contains a name element, then it declares and defines a group, otherwise it only declares the group which name is the concatenation of its inDOM text.

A group element may contain other group and user elements, but only after its name element. It means that the user or group is added to the currently defined group.

Note: a group can not contain itself, even indirectly, because it would either require a declaration of the group before it is fully defined, or require a group redefinition.

Access control markup

Access control is divided in execution right, deletetion right, new instantiation right, and edition right. Each right may be denied by an element, and given back by a child element.

AttributeDescriptionExample
ac="(±)c…"
rank=-10
Access control.

(±)c… is a string of letters. The same letter should not appear several times in (±)c…. Each letter may be prefixed with the plus or minus character, or no character.

The next prefix characters are supported:

  • none: set access, i.e. the access is given if the condition is met, otherwise it is suppressed;
  • +: add access, i.e. the access is given if the condition is met;
  • -: suppress access, i.e. the access is suppressed if the condition is met.

The next letters are supported:

  • x: access to execute: without this access no result is produced; note that login attributes and attributes with a smaller or equal rank to ac are still executed;
  • d: access to delete;
  • n: access to create new instances;
  • e: access to edit.

This attribute must be used with exactly one of the group, user, req, or internal attribute on the same element.

<w2:g ac="x" user="Joe 2">
 execute access only for Joe 2
</w2:g>
<w2:g ac="d+e-n" group="admins">
 give delete access only to admins,
 give edit access to admins,
 suppress instance access for admins
</w2:g>
group="group"
rank=-10
ac condition is met if the visitor is member of the group.
user="user"
rank=-10
ac condition is met if the visitor is user.
req="parameter"
rank=-10
ac condition is met:
  • without match or attribute nmatch: if the parameter is defined;
  • otherwise: if parameter value matches the regex.
internal="variable"
rank=-10
ac condition is met:
  • without match or attribute nmatch: if variable is defined;
  • otherwise: if variable value match the regex.
match="regex"
rank=-10
regex is a Perl-compatible regular expression.

ac condition is met if the parameter/variable is defined and matches regex; for multivalues, one match is enough.

nmatch="regex"
rank=-10
regex is a Perl-compatible regular expression.

ac condition is met if the parameter/variable is undefined or does not match regex; for multivalues, no match is allowed.

Filtering markup

Filtering markup disables the processing of selected or rejected markup. The filtering occurs with a rank of -9, i.e. before processing of configuration attributes. It means that filtering occurs only on the content of the element with the filtering configuration attribute, not on the element tag. Filtering processing occurs after time suspension, login and access control processing.

Generic filtering attributes

AttributeDescription
seli="IDs"
rank=-5
Selects IDs.

IDs is a spaces separated list of element IDs.

Only the first identified descendant element is processed. Filtering does not apply to process the element content.

sele="elements"
rank=-5
Select element.

elements is a spaces separated list of (namespace prefixed) element names.

Only the first descendant element matching a listed element is processed. Filtering does not apply to process the element content.

seles="elements"
rank=-5
Select elements.

elements is a spaces separated list of (namespace prefixed) element names.

Only descendant elements matching listed elements are processed. Filtering does not apply to process the content of elements.

selt="elements"
rank=-5
Select tags.

elements is a spaces separated list of (namespace prefixed) element names.

Non-listed descendant element tags are not processed, except acces control attributes. In effect, it removes some tags and keeps text nodes.

sela="attrs"
rank=-5
Select attributes.

attrs is a spaces separated list of (namespace prefixed) attribute names.

Only listed generic and non-W2ML attributes of descendant elements are processed. In effect, it disables some attributes.

reji="IDs"
rank=-5
Reject ID.

IDs is a spaces separated list of element IDs.

Only the first identified descendant element of a listed ID is not processed.

reje="elements"
rank=-5
Reject element.

elements is a spaces separated list of (namespace prefixed) element names.

Only the first descendant element matching a listed element is not processed.

rejes="elements"
rank=-5
Reject elements.

elements is a spaces separated list of (namespace prefixed) element names.

Descendant elements matching listed elements are not processed.

rejt="elements"
rank=-5
Reject tags.

elements is a spaces separated list of (namespace prefixed) element names.

Descendant element tags matching listed elements are not processed. Their non-listed children and text nodes are processed.

reja="attrs"
rank=-5
Reject attributes.

attrs is a spaces separated list of (namespace prefixed) attribute names.

Listed attributes of descendant elements are not processed.

The seli, sele, seles, reji, reje, and rejes attributes may not be used together on the same element. The selt and rejt attributes may not be used together on the same element. The sela and reja attributes may not be used together on the same element.

The selt and rejt attributes do not apply on non-processed elements. The sela and reja attributes do not apply on non-processed tags.

Self-modifying markup

Processing of self-modifying markup modifies the inDOM.

Generic self-modification attributes

AttributeDescription
once="attrs-list"
rank=-7; 9
Process attributes once.

attrs-list is a well-formed list of attributes.

The attrs-list is parsed and its attributes are added to the element (rank=-7), processed, then removed from the element (rank=9). The once attribute is also removed.

XML namespace attributes are not supported.

next="attrs-list"
rank=8
Process attributes next time.

attrs-list is a well-formed list of attributes.

Parse the attrs-list as an attributes list. Remove the next attribute. Add or update parsed attributes to the element.

timesuspe="susp-time"
rank=-13
Suspend processing for some time. For timesuspe, the processing of the element and its content is disabled. For timesuspt, only the processing of the tag is disabled, not the processing of its content.

susp-time is either a timestamp in RFC 822 format, or a duration the same format than the sleep element. When the value is a duration, then the request time is added to the duration and the result is saved in the inDOM as a timestamp. The processing is disabled if the timestamp is not in the past. The attribute is destroyed when the timestamp is for the first time in the past.

Note: timesuspe on an element disables its processing until the timestamp is in the past. timesuspt on a once element destroys the element when the timestamp is in the past, ie the time acts like an expire delay. timesuspt on an element with access control attributes allows an element to introduce new accesses when a timestamp is in the past.


timesuspt="susp-time"
rank=-12

Self-modifying elements

ElementDescriptionExample
counter
rank=-1
Count.

This element increments its inDOM content, then write it to the outDOM. The element must be empty or its content must be text and represent an integer number. If the element is empty, then the counter starts with value 0.

W2ML in
<w2:counter>7</w2:counter>
HTML out
8
W2ML out
<w2:counter>8</w2:counter>
del
rank=-1
Delete itself.

The del element removes itself (and its content) from the inDOM.

W2ML in
<w2:del>bla</w2:del>
HTML out

W2ML out

res
rank=6
Replace itself with the result of its processing.

This element copies the outDOM to the inDOM.

W2ML in
<w2:res>
 <w2:counter>7</w2:counter>
</w2:res>
HTML out
8
W2ML out
8
once
rank=6
Process this element only once.

This element removes itself (and its content) from the inDOM after having been processed.

W2ML in
<w2:once>
 <w2:counter>7</w2:counter>
</w2:once>
HTML out
8
W2ML out

next
rank=6
Do not process this element until next time.

This element removes its tags from the inDOM after having been processed. Its content is not processed. Of course, it will be processed next time.

W2ML in
<w2:next>
 <w2:counter>7</w2:counter>
</w2:next>
HTML out

W2ML out
 <w2:counter>7</w2:counter>
undo
rank=-15; 10
Undo content modifications.

Undo any modification made in its inDOM content during processing. Modifications made in included content are not undone.

W2ML in
<w2:undo>
 <w2:counter>7</w2:counter>
</w2:undo>
HTML out
8
W2ML out
<w2:undo>
 <w2:counter>7</w2:counter>
</w2:undo>

File operations markup

File operations markup creates, deletes, renames resources (files) on the server.

File operations elements

File operations elements have two mutually exclusive methods to identify resources:

  1. With an URI in a single attribute value; this is the value of the src attribute for source, and of the dst attribute for destination. It is unsafe to use visitor supplied values.
  2. An URI divided in two parts: the path part and the filename part. The path part may be a base URI, an abolute path, or a relative path. In the filename part, reserved characters and characters used as path components are encoded to avoid directory traversal. It is safe to use visitor supplied values for the filename part, but not for the path part. This method uses the srcpath and srcfile attributes for source, and dstpath and dstfile attributes for destination.
ElementDescriptionExample
fdel Delete file (or more generally a resource).

Operation success can be tested by child conditional elements.

W2ML in
<w2:fdel dst="foo.w2ml"/>
HTML out

in client
AttributeDescription
dst="URI" URI of the resource to delete.
dstpath="URI" Path part of the resource to delete.
dstfile="name" File name part of the resource to delete.
fcopy Copy file (or more generally a resource).

Operation success can be tested by child conditional elements.

W2ML in
<w2:fcopy src="foo" dstpath="bar/">
<w2:a n="dstfile"
 ><w2:v req="fname"/></w2:a>
</w2:fcopy>

HTML out

in client
AttributeDescription
src="URI" URI of the resource to copy.
srcpath="URI" Path part of the resource to copy.
srcfile="name" File name part of the resource to copy.
dst="URI" URI of the resource copy.
dstpath="URI" Path part of the resource copy.
dstfile="name" File name part of the resource copy.
fren Rename file (or more generally a resource).

Operation success can be tested by child conditional elements.

W2ML in
<w2:fren src="foo" dst="bar"/>
HTML out

in client
AttributeDescription
src="URI" URI of the resource to rename.
srcpath="URI" Path part of the resource to rename.
srcfile="name" File name part of the resource to rename.
dst="URI" URI of the renamed resource.
dstpath="URI" Path part of the renamed resource.
dstfile="name" File name part of the renamed resource.
fsave Save uploaded file.

Operation success can be tested by child conditional elements.

W2ML in
<w2:fsave src="foo" dst="bar"/>
HTML out

in client
AttributeDescription
src="name" Request variable name of the uploaded file.
dst="URI" URI of the saved resource.
dstpath="URI" Path part of the saved resource.
dstfile="name" File name part of the saved resource.

Conditional markup

Conditional elements

ok Process if result is ok.

This element processes its content if the processing of its nearest fallible ancestor was unsuccessful. The following elements may be unsuccessful: fdel, fcopy, fren, and fsave.

W2ML in
<w2:fdel src="foo">
 file
 <w2:ok>successfully</w2:ok>
 <w2:ko>not</w2:ko>
 copied.
</w2:fdel>
HTML out (successful)
 file
 successfully
 copied.
in client
file successfully copied.
ko Process if result is not ok.

This element processes its content if the processing of its nearest conditional ancestor was unsuccessful. The following elements may be unsuccessful: fdel, fcopy, fren, and fsave.

Edition markup

Edition attributes let elements be edited by visitors. They are two types of edition: edition of element content, and template edition. On the HTML output side, the W2ML processor automatically outputs markup and scripts implementing an online in-browser editor for each editable element. When an edition is submitted, the processor checks (for well-formedness, against injections and concurrent editions) and saves it. It may also self-modify the inDOM, possibly with reserved W2ML markup, even when not saving.

Edition of element content is conceptually the simplest: the content of the element is editable. Edition may be disabled with the e access control letter.

Template edition involves creation or deletion of predefined elements. It is possible to create an element with editable children, thus providing structured edition.

Generic edition attributes

AttributeDescriptionExample
ed="editor"
rank=-2; 6
Editable element.

Supported editor values:

  • "" or "none": No editor.
  • Element editors (may be disabled by the e access control letter):
    • "text": Text level editor. Submitted data is saved in a text node.
    • "wysiwyg": In-browser WYSIWYG editor. Submitted data may only contain stylistic and semantic XHTML markup.
    • "html": HTML source level editor.
  • Templates editors:
    • "new": Create new template instance.

      See to attribute, from and new attributes to identify the template and its instance destination.

      It may be disabled with the n access control letter.

      Suggested UI to start edition in the browser: onclick attribute.

    • "del": Delete element.

      The to attribute must be used to identify the element to delete.

      It may be disabled with the d access control letter.

      Suggested UI to start edition in the browser: onclick attribute.

The ed attribute should not be used on W2ML elements.

W2ML in
<p w2:ed="text">bla</p>
HTML out

W2ML processor and editor specific.

in client

bla

edrun="method"
rank=-6
default=""
Configure running method of editor.

Supported method values:

  • "": Editor dependant.
  • "auto": Automatically activate editors on load.
onedconflict="URI"
rank=-6
default=""
Configure the resource to outclude in case of edition conflict.

URI is an URI.

The edited element can be backcluded, but editing is automatically disabled to avoid an infinite recursive conflict.

Templates

Templates provides structured edition. Templates are elements in the inDOM with an instance or template attribute. A template instance is created by duplicating a template. The UI to instantiate a template is provided by the ed="new" attribute/value. The template is referred by the from attribute. The template instance destination, i.e. where the instance is saved in the document, is identified by the new attribute, and referred by the to attribute.

During template instantiation, the configuration (and notably the access control) of the destination, is used. Care should be taken to have a consistent configuration for the template element and the destination element; otherwise, instantiation in the visitor UI will not be consistant with the result, when actual access control is enforced.

If a template contains editable elements, then they may be edited on instantiation. If the template itself contains new, del or to attributes, then they are automatically given new random ids. In case of concurrent instantiations by several HTTP clients, instances are simply saved in the order they are submitted. It is possible to submit several instances in the same request, and notably to instantiate several instances from the same template.

Template attributes

AttributeDescription
instance="id"
rank=-15; 5
Template declaration.

id is an identifier. Two templates should not share the same id.

This attribute declares a template that can be referred by the from attribute. This attribute should only be used on non-W2ML elements.

W2ML in
p template, button editor, and div destination.
<p w2:template="tpl">
 The template.
</p>

<button w2:ed="new"
        w2:to="tdest">
new
</button>

<div w2:new="tdest"
     w2:from="tpl"
     w2:to="lastChild">
...
</div>
W2ML in
p template, button editor and destination.
<p w2:template="tpl">
 The template.
</p>

<button
  w2:ed="new"
  w2:from="tpl"
  w2:to="nextSibling">
 new
</button>
W2ML in
p deletable, button editor.
<p w2:del="me">
 A paragraph.
</p>

<button w2:ed="del"
        w2:to="me">
 new
</button>
template="id"
rank=-15; 5; 10
Frozen template declaration.

id is an identifier. Two templates should not share the same id.

This attribute acts like the undo element and the instance attribute and edrun="auto" attributes. The template attribute provides a frozen template where modifications are undone. It is a classic template in the sense that is it cannot be changed. Its typical use is in an undisplayed XHTML division, so the uninstantiated template remains hidden for the visitor.

Unlike instance, template is not duplicated to the instantiated element. It means that modifications take effect when the template is instantiated.

If present on the same element than the instance attribute, then it takes precedence.

new="id"
rank=-3; 7
Template instance destination.

id is an identifier.

This attribute identifies destinations of the new editor. It is also added by the ed attribute on its element with a random value when the to attribute value is relative and no new attribute is present.

del="id"
rank=-3; 7
Deletable element.

id is an identifier.

This attribute identifies deletable elements, i.e. destinations of the del editor.

from="idref"
rank=-3; 6; 7
Referred template.

id is an identifier.

This attribute is required by the new editor to identify the template source. The from attribute must be present on the destination element, i.e. the element with ed="new" when the to attribute value is relative, or the element identified by to when the to attribute value is absolute.

to="dest"
rank=-3; 6; 7
Refer to template instance or deletion destination.

This attribute is required by the new and del editors.

The dest value can be a relative or absolute destination. An absolute destination is a reference to a new or del attribute identifier. A relative destination is one of the following dest values:

  • firstChild: first child of the element.
  • lastChild: last child of the element.
  • previousSibling: previous sibling of the element.
  • here: the element.
  • nextSibling: next sibling of the element.
  • lastSibling: last sibling of the element.

For ed="new", it gives the template instantiation destination. If it is relative, then the destination is relative to the current element. If it is absolute, then it identifies a destination element with a new attribute that must have another to attribute with a relative destination.

For ed="del", the to attribute destination must always be absolute.

Data markup

Data elements

ElementDescriptionExample
v
empty
Write variable value(s) to outDOM.

A variable is a GET or POST HTTP request parameter, or a cookie, or an internal variables of the W2ML processor.

When a variable is multi-valued, each value is written in a span element, and elements are separated with a whitespace.

AttributeDescription
req="name" Write value of request parameter or cookie named name. W2ML in
You are <w2:v req="age"/>.
HTML out
You are 21.
in client
You are 21.
internal="name" Write value of internal variable name.

Supported internal variable name values:

  • "uri": URI of the processed W2ML document
  • "parent uri", "parent parent uri"...: URIs of W2ML documents including the processed W2ML document
  • "request method": the HTTP request method
  • "request host": the HTTP request host (from Host header or full URI)
  • "request uri": the HTTP request URI
  • "request body": the HTTP request body
  • "request content-type": the HTTP request Content-Type
  • "request variables": parsed request parameters
  • "all users": list of all defined users
  • "all groups": list of all defined groups
  • "user": user name of visitor
  • "groups": group names of visitor
  • "user ip": visitor IP address
  • "server ip": server IP address
  • "processor name": name of the W2ML processor; "interpreter name" is deprecated
  • "processor version": version the processor; "interpreter version" is deprecated
  • "processor build": build ID the processor; "interpreter build" is deprecated
  • "processor full name": name, version and build of the W2ML processor; "interpreter full build" is deprecated
  • "copyright": copyright
  • "running time": running time of the software in seconds
W2ML in
Hello
<w2:v internal="user"/>
of IP
<w2:v internal="user ip"/>.
HTML out
Hello
Joe
of IP
192.168.1.3.
in client
Hello Joe of groups male guest.

Markup markup

Markup elements

ElementDescriptionExample
a Attribute for parent.

The a element is processed by the file operations elements. It must be the first children of one of these elements. The outDOM of the a element is used as value of the attribute n of the parent element.

W2ML in
<w2:fcopy src="tpl.w2ml">
 <w2:a n="dst"><w2:v req="newPage"/></w2:a>
</w2:fcopy>
AttributeDescription
n="name"
required
Attribute name.

Debugging markup

Generic debugging attributes

AttributeDescription
log="level"
rank=-6
default=""
Log events on the server.

Supported level values:

  • "": Reset to the default level.
  • "emergency": Log when the system is unusable.
  • "alert": Log errors that may cause emergency.
  • "critical": Log errors that may affect several requests.
  • "error": Log unrecovered errors that may cause unexpected behaviour.
  • "warning": Log unexpected but recovered errors.
  • "notice": Log interesting events.
  • "information": Log information not normally interesting in logs.
  • "debug": Log debugging informations.

The level values are inspired from the Apache HTTP Server LogLevel directive.

Events of the selected level and more critical levels are logged. The default level is taken from the server configuration.

Logging destination depends on the W2ML processor implementation. For instance, the HTTP server log files may be used.

External references


© 2003-2007, Marc Mongenet.