[docs] docs - heins modified 2 files
docs@interchange.redhat.com
docs@interchange.redhat.com
Thu Jul 25 16:34:00 2002
User: heins
Date: 2002-07-25 20:33:51 GMT
Added: . icprogrammer.sdf
Removed: . icvars.sdf
Log:
* Retarget icvars.sdf as icprogrammer.sdf
Revision Changes Path
1.1 docs/icprogrammer.sdf
rev 1.1, prev_rev 1.0
Index: icprogrammer.sdf
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
!init OPT_LOOK=3D"akopia"; OPT_STYLE=3D"manual"=20
# $Id: icprogrammer.sdf,v 1.1 2002/07/25 20:33:51 mheins Exp $
!define DOC_NAME "Interchange Vars Reference"
!define DOC_TYPE ""
!define DOC_CODE "icvars"
!define DOC_VERSION substr('$Revision: 1.1 $', 11, -2)
!define DOC_STATUS "Draft"
!define DOC_PROJECT "Interchange"
!define DOC_URL "http://interchange.redhat.com/doc/icvars.html"
!define DOC_OWNER "1996-2002 Red Hat, Inc. {{EMAIL:interchange@redhat.com}}"
!define SHOW_COMMENTS 0
!define EXAMPLE_SESSION "6CZ2whqo"
!define EXAMPLE_DOMAIN "www.here.com"
!define EXAMPLE_CATALOG "mycatalog"
!define EXAMPLE_VLINK "mycatalog"
!define EXAMPLE_SECURE_DOMAIN "secure.here.com"
!define EXAMPLE_SKU "os28044"
!define EXAMPLE_PRICE 19.99
!define EXAMPLE_SIZE "15oz"
!define EXAMPLE_SIZE1 "10oz"
!define EXAMPLE_SIZE2 "20oz"
!define EXAMPLE_DESCRIPTION "Framing Hammer"
!build_title
H1:Interchange Variable Reference
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.=20
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.
H2: "Variable" configuration file definitions
Defined in interchange.cfg or catalog.cfg with the C<Variable>
configuration directive, these are accessed with:
!block example
Access in ITL with From
----------------------- -------------------
__VARNAME__ (catalog.cfg only)
@_VARNAME_@ (catalog.cfg, falls back to interchange.cfg)
@@VARNAME@@ (interchange.cfg only)=20
[var VARNAME] (catalog.cfg only)=20
[var VARNAME 1] (interchange.cfg only)=20
[var VARNAME 2] (catalog.cfg, falls back to interchange.cfg)
=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=
=20=20=20=20=20
Embedded Perl From
----------------------- -------------------
$Variable->{VARNAME} (catalog.cfg only)
$Tag->var('VARNAME') (catalog.cfg only)
$Tag->var('VARNAME', 1) (interchange.cfg only)=20
$Tag->var('VARNAME', 2) (catalog.cfg, falls back to interchange.cfg)
$Global::Variable->{VARNAME} (interchange.cfg only, only in Global code)=
=20
!endblock
Variables set with C<Variable> are not normally modified dynamically, though
you can do it as a part of the C<Autoload> routine or in other code. They w=
ill
not retain the value unless C<DynamicVariables> is in use.
H2: Scratch
User scratch variables are initialized whenever a new user session is
created. They start with whatever is defined in the C<ScratchDefault>
directive in catalog.cfg; otherwise they are not defined.
!block example
Access in ITL with Attributes
----------------------- -------------------
[scratch varname] Displays
[scratchd varname] Displays and deletes
=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=
=20=20=20=20=20
Embedded Perl From
----------------------- -------------------
$Scratch->{varname} Accessor
$Session->{scratch}{varname} Equivalent
!endblock
They can be set in several ways:
!block example
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
=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=
=20=20=20=20=20
Embedded Perl From
----------------------- -------------------
$Scratch->{varname} =3D 'VAL'; Sets to VAL
$Tag->tmp(varname); Set as temporary, must set value afterwards.
!endblock
H2: 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.
!block example
[calc]
#### DO NOT DO THIS!!!!
my $out =3D $CGI->{varname};
return $out;
[/calc]
!endblock
That will transform the value. If you wish to output a safe value but
keep the actual value intact, do:
!block example
[calc]
#### This is safe, makes value safe for rest of page
my $out =3D $Tag->cgi( { name =3D> 'varname', filter =3D> 'entities=
' } );
#### This is safe too, doesn't transform value
my $other =3D $Tag->filter($CGI->{varname}, 'entities');
### Now you can return stuff to the page
return $out . $other;
[/calc]
!endblock
The access methods are:
!block example
Access in ITL with Attributes
----------------------- -------------------
[cgi varname] Doesn't stop ITL code, don't use!
[cgi name=3Dvarname filter=3Dentities] Use this for safety
=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=
=20=20=20=20=20
Embedded Perl From
----------------------- -------------------
$CGI->{varname} Don't use for output values!
!endblock
They can be set as well.
!block example
Set in ITL with Attributes
----------------------- -------------------
[cgi name=3Dvarname set=3D"VAL"] Sets to VAL, VAL can be ITL, sh=
ows VAL
[cgi name=3Dvarname set=3D"VAL" hide=3D1] Sets to VAL, VAL can be ITL, =
no output
=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=
=20=20=20=20=20
Embedded Perl From
----------------------- -------------------
$CGI->{varname} =3D 'VAL'; Sets to VAL, next access to [cgi varname]
shows new value
!endblock
H2: Values
User form variables are initialized whenever a new user session is
created. They start with whatever is defined in the C<ValuesDefault>
directive in catalog.cfg; otherwise they are not defined except as
called out in other configuration directives, i.e. the obsolete
DefaultShipping.
!block example
Access in ITL with Attributes
----------------------- -------------------
[value varname] Displays
=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=
=20=20=20=20=20
Embedded Perl From
----------------------- -------------------
$Values->{varname} Accessor
!endblock
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 C<go> or C<return>, C<refresh>, or
C<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
!block example
Set in ITL with Attributes
----------------------- -------------------
[value name=3Dvarname set=3D"VAL"] Sets to VAL, VAL can be ITL, =
shows VAL
[value name=3Dvarname set=3D"VAL" hide=3D1] Sets to VAL, VAL can be ITL=
, no output
=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=
=20=20=20=20=20
Embedded Perl Attributes
----------------------- -------------------
$Values->{varname} =3D 'VAL'; Sets to VAL, next access to
[value varname] shows new value
!endblock
H2: 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 C<username>, which holds the logged-in user's username.
!block example
Access in ITL with Attributes
----------------------- -------------------
[data session username] Displays
=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=
=20=20=20=20=20
Embedded Perl From
----------------------- -------------------
$Session->{username} Accessor
!endblock
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.
H2: Values not transmitted from CGI
The following variables are never copied from CGI:
!block example
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
!endblock
You can define more with the C<FormIgnore> catalog.cfg directive.
H2: 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 C<Global> package is used to hold variables that are set at
program start and whose value is retained.
The C<Vend> package is used for variables that might be set at some
point during program execution, but that will always be reset to=20
undefined at the end of the transaction.
One example is $Vend::Cookie, which holds the raw cookie value
sent by the user.=20
If you are going to set or access these variables, you should be
getting your documentation from the source code. A few will be=20
shown here, but most will not.
H1: Variable listing
H2: Standard global (interchange.cfg) Variable values