1. Interchange Special Variables
Interchange defines some special variables which control behavior. They can be of several types, and the conventions for using them depend on whether you have based your catalog and server on the standard "foundation" distribution.
We will distinguish between these by calling intrinsic variables CORE variables, noting the distribution variables as DISTRIBUTION, and noting the foundation catalog practices as FOUNDATION.
"Variable" configuration file definitions
Defined in interchange.cfg or catalog.cfg with the Variable configuration directive, these are accessed with:
Access in ITL with From ----------------------- ------------------- __VARNAME__ (catalog.cfg only) @_VARNAME_@ (catalog.cfg, falls back to interchange.cfg) @@VARNAME@@ (interchange.cfg only) [var VARNAME] (catalog.cfg only) [var VARNAME 1] (interchange.cfg only) [var VARNAME 2] (catalog.cfg, falls back to interchange.cfg) Embedded Perl From ----------------------- ------------------- $Variable->{VARNAME} (catalog.cfg only) $Tag->var('VARNAME') (catalog.cfg only) $Tag->var('VARNAME', 1) (interchange.cfg only) $Tag->var('VARNAME', 2) (catalog.cfg, falls back to interchange.cfg) Global subs / Usertags From ----------------------- ------------------- $::Variable->{VARNAME} (catalog.cfg only) $Tag->var('VARNAME') (catalog.cfg only) $Tag->var('VARNAME', 1) (interchange.cfg only) $Tag->var('VARNAME', 2) (catalog.cfg, falls back to interchange.cfg) $Global::Variable->{VARNAME} (interchange.cfg only, only in Global code)
Variables set with Variable are not normally modified dynamically, though you can do it as a part of the Autoload routine or in other code. They will not retain the value unless DynamicVariables is in use.
Scratch
User scratch variables are initialized whenever a new user session is created. They start with whatever is defined in the ScratchDefault directive in catalog.cfg; otherwise they are not defined.
Access in ITL with Attributes ----------------------- ------------------- [scratch varname] Displays [scratchd varname] Displays and deletes Embedded Perl From ----------------------- ------------------- $Scratch->{varname} Accessor $Session->{scratch}{varname} Equivalent Global subs / Usertags From ----------------------- ------------------- $::Scratch->{varname} Accessor $::Session->{scratch}{varname} Equivalent
They can be set in several ways:
Set in ITL with Attributes ----------------------- ------------------- [set varname]VAL[/set] Sets to VAL, no interpretation of ITL inside [seti varname]VAL[/seti] Sets to VAL, interprets ITL inside [tmpn varname]VAL[/tmpn] Sets to VAL, no ITL interpretation, temporary [tmp varname]VAL[/tmp] Sets to VAL, interprets ITL inside, temporary Embedded Perl From ----------------------- ------------------- $Scratch->{varname} = 'VAL'; Sets to VAL $Tag->tmp(varname); Set as temporary, must set value afterwards. Global subs / Usertags From ----------------------- ------------------- $::Scratch->{varname}='a' Sets to a
CGI
CGI variables are the raw data which comes from the user.
-
WARNING: It is a security risk to use these variables for display in the page.
You can use them for testing without worry, though you should never set their value into a database or display on the page unless you have processed them first, as they can have arbitrary values. The most common security risk is displaying HTML code, which allows remote scripting exploits like cookie-stealing.
[calc]
#### DO NOT DO THIS!!!!
my $out = $CGI->{varname};
return $out;
[/calc]
That will transform the value. If you wish to output a safe value but keep the actual value intact, do:
[calc]
#### This is safe, makes value safe for rest of page
my $out = $Tag->cgi( { name => 'varname', filter => 'entities' } );
#### This is safe too, doesn't transform value
my $other = $Tag->filter($CGI->{varname}, 'entities');
### Now you can return stuff to the page
return $out . $other;
[/calc]
The access methods are:
Access in ITL with Attributes ----------------------- ------------------- [cgi varname] Doesn't stop ITL code, don't use! [cgi name=varname filter=entities] Use this for safety Embedded Perl From ----------------------- ------------------- $CGI->{varname} Don't use for output values!
They can be set as well.
Set in ITL with Attributes ----------------------- ------------------- [cgi name=varname set="VAL"] Sets to VAL, VAL can be ITL, shows VAL [cgi name=varname set="VAL" hide=1] Sets to VAL, VAL can be ITL, no output Embedded Perl From ----------------------- ------------------- $CGI->{varname} = 'VAL'; Sets to VAL, next access to [cgi varname] shows new value
Values
User form variables are initialized whenever a new user session is created. They start with whatever is defined in the <ValuesDefault> directive in catalog.cfg; otherwise they are not defined except as called out in other configuration directives, i.e. the obsolete DefaultShipping.
Access in ITL with Attributes ----------------------- ------------------- [value varname] Displays Embedded Perl From ----------------------- ------------------- $Values->{varname} Accessor
They can be set as well, though the normal method of setting is from user input via form. If Interchange receives an action which performs the update of values (by default go or return, refresh, or submit), the value of CGI variables will be transferred to them subject to other considerations (FormIgnore settings, credit card variables, etc., discussed below).!block example
Set in ITL with Attributes ----------------------- ------------------- [value name=varname set="VAL"] Sets to VAL, VAL can be ITL, shows VAL [value name=varname set="VAL" hide=1] Sets to VAL, VAL can be ITL, no output Embedded Perl Attributes ----------------------- ------------------- $Values->{varname} = 'VAL'; Sets to VAL, next access to [value varname] shows new value
Session variables
You can also directly access the user session. Normally you don't set these values unless you are an experienced Interchange programmer, but there are several values that are frequently used.
One example is username, which holds the logged-in user's username.
Access in ITL with Attributes ----------------------- ------------------- [data session username] Displays Embedded Perl From ----------------------- ------------------- $Session->{username} Accessor
They can be set as well, but if you are experienced enough to contemplate doing these things you will easily be able to figure it out.
Values not transmitted from CGI
The following variables are never copied from CGI:
mv_todo
mv_todo.submit.x
mv_todo.submit.y
mv_todo.return.x
mv_todo.return.y
mv_todo.checkout.x
mv_todo.checkout.y
mv_todo.todo.x
mv_todo.todo.y
mv_todo.map
mv_doit
mv_check
mv_click
mv_nextpage
mv_failpage
mv_successpage
mv_more_ip
mv_credit_card_number
mv_credit_card_cvv2
You can define more with the FormIgnore catalog.cfg directive.
Global program variables
If you are programming a GlobalSub or global UserTag, you have access to all Interchange facilities including all the preset variables and configuration directives.
The Global package is used to hold variables that are set at program start and whose value is retained.
The Vend package is used for variables that might be set at some point during program execution, but that will always be reset to undefined at the end of the transaction.
One example is $Vend::Cookie, which holds the raw cookie value sent by the user.
If you are going to set or access these variables, you should be getting your documentation from the source code.