|
WCTL
Server-side Scripting
WCTL
Macros
Introduction
Macros
Turning a Script into a Macro
Calling your Macro with the use Command
Calling your Macro from a URL
Troubleshooting
Resources
Next Section
Introduction
In the
previous section, you learned
about while loops - how to automatically execute large numbers
of repetitive commands, such as displaying all the user names,
or using the titles of all the discussions in a folder in order
to generate a folder header automatically.
In all
the examples to date, you tested your WCTL by placing it directly
in a test folder (as described in the intro
section). In this section you will learn how to create WCTL
scripts that can be executed from anywhere. And by anywhere, we
mean anywhere. You will be able to use your WCTL scripts
inside any folder or discussion header. You will even be able
to call your scripts from outside Web Crossing, using a special
URL syntax. This will allow you to use your scripts as CGI, for
form processing or to add new commands to your Web Crossing site.
Macros
A macro
is just a named WCTL script. All the WCTL scripts we have practiced
with so far in previous sections did not have names; they were
just raw WCTL lines of code placed directly in a test folder's
header.
If you
give a WCTL script a name then you can use that name in different
locations to execute the script. In programming lingo we would
refer to this as "calling a macro" or "using a macro" or "executing
a macro."
Conceptually
this is pretty easy. You are already somewhat familiar with WCTL
scripts. All you have to do to create a macro is to give your
script a name by placing it in a macro section.
For example,
let's create a script first that greets a user, displays the date
and tell the user whether or not there are new messages to read
or not. After testing it we will turn it into a macro.
To test
this script, first place the following WCTL in your test folder
header (go back to the intro section
if you need help in doing this):
%% if user.userIsRegistered %%Welcome, %% user.userName %% <BR>It is now %% date %% <BR>%% if user.userNewMessages %%There are new messages you have not read yet <BR>%% else %%There are no new messages <BR>%% endif %%
%% endif %%
Note
that this WCTL script has two if sections, so there are
two endif statements to close things off properly. Programmers
call this "nested ifs."
Enter
the test folder. If you enter as a registered user then you are
greeted with your user name, today's date and a message telling
you if you have new, unread messages or not. You can find more
details about the %% date %% command and %% user.userNewMessages
%% in the online
sysop reference manual section dealing with commands and variables.
Turning
a Script into a Macro
Now that
you see how this works, let's turn your script into a macro so
you can call it (execute it) from different places.
|
Note:
Macros are stored on your Web Crossing server machine in
the Web Crossing folder (or directory, as they are called
on Unix machines). You must have the access to this folder
(including the ability to add new files to the folder) in
order to be able to create or change macros.
|
After
you are sure you can find the Web Crossing Web Crossing
folder on the server machine, and you know how to add new files
to the folder, do the following steps to turn your script into
a macro:
(1)
Create a new text file called mymacro.tpl. Add the following
text to mymacro.tpl:
%% macro myMacro %%
%% if user.userIsRegistered %%Welcome, %% user.userName %% <BR>It is now %% date %% <BR>%% if user.userNewMessages %%There are new messages you have not read yet <BR>%% else %%There are no new messages <BR>
%% endif %%
%% endif %%
%% endmacro %%
By surrounding
your script with the lines:
%% macro myMacro %%
%% endmacro %%
we are
creating a macro with the name myMacro.
|
Note:
When you create mymacro.tpl make sure it is an ordinary
text file, not a word processor file with special formatting
commands in it. For example, if you use Microsoft Word to
create mymacro.tpl, be sure to save the file as ordinary
text. You will find that a word processor is inconvenient
for editing macro files; you will want to acquaint yourself
with a good text editor instead. A text editor is light
and fast and creates ordinary text files instead of formatted
documents. Every programmer has one. For Mac users, check
out BBEdit or TexEdit. Windows users can use the Notepad
application in your Program
> Accessories
menu. Unix users tend to like using the ancient, but quick
and easy-to-use (once you get used to it) editor "vi."
|
(2)
Now transfer the mymacro.tpl file over to your Web Crossing
folder on the server machine, using whatever method you normally
use to transfer files (FTP, network folder sharing, etc.)
|
Note:
When transferring ordinary text files, such as webx.tpl
files, from your computer to the Web Crossing server, use
FTP if your computer and the Web Crossing server are different
platforms - and make sure that you are sending your files
in text (ASCII) mode, not binary mode. Mac, Windows and
Unix all use different codes to indicate the "linebreak"
at the end of lines. FTP will automatically adjust text
files when transferring them to that the linebreaks are
correct on the receiving machine. If you are not careful
and transfer, for example, a Mac text file as binary to
a Unix server the linebreaks will be funny. This could affect
the execution of your macro.
|
(3)
Look for a file in your Web Crossing folder with the filename
webx.tpl. This very important file contains all your macros.
If webx.tpl exists open it for editing. If webx.tpl
does not exist, create a new one.
(4)
Using any text editor, add the following line to the beginning
or end of webx.tpl, save your changes to webx.tpl and quit
the editor.
<!--#Include File="mymacro.tpl"-->
|
Note:
You could also have added %% macro myMacro %% through
%% endmacro %% directly to the webx.tpl file
without creating a separate file. There is nothing wrong
with doing that. But the advantage of keeping your macros
in separate files is that it is real easy to turn off just
one macro - all you have to do is delete the
<!--#Include File="mymacro.tpl"-->
line
and reset the file cache.
|
(5)
In the Control Panel (near the bottom),
make sure that webx.tpl templates are currently turned on
(if not, turn them on) and click on the Reset the file cache
link, as shown in figure 1:
Figure
1 - resetting the file cache
Calling
your Macro with the use Command
Now you
are ready to use your myMacro macro somewhere! Go back
to your test folder. This time replace any WCTL scripts that might
still be in the header with just this line:
%% use myMacro %%
The use
command is a special WCTL command that calls a customized macro.
Look at the result by entering the folder. It is the same as before!
You are getting the same greeting, time and notice about new messages
by calling your own macro!
|
The
confused reader will, at this point, probably say, "Well
whoopee do. I've managed to take a simple task that I accomplished
previously by just entering some WCTL into a header and
instead accomplished the same thing by half-a-dozen complicated
tasks. What was the point?
First,
if you do say this you should congratulate yourself. It
means you now consider writing a WCTL script a simple task!
(^_^)
Now
think of the possibilities. Instead of executing the script
just in your test folder, you could execute it any number
of places - in other folders, in your login greeting, in
your site banner, etc. If you had to copy the same WCTL
script everywhere you wanted to use it, what would you do
if you needed to change the WCTL script? You would have
to remember every place you put it and make the same changes
everywhere! But by turning your script into a macro, you
now have the ability to make changes in just one place and
have your changes take effect everywhere the macro is used.
That is just one of many advantages of making macros. You
will see lots of possibilities soon. Trust me.
|
Calling
your Macro from a URL
One neat
thing you can do at this point is execute your macro directly
by entering a special URL of the form:
http://yourdomain.com/cgi-bin/webx?myMacro@@
where
yourdomain.com/cgi-bin/webx should be replaced by the actual
URL you normally use to access your Web Crossing server. Go ahead
and try it! You should see the same result as when executing the
macro with the use command inside a folder header.
For more information on Web Crossing URLs, see urls.html.
|
Note:
You have to admit this is pretty neat. You can create your
own commands and execute them using the use command
or you can create your own links - inside Web Crossing
or anywhere in the world (!) and have your Web Crossing
server execute them.
In
other words, you can think of your Web Crossing server as
not just a web conferencing and chat system, but also as
a full fledged web application development tool that runs
applications over the Internet! Your applications all have
full access to the conferencing and email features of Web
Crossing, including full access to your conference and user
database. It is like a CGI programming tool on steroids
- with the hard part (web conferencing and chat and all
the other features of Web Crossing) already built in!
|
Let's
review the procedure for creating a macro once more, briefly,
in an easy-to-remember format:
-
Create
a macro inside a text file (example: mymacro.tpl).
The .tpl file extension, by the way, stands for "template".
-
Move
the text file over to the Web Crossing folder.
-
Modify
webx.tpl to include your new file.
-
Reset
the file cache to read in your new macro.
That's
all there is to it!
|
A
couple of important notes:
-
You
can have as many macros as you want in any .tpl file.
It is convenient to group sets of common macros together
- like macros dealing with login and registration,
etc., all in one file.
-
Don't
forget to reset the file cache whenever you change
any of your macros!
|
This
last note is so important that we have placed it in its own
box in a different color!
|
A
very important note! Creating your own macros is a very
powerful tool. It is also easy to make mistakes and create
macros with unintended results. Some of these results might
even interrupt the normal execution of your Web Crossing
site!
If
something seems to be going wrong with your Web Crossing
server, the first thing you should do (please remember this!)
is to Turn
Off Your Macros (Templates)
in the Control
Panel.
Turning
off webx.tpl templates removes all your customized macros
from execution.
|
The next
section will show you how to use macros to do form processing,
such as taking the data from a form and sending the contents by
email to yourself. It is a relatively easy task to accomplish
using WCTL macros, and such a common thing to do that it is worth
looking over that section. After you have completed that section
we will conclude with a section on templates,
the macros that determine the basic look-and-feel and operation
of the Web Crossing folders and discussions themselves.
Troubleshooting
After
creating my own macro I am no longer able to open up Control
Panel > Other Settings.
- Control
Panel > Other Settings
is controlled by webxextn.tpl, which loads after webx.tpl.
If you have a syntax error in one of your macros, webxextn.tpl
will not load correctly and thus you will not be able to see
the Other Settings. You should
check your webx.tpl (and included .tpl files)
to find the macro causing the problem. Handy
hint: Check Other Settings
if you are experiencing a problem with your macros. This will
tell you right off if your macros even loaded correctly!
Resources
Web Crossing
FAQ:
Sysop
docs:
WCTL
Concept Reference Page
Web
Crossing Tech Support Forum
Developer
Center
WebX
Harbor
|
