Replacement Variables

ConferenceRoom's included web server offers an advanced language for embedding commands and interactivity in the web pages it serves. Some of these features are used in our theme pages and administration pages. A thorough understanding of these features will allow you to build more interesting and interactive web pages.

Note that these features will only work on .adm, .htm, .html, or .prm files served off of ConferenceRoom's included web server. This documentation assumes you have version 1.6.7 or later -- not all features will be available in earlier versions.

Text in this font is normal text meant to be read and understood. Text in this font is meant to be used literally as a command, value, or as source code. Text in this font is meant to be replaced with what it names, for example name should be replaced with something's name or channel should be replaced with a channel.

All commands begin and end with the % character. If you want to use a normal % character, you should double it -- %% to ensure that it is not seen as a command. If you want to make web pages that work on both our web server and other web servers, ensure that there are never two % signs on the same line of HTML source.

Do not do the following:
We estimate the probability to be between 80% and 85%.
The text between the two % signs will be seen as a replacement variable. If you are only using our web server, you may use:
We estimate the probability to be between 80%% and 85%%.
This will cause the page to not work correctly on other web servers. If you want a portable page, you can do:
We estimate the probability to be between 80%
and 85%.

ConferenceRoom's web server will not look across lines.

The most basic thing you can do is access replacement variables. Replacement variables can be fetched by name. They can be set by code embedded in the web server, tags in the URL, or by fields posted from a form. To set a tag from a URL or form, you must precede its name with an @ character.

For example, the line:
Hello, %name%.
Will say:
Hello, Jack.
if accessed with:
on the end of the URL or through a form submission with:
<input type="text" name="@name">
and the person enters:

Parts of a web page may be made conditional upon a replacement variable being set. The syntax for this is:
HTML that will be ignored if the variable is not set

So, you can make a web page that says hello to someone only if their name has been set:

Hello, %%name%.

Loop control commands (such as %%!name% and %%!!%) must be the first non-whitespace on a line. A loop cannot begin or end in the middle of a line.

There are a few special commands available to set, unset, and conditionally set replacement variables from inside a page. Suppose you want to set the replacement variable name to whoever you are if it's not set. The conditional set command will do this:
%%_cset name whoever you are%

This will set the replacement variable name to whoever you are if it's not already set. If it's already set, it will not be changed.

If you put this line before the other example, it will say, Hello, whoever you are if no name is specified, otherwise it will say Hello, followed by the name.

Note: Unfortunately, there's a bug in _cset in versions up to and including 1.6.7b. So you may find that _cset doesn't work as documented, actually doing the same thing as _set. If this bug causes you a problem, upgrade to 1.7 or later.

You can set a replacement variable to a specified value with _set:
%%_set name value%

You can clear a replacement variable with _unset:
%%_unset name%

While there is no specific way to make parts of a page conditional on a replacement variable not being set, you can do it in a roundabout way:
%%_set noname foo%
%%_unset noname%
You haven't told me your name!

The first line sets the replacement variable noname to foo (any value would do, it doesn't matter). The next three lines unset it if and only if a name was specified. At the end of that, noname is set if and only if no name was supplied, allowing the next three lines to complain if and only if no name is supplied.

A replacement variable can also have more than one value (like an array). You can then loop through all the values. The syntax for such a loop is:
Stuff to be repeated goes here

Both %%!% and %%!!% mark the end of a block. The difference is that %%!!% will never loop. Both types of blocks will skip everything between the start and end if the replcement variable named to open the loop or block has no value. The %%!% means to repeat the loop as many times as there are values in the replacement variable.

Inside a %%!% loop, replacement variables behave like arrays. For example, suppose the replacement variable masks contains a list of masks. To list all the masks, you can do:

If you wish to, you can add a value to a replacement variable with the special replacement variable _add. For example:
%%_unset names%
%%_add names David%
%%_add names Jack%
%%_add names Joe%
%%_add names Jill% Your hosts are:

Blocks may be nested. There is an upper limit on the number of nested blocks or loops. The exact limit depends upon several factors, but you should always be able to nest at least 8 levels deep.

Some replacement variables are called action replacement variables. They generally don't replace to anything at all, but they trigger certain actions in the web server. Most action replacement variables begin with the word do.

For example, the action variable dolusers causes the web server to query the IRC server for much the same information the IRC command LUSERS returns. ConferenceRoom's web-based administration uses action replacement variables heavily.

You can simply place an action variable on a line by itself. For example:
<P>There are currently %%lu_usercount% users on the network,
%%lu_localuser% of them are on this server.
There are %%lu_channel% available channels.
This server has been up for %%lu_uptime%.

Some action replacement variables are considered secure and will only work on .adm pages. You can learn more about action replacement variables by looking at the .adm pages supplied with ConferenceRoom. Some action variables only permit certain features if they are launched from .adm pages.

The _unset command is especially useful to ensure that you get the default internal behavior of action replacement variables. If an action replacement variable has been defined, no action will be taken, so you may wish to ensure they are not defined if you require the default action.

For example, the replacement variable channel will replace to the server's default channel -- if it hasn't been specifically defined otherwise. Thus a URL with
will cause channel to replace to foo instead of the default channel.

If you wish to absolutely ensure that the special replacement variable channel gets you the server's default channel and cannot be overriden, put a:
%%_unset channel%
in your web page before you use the replacement variable. Otherwise, someone can override the default channel by putting:
on the end of a URL.

Of course, do not do this if you want to be able to override the default channel in a URL or form.

Note that if you wish to set replacement variables from a URL, you must follow the specifications for URLs. Reserved characters must be encoded with a % followed by their two digit hexadecimal representation. For example, a space is encoded as %20. A ? must separate the URL body from the parameters. An = separates a parameter name from its value. An & separates one value from the next.

Links to documentation for action replacement variables and special replacement variables are forthcoming. But a knowledge of the basics is essential to understanding how our themes and administration pages work.