XactCommerce




	Typical Applications
	Custom Development
	Private Backend
	XactScript Language
	Performance
	Deployment

XactScript Language < XactScript Object Control Language Tags

XactScript (Lexml version 2) language specification

(c)2004 XactSystems, Inc.

All XactScript control tags begin with an underscore (_) character. All other tags are specific to the renderer implementation, with the simplest renderer being the HTML renderer which simply passes through other tags as native HTML tags. Other renderers may process tags to produce PDF or PostScript or other types of output.

XactScript Control Tags

<_xactscript>:

Function:

Attributes:

name: This is an optional name for the document. This along with the author and version attributes are simply for documentation purposes as the moment although they may be used in the future for document indexing or revision control or other purposes.
author: This is an optional author name for the document.
version: This is an optional version for the document.
options: This attribute contains option expressions seperated by commas and can be used to toggle certain behaviors with regard to how the page is rendered, cached, delivered, etc. Some feature options are specific to a given renderer and will not function if the document is rendered using other renderers.

<_load>:

Function:

Attributes:

name: This is the name of the variable to load the object into. Name can be given with or without the proper $ character, but the "$variable" form is preferred to just "variable."
class: This is the name of the object class to create a new instance of. This name is totally dependant upon connection type. For example, using the "jvm" connection type (local Java virtual machine) the class argument would be a Java class name.
connection: The connection specifies how the object is to be reached. The default value is "jvm" meaning that we are loading a class from the local Java virtual machine. Other types that may be supported in the future might be "corba," "rmi," and "xmlrpc."
static: If this is set to "yes" then a static reference will be loaded. A static reference allows static methods in object classes to be called without actually creating an instance of the object. Not all connection types may support static references, and an error will be generated if you attempt to load a static reference for a connection type that doesn't support this feature.

Example:

<_load name="$customer" class="some.tree.location.CustomerManager" connection="jvm">
 <_arg name="cust_id" value="$customer.id:-1"/>
 <_arg name="cust_name" value="$customer.name:-1"/>
 <_arg name="cust_note">
 This customer was automatically created at <_print name="$time"/>.
 </_arg>
</_load>

<_arg>:

Function:

tags.

Attributes:

name: Name of argument

value: Optional value; if this attribute is not present than whatever is contained within tags will be parsed and counted as the argument. Any other tag including other control tags may be used inside arguments to generate arguments from other data. If the value of this attribute is a variable, whatever is contained within the variable will be passed as the argument. Note that variables will only be exapanded if this attribute is used. Variables will not be expanded from the tag body.

<_onerror>:

Function:

Attributes:

error: The name of the error to match, * and ? wildcards permitted.

Example:
error="*SQL*" would match any error whose name contains the string "SQL." Matches are case insensitive.

Examples:

<_call name="$string" method="substring" assign="$newstring">
 <_arg name="1" value="2"/>
 <_arg name="2" value="4"/>
 <_onerror error="*OutOfBounds*">
 The string has to be at least 4 characters!
 <_print name="$error.name"/>
 <_print name="$error.detail"/>
 </_onerror>
</_call>

<_call name="$customer" method="getCustomerId" assign="$customer.id">
 <_onerror error="*SQL*">
 <_set name="$session.errormsg" value="$error.message"/>
 A database error occurred. <a href="senderror.xact">Click here</a> to report this problem to the site administrator.
 <_end/>
 </_onerror>
</_call>

<_call>:

Function:

Attributes:

name: This is the variable name containing the object whose method is being called. This is the same variable that you specified when you used the <_load> tag to load the object.
asarg: The results of calls can be used as arguments to other calls using this argument. If a <_call> tag is placed inside a <_call> or method-calling <_if> statement with this attribute, the result of the call is passed to the previous call as an argument.
method: This is the name of the method within the object being called.
quiet: The quiet attribute affects methods that have a specified argument to automatically recieve the output stream. This can be configured in the configuration of user-friendly argument names (see section below on argument names). If this attribute is 'yes' then a null output rather than the real output will be passed for this argument if it is present. Otherwise this attribute has no effect.
echo: If this attribute is 'yes' then the return value of the method being called will be echoed in string form if possible. If this is not possible, nothing will be echoed. (Whether or not this is possible may depend on object type and/or the connection type through which this object is being reached.)
assign: This attribute designates the name of a variable to assign the return value of this method to. If this attribute is not present, the return value will be assigned to the default variable "$result".

<_if>:

Function:

Attributes:

expr: Comparison expression (see section on if expressions below).
cs: Toggles case sensitivity for string comparisons; default is 'no'.

If Expression Syntax:

Allowed comparison operators:

'meta-values'

Expresssion Examples:

"($variable eq 1) or ($variable eq 2)"
"$somevalue ne 0"
"$sentence eq Hello\ my\ name\ is\ John"
"($somevalue is not number) and ($somevalue is not empty)"
"(($somevalue gt 0) and ($anothervalue gt 0)) or ($i eq 1)"

If Tag Examples:

<_if expr="($customer.id eq 0) or ($customer.name is empty)"/>
Customer information was not entered correctly. Please
press the Back arrow on your browser and re-enter.
<_endif/>

<_if expr="$form.password ne $customer_record.password" cs="yes"/>
Your password is incorrect.
<_endif/>

<_if name="$order" method="gettotal" assign="$ord_total" expr="$result eq 0"/>
Your order total is 0.
<_else/>
Your order total is <_print name="$ord_total"/>
<_endif/>

<_elseif>:

Function:

<_else>:

Function:

Attributes:

<_endif>:

Function:

Attributes:

<_set>:

Function:

Attributes:

name: Name of variable (with $ sign) to assign value to. (See variables section below for more information on variable behavior.)
value: If this attribute is present, the string contained within it will be assigned to the variable. If this attribute is not present, whatever is contained within the <_set> opening and closing tags will be assigned to the variable. This may include other control tags, text, and native tags.

<_unset>:

Function:

Attributes:

name: Name of variable to remove.

<_print>:

Function:

Attributes:

name: Name of variable to print.
format: Format can be one of the following:

normal

urlencode / urldecode

(This & That?

This+%26+That%3F)

xmlescape / xmlunescape

(This & That?

This & That?)

lowercase / uppercase

(Hello there.

HELLO THERE.)

jsescape

(He's not really "there".

He\'s not really \'\'there\'\'.)

round

(432.5436

432)

money

(432.5436

432.54, 3

3.00)

hex

(545354542542

7ef9a9edce)

propernouns

(Hello it is nice to meet you.

Hello it is Nice to Meet You)

plural

(friend

friends, knife

knives, party

parties)

hrfilesize

(324232

316 K, 423523643

403.0 MB)

removereturns

Example:

<_print name="$total" format="money"/>

<_stepthrough>:

Function:

Attributes:

through: Variable (must be an array or List) to iterate over.
with: Variable to use as iteration variable. Each element of the array or List will be assigned to this variable for each iteration. This variable can then be used inside the iterator to access the current element.
counter: A numberic counter starting at 1 will be assigned to this variable if this attribute is present.
mastercounter: This counter will be independent of recursion using the <_stepinto> tag.
startat: Index in the array or list to start at. Default is zero.
count: Maximum number of elements to iterate through. Default is zero which means no limit (iterate through all remaining items in array or List).

Examples:

List of all customers in system:
<_stepthrough through="$customers" with="$c" counter="$cnt" startat="0">
 
 Customer name: <_print name="$c.name"/> 
 Customer description: <_print name="$c.description"/> 
 Customer ID: <_print name="$c.id"/> 
 
</_stepthrough>


<_stepthrough through="$form" with="$f">
 <_print name="$f.key"/> = <_print name="$f.value"/>
</_stepthrough>


<_stepthrough through="$session" with="$s">
 <_print name="$s.key"/> = <_print name="$s.value"/>
</_stepthrough>

<_stepinto>:

Function:

Attributes:

into: This is the name of the variable to recurse into.
depthcounter: This is the name of a variable to keep track of the current depth. (optional)

Example:

<_stepthrough through="$items" with="$i" counter="$cnt">
 <_repeat counter="$n" count="$depth:0"> </_repeat>
 Item: <_print name="$i.name"/>
 <_stepinto into="$i.subitems" depthcounter="$depth"/>
</_stepthrough>

<_repeat>:

Function:

Attributes:

count: Number of times to repeat.
counter: Variable to use as counter (starts at 1).

<_break>:

Function:

Attributes:

<_jumpto>:

Function:

Attributes:

to: New index to set location to. If this is out of bounds, the index will be set to the nearest boundary (e.g. a negative number would set the index to zero and a number greater than the maximum number of items in the List or array would set the index to the number of items and stop iteration).

<_sub>:

Function:

Attributes:

name: Name by which this subroutine can be called with a <_gosub> tag.
transparent: If this is "yes" (the default) then the contents of this <_sub> tag will not be executed inline as the parser passes over it. If this is "no" the tag will act like a marker still but it's contents will be executed regardless at least once as the parser passes over it.

<_gosub>:

Function:

name: Name of sub to call. A fatal error will occur if there is no sub declared by that name. Keep in mind that parsing is linear, so a sub declared below a <_gosub> will not be available to it.

<_include>:

Function:

Attributes:

file: Relative or absolute pathname of file to include.
parsed: If this is "yes" (the default) then the file will be parsed as an XactScript document.
override: This overrides whatever maps exist in the included page with other maps specified. For example, if you wish to include an XactScript page, but use a separate $form and $session map already defined, you could use <_include file="somepage.xact" parsed="yes" override="$form:$newform,$session:$newsession"/>

<_template>:

Function:

Attributes:

name: Anything you like; this name is simply used to identify this template internally. This name must be unique in the document in which it appears.
frequency: This is the frequency for template refresh, in seconds.
dependencies: This is a comma seperated list of variable names from whose contents a fingerprint will be computed. Multiple templates will be stored, each representing a different value of this fingerprint. This should be used if the templated code varies only slightly over a few conditions. Avoid using a condition that changes often, since this would defeat the purpose of the template tag altogether.

<_math>:

Function:

Attributes:

expr: A valid math expression.
assign: Variable name to assign result to. If blank, result will not be assigned to any variable.
result: This controls the format of the result variable. Possible values are round, integer, money, decimal, roundup, or rounddown. The default is decimal.
echo: If this is "yes", the result will be printed. Default is "no".
echoformat: This controls the printed format of the result. Possible values are round, integer, money, decimal, roundup, or rounddown. The default is decimal.

Example:

Your new total is:
$<_math expr="$order_total + $new_item_price" echo="yes" echoformat="money"/>

Variable Syntax

XactScript allows powerful and easy manipulation of variables within documents. Simple variables as well as "Maps" (variables containing multiple internal fields) can be manipulated simply and easily. The variable syntax is:

$variablename[.mapfieldname][:default]

If "mapfieldname" is present, then this variable name refers to a field inside a Map variable. If the variable name is not defined or is not a Map variable, it will be automatically redefined as a Map variable. If the default value is present, this value will be substituted in the event that the variable (or Map field) is not defined.

Examples:

$user.first_name:Unknown

Return first_name field in Map stored in variable $user and return "Unknown" if $user or the first_name field inside it are not defined.
$user.first_name:$user.name:Unknown

Return first_name field in Map stored in variable $user but evaluate $user.name:Unknown if undefined.
$counter

Simply return value of simple (non-Map) variable $counter or null if not defined.
$counter:0

Return $counter or 0 if not defined.
Predefined/System Variables

Various renderers in the XactScript engine may define certain variables as predefined and available to all documents. Here is a list of currently supported predefined variables for all current renderer options.

For all renderers:

$system.osversion -

Operating system type and version string

$system.jvmversion -

Java virtual machine version

$system.time -

Time in human-readable form

$system.timeutc -

Time in UTC64 (ms)

$system.machinename -

Name of this machine or 'unknown' if it wasn't set

$system.usercount -

Number of concurrent users currently on

$system.userlimit -

Maximum number of licensed users

$system.xactscriptversion -

XactScript engine version

$chars.tab -

A Tab Character (\t)

$chars.return -

A Return Character (\n)

$chars.linefeed -

A Line Feed Character (\r)

For HTML and XHTML renderers:

$requestmethod -

GET, PUT, POST, etc.

$requestsecure -

Is this connection secure; true or false

$requestreferer -

URL of referring page

$remoteaddr -

IP address of remote user

$remoteuser -

Remote user (only set if http auth is being used)

$remoteagent -

User's browser ID string

$thisurl -

URL of the current page

$thishost -

Server Host Name

$servername -

Server Name

$serverport -

Server Port

$thispage -

File Path of this page on server

$thispagedir -

Directory Path where page resides on server

$thispagename -

This Page's File Name

$thispage_canonical -

Canonical File Path of this page on server

$thispagedir_canonical -

Canonical Directory Path where page resides on server

$invoker -

Class name of invoker for this document

$outputtype -

Output MIME type

$webtools -

Instance of com.xactsys.xactscript.utils.WebTools

$sessionid -

Session ID

$session -

Session Map

$form -

Form variables Map (read only)

$cookie -

Cookies Map

$forminfo.resubmit -

Double-tap protection - checks whether a submitted form has already been submitted (true/false) (read only)

$forminfo.age -

Age in seconds since the submitted form was originally generated (read only)

$forminfo.sameorigin -

checks whether the original submitted form was from the same IP address and User Agent (true/false) (read only)

$on_error_push_url -

URL to push to when an error ocurrs on a page

Printable Version