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
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.
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.
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 /webxTemplates 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 /webxTemplates 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 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. |
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:
|
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.
After creating my own macro I am no longer able to open up Control Panel > Other Settings.
Web Crossing FAQ:
Sysop docs: