• include
• Assignment
• print
• if/then and iff
• repeat
• break and continue
• try and catch
• case
• return
• stop

An include statement is used to gain access to functions or scripts in another file and literally "include" them in your template. This is very helpful for building libraries of often-used functions that you wish to use among many different templates.

The form of an include statement is: include file-path;

The file path provided follows WebSiphon's standard file location algorithm, so if a full path is not provided, the following steps will be performed:

1. Current directory + file-path
2. Site root + file-path
3. "Templates" folder + file-path
4. "Templates" folder + file name

Keep in mind that all includes are performed prior to a template actually compiling and executing, so you cannot substitute the value of a variable to specify included files.

Dependencies between templates and any files they include are tracked, so if a change is made to any file which is included with another it will trigger a recompilation the next time the template is requested.

Examples:

1. // include the file "UtilFunctions.incl" located in the 
   // same folder as this template.
   include "UtilFunctions.incl";

2. // include a script library located in the "Templates" folder.
   include "FormValidation.lib";

An assignment statement is used to set a variable to the value of any given expression. Any changes made to WebSiphon's built-in variables may be performed using a standard assignment statement, but any change will only last for the duration of the template.

The form of an assignment statement is: variable = expression;

Items within a list may also be set with an assignment statement, but only one level deep so this is less-useful for heavily structured lists.

The basic form of a list item assignment statement is:

list_variable'index = expression;

Examples:

1. filename = "petunia.gif";

2. four = 2 + 2;

3. encoded_text = encodeURL(filename);

4. my_list = [1 2 3 4 5];
   my_list'3 = "hello";
   printList(my_list);
   
   >> [1 2 "hello" 4 5]

A print statement is used to append a value to the HTML text that is returned to the web server.

The form of a print statement is: print expression;

All values will be coerced to strings prior to actually printing. To gain greater control over the formatting of output values, use the as operator.

Examples:

1. print uppercase(client_address) & "<br>";
   
   >> ALQA.PURITY.COM<br>

2. // Multiple values can be concatenated using the & 
   // operator as is shown here, or simply separated using spaces 
   // as in the next example.
   x = 1.045;
   print (x as integer) & " " & (x as float);
   
   >> 1 1.045

3. // Same as above, using spaces rather than & 
   // operator.
   x = 1.045;
   print (x as integer) " " (x as float);
   
   >> 1 1.045

An if (or if-related) statement is used to conditionally include or exclude portions of SiphonScript and/or HTML. The complete statement structure is shown below, but note that items in brackets are optional. Parenthesis are not required around the boolean test expressions, but they often help make the statement easier to read if used.

The form of an if statement is: if boolean-test [then] ... [ else if boolean-test [then] ... ] [ else ... ] end [if];

Examples:

1. if client_address ends with ".fr" then
     print "Bonjour";
   else if client_address ends with ".jp" then
     print "Konichiwa";
   else
     print "Hello";
   end if;

2. if (fuddle/2 = juggle*2)
     it_works = true;
   else
     it_works = false;
   end if;

SiphonScript also supports the use of an iff statement, which may be used as a short-hand statement when you only want to perform a single statement if the condition tests true. Unlike a regular if statement, iff does not support use of then, else if, or else keywords nor does it require an explicit end.

The form of an iff statement is: iff boolean-test [then] expression;

Examples:

1. // Tests if the variable first_name is empty or a single 
   // space. If so, sets a form input error variable to true.
   // Compare with iff statement in the next example.
   if (first_name = "") or (first_name = " ") then
     form_input_error = true;
   end if;

2. // Same as above, using iff statement
   iff (first_name = "") or (first_name = " ")
     form_input_error = true;

A repeat statement is used to continually execute a section of SiphonScript or HTML. There are a number of different types of repeat statements, which all follow the same basic form, but allow you to specify extra actions to be automatically performed each time the loop is run.

The form of a repeat statement is: repeat number times ... end [repeat];

The code within this repeat statement will be run number times, where number is an integer value.

Example:

repeat 3 times
  print "hello, ";
end repeat;
print "goodbye!";

>> hello, hello, hello, goodbye!

To force a section of code to repeat until a specific condition is met, there are two different methods available.

The form of a repeat until statement is: repeat until boolean-test ... end [repeat]; The form of a repeat while statement is: repeat while boolean-test ... end [repeat];

A "repeat until" loop will repeat until boolean-test evaluates true. The "repeat while" loop is the exact opposite, whereas the repeat will continue until boolean-test evaulates false.

To create a loop that automatically increments a variable from one value to another, use this form:

The form of a repeat from/to statement is: repeat with variable from start to stop ... end [repeat];

Each iteration through this type of loop will increment variable to the next value in the range start to stop.

With version 2.0, SiphonScript now supports the reverse operation with the downto keyword.

The form of a repeat from/downto statement is: repeat with variable from start downto stop ... end [repeat];

Each iteration through this type of loop will decrement variable to the next value in the range start to stop.

Examples:

1. repeat with i from 1 to 10
     print i & " ";
   end repeat;
   
   >> 1 2 3 4 5 6 7 8 9 10
   

2. // Same as above, but reversed with downto
   repeat with i from 10 downto 1
        print i & " ";
   end repeat;
   
   >> 10 9 8 7 6 5 4 3 2 1
   

A final form of the repeat loop lets you iterate through the items contained in a list.

The form of a repeat in statement is: repeat with variable in list ... end [repeat];

This form of the repeat statement is very useful when working with lists, particularly when returning form results based on a database query as is exhibited in the last example below.

Examples:

1. repeat with i in [1 2 3 4 5]
     print i & " ";
   end repeat;
   
   >> 1 2 3 4 5

2. results = vRetrieve("users", "name", "all", "", ["name" "age"]);
   print "<ul>";
   repeat with the_user in results
     print "<li>" the_user'1 " (" the_user'2 " yrs old)\r";
   end repeat;
   print "<ul>";

See Also:

• Break and Continue

The form of a try statement is: try ...statements that may cause a Runtime Error... (or) throw(errCode, errString); catch ...statements executed if an error occurs.. (or) throw(errCode, errString); // Sends an exception to next higher nested try/catch block. end try;

try/catch will also catch any builtin-function Runtime errors.

Example:

See Also:

• throw()

The break and continue statements are used to better control execution within a repeat loop. Unlike some other languages, break is not supported within a case statement.

The form of a break statement is: break; The form of a continue statement is: continue;

A break statement will immediately exit any loop, whereas a continue statement will jump to the end of the loop and either repeat again or exit the loop if the last value or iteration has already been reached.

Example:

repeat with i from 1 to 10
  print i & " ";
  if (i < 5) then
    continue;
  else 
    print "STOP!";
    break;
  end if;
end repeat;

>> 1 2 3 4 5 STOP!

A case statement is a convenient method of conditionally executing a segment of script based on the value of a variable or expression. Similar in use to large if/then/else if statements, the case statement is more effecient and is much easier to use.

The form of a case statement is: case expression of value1, value2: ... value3: ... [otherwise]: ... end [case];

Any case value may be an expression, such as a function call, a string or list operation, and so forth. It is important to note that case item expressions are evaluated in lexical order, and once a match has been found any remaining expressions will not be evaluated. Thus, later script should not depend on a case item as having been executed or you may experience troubles.

Examples:

case secret_number of
  1, 2, 3: 
    print "the secret number is one, two, or three";
  "4":
    print "the secret number is four";
  otherwise:
    print "the secret number is not one, two, three or four";
end case;

A return statement sets the return value of a function or the main template script and immediately returns the output.

The form of a return statement is: return [expression];

If expression isn't provided, null will be substituted which will provide different results depending on if the return statement is within a function or the main template script. If return is used within the main template script, and expression is not provided, the output returned will be that generated using print statements and any HTML blocks in the template. If you wish to ensure that the output is empty, return an empty string.

Example:

// This example will return an image to the browser
image_path = template_path & "images:logo.gif";
image_data = readBinaryFile(image_path);
setMIMEType("image/gif");
return image_data;

A stop statement will immediately abort execution of the template and return the current HTML output.

The form of a stop statement is: stop;

contents prev next