W2ML markup examples

Table of content

Formatting conventions

Complete document with W2ML

XHTML+W2ML → XHTML

Here is a complete XHTML document with W2ML markup. It displays Hello, world, an horizontal separation, then the GMT time:

<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:w2="http://w2ml.org/2005/w2ml"
      lang="en" xml:lang="en">
 <head><title>XHTML+W2ML hello world example</title></head>
 <body>
  <p>Hello, world.</p>
  <hr/>
  <p w2:tz="GMT">
   It is <w2:hour/>:<w2:minute tfiller="0" w2:twidth="2"/> GMT.
  </p>
 </body>
</html>

If you view the source of the resulting XHTML document with your browser, you can notice that the W2ML processor emits tags for empty elements like <hr /> that are closed with a space in front of the / character, according with the HTML Compatibility Guidelines of the W3C XHTML 1.0 Recommandation. You can also notice that the result contains no W2ML markup.

XHTML+W2ML → HTML

When the W2ML processor finds an HTML DTD in a document, it outputs the document in HTML instead of XHTML.
Note that the XHTML+W2ML document on the server must still be well-formed XML.

<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
          "http://www.w3.org/TR/html4/strict.dtd">
<html xmlns:w2="http://w2ml.org/2005/w2ml" lang="en">
 <head><title>W2ML and HTML example</title></head>
 <body>
  <p>Hello, world.</p>
  <hr/>
  <p w2:tz="GMT">
   It is <w2:hour/>:<w2:minute tfiller="0" w2:twidth="2"/> GMT.
  </p>
 </body>
</html>

If you view the source of the resulting HTML document with your browser, you can notice how an attribute value like lang=en is unquoted, and the empty element tag <hr> is not closed. This is valid HTML.

W2ML namespace

XML namespaces must be used to add W2ML markup to XHTML documents. Generally, the XHTML namespace is the default namespace and the W2ML namespace declaration gives a namespace prefix for W2ML markup (the w2 prefix in the examples of this document).
The next example is a typical namespace declaration on the html opening tag:

<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:w2="http://w2ml.org/2005/w2ml">

W2ML elements are prefixed with the declared W2ML namespace prefix:

<p>It is <w2:hour/> o'clock.</p>

W2ML attributes on XHTML elements are also prefixed, but the prefix is optional for W2ML attributes on W2ML elements:

<p w2:tz="GMT">
 It is <w2:hour/>:<w2:minute tfiller="0" w2:twidth="2"/> GMT.
</p>

Self-modification

Self-modifying W2ML markup modifies itself in the XHTML+W2ML source file.

Counter

The counter W2ML element is a simple page counter, incremented every time it is processed. Any integer value can be given to start counting from; the incremented value is displayed:

Source before processing:

<w2:counter>123468860</w2:counter> <w2:counter>-123444718</w2:counter>

Processing result:

123468861 -123444717

Source after processing:

<w2:counter>123468861</w2:counter> <w2:counter>-123444717</w2:counter>

Undo modifications

The undo W2ML element reverts modifications of its content. It is mostly useful for demonstration purpose. Here a counter is reverted, so it always stays at its initial value:

<w2:undo><w2:counter/></w2:undo>
1

Note: this counter is an empty counter element, meaning that it counts from 0, and displays 1 after having been incremented. The undo element reverts the incremented counter back to its initial empty state. The undo element only reverts the XHTML+W2ML source, it does not revert the value that was output by the counter.

Execute once

The once W2ML element and attribute delete themselves after having been processed; it means that their content is only processed once and then is erased. The once element and attribute are mostly useful in template instantiations.

On first use:

<em w2:once="style=&quot;color:red&quot;">hello</em>
<w2:once>world</w2:once>
hello world

After first use:

<em>hello</em>
hello

Execute next time

The next W2ML element and attribute ignore their content on first use and delete themselves without deleting their content. It means that only the content remains and will be processed the next time. The next element and attribute are mostly useful in template instantiations.

On first use:

<em w2:next="style=&quot;color:red&quot;">hello</em>
<w2:next>world</w2:next>
hello

After first use:

<em style="color:red">hello</em>
world
hello world

Replace by result

The res element replaces itself by its result, i.e. by what it has displayed. It is mostly useful in template instantiations.

Before first use:

<w2:res><w2:counter>1</w2:counter></w2:res>
2

After first use:

2
2

Generic element

The g W2ML element is a generic container; it does nothing by itself:

<w2:g>Hello world!</w2:g>
Hello world!

The g element is mostly useful when used with W2ML attributes, like text manipulation attributes:

<w2:g tlast="6">Hello world!</w2:g>
world!

Text manipulation

Text manipulation attributes modify the output of their element.

<w2:g tfirst="4">Hello world!</w2:g>
Hell
<w2:g tfirst="-4">Hello world!</w2:g>
o world!
<w2:g tlast="4">Hello world!</w2:g>
rld!
<w2:g tlast="-4">Hello world!</w2:g>
Hello wo

Note that if the tfiller W2ML attribute is not present, then it is inherited from a parent element. If no parent has a tfiller attribute, then the default value is " ".

<tt w2:twidth="79" w2:tfiller="_.:*~*:.">Hello world!</tt>
_.:*~*:._.:*~*:._.:*~*:._.:*~*:._.:*~*:._.:*~*:._.:*~*:._.:*~*:._.:Hello world!
<tt w2:twidth="-79" w2:tfiller="_.:*~*:.">Hello world!</tt>
Hello world!_.:*~*:._.:*~*:._.:*~*:._.:*~*:._.:*~*:._.:*~*:._.:*~*:._.:*~*:._.:

Every printable character of the text nodes of an element can be displayed by an image using img XHTML elements. The timg W2ML attribute gives the first part of the img src URI where the browser should get the images. The URI is built by concatenating the timg attribute value, NNNN and the (inherited) timg2 attribute value. NNNN is the 4 digits Unicode character code point in uppercase hexadecimal notation, left-padded with 0.

In the next example, 'H' is replaced by <img src="/fonts/glowhot/0048.png" alt="H">, 'o' by <img src="/fonts/glowhot/006F.png" alt="o">… Space characters are left as is by the timg attribute.

<w2:g timg="/fonts/glowhot/" timg2=".png">Hello world!</w2:g>
Hello world!

When an element has several W2ML text manipulation attributes, they are applied in the following order: tfirst, tlast, twidth, timg. The tfiller and timg2 attributes only provide inheritable configuration to respectively twidth and timg attributes. Their default values are respectively " " and "".

<w2:g tfirst="-6" tlast="-1" twidth="-8" tfiller="."
     timg="/fonts/glowhot/" timg2=".png">Hello world!</w2:g>
world...

W2ML text manipulation attributes can be used to alter the output of their element. For instance, here is a counter displayed with a bitmap font:

Before:

<w2:counter timg="/fonts/glowhot/" timg2=".png">12165</w2:counter>
12166

After:

<w2:counter timg="/fonts/glowhot/" timg2=".png">12166</w2:counter>

Text manipulation attributes also work with children elements:

<em w2:tfirst="10">Link to <a href="/">home</a>.</em>
Link to ho

Inclusion

The include W2ML element performs a server-side document inclusion; the root element of the included document is processed as the only child of the include element. The original content of the include element is ignored, excepted if the inclusion fails, in which case it is used as an alternate content (this is inspired by the object XHTML element).

In this example, include is used twice to include two documents: example2.w2ml and noexample.w2ml. The noexample.w2ml document does not exist, so include element content is processed instead.

<!-- including document -->
<w2:include src="example2.w2ml">inclusion 1 failed</w2:include>,
<w2:include src="noexample.w2ml">inclusion 2 failed</w2:include>.
<!-- example2.w2ml -->
<g xmlns="http://w2ml.org/2005/w2ml">Hello</g>
Hello, inclusion 2 failed.

It is also possible to include documents as raw text:

<w2:include src="example2.w2ml" type="text/plain"/>
<!-- example2.w2ml --> <g xmlns="http://w2ml.org/2005/w2ml">Hello</g>

Outclusion

With the outclude and backclude W2ML elements, it is possible to include a document around the content of outclude. The content of the outclude element is kept on a stack and can later be included back by backclude.

In this example, we include example3.w2ml around the "hello world" text, putting the text in a styled paragraph:

<w2:outclude src="example3.w2ml">hello world</w2:outclude>
<?xml version="1.0"?><!-- example3.w2ml -->
<p xmlns="http://www.w3.org/1999/xhtml"
   xmlns:w2="http://w2ml.org/2005/w2ml"
   style="background:pink">
 <w2:backclude/>
</p>

hello world

It is possible to use backclude several times to include seceral times the same content:

<w2:outclude src="example4.w2ml">hello world</w2:outclude>
<?xml version="1.0"?><!-- example4.w2ml -->
<w2:g xmlns="http://www.w3.org/1999/xhtml" xmlns:w2="http://w2ml.org/2005/w2ml">
 <span style="background:#F99" w2:tfirst="5"><w2:backclude/></span>
 <span style="background:#9F9" w2:tlast="5" ><w2:backclude/></span>
</w2:g>
hello world

Date and time

The default time is the request time in the time zone of the web server.

Various date formats:

<w2:day fmt="name"/>, <w2:day/> <w2:month fmt="name"/> <w2:year/>
Wednesday, 23 July 2008
<w2:day fmt="abbr"/> <w2:day/> <w2:month fmt="abbr"/> <w2:year/>
Wed 23 Jul 2008
<w2:year/>-<w2:g tfiller="0"><w2:month twidth="2"/>-<w2:day twidth="2"/></w2:g>
2008-07-23
<w2:month tfiller="0" twidth="2"/>/<w2:year tlast="2"/>
07/08

12-hour clock with time zone:

<w2:hour fmt="12"/>:<w2:minute w2:tfiller="0" twidth="2"/><w2:ampm/> <w2:tz/>
9:58PM CEST

24-hour clock:

<w2:g tfiller="0">
 <w2:hour twidth="2"/>:<w2:minute twidth="2"/>:<w2:second twidth="2"/>
</w2:g>
21:58:02

Predefined RFC 822 format (as amended by RFC 1123):

<w2:time fmt="rfc822"/>
Wed, 23 Jul 2008 21:58:02 +0200

Time of:

In case of modification, the last modification time is the same than the request time. The time is displayed in the default fmt="local" format:

<w2:time timeof="modification"/><br/>
<w2:time timeof="doc modification"/><br/>
<w2:time timeof="clock"/><br/>
<w2:time timeof="request"/>
Wed Jul 23 21:58:02 2008
Wed Jul 23 21:58:02 2008
Wed Jul 23 21:58:02 2008
Wed Jul 23 21:58:02 2008

Complicated format displaying time of last modification and using CSS for styling:

<p w2:timeof="modification" w2:tfiller="0">
 Updated:
 <w2:hour/>:<w2:minute twidth="2"/>
 <span style="text-transform:lowercase"><w2:ampm tfirst="1"/>.<w2:ampm tlast="1"/>.</span>
 <w2:tz/>
 <w2:g tz="utc">(<w2:hour/>:<w2:minute tfiller="0" twidth="2"/> GMT)</w2:g>,
 <w2:month fmt="name"/> <w2:day/>, <w2:year/>
</p>

Updated: 21:58 P.M. CEST (19:58 GMT), July 23, 2008

To display the creation time, if you cannot simply hardcode the time, then the res W2ML element can be used to save the current time when it is processed for the first time.

On first use:

Created: <w2:res><w2:time/></w2:res>
Created: Thu Mar 9 05:49:59 2006

After first use:

Created: Thu Mar  9 05:49:59 2006

Edition

Note: For demonstration purpose, you can edit the examples of this chapter, but all modifications are automatically reverted (with undo).

The ed W2ML attribute adds browser-embedded edition to XHTML elements. When it is over an editable element, the mouse pointer shows a pencil and the editor is started by a double-click.

For instance, ed="wysiwyg" allows block elements to be edited with a WYSIWYG editor:

<div w2:ed="wysiwyg">
 Double-click me to edit me!
</div>
Double-click me to edit me!

With ed="text", inline text is editable without formatting:

<p>
 You can edit <span w2:ed="text">this word</span>.
</p>

You can edit this word.

Editors may be automatically started with the edrun="auto" attribute:

<p w2:edrun="auto">
 You can edit <span w2:ed="text">this word</span>.
</p>

You can edit this word.

Templates

Note: For demonstration purpose, you can edit the examples of this chapter, but all modifications are automatically reverted (with undo).

A template is an XHTML element that can be duplicated, creating a new instance of the template. Only the root element of the template must be XHTML, the template may contain W2ML markup. The template W2ML attribute is used to mark and identify templates:

<span w2:template="t1" style="background:#FF9; font-family:fantasy">
 This line is a <em>template</em>.
</span>

This line is a template.

A template can be duplicated in the document using the ed="new", from and to W2ML attributes. The from W2ML attribute identifies the template to duplicate (t1 in this example). The to W2ML attribute gives the position of the duplicated template relative to its element:

<button w2:ed="new" w2:from="t1" w2:to="previousSibling">duplicate</button>
before this button
before this button
<button w2:ed="new" w2:from="t1" w2:to="nextSibling">duplicate</button>
after this button
after this button
<button w2:ed="new" w2:from="t1" w2:to="lastSibling">duplicate</button>
after this text
after this text
<button w2:ed="new" w2:from="t1" w2:to="here">duplicate</button>
and replace this button
and replace this button
<button w2:ed="new" w2:from="t1" w2:to="firstChild">duplicate</button>
at the beginning of this button
at the beginning of this button
<button w2:ed="new" w2:from="t1" w2:to="lastChild">duplicate</button>
at the end of this button
at the end of this button

A template can also be duplicated near an element remote from the one with ed="new". In this case, the to attribute refers to a new attribute on another XHTML element.

<button w2:ed="new" w2:to="dest1">duplicate</button> somewhere else
somewhere else

Elements with a new attribute must also have a from and a to attribute. This to attribute may not refer to another new attribute.

Duplicated <em w2:new="dest1" w2:from="t1" w2:to="lastSibling">here</em>:

Duplicated here:

Deletion

Note: For demonstration purpose, you can delete the examples of this chapter, but all modifications are automatically reverted (with undo).

An XHTML element identified by a del W2ML attribute can be deleted with the ed="del" and to W2ML attributes:

<button w2:ed="del" w2:to="dest2">Delete</button>
You can delete this <em w2:del="dest2">word</em>.

You can delete this word.

Request variables

Request variables passed with HTTP GET and POST requests, and with cookies, can be displayed with the v W2ML element. In this example, you can pass the hello variable through HTTP GET and POST methods:

<a href="?hello=world#reqvar">set hello=world</a> (GET)
<form action="?#reqvar" method="post">
set hello=<input type="text" name="hello"/> <input type="submit"/> (POST)
</form>
<strong>hello=<w2:v req="hello"/></strong>
set hello=world (GET)
set hello= (POST)
hello=

Internal variables

The v W2ML element can also display internal variables:

<table border="1">
<tr><th>Variable</th><th>Value</th></tr>
<tr><td>request body</td><td><w2:v internal="request body"/></td></tr>
<tr><td>request content-type</td><td><w2:v internal="request content-type"/></td></tr>
<tr><td>request variables</td><td><w2:v internal="request variables"/></td></tr>
<tr><td>uri</td><td><w2:v internal="uri"/></td></tr>
<tr><td>all users</td><td><w2:v internal="all users"/></td></tr>
<tr><td>all groups</td><td><w2:v internal="all groups"/></td></tr>
<tr><td>user</td><td><w2:v internal="user"/></td></tr>
<tr><td>groups</td><td><w2:v internal="groups"/></td></tr>
<tr><td>user ip</td><td><w2:v internal="user ip"/></td></tr>
<tr><td>server ip</td><td><w2:v internal="server ip"/></td></tr>
<tr><td>processor name</td><td><w2:v internal="processor name"/></td></tr>
<tr><td>processor version</td><td><w2:v internal="processor version"/></td></tr>
<tr><td>processor build</td><td><w2:v internal="processor build"/></td></tr>
<tr><td>processor full name</td><td><w2:v internal="processor full name"/></td></tr>
<tr><td>copyright</td><td><w2:v internal="copyright"/></td></tr>
<tr><td>running time</td><td><w2:v internal="running time"/></td></tr>
</table>
VariableValue
request body
request content-type
request variables
urisite:///documentation/language/examples.w2ml
all usersw2mlwrong w2mlunknown w2mlnopwd w2mlnolog w2mllogout w2mlanon
all groups
userw2mlanon
groups
user ip38.103.63.16
server ip62.220.136.5
processor namemod_w2ml
processor version0.15
processor build200711091607
processor full namemod_w2ml-0.15.200711091607
copyright©2005-2007 Marc Mongenet
running time315153

Users

Here is how users authentication (login) is handled with W2ML:

Request variables for login and logout

The next request variables are used for login and logout:

VariableValue
w2mlusr=stringa user name
w2mlpwd=stringthe user password
w2mllog=outout to logout, otherwise ignored

The w2mlusr and w2mlpwd variables are necessary to perform a login, but not sufficient. It is the login W2ML attribute that performs a login, and needs the variables. If the variable w2mllog=out is submitted, then no login is performed.

Here is a login form to submit w2mlusr and w2mlpwd:

<form action="" method="post">
 User name: <input type="text" name="w2mlusr"/>
 password: <input type="password" name="w2mlpwd"/>
 <input type="submit" value="log in"/>
</form>
User name: password:

Here is a logout form to submit w2mllog=out:

<form action="" method="post">
 <input type="hidden" name="w2mllog" value="out"/>
 <input type="submit" value="log out"/>
</form>

The w2mlusr and w2mlpwd variables are automatically transferred from page to page in the site (with a cookie) until w2mllog=out is submitted; so, after having been submitted, they remain automatically available to the W2ML processor until logout. You can submit the variables with the forms above and observe how w2mlusr, w2mlpwd, and w2mllog variables are handled:

<code>w2mlusr</code>=<w2:v req="w2mlusr"/><br/>
<code>w2mlpwd</code>=<w2:v req="w2mlpwd"/><br/>
<code>w2mllog</code>=<w2:v req="w2mllog"/>
<form action="" method="post"><input type="submit" value="reload"/></form>
w2mlusr=
w2mlpwd=
w2mllog=

Users and groups definitions

The user, group, name and password W2ML elements are the users and groups definitions markup. They define users and groups. Here we define a user named demo without password, and a user Tim with 123 as password:

<w2:user><w2:name>demo</w2:name></w2:user>
<w2:user><w2:name>Tim</w2:name><w2:password>123</w2:password></w2:user>

Users and groups definitions can be mixed with other XHTML and W2ML markup to provide visual formatting, edition, and so on. The next example defines the same users and passwords, but presented in a table, with Tim's password editable:

<table border="1">
<tr><th>Name</th><th>Password</th></tr>
<tr>
 <w2:user>
  <td><w2:name>demo</w2:name></td>
 </w2:user>
</tr>
<tr>
 <w2:user>
  <td><w2:name>Tim</w2:name></td>
  <td><w2:password><span w2:ed="text">123</span></w2:password></td>
 </w2:user>
</tr>
</table>
NamePassword
demo
Tim 123

Here we define a group named admin and add user Tim to the group. Then we define a group normal and add group admin and user demo to it. It means that user Tim is also a member of group normal. Note that <w2:user>Tim</w2:user>, <w2:group>admin</w2:group> and <w2:user>demo</w2:user> are declarations but not definitions: they declare a previously defined user or group.

<w2:group><w2:name>admin</w2:name><w2:user>Tim</w2:user></w2:group>
<w2:group><w2:name>normal</w2:name><w2:group>admin</w2:group><w2:user>demo</w2:user></w2:group>
adminTim normaladmindemo

When processed in a normal way, users and groups definitions markup has in fact no effect: defined users and groups are not compared to submitted request variables for login and logout and no login occurs. The login W2ML attribute must be used to perform a login.

Default user names

Out of elements with the login W2ML attribute, visitors are known under one of the next predefined default user names:

In elements with the login W2ML attribute, visitors are known as:

Default user names are always defined and can be added to any groups. Here we create a group nolog and add all default users to it:

<w2:group>
 <w2:name>nolog</w2:name>
 <w2:user>w2mlanon</w2:user>
 <w2:user>w2mlnolog</w2:user>
 <w2:user>w2mllogout</w2:user>
 <w2:user>w2mlunknown</w2:user>
 <w2:user>w2mlnopwd</w2:user>
</w2:group>
nolog w2mlanon w2mlnolog w2mllogout w2mlunknown w2mlnopwd

Login

You can use this form to try various user names and passwords and observe the results in the examples of this chapter. The users and groups definitions previously demonstrated are applied.

name: password:

Login is performed by the login W2ML attribute. The login is performed in several steps:

1. The login W2ML attribute value gives the name of an XHTML+W2ML document to load ("" to load itself).

<div w2:login="" style="margin-left:1em">

2. The loaded document is processed in a special mode: only Users and groups definitions markup is processed, any other markup is ignored and nothing is displayed. This dual mode of processing allows documents in which users and groups are defined to be used both to load users and groups (when processed by login), and to manage users and groups with XHTML for visual formatting, edition, access rights… (when directly processed)

3. The request variables for login and logout are compared with defined users. If the login is successful, then, in the element with the login attribute, the user name is given to the visitor. Otherwise, a default user name is given.

Your name is <w2:v internal="user"/>.
Your name is w2mlanon.

4. In all cases, the visitor becomes member of groups containing its (default) user name.

You are member of groups: <w2:v internal="groups"/>.
You are member of groups: nolog .
</div>

Here you can see the value of the same internal variables when not logged in:

You are known as "<w2:v internal="user"/>".
You are known as "w2mlanon".
You are member of groups: <w2:v internal="groups"/>.
You are member of groups: .

Access rights

You can use this form to try various user names and passwords. The users and groups definitions previously demonstrated are applied.

name: password:
<div w2:login="" style="margin-left:1em">

You are user w2mlanon, member of groups nolog .

Access control to users and groups can be exercised on any element with the ac, user and group W2ML attributes. Access (here x for execution) can be given to a single name with ac="x", given to a name with ac="+x", or withdrawn to a name with ac="-x". Access is evaluated (set, given, withdrawn) from parent to child elements.

<w2:g ac="x" user="demo">
 access given only to user demo<br/>
 <w2:g ac="+x" group="normal">
  access to visitors of group normal added<br/>
  <em w2:ac="-x" w2:user="Tim">
   access to user Tim withdrawn<br/>
   <strong w2:login="">
    login again, same access
   </strong>
  </em>
 </w2:g>
</w2:g>

Here the right to execute (x) the element is given only to user demo. Without the right, the counter does not work and no result is produced (no text):

Only user demo can execute the next element:
<em w2:ac="x" w2:user="demo"> <w2:counter>149</w2:counter></em>.
Only user demo can execute the next element: .

Here the right to edit (e) the element is given only to visitors of group admin:

Only administrators can write<em w2:ac="e" w2:group="admin" w2:ed="text"> this</em>.
Only administrators can write this.

Here the right to create a new template instance (n) is given only to visitors of group admin:

Only administrators can duplicate a template
<em w2:ac="n" w2:group="admin" w2:new="destadm1" w2:from="t1" w2:to="firstChild">here</em>.
<button w2:ed="new" w2:to="destadm1">duplicate</button>
Only administrators can duplicate a template here.

Here the right to delete (d) is given only to visitors of group admin:

Only administrators can delete
<em w2:ac="d" w2:group="admin" w2:del="destadm2">this</em>.
<button w2:ed="del" w2:to="destadm2">delete</button>
Only administrators can delete this.

Several access rights can be simultaneously changed by one ac attribute:

Only administrators can
<w2:g ac="en-d" group="admin">
 <em w2:ed="text">edit</em>
 <strong w2:new="destadm3" w2:from="t1" w2:to="firstChild">and create</strong>,
 but <span w2:del="destdel3">not delete</span>.
 <button w2:ed="new" w2:to="destadm3">duplicate</button>
 <button w2:ed="del" w2:to="destdel3">delete</button>
</w2:g>
Only administrators can edit and create, but not delete.
</div>