WCTL Server-side Scripting

WCTL Loops

Introduction
Split
Break
Continue
Troubleshooting
Resources
Next Section

Introduction

In the previous section, you learned about conditionals - how to test for different conditions and take the appropriate action depending on the results.

In this section you will learn a powerful tool that allows you to automate repetitive tasks - a programming feature called looping.

To get started, place the following WCTL in your test folder header (go back to the intro section if you need help in doing this):

%% set number 1 %%

%% while number <=10 %%

%% number %% 

%% set number number + 1 %%

%% endwhile %%

Look at the result of executing this WCTL code by entering the test folder. You should see the numbers 1 through 10, each displayed on a separate line.

The while keyword marks the beginning of a loop section. The endwhile keyword marks the end of the section.

Let's go through this WCTL line-by-line to make sure we understand it all:

%% set number 1 %%
number is just the name of a variable. We store the value 1 in number because the first value we want to show is 1. (Programmers would say we have "initialized" number with the value 1.)
%% while number <=10 %%
The format of a while statement is
%% while condition %%
As long as the condition (which we studied in the previous section) is true, everything in the while section is repeated over and over again. In this example, so long as the value of number is less than or equal to 10, the while loop will continue to execute.
%% number %% 
The value of the variable number is output to the web page, followed by a tag - an HTML line break. If you left out the tag, all 10 numbers would run together on the same line.
%% set number number + 1 %%
Here we increment number (add 1 to number). If we left out this important line the value of number would never change and the condition in the while statement (number <=10) would always be true!
%% endwhile %%
This marks the end of the while loop.

Note: So, what would actually happen if you left out the %% set number number + 1 %% line? Would the while loop really never stop? Those of you who are courageous enough to try this, go ahead. Remove that line from your WCTL and see what happens.

A lot of lines with 1 are shown. An awful lot of lines. Hundreds in fact. But the while loop did, in fact, stop. <whew!>

To prevent mistakes like that from occurring (a situation known by programmers as an "infinite loop") Web Crossing limits the number of times a while loop can execute. You can increase or decrease the default value for this limit in Control Panel > General Settings > Maximum while-loop iterations per page:. If you are ever running a while loop and you feel that the loop is ending sooner than you expect and you cannot find any other reason for it, check that setting. It may be too low. One common situation where this might occur is if you have a large number of users and you want to loop through all your users.

In plain English, you would read this test WCTL as follows:

First set number to be 1.
While number is less than or equal to 10, output number and then increment number.

The concept is easy to understand. But why would you want to loop in webx?

Well, for example, lets say you wanted to generate a list of all the users and their email addresses. Using a while loop you could show one user and his or her email address on a line, or inside a nice-looking table.

Or suppose you didn't like the standard list of items in a folder, and you wanted to make your own list, formatted in a completely different way, perhaps using a multiple-column table. You could use a while loop and loop through all the items inside a folder, showing the items however you want.

There are really an unlimited number of situations for using while loops inside Web Crossing. And there are a few commands to help make things easier.

Using the split Command

Let's try a looping experiment in a folder to make all this clearer. First, create a test folder called Pets. Add as many discussions as you like to the folder. Figure 1 shows what our Pets folder looks like (yours can be different):

Figure 1 - A Test Pets Folder

For an experiment, lets use the names of all the discussions contained inside Pets to automatically create an interesting folder header. We can do this with the following WCTL code. Place the code inside the header and see for yourself how it works:

All about:

%% set items pathSelect %%

%% set item items.split %%

%% while item %%

   %% setPath(item) %%

   %% pathTitle %% and

   %% set item items.split %%

%% endwhile %%

other pets...

In our case, when we enter the folder, the folder header now says:

All about: cats and dogs and tropical fish and snakes and other pets...

Try it with your folder and see the results. Try adding more discussions and see how the folder header automatically add the names of the new discussions to the folder header.

Well, this example uses a number of concepts that are new to you, so lets examine this code line-by-line to make sure it is all clear:

All about:
This line is just ordinary text (it isn't between %% marks), so that text is just displayed as is.
%% set items pathSelect %%
pathSelect is a WCTL built-in variable whose value is a blank-delimited character string containing all the unique ID numbers for all the items at the present location.

For example, if you have three items (discussions) in your Pets folder pathSelect would have a value that looked something like ".ee6d6d6 .ee6d6d7 .ee6d6d8", though the actual numbers would be different for your Web Crossing site.

What this line does is initialize a local variable called items with the list of discussion IDs in the Pets folder. We can then use items in our while loop.

For a complete list of WCTL built-in variables, see the Web Crossing Sysop Docs web page.
%% set item items.split %%
You can add .split to the end of any variable. What Split does is split off the first word (words are separated by blanks) contained in the variable and leave the rest of the character string inside untouched.

For example, if the variable items contains the character string "today it is sunny" then the value of items.split is "today" and after the split items will contain the remaining string "it is sunny".

So what we are doing here is just setting the variable item to the first word in items - the unique ID number for the first discussion in the folder.
%% while item %%
So long as item contains a value the loop will repeat itself.
%% setPath(item) %%
Web Crossing is very conscious of "where you are" at any time and calls this location a path. Many WCTL commands use the current path when performing basic operations like displaying a title or author.

For example, the WCTL command %% pathTitle %% shows the title of whatever the current path is - the current folder, discussion, message, chat room or link name.

setPath is a WCTL command that sets your current location temporarily to the location of the folder, discussion, message or chat room that you specify inside the parentheses.

Here we are setting the path to item so that we can then use the pathTitle command to show the title of the discussion specified by the discussion number stored in item.
%% pathTitle %% and
Here we are just displaying the current path title (the title of the current discussion in our loop). The word and is outside %% marks, so it is treated as ordinary HTML - just a word to be output to the folder header.
%% set item items.split %%
At the end of the loop section we split off the next discussion ID number and store it in item. If there are no more discussion numbers in items, then a null value (an empty character string) is stored in item. That is how the while loop ends! The while loop is always testing to see if item contains a value. When it no longer contains a value, the while loop test condition is no longer true and the loop stops.
%% endwhile %%
The endwhile keyword marks the end of a while section.
other pets...
This is just ordinary HTML - extra words to add to the folder header after the while loop is done.

Well, this section threw quite a few new concepts at you - while loops, paths and the split command. Try this WCTL and variations of it in a test folder to get a better feel for how it works.

The break Command

Sometimes you want to finish up a while loop even before the test condition becomes false. For example, you might find some unexpected result in the middle of your loop and decide not to continue. You can use the break command to get out of a loop immediately. For example, consider the following WCTL code (that you can also try out in your test folder header):

%% set users selectUsers %%

%% set thisUser users.split %%

%% while thisUser %%

%% if thisUser.userName == "Hacker King" %%
Warning! Hacker King should not be a member! %% break %% %% endif %% %% thisUser.userName %% is a member in good standing %% set thisUser users.split %% %% endwhile %%


            Here we 
              are using split and while to loop to go through a list of users 
              one-by-one, displaying a message saying that the user is in good 
              standing. However if for some reason one of the user's names is 
              "Hacker King" we realize something is wrong and we break out of 
              the loop without finishing.
            The selectUsers 
              command returns a list of users. (There are lots of options that 
              can be used with the selectUsers command. You can read about them 
              all in the sysop 
              reference documents section on selectUsers. Without any options, 
              as we have used it here, selectUsers just returns the first 50 users 
              in your database.)
            
            The 
              continue Command
            Unlike 
              the break command, where you want to quit the while loop 
              entirely, the continue command gives you the ability to stop 
              executing from the middle of a while loop and continuing from the 
              start of the loop again.
            For example, 
              consider the following WCTL code that divides 10 by all the numbers 
              from -5 to 5:

            
             
               
                %% set n -6 %%
                %% while n < 5 %%
                   %% set n n + 1 %%
                   %% if n == 0 %%
                      %% continue %%
                   %% endif %%
                   10 divided by %% n %% is %% 10 / n %% <BR>
                %% endwhile %%
              
            
            Try this 
              in your test folder. You will see that a line is output for each 
              calculation and the case where n is equal to zero is neatly avoided 
              with the use of the %% continue %% statement.
            By the 
              way, all the results are truncated to integer (round) values; WCTL 
              only does integer arithmetic. If you need to do more sophisticated 
              numerical calculations you should use Web Crossing's Server-side 
              JavaScript.

            
            
The next 
  section describes you can create your own commands (macros) which can be 
  used from anywhere inside Web Crossing - not just in your test folder.
            Troubleshooting 
            I tried 
              the examples above, but when I look at the header all I see is the 
              WCTL itself, with all the double-percent marks. What am I doing 
              wrong?  
            
              Make 
                sure you have turned on WCTL evaluation in the Control 
                Panels > General Settings:

    
            
            Resources 
            Web Crossing 
              FAQ:
            
              WCTL
            
            Sysop docs: 
            
            
               syswctl.htm

              
            
            
WCTL 
  Concept Reference Page
            Web 
              Crossing Tech Support Forum
            Developer 
              Center
            WebX 
              Harbor