 |
| |
Internet Services Script Library - An Introduction
Contents
The Internet Services script library is a compilation of X-FC tags, global constants, functions, and commands used in web templates.
About X-FC tags
Internet Services uses X-FC tags as the primary way to bring together object data with the template for that object. These tags are used to indicate the places where Internet Services should insert any volatile data about the current session, user, or object.
For a complete listing of X-FC tags, including function, sytnax, and examples, see Internet Services X-FC tags reference.
Documentation conventions
X-FC tags use some standard conventions, such as:
• [] to indicate something is optional
• | to indicate 'OR' in a list of choices
• italics to represent arguments or variables replaced with an appropriate value
• [] (bolded square brackets) to indicate the brackets are not optional but are part of the syntax.
Coding conventions
In FirstClass web templates, we use blue for all X-FC tags to differentiate them from static code or other Internet Services Script syntax. In the event that an X-FC tag uses embedded IS Script (for example, if an argument to an X-FC tag is drawn from an Internet Services Script variable), then that embedded script is in magenta. As is the case with all our styling
conventions, this is just for convenience as it greatly improves the readability of the templates. Although not necessary, we recommend you follow this convention, as it greatly simplifies template debugging.
Note
X-FC tags and arguments are case insensitive.
A note on scope
Since X-FC tags are used to draw data about a variety of things, not all of them will work in all contexts. Generally speaking, X-FC tags can be classified into 2 categories:
• those that access data about the current session
• those that access data about the current object.
Session X-FC tags are available any template or server parsed file. They do not depend on the context of any particular object but on the context of the session. However, since there is a great deal of variety in the types of objects on a FirstClass server, many of the object X-FC tags are specific to a certain type of object. This means these X-FC tags are available only in templates for that specific object type.
The list of tags that follows is hierarchical; each tag group includes the functionality of the tag group below it. This means that the universal tags work in all templates as well as all server-parsed files, all global tags work in all container listing templates as well as all templates, and so on. Using an X-FC tag outside of its valid scope will usually cause it to return nothing.
Internet Services script global constants
Internet Services script global constants are a collection of variables with fixed values containing information about various aspects of the Internet Services HTTP module.
Generally, they are provided for compatibility with Apache's Extended Server Side Includes (XSSI) set of constants and, with a few exceptions, have no real use within Internet Services or the web templates.
These constants are used exactly like Internet Services Script variables, and can be used anywhere a variable can accept a #set command. For detailed information and definitions of global constants, see the Apache web site.
For a complete listing of Internet services script global constants, including function, sytnax, and examples, see IS script global constants reference in Admin Help.
Internet Services script functions
Internet Services Script functions can be used in any Internet Services Script expression to perform a variety of basic operations on strings.
The syntax for all functions is @functionname(arg1, arg2, ....). The number and type of arguments varies from function to function. Arguments to functions can be Internet Services Script variables, global constants, X-FC tags or constant values.
When including literal characters or strings in argument lists (either as a constant value or through an X-FC tag), they should be surrounded by quotes (') or back-quotes(`). It is best to use back-quotes in X-FC tags, since they are less likely to occur in user-defined strings.
Function names are not case-sensitive.
For a complete listing of Internet services script functions, including function, sytnax, and examples, see IS script functions reference in Admin Help.
Internet Services script commands
Internet Services Script commands are based on the Apache XSSI commands, and are designed to give a measure of flow control, dynamic storage and mathematical calculation to template processing. Additionally, some of these commands can be use to read or set some configuration data for the IS HTTP module.
For a complete listing of Internet services script global constants, including function, sytnax, and examples, see IS script commands reference in Admin Help.
Styling conventions
In FirstClass web templates we use red for all Internet Services Script commands, except #rem, to differentiate them from static code or other Internet Services script constructs. Like all other FirstClass styling conventions this is just for convenience, as it greatly improves the readability of the templates. There is no need for other editors to follow this convention, though we recommend it as it greatly simplifies template debugging.
All command and argument names are case sensitive.
Internet Services script expressions
An Internet Services script expression is any series of operations resulting in a single value. These can contain any number of fixed values (strings, numbers, and others), Internet Services script variables, Internet Services script functions, X-FC tags and operators. Order of operations is as specified by standard mathematical convention. Internet Services scripts do not support floating point operations.
Operators supported by Internet Services script expressions
• + standard addition
• - standard subtraction (or unary negation, depending on context)
• * standard multiplication
• /standard (integer) division
• % integer remainder (modulus)
• () used to alter order of operations
• ++ used only with Internet Services script variables; pre/post increment
• -- used only with Internet Services script variables; pre/post decrement
• = or == equality operator (since Internet Services script does not have an assignment operator, instead using the SET command, a single = sign is accepted as the equality operator as well as the C standard double == operator)
• != inequality operator
• < less than operator
• > greater than operator
• <= less than or equal to operator
• >= greater than or equal to operator
• ==~ string equality operator (case insensitive)
• !=~ string inequality operator (case insensitive)
• && AND operator
• !NOT operator (unary)
• !! OR operator
General rules for operators
Expressions surrounded by forward slashes ('/') are interpreted as regular expressions. To prevent regular expression parsing, surround the section in question with back slashes (').
Internet Services script string functions may fail if used on data that can be interpreted as a number. To prevent this, surround the data in single quotes (').
Internet Services scripts will evaluate any not zero, non-empty string value as 'true', for purposes of boolean analysis (in IF and WHILE statements).
|