This section will introduce the If plugins used as attributes with <if> and <elseif>.
After reading this section you will have knowledge of the different plugin categories and the usage of the plugins.
The following sections will contain examples of how to use different plugins for creating dynamic web pages in many different ways.
The If plugins are sorted into four categories according to their function: Eval, Match, State and Utils.
The following parts will go through these categories and the corresponding plugins. We will look at the proper way of usage and some traps you might fall into.
The Eval category is the one corresponding to the regular tests made in programming languages, and perhaps the most used. They evaluate expressions containing variables, enities, strings etc and are a sort of multi-use plugins. All If-tag operators and global patterns are allowed (see The syntax of If tags).
Cookie and Variable plugins use a similar syntax. is can be any valid operator and name is the name of any defined or undefined variable(cookie). They first check if the named variable(cookie) exists, and if it does and a pattern(value) is specified, the expression will be evaluated. Variable is a general plugin while Cookie is for testing existence and/or values of cookies.
Please note that it is the name of the variable, not the entity representing it, that should be used. Here we receive an error from the RXML parser becase we used an entity instead of a variable name. The proper way to do the test above is <if variable='var.foo = 10'>.
Match is used in a similar way, but there are certain differences. The syntax is <if match="pattern">, where pattern could be any expression. We could use <if match='var.foo = 10'> although this is rather meaningless, since we would check if the name of the variable var.foo (or the string "var.foo") was equal to the string "10", which it obviously is not. The only thing that would return true in this case is another meaningless expression: <if match="var.foo is var.foo">.
Instead we should always use entities with Match, i.e. &var.foo;. In RXML, entities are used to represent the contents of something, e.g. a variable. An entity is written as a variable name enclosed with '&' and ';'. Above the name of the variable is var.foo, the value is '10' and the entity is &var.foo;. The entity is replaced by its content when parsed to HTML, in this case '10'.
Again, variable name goes with Variable and entity goes with Match.
A warning when testing patterns with whitespaces. If you want to test if the entity &var.foo; equals the string 'he is nice' and do like this...
...you won't get the expected result. This is because the Match plugin interprets the first valid operator after a whitespace as the operator to use. In the example above the test really is if 'he' equals 'nice is he is nice', which obviously is false. Rember that the string 'is' also is a valid operator.
Expr evaluates mathematical and logical expressions. The following characters only should be used in the expression:
If any other character is used there will be an error in the RXML parser. Therefore entities should be used, not the variable name, in a similar way as Match.
An example of expr showing that the regular rules of mathematics applies here. The expression evaluates correctly as1+2*3 == 1+6 == 7
and not as1+2*3 == 3*3 == 9
Note that the '==' operator must be used for 'equals', unlike the other Eval plugins. Also note that whitespaces around operators are not mandatory.
Clientvar extends the Supports plugin, see State below. It is used for tests of the client requesting the web page, e.g. a browser or a WAP phone. The following variables (var) are currently testable:
is can be any valid operator.
The Match category contains plugins that match contents of something, e.g. an IP package header, with arguments given to the plugin as a string or a list of strings.
Accept checks which content types the browser accepts as specified by it's Accept-header, e.g. 'image/jpeg' or 'text/html'.
Client compares the user agent string with the given pattern.
Domain and Ip plugins checks if the DNS name or IP address of the user's computer match any of the patterns specified. Note that domain names are resolved asynchronously, and that the first time the browser accesses a page containing <if domain>, the domain name might not have been resolved yet.
Language matches languages with the Accept-Language header.
Referrer checks if the Referrer header match any of the patterns.
State plugins check which of the possible conditions something is in, e.g. if a flag is set or not, if something is supported or not, if something is defined or not etc.
True and False are plugins used in exactly the same way as <then> and <else>. Should not be confused with the <true> and <false> tags.
Config tests if the RXML config named has been set by use of the <aconf> tag.
Pragma compares the HTTP header pragma with the given string.
Prestate checks if all of the specified prestate options, e.g. '(debug)', are present in the URL.
The Utils category contains additional plugins, each specialized in a certain type of test.
Date and Time plugins are quite similar. They check if today is the date "yyyymmdd" or if the time is "hhmm". The attributes before, after and inclusive may be added for wider ranges.
Exists checks if a file path exists in a file system. If the entered path does not begin with '/', it is assumed to be a URL relative to the directory containing the page with the <if exists> statement.
Group checks if the current user is a member of the group according the groupfile.
A useful Util plugin is User, that tests if the user accessing a site has been authenticated as one of the users specified. The argument any can be given for accepting any authenticated user.
This Section has presented the If plugins that is divided into four categories, Eval, Match, State and Utils, Utils and SiteBuilder, according to their function.
Eval plugins evaluate expressions as in regular programming languages, Match plugins match contents with arguments given and State plugins check which of two possible conditions is met. Utils plugins perform specific tests such as present date or time.
More details about If plugins are found in the Web Site Creator Manual.
The next Section, A basic example of <if>, will show an example of a basic usage of the Match plugin.