General Info | Template Language | WCTL Commands | WebX/Chat | WebX/Pro |
Release Notes | Standard Templates | URL Codes | WebX/Multi | FastCGI, NSAPI, ISAPI |
Visit the Web Crossing Conference to find a wealth of WebX info and a community of WebX experts on the Web!
Using the Web Crossing Template Language
Location | path.xxxx | path$xxxx |
---|---|---|
Folder 1 | "abc" | "abc" |
Folder 1/Folder 2 | "" | "abc" (from Folder 1) |
Folder 1/Folder 2/Discuss | "def" | "def" |
WCTL directives are identified by two percent signs, the command, and then two more percent signs, i.e. %%...%%. If you enter
Hello <b>%% username %%!</b>
the actual display seen by the user will be something like
A template is the HTML text for an entire page or portion of a page to be served by Web Crosing. You can enter templates in the various sysop control panels to easily customize much of the apperance of your site, such as the banner and footer for each page.
In addition to the sysop control panel, you can use the webx.tpl file to customize your entire site. The webx.tpl file is a collection of templates and macros to be used by Web Crossing. You can specify template macros for any of the user interface pages served by Web Crossing. You can also define your own templates to create your own unique pages, or define your own templates as a convenience when the same HTML and WCTL directives are used in more than one place.
Web Crossing also uses a second file of templates called
webxextn.tpl. This file is used by L&A to deliver drop-in updates to Web
Crossing, and should never be modified, deleted, or renamed. Features enabled by
webxextn.tpl may be disabled with the "Other Settings" form on
the sysop Control Panel. A template defined in
webxextn.tpl may be overridden by defining a template of the same name in
webx.tpl. If you have already defined a template in
webx.tpl and later install an updated webxextn.tpl file which
also defines that template, the original template will continue to be
used by Web Crossing.
If there is no whole-page template, then Web Crossing will construct
the page from smaller pieces.
These pieces are specified through the sysop control panel
or through templates in your webx.tpl and webxextn.tpl files.
The template files are checked first, and if a template
is defined therein it is used; otherwise, the sysop control panel setting is used.
When Web Crossing builds a response page, it starts with the sysop-defined banner,
adds items appropriate for the response, and concludes with the
sysop-defined footer.
You can do extensive customization of each page through the various sysop
control panels. You can edit default HTML text, and
you can use WCTL directives as appropriate.
Building response pages
When Web Crossing builds a reponse page,
it firsts checks the webx.tpl and webxextn.tpl files to see
if a whole-page template macro has been defined for the response.
If so, this template macro is used to build the entire page.
For example, you can replace the entire login page by
specifying a %% macro login %% in your webx.tpl file.
Where to go from here
You can customize many aspects of Web Crossing though the sysop control panel.
To customize whole pages, follow the
step-by-step instructions for Customizing Web Crossing Pages.
The section on Using the Web Crossing Template Language is recommended
reading for anything you need to do with WCTL.
There are detailed descriptions of all the
WCTL variables and templates,
and some examples of putting all this together.
The steps to customize whole pages are as follows.
%% macro login %% ...contents of login template... %% endmacro %%
All of the templates used to layout a folder page are optional. They may be specified through the sysop control panel, through the webx.tpl file, or on a folder-by-folder or discussion-by-discussion basis.
For more detail on the folder templates, see the Folder template sections.
All of the templates used to layout a discussion page are optional. They may be specified through the sysop control panel, through the webx.tpl file, or on a folder-by-folder or discussion-by-discussion basis. (If specified in a folder, then all discussions in that folder will share the same templates.)
For more detail on discussion templates, see the Discussion template sections.
For your convenience, you can also collect changes to these additional fields through the built-in registration and user-preferences forms. To customize the register and editPreferences template forms, follow the steps above in the Customizing whole pages section to move these templates into your webx.tpl file.
To add your own user information fields, edit the templates in your webx.tpl file. Use <input name=user followed by a dot and your variable name, such as <input name=user.city. Then, when Web Crossing processes the form, it will set this user value for you from the form input.
For example, to have users enter their phone number at registration time, add the following to the register template:
Your phone number: <input name=user.phone type=text size=30 max=50>
Note that "user." is required. Web Crossing specifically checks for variables starting with "user." for values to store into your variables. In this example, once the phone number has been added to the user record, you can access it with user.phone or author.phone.
To continue this example, you can allow users to edit their phone number in their user-preferences form, by adding the following to the editPreferences template:
Your phone number: <input name=user.phone type=text size=30 max=50 value="%% user.phone %%">
Note that %% user.phone %% will show the current phone number for editing.
To display a user's phone number in your site's personal information form, use author.phone in the userInfo template, such as
%% if author.phone %% Phone number: %% author.phone %%<p> %% endif %%
This will display the phone number if available.
WCTL expressions are not case-sensitive, so "username" is the same as
"USERNAME" or "UserName". You may place blanks inside the %% marks for readability.
For example,
You may use tabs to indent conditional sections.
All of these leading tabs are automatically removed from the output.
In order to make it WCTL easier to read, the newline
following a directive is also removed. For example,
All variables evaluate to either a text string, an integer number, or to a
boolean (true/false) value.
For example, %% username %% evaluates to the name of the current user,
while %% if userIsSysop %% takes the true branch if the current user is the sysop.
Text variables may evaluate to an empty string, that is, a string with no characters.
For example,
%% user2ndLine %%, the second line of user information,
will be empty until a user fills it in.
In an if test, text strings are true when they have any characters,
and false when they are empty. For example,
will only insert <p>Other information:... when there is a second line.
Numeric values are considered to be true if they are non-zero, or false if they are zero.
String and integer values are automatically converted as required.
A non-numeric string is converted to the integer value 0.
For example,
Boolean variables are 0 for false and 1 for true.
You can use boolean variables to control the text that is placed into the
page returned to the user.
For example,
Operator precedence, from highest to lowest (highest are done first):
Numeric constants can be a number, such as -5, 0, or 1429.
They can also be the integer value of a character, such as 'a' or 'Z'.
String constants are in double-quotes, such as "abc".
The empty string is "".
To put a double-quote character in a string, repeat it, such as
"""" (which evaluates to a string of one double quote).
For example,
For example,
In the user registration and editPreferences templates, you can use these
variables as the name of an input field, and Web Crossing
will automatically set them for you when it processes the form.
For example, adding
For example, in a message display or personal information form,
For example,
Sometimes you want to find a value from either the current location or,
if not defined there, then from the
closest parent that defines it. This allows you to use "inheritance"
by folder and discussion hierarchy.
To find the closest definition of a value, use path$varname.
For example,
For example,
The built-in location and pathXxx variables a reference the current
location in the Web Crossing forums. You can change the current location
with setPath(...).
Values for custom "path" variables like path.customFooter
must be assigned to each folder/discussion/message object. They do not inherit
values from the same variables in their containing objects, but you can use
path$customFooter to reference either the value from the current location,
or from the closest parent if not defined in the current location.
will display as
The conditional commands are if, else, endif, else if,
elsif, and elseif. (The various "else if" options are all equivalent.)
You can use any built-in variable or expression in an if test.
Empty strings evaluate as false, and non-empty strings as true.
You can also use
In a while loop, you can use %% break %% to exit the loop, and
%% continue %% to go to the top of the loop.
For example, the following rather contrived loop will display all the
even numbers less than 100:
In order to prevent infinite loops, Web Crossing limits the maxiumum number of
while-loop iterations per page. The default setting is 1000, and can be changed
through the sysop General Settings panel.
is a macro that evaluates to something like Hello World on Feb 26, 1998.
The webx.tpl file allows you to define macros for a variety of uses.
When Web Crossing constructs a reponse to a URL, it first
checks the webx.tpl and webxextn.tpl files for a
template macro for the response.
The template macro for a specific request is located by name;
see the Standard Templates
document for a listing.
The standard.tpl file contains a complete set of
default templates that you can easily customize for your site.
Before Web Crossing gets a value from the sysop control panel,
it checks to see if this value is defined in the webx.tpl
or webxextn.tpl files. (This allows you to define all of the
sysop settings together in webx.tpl.)
Again, see the Standard Templates
document for a listing.
Note: after you make changes to the webx.tpl file, you must
click on the "Reset file cache for HTML files and webx.tpl
templates" link
in the sysop control panel, in order for Web Crossing to pick up your changes.
The template you call can be either built-in or one you have defined.
There is a maximum depth of 50 calls, so that infinite loops (e.g.
a calls b, b calls a) don't run forever.
To define your own pages, use the following steps:
It is good practice to put an underscore in your template name, because Web Crossing built-in
templates will never use this character.
If you need a user to be logged in before a full-page template macro should be used, you can
insert the following check at the start of the macro:
When a full-page template macro returns all white space, Web Crossing
will display a login page. On a successful login, the original template macro
will be reexecuted with the same parameters.
You process a form by linking the submit button to a Web Crossing template.
For example,
where myFormProcess is the name of your form-processing template.
Web Crossing will replace
%% urlBase %% with the base URL for your Web Crossing server,
%% certificate %% with the user's current access certificate, and
%% location %% with the user's current location in the Web Crossing conference.
(These are all standard components of a Web Crossing URL).
You access form variables by using %% form.fieldname %%.
For example,
The complete templates could be something like:
If you are running with FastCGI, all of the environment
variables are avaiable. Through the standard CGI, you can only access a subset of the variables.
To get a list of variables in your environment,
use the showEnvir template from standard.tpl.
You first need to move the showEnvir template into your webx.tpl file,
as described in the
Customizing Whole Pages section.
Then use a URL to access Web Crossing as
To send a cookie along with the response to the client,
use something like
To get the value of a cookie that is part of the current request,
use
Note that cookie values cannot include white space or semicolons.
If you are building a cookie value dynamically, it is recommended that you
URL quote it, which will remove all these values.
For example, set the cookie to a value
with
The set-cookie syntax is as follows.
The date string is formatted as:
expires is an optional attribute. If not specified, the cookie will
expire when the user's session ends.
Note: There is a bug in Netscape Navigator version 1.1 and earlier.
Only cookies whose path attribute is set explicitly to "/" will
be properly saved between sessions if they have an expires
attribute.
Only hosts within the specified domain
can set a cookie for a domain and domains must have at least two (2)
or three (3) periods in them to prevent domains of the form:
".com", ".edu", and "va.us". Any domain that fails within
one of the seven special top level domains listed below only require
two periods. Any other domain requires at least three. The
seven special top level domains are: "COM", "EDU", "NET", "ORG",
"GOV", "MIL", and "INT".
The default value of domain is the host name of the server
which generated the cookie response.
Because of various browser bugs, you must specify the path.
If secure is not specified, a cookie is considered safe to be sent
in the clear over unsecured channels.
To find the correct template, Web Crossing first checks the templates assigned to
the current folder. If not found, then the parent folder is checked, and so on to the
top-level. If still not found, then the top-level of the
webx.tpl and webxextn.tpl files are checked. If
still not found, then the sysop panel templates are checked.
To override the templates for a folder, use the following steps:
where filename is the file to include.
You must use this syntax exactly: spaces, capitalization, and all.
Whenever a WCTL page evaluates to text starting with "HTTP/", that page
is returned as is, without adding the normal HTTP response heading.
For example, the following template forwards the request
...WebX?forward@@ to a discussion.
HTTP/1.0 302 Redirect is the standard first line for a response
from a Web server to the user's Web browser. This one has a response code
of 302, which asks the browser to temporarily forward the original URL to
a new location.
Location:... is the fully-qualified URL to which to forward.
Note that the response must end with a final blank line.
HTML documents include formatting and other directives.
For example,
SGML quoting converts all of the HTML special characters (<, >, etc) to their
quoted format (<, >, etc).
The result is a text string that displays exactly as
the original text.
If you "SGML quote" the sample text in an HTML document
to
URL quoting takes the actual pathname and replaces special URL characters with
a percent sign and 2 hexadecimal digits (e.g. blanks are replaced with %20).
For example, in a URL,
In WCTL, most values are automatically quoted. For example,
%% userName %% is SGML quoted, and
%% parentUrl %% is URL quoted.
You can explicitly control SGML and URL quoting in Web Crossing. For example,
%% userName.fromSGML %% is the original user name without SGML quotes.
See the string functions in the
WCTL Built-in Variables document for a list of available conversions.
For example, suppose you need to get the e-mail address of a user from an external database.
You can run a script to obtain this from the external database, and then embed this information
into the current page. You might use
The server-side include directives for Web Crossing are:
The results from exec, cgi, or file can be multiple lines long, they
are not restricted in any way.
Also, the results of exec, cgi, or file can also be stored
into a variable for use as desired. For example,
The first line of the message is the list of users, and the remainder of the message
is a normal e-mail message including the full heading. For
example,
Filter macros can examine form fields and take appropriate action:
return a complete page to send to the user,
forward the user to a different URL,
construct an error message,
return a user ID for the registered user, or
return a blank page for normal processing.
For example, the following macro will check a registration post
for objectionable words, and return an error message to be displayed
for the user to correct the problem:
This macro outputs one of the following:
This macro outputs one of the following:
This macro outputs one of the following:
To just link to a folder or discussion, you can go to that location in your Web browser,
copy the URL of the location, and delete the text between the at (@) signs.
For example,
would be edited to
for use in a link you are building.
where [...] is an optional component.
This is almost always the location in the conference to which a command applies.
The location may be a folder, a discussion, or a message in a discussion.
If the command is omitted entirely, then Web
Crossing uses the default command you entered in your
Banner, footer, background, and top-level page appearance panel,
or to the top-level folder.
Commands typically apply to a location.
Some login and registration messages need to first login the user, then perform
the command. They take an actionPath as a parameter. The action path is
the command code, an at (@) sign, and the parameters for that command. For example,
the action path to show a particular folder might be 14@/Books.
Some commands process a form submitted by POST command. The contents of
the form is sent as a string where each
input item starts with a name, followed by '=', followed by a value,
followed by '&'. For example, the post data for Process Login (23)
includes the user's name and password, e.g.,
username=Adam Smith&password=xx&.
The set of input items for a command is defined by the corresponding
form from Web Crossing.
On Unix systems, you may use 'webx-go -stdio' to retrieve the form.
For example get 15@@
shows the form that invokes Process Login. On Mac and Windows NT, use
Save As Source in your browser.
See the Command Codes document for a complete listing of
available codes.
Certificate syntax is:
where [...] is an optional component.
For example, the following table shows some possible certificates:
To customize your site based on the user's tag, use the
%% if certificateIs tag %% variable.
As a user navigates through the conference,
the original entry tag is propagated automatically.
You can switch the certificate to a new tag through the
certificate variable.
Folder pathnames may use folder titles, such as /Books, or the
unique ID of the folder, such as .aef345. Note that long titles
may cause errors in your HTTP server.
Discussion pathnames may be either a folder pathname and discussion ID number, such
as /Books/3, or the unique ID of the discussion,
such as .aef34a.
(Discussion IDs are assigned starting from 1 and are not reused if a discussion
is deleted.)
Individual messages
are located by their discussion pathname and message ID.
For example, /Books3/22 or .aef372/22.
(Message numbers are assigned starting from 0 and are not reused if a message is deleted.)
The location pathname must use URL quotes. For example, blanks must
be replaced by %20, as in /Books%20in%20Russian/3.
This might display as:
Note how this template is made more readable by using
%%nop%% to suppress newlines in the output.
(This works because Web Crossing removes newlines that immediately follow a variable.
The indents in this example should be replaced by tabs
if you copy this for your use (again, because Web Crossing strips leading tabs
to help make the template more readable).
You can see some of the various substitution values by going to the Folder appearance
control panel and setting the HTML template for each item in a folder
to the following:
The result is that when a user logs in and they are going to the top level,
they will see your normal login heading. If they follow a link from that login page,
they will be going to a specific place, and will just see the "Please log in" heading.
» Using the Web Crossing Template Language
The Web Crossing Template Language (WCTL) may be used
anywhere that the sysop or conference host enters HTML text.
For example,
Title: <b>%% pathTitle %%</b>
might display as
Title: General Interest
%% username %% is the same as
%%username%% or
%% username%%
<a href="xxx">%% nop %%
<img src=yyy></a>
would be output as
<a href="xxx"><img src=xxxx></a>
» Built-in variables
Web Crossing provides a number of built-in variables.
These variables let you insert information into the text served
to your user. They also let you check for various conditions,
and to customize served text based on these conditions.
%% if user2ndLine %%
<p>Other information: %% user2ndLine %%
%% endif %%
%% set i 50 %% -- sets i to 50
%% i %% -- evaluates to 50
%% set i i + 1 %% -- sets i to (i+1)
%% i %% -- evaluates to 51
%% set i "abc" %% -- sets i to "abc"
%% i %% -- evaluates to abc
%% set i i + 1 %% -- sets i to (i+1)
%% i %% -- evaluates to 1
%% "abc" & "def" %% -- catenates the strings to evaluate to abcdef
%% "abc" + "def" %% -- adds two numbers to evaluate to 0
» Substitutions
All of the built-in variables can be used to substitute text into the
HTML output sent to the user. For example, %% userHomePage %%
will add a URL to the user's home page (or an empty string if this has
not yet been entered by the user).
%% if userIsSubscribed %%
subscribed
%% else %%
not subscribed
%% endif %%
will add subscribed or not subscribed to the page.
» Expressions
You can use expressions in WCTL.
The operators are the same as in C/C++/Java,
except that the ampersand (&) is used for string concatenation.
For example,
%% 10 % 7 %% -- evaluates to 3
%% (10+45) % 7 %% -- evaluates to 6
%% "abc" & 0 %% -- evaluates to "abc0"
%% 5 & 6 %% -- evaluates to "56"
Operators Use + - unary plus and minus * / % & times, divide, modulus, string-catenate operators + - plus or minus operators < <= > >= less-than, less-than-or-equal, greater-than, greater-than-or-equal comparison == != equal and not-equal comparison && logical AND || logical OR () in an expression » Constants
Constants can be numbers or string.
» Defining your own variables
WCTL lets you define your own variables.
You can define temporary variables in a template,
or permanent variables that are stored as fields in the Web Crossing database.
If you reference any variable before you set it,
its value is the empty string.
Variable Usage Scope varName Local variable. Once you set a local variable it
can be referenced from any template in the current execution,
not just the one that set it.
Local variables are always cleared before evaluating a new template or
sysop template.
To keep a value around from page to page, use a user-record variable,
a current-location path variable, or a global site variable.
%% set currentAd "General Rotation" %%
<img src=http://mysite/%% currentAd %%>
user.varName User variable.
User variables are stored in the database as an additional field in the user record,
so they are saved with the database and are available as a permanent part
of the user's record.
%% set user.phone getValue "phone" %%
Your phone number is now: <b>%% user.phone %%</b>
<input name=user.phone type=text value="%% user.phone %%">
to your editPreferences template will allow users to edit their
phone number in their personal preferences page.
author.varName Author variable. Same as a user variable, but in the
user-record for the author of the current location.
Phone number: <b>%% author.phone %%</b>
You can set the current author through the setAuthor function.
path.varName Path or location variable, defining an additional
field for the current location.
Path variables are stored in the database as an additional field for
any folder, discussion, message, link, or chat room, and are saved with the database.
%% set path.totalHits path.totalHits+1 %%
In the templates that add or edit a location (addFolder, editFolder,
addDiscussion, editDiscussion,
addMessage, editMessage, addChat, editChat,
addLink, and editLink),
you can use these variables as the name of an input field, and Web Crossing
will automatically set them for you when it processes the form.
For example, adding<input name=path.title type=text value="%% path.title %%">
to your addMessage and editMessage templates will allow users to specify
a title for the message. (For this example, you could also customize
the messageListItem
template to show the title as part of the message display).
Location path.xxxx path$xxxx Folder 1 "abc" "abc" Folder 1/Folder 2 "" "abc" (from Folder 1) Folder 1/Folder 2/Discuss "def" "def" site.varName Global site variable, defining an
additional field for the global site information. Site variables are saved with the database.
%% set site.sysopPhone getValue "phone" %%
The sysop phone number is now: <b>%% site.sysopPhone %%</b>
» Scope of variables
User-defined local variables such as x are defined for the
current execution chain:macro: m1 m2 m3
calls: use m2 ->
set x 1
use m3 ->
x == 1
endmacro
x == 1 <-
endmacro
x == 1 <-
endmacro
Outside of this context, x will be "", the default.
» Conditional sections
WCTL supports conditional sections. For example,
%% if 1 %%
TRUE
%% else %%
FALSE
%% endif %%
TRUE
if awayhours > nnn
to check for the last
login having been more than "nnn" hours ago, or
if lastLogin < mm/dd/yyyy.hh:mm:ss
to check whether the prior login
was before a particular date.
» While loops
A while loop lets you repeatedly cycle through the same instructions
while a condition is true.
For example, you can process all the entries in a list of user posts:
%% set posts user.userposts(5) %%
%% set post posts.split %%
%% while post %%
%% setPath(post) %%
%% pathDate %%<br>
%% set post posts.split %%
%% endwhile %%
This while loop iterates over a list of up to 5 most recent posts by the current user,
and displays the date for each post. userposts(5) returns the 5 most recent posts
as location unique IDs. posts.split returns the first blank-delimited location, and sets
posts to the remaining locations. setPath(post) sets the current location,
so pathDate can display its date.
%% set start -1 %%
%% while 1 %%
%% set start start+1 %%
%% if start >= 100 %%
%% break %%
%% endif %%
%% if start % 2 == 1 %%
%% continue %%
%% endif %%
%% start %%-
%% endwhile %%
» Macros
A macro is a named piece of text defined in the webx.tpl file.
A macro can include both HTML text and WCTL expressions.
For example,
%% macro testMacro %%
Hello World on %% date %%.
%% endmacro %%
%% macro folder %%
...layout for folders...
%% endmacro %%
%% macro greetingNews %%
Hello %% userName %%.
%% endmacro %%
will set the sysop Greeting
template to Hello %% userName %%.
%% macro realAudioSource %%http://mysite.com/audio.ram%% endmacro %%
... %% use realAudioSource %% -- will insert the correct URL
» Calling another macro
You can call another macro with the use directive. For example,
%% use greetingNews %%
would insert the current greeting template into the output text.
» Return statement
You can return from a template at any point with the return statement.
For example,%% if i > 50 %%
%% return %%
%% endif %%
When a return statement is processed, no more text from the current template is
added to the output page, and no more expressions are evaluated.
» Creating your own pages
You can create your own pages associated with a location parameter in a
Web Crossing command. You can use this to show alternative views, to split
user preferences into multiple forms, etc.
%% macro yourMacro_ %%
...HTML and template expressions for your page...
%% endmacro %%
» Forcing a user login
Template macros do not require the user to be logged in.
%% if userIsUnknown %%
%% return %%
%% endif %%
» Processing forms
You can use WCTL to process forms and update variables stored in the Web Crossing
database. For example, you could take a survey or extend the built-in
user directory with additional fields.
<form method="POST" action="%% urlBase %%myFormProcess@%% certificate %%@%%location%%">
<input name=phone...> -- in the form
%% form.phone %% -- in the forms-processing template
%% macro myForm %%
<HTML>
<HEAD><title>%% siteTitle %% - New Address </title></HEAD>
<BODY %% background %%>
<form method="POST" action="%% urlBase %%myFormProcess@%% certificate %%@%%location%%">
Please enter your address:
<input type=text name=address value="%% user.address %%">
<p>
<input type=submit value=" OK ">
</form>
</BODY>
</HTML>
%% endmacro %%
%% macro myFormProcess %%
<HTML>
<HEAD><title>%% siteTitle %% - New Address Entered </title></HEAD>
<BODY %% background %%>
%% if form.address %%
%% set user.address form.address %%
%% endif %%
Your address is now: %% user.address %%
<p>
<a href="%% urlBase %%@%% certificate %%@/">
<img alt=" OK " border=0 align=middle
src="%% siteImages %%/ok.gif" %% pictSizeButton %%
></a>
</BODY>
</HTML>
%% endmacro %%
» CGI environment variables
You can access CGI environment variables in the Web Crossing Template Language.
For example,envir.query_string
is the complete query string from the URL for the current request.
...?showEnvir@@
to see a list of variables and their values.
(The showEnvir template uses the envirList WCTL variable to get a list of all the
CGI variables, then iterates over this list to display each variable name and its value.)
» Using cookies in WCTL
Using WCTL, you can send cookie values to the client, and get cookie values sent
from the client as part of the current request.
%% addResponseHttp( "Set-cookie: abc=xxx; path=/" ) %%
This will set a cookie named abc to the value xxx.
%% envirCookie( "abc" ) %%
This will access the value of the cookie named abc.
%% setHttpResponse( "Set-cookie: abc=" & value.toUrl & "; path=/" ) %%
and get the value
with%% set value envirCookie( "abc" ).fromUrl %%
Set-Cookie: NAME=VALUE; expires=DATE;
path=PATH; domain=DOMAIN_NAME; secure
Wdy, DD-Mon-YYYY HH:MM:SS GMT
» Using templates on a folder-by-folder basis
You can assign template macros on a folder-by-folder
or discussion-by-discussion basis.
This allows you to customize the look of a specific set of folders or discussions.
%% macro yourFolderMacro %%
%% macro folderListBefore %%
...your HTML text to insert before the folder's item list...
%% endmacro %%
%% macro folderListItem %%
...your HTML text to customize each folder item...
%% endmacro %%
%% macro folderListAfter %%
...your HTML text to insert after the folder's item list...
%% endmacro %%
%% endmacro %%
» Include files for webx.tpl
You can include files into webx.tpl by using the following directive:
<!--#Include File="filename"-->
» Forwarding URLs, and other HTTP responses
Web Crossing allows you to forward requests to another URL, and in general, to
return any HTTP response.
%% macro forward %%
HTTP/1.0 302 Redirect%% crlf %%
Location: http%% if siteIsSecure %%s%% endif %%://%%siteHost%%
%%urlBase%%14@%%alwaysCertificate%%@%%location%%%% crlf %%%% crlf %%
%% endmacro %%
A carriage-return/linefeed is added to the end of each line by the
built-in crlf variable. Because Web Crossing strips trailing
newlines following an expression (e.g. following %% crlf %%),
you can write the response on multiple lines for readability, without
having extra newlines inserted into the result.
» SGML and URL quoting
In order for text to display exactly as intended in the user's Web browser,
you sometimes need to be aware of the quoting conventions used in HTML.
<b>Sample text</b>
will display asSample text
in the user's Web browser.
<b>Sample text</b>
then it will display exactly as the original.
My pathname
becomes My%20pathname
» Server side includes: scripting and using external files
You can call external programs and use the values they return (on Unix and Windows).
E-mail address: %% exec( "getEmail " & userName ) %%
to run an external program named getEmail, with a command line of something
likegetEmail Smith, Bob
The output of this program is inserted into the page being prepared by WCTL.
exec( commandLine )
Run a program with the specified command line, and return the output from the program.
For example, exec( "myProgram" ). cgi( commandLine )
Run a program with the specified command line, and also set all the environment
variables from the current CGI request.
For example, cgi( "myCgiProgram" ). (See the section on CGI Environment Variables
above.) file( pathname )
Read the contents of the specified file, such as file( "prefix" ). scriptError
The error message for the last exec or cgi program, or the empty string if no error.. fileError
The error message for the last file include, or the empty string if no error.. %% set address exec( "getAddress " & userName ) %%
will store the result of running something
likegetAddress Smith, Bob
into the variable address.
» Sending e-mail messages
You can send email messages from WCTL by using the email
command. This requires that the "Domain name server" field on the General
Settings control panel be set correctly for your site. (Note: the Web
Crossing server must be restarted when this field is set or changed.)
%% set _message
"<" & user.userEmail & ">" & crlf &
"To: " & user.userName & " <" & user.userEmail & ">" & crlf &
"From: Web Crossing Admin <" & sysopEmail & ">" & crlf &
"Subject: Welcome to Web Crossing" & crlf & crlf &
"Thanks for joining the " & siteTitle & " online community..." & crlf %%
%% email( _message ) %%
will compose a welcome message and mail it to a newly-registered user. Note that the "To:" field
is not used to send the message: The message is actually sent to each user in the first line,
and the first line is not included in the message. You can send to multiple users by
including them in the first line, such as <user1> <user2>.
» Filter macros
Web Crossing allows you to filter authentication, login, registration and user-preferences changes,
so that you have total control over these actions.
%% macro registerProcessFilter %%
%% if form( "username" ).isObjectionable %%
The user name is not allowed.
%% else if form( "email" ).isObjectionable %%
The email address is not allowed: %% form( "email" ).markObjectionable %%
%% endif %%
%% endmacro %%
In this example, if either the username or email form fields contain objectionable text, an
error message is added to the macro output. This will cause the registration form to
be redisplayed for the user to remove the objectionable text. If there are no objectionable
words, the macro returns all white space, and processing continues normally.
Filter macro Usage authenticateFilter
If present, called after the normal WebX authentication,
before processing the request. The user variable is set to the
user as authenticated by Web Crossing.
The original request including the certificate is available through
envir.query_string, and any cookies are available through
envirCookie( "cookieName" ).
loginFilter If present, called after the normal WebX login,
before processing the login actionPath. The user variable is set to the
user as authenticated by Web Crossing.
The original request including the certificate is available through
envir.query_string, and any cookies are available through
envirCookie( "cookieName" ).
loginFailureFilter
If present, called after the normal WebX login fails. If the user exists but
the password was wrong, then the user variable is set.
The original request including the certificate is available through
envir.query_string, any cookies are available through
envirCookie( "cookieName" ), and the login form fields are available through
form.username and form.password.
registerProcessFilter
If present, this macro is called before processing a registration form.
It returns one of the following:
registerFailureFilter If present, this macro is called after processing a registration form,
when the registration request had some error.
It returns one of the following:
httpBasicNewFilter
If present, this macro is called when HTTP basic authentication is turned on,
and the incoming user is not in the Web Crossing user directory.
It returns one of the following:
» Web Crossing URLs
When you build links into Web Crossing, either from outside the conference or between
pages you are customizing, you will need to construct URLs that perform Web Crossing commands.
http://webcrossing.com/webx?14@0.ag4d3fde^0@/Test
http://webcrossing.com/webx?14@@/Test
» Web Crossing URL format
A Web Crossing URL has the format:
http://your_site/<access path>[?<command>[L]@<certificate>@<parameters>]
<access path> is the name of the CGI script or other
interface between Web Crossing and your Web server.
<command> is either a command code or
a template you have defined.
L if the command code is followed
by L, the user will be asked to login.
(This option is not available for pages you have defined.)
<certificate> is used to identify the current user,
provides an optional tag used by you to configure the user interface
for a particular access path, and includes a sequence number to force
a user's client to fetch new information instead of using old cached material.
<parameters> is additional information required for a command.
» Command codes
The first element of a Web Crossing request is a command code. For example, the command
code could tell Web Crossing
to display a folder or discussion, to show a user's preferences, or to post a new message.
» Certificates
Certificates are used to
[<slot>.][<userkey>][-<tag>][^<seqno>]
<slot> is a number from 0 to 999,
and is the slot assigned to this certificate.
<userkey> is omitted for an unknown user,
or is 8 random characters for a registered or guest user. This random user key
is used to identify the user, and authorizes his/her access.
The userkey is assigned at the time the user logs in or registers.
The userkey is valid for a timeout period, usually 30 minutes, and
expires automatically if the user doesn't issue another request during the
timeout period.
<tag> is an optional component that may be used in templates to
keep track of a user's options. The meaning of a tag is defined by the site designer.
<seqno> is a number starting with 1 that is incremented for each response, and
is used to make the client side fetch new pages instead of showing an old cached page.
Certificate Usage
0.abcxyzaa^1 A typical certificate for a logged-in user.
0.abcxyzaa-TEXT^2 A typical certificate for a logged-in user, with a tag of TEXT.
An empty certificate for first-time entry
-TEXT A tag-only certificate for first-time entry.
^243 A typical unknown user with guest access.
The sequence number is used to force the user's browser to
fetch current pages.
» Tags
The tag component of a certificate can be used to customize the user
interface to match the original URL. For example, you could have a text-only interface
as an option, or provide a version of your site in other languages. You could also use
the tag to keep different users in different areas, by not showing different
navigation tools depending on the user's tag.
» Locations
A location may be any folder,
discussion, or message in the Web Crossing conference.
» Examples
» Changing the current location appearance
You can specify the current location appearance by changing the title and toolbar settings.
For
example, you could use a three-level "forum/topic/thread" terminology by
replacing the %%backpath%% in
the default templates with the following:
<b><a href="%%siteUrl%%">The Best Place</a></b><br>
<b>Forum: <a href="%% parentUrl 1 %%">%% parentTitle 1 %%</a></b>
%% if pathIsFolder %%
<p>
%% else %%
<br><b>Topic:
<href="%% parentUrl 2 %%">%% parentTitle 2 %%</a></b><p>
>%% endif %%
The Best Place
Forum: Bicycles For Everyone
Topic: Mountain Bikes
» Specifying folder item appearance
The default template for displaying folder items is as follows: <a href="%% pathUrl %%">
%% pathIcon border=0 align=bottom%%
<b>%%nop%%
%% pathTitle %%
</b>%%nop%%
%% if pathHasMessages %%
<font size=2>(%%nop%%
%% pathMessageCount %%
%% if pathHasOneMessage %%
message%%nop%%
%% else %%
messages%%nop%%
%% endif %%
%% if pathHasNewMessages %%
,%%nop%%
%% pathNewMessageCount %%
new %%nop%%
%% endif %%
)</font>%%nop%%
%% endif %%
</a><br>
<a href="%%pathUrl%%">link</a><br>
title - %% pathtitle %%<br>
url - %% pathurl %%<br>
icon - %% pathicon align=top %%<br>
has messages - %% pathhasMessages %%<br>
one message - %% pathhasoneMessage %%<br>
message count - %% pathmessagecount %%<br>
new messages - %% pathhasnewmessages %%<br>
one new message - %% pathhasonenewmessage %%<br>
new message count - %% pathnewmessagecount %%<br>
created by sysop - %% pathcreatedbysysop %%<br>
creator name - %% pathcreatorName %%<br>
creator URL - %% pathcreatorURL %%<br>
created date - %% pathcreatedDate M2D2Y2%%<br>
created date default - %% pathcreatedDate %%<br>
modified date - %% pathModifiedDate M2D2Y2 %%<br>
modified date default - %% pathModifiedDate %%<br>
path is none - %% pathisnone %%<br>
is folder - %% pathisfolder %%<br>
is discussion - %% pathisdiscussion %%<br>
is top - %% pathistop %%<br>
date - %% date M2D2Y2%%<br>
date default - %% date %%<br>
time - %% time H2I2 %%<br>
time default - %% time %%<br>
<pre>
12345%%pad 10%%xx
12345%%pad 2%%67890
12<b>34</b>5%%pad 10%%xx
</pre>
is unknown - %% userIsUnknown %%<br>
is sysop - %% userIsSysop %%<br>
is host - %% userIsHost %%<br>
is guest - %% userIsGuest %%<br>
is registered - %% userIsRegistered %%<br>
certificate - %% certificate %%<br>
creator line 2 - %% pathcreatorLine2 %%<br>
site title - %% sitetitle %%<br>
site URL - %% siteUrl %%<br>
parent URL - %% parentUrl %%<br>
back path - %% backpath %%<br>
serve pictures - %% servepictures %%<br>
serve info pictures - %% serveInfoPictures %%<br>
version - %% version %%<br>
platform - %% platform %%<br>
newdiscuss - %% newdiscuss %%<br>
» Links into the conference from your login page
If you want to include links into the conference in your login page, you should use a conditional
heading similar to the following:
%% if pathIsTop %%
...your normal text, including links into the conference...
%% else %%
Please log in.
%% endif %%
» The standard.tpl file
The standard.tpl file is a rich source of examples.
This file includes standard templates
for all of the whole-page templates. It also includes sample templates for customizing
folders and discussion messages.
» Taking a survey
You can use the form-processing and user/site variables supported by WCTL to take surveys
and show the results to date.
For an example, see the survey.tpl example included with the Web Crossing release.
You will find it in the same directory as the Web Crossing program and standard.tpl
file.
Copyright © 1996-98 by Lundeen & Associates, Alameda, California.