[docs] docs - pvinci modified icprogrammer.sdf
docs at icdevgroup.org
docs at icdevgroup.org
Tue Jan 6 23:46:22 EST 2004
User: pvinci
Date: 2004-01-07 04:46:22 GMT
Modified: . icprogrammer.sdf
Log:
Moved variable documentation to an icvariables.sdf along with variable definitions.
Revision Changes Path
1.9 +3 -251 docs/icprogrammer.sdf
rev 1.9, prev_rev 1.8
Index: icprogrammer.sdf
===================================================================
RCS file: /var/cvs/docs/icprogrammer.sdf,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- icprogrammer.sdf 30 Oct 2002 17:24:00 -0000 1.8
+++ icprogrammer.sdf 7 Jan 2004 04:46:22 -0000 1.9
@@ -1,10 +1,10 @@
!init OPT_LOOK="icdevgroup"; OPT_STYLE="manual"
-# $Id: icprogrammer.sdf,v 1.8 2002/10/30 17:24:00 mheins Exp $
+# $Id: icprogrammer.sdf,v 1.9 2004/01/07 04:46:22 pvinci Exp $
!define DOC_NAME "Interchange Programmer Reference"
!define DOC_TYPE ""
!define DOC_CODE "icprogrammer"
-!define DOC_VERSION substr('$Revision: 1.8 $', 11, -2)
+!define DOC_VERSION substr('$Revision: 1.9 $', 11, -2)
!define DOC_STATUS "Draft"
!define DOC_PROJECT "Interchange"
!define DOC_URL "http://www.icdevgroup.org/doc/icvars.html"
@@ -57,7 +57,7 @@
H2: Software installation
To follow along, it is recommended you get the latest release of
-Interchange (4.9.1 as of this writing), unpack it from the tar file, and
+Interchange (5.0 as of this writing), unpack it from the tar file, and
install it at a private directory. For the purposes of this document, it
will be assumed that Interchange is installed at C</usr/local/interchange>
and that the catalogs are installed at C</usr/local/catalogs>.
@@ -547,253 +547,5 @@
and the expensive initialization is done. This allows many tables
to be ready for access while only the ones used take up CPU and
IO time.
-
-H1: 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.
-
-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)
- [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::Variable->{VARNAME} (interchange.cfg only, only in Global code)
-!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 will
-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
-
- 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
-
- Embedded Perl From
- ----------------------- -------------------
- $Scratch->{varname} = '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 = $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 = $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]
-!endblock
-
-The access methods are:
-
-!block example
- 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!
-!endblock
-
-They can be set as well.
-
-!block example
- 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
-
-!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
-
- 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=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
-!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
-
- 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
-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. A few will be
-shown here, but most will not.
-
-H1: Variable listing
-
-H2: Standard global (interchange.cfg) Variable values
N:Copyright 2002 ICDEVGROUP. Freely redistributable under terms of the GNU General Public License.
More information about the docs
mailing list