[interchange-docs] xmldocs - docelic modified 2 files
docs at icdevgroup.org
docs at icdevgroup.org
Tue Jun 20 18:53:42 EDT 2006
User: docelic
Date: 2006-06-20 22:53:42 GMT
Modified: glossary scratch variable
Log:
* Write/update variable/scratch glossary entries
Revision Changes Path
1.4 +188 -15 xmldocs/glossary/scratch
rev 1.4, prev_rev 1.3
Index: scratch
===================================================================
RCS file: /var/cvs/xmldocs/glossary/scratch,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- scratch 9 Jun 2005 12:02:43 -0000 1.3
+++ scratch 20 Jun 2006 22:53:42 -0000 1.4
@@ -1,27 +1,200 @@
-To each new visitor, Interchange assigns an unique
-<firstterm>session ID</firstterm> and (among other things) creates a
+
+When &IC; creates a user &glos-session;, it also initializes the
<firstterm>scratch space</firstterm> (also referred to as
the <emphasis>scratchpad</emphasis>) to hold various variables
which are valid throughout the session.
-</para>
-<para>
+</para><para>
+By default, the scratch space is created empty. You can define default
+scratch variables and their values using &conf-ScratchDefault;.
+</para><para>
Once defined, a scratch variable will exist either until it is explicitly
-deleted, or the session terminates.
-</para>
-<para>
+deleted (most probably using &tag-scratchd; tag) or the session ends.
+The exception are so-called "temp" variables, which are normal scratch
+variables (they live in the scratch space), but are automatically deleted
+when page processing ends. You can use them for saving intermediate results
+that you calculate and display, and then want &IC; to automatically forget.
+</para><para>
The catalog programmer has complete control over the scratch variables.
The following tags manipulate the scratch space:
<tag>set</tag>,
<tag>seti</tag>,
<tag>tmp</tag>,
<tag>tmpn</tag>,
-<tag>scratch</tag>,
-<tag>scratchd</tag>,
-</para>
-<para>
-Scratch variables are also used in form processing. See the
-<tag>button</tag> tag for examples.
+<tag>scratch</tag> and
+<tag>scratchd</tag>.
+</para><para>
+
+
+
+Here's a complete list of ways to set scratch variables.
+</para><para>
+
+<emphasis role='bold'>In ITL:</emphasis><sbr/>
+<informaltable pgwide='1' frame='none'>
+
+ <tgroup cols='2' align='left'>
+ <colspec colname='how'/><colspec colname='from'/>
+
+ <thead>
+ <row><entry>Set syntax</entry><entry>Attributes</entry></row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>[set <replaceable>VARNAME</replaceable>]<replaceable>VALUE</replaceable>[/set]</entry>
+ <entry>&glos-ITL; code in value body is not &glos-interpolate;d</entry>
+ </row>
+ <row>
+ <entry>[seti <replaceable>VARNAME</replaceable>]<replaceable>VALUE</replaceable>[/seti]</entry>
+ <entry>&glos-ITL; code in value body is &glos-interpolate;d</entry>
+ </row>
+ <row>
+ <entry>[tmp <replaceable>VARNAME</replaceable>]<replaceable>VALUE</replaceable>[/tmp]</entry>
+ <entry>&glos-ITL; code in value body is &glos-interpolate;d, variable is temporary</entry>
+ </row>
+ <row>
+ <entry>[tmpn <replaceable>VARNAME</replaceable>]<replaceable>VALUE</replaceable>[/tmpn]</entry>
+ <entry>&glos-ITL; code in value body is not &glos-interpolate;d, variable is temporary</entry>
+ </row>
+ </tbody>
+
+ </tgroup>
+</informaltable>
+
+
+
+<emphasis role='bold'>In embedded Perl:</emphasis><sbr/>
+<informaltable pgwide='1' frame='none'>
+
+ <tgroup cols='2' align='left'>
+ <colspec colname='how'/><colspec colname='from'/>
+
+ <thead>
+ <row><entry>Set syntax</entry><entry>Attributes</entry></row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>$Scratch->{<replaceable>VARNAME</replaceable>} = '<replaceable>VALUE</replaceable>';</entry>
+ <entry>Set value</entry>
+ </row>
+ <row>
+ <entry>$Tag->tmp('<replaceable>VARNAME</replaceable>');</entry>
+ <entry>Mark scratch variable as temporary, must set a value afterwards</entry>
+ </row>
+ </tbody>
+
+ </tgroup>
+</informaltable>
+
+
+
+<emphasis role='bold'>In GlobalSub code or usertags:</emphasis><sbr/>
+<informaltable pgwide='1' frame='none'>
+
+ <tgroup cols='2' align='left'>
+ <colspec colname='how'/><colspec colname='from'/>
+
+ <thead>
+ <row><entry>Set syntax</entry><entry>Attributes</entry></row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>$::Scratch->{<replaceable>VARNAME</replaceable>} = '<replaceable>VALUE</replaceable>';</entry>
+ <entry>Set value</entry>
+ </row>
+ </tbody>
+
+ </tgroup>
+</informaltable>
+
+
+</para><para>
+
+
+Here's a complete list of ways to get scratch variables.
+</para><para>
+
+<emphasis role='bold'>In ITL:</emphasis><sbr/>
+<informaltable pgwide='1' frame='none'>
+
+ <tgroup cols='2' align='left'>
+ <colspec colname='how'/><colspec colname='from'/>
+
+ <thead>
+ <row><entry>Get syntax</entry><entry>Attributes</entry></row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>[scratch <replaceable>VARNAME</replaceable>]</entry>
+ <entry>Display value</entry>
+ </row>
+ <row>
+ <entry>[scratchd <replaceable>VARNAME</replaceable>]</entry>
+ <entry>Display value, delete scratch variable</entry>
+ </row>
+ </tbody>
+
+ </tgroup>
+</informaltable>
+
+
+
+<emphasis role='bold'>In embedded Perl:</emphasis><sbr/>
+<informaltable pgwide='1' frame='none'>
+
+ <tgroup cols='2' align='left'>
+ <colspec colname='how'/><colspec colname='from'/>
+
+ <thead>
+ <row><entry>Get syntax</entry><entry>Attributes</entry></row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>$Scratch->{<replaceable>VARNAME</replaceable>};</entry>
+ <entry>Get value</entry>
+ </row>
+ <row>
+ <entry>$Session->{scratch}{<replaceable>VARNAME</replaceable>};</entry>
+ <entry>Equivalent</entry>
+ </row>
+ </tbody>
+
+ </tgroup>
+</informaltable>
+
+
+
+<emphasis role='bold'>In GlobalSub code or usertags:</emphasis><sbr/>
+<informaltable pgwide='1' frame='none'>
+
+ <tgroup cols='2' align='left'>
+ <colspec colname='how'/><colspec colname='from'/>
+
+ <thead>
+ <row><entry>Get syntax</entry><entry>Attributes</entry></row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>$::Scratch->{<replaceable>VARNAME</replaceable>};</entry>
+ <entry>Get value</entry>
+ </row>
+ <row>
+ <entry>$::Session->{scratch}{<replaceable>VARNAME</replaceable>};</entry>
+ <entry>Equivalent</entry>
+ </row>
+ </tbody>
+
+ </tgroup>
+</informaltable>
+
+</para><para>
+One other predefined use for scratch variables is to hold form processing
+code (code that is executed on users' form submission).
+See the <tag>button</tag> tag for examples.
-<!--
-howto define/call scratch sub -->
1.2 +201 -0 xmldocs/glossary/variable
rev 1.2, prev_rev 1.1
Index: variable
===================================================================
RCS file: /var/cvs/xmldocs/glossary/variable,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- variable 20 May 2005 15:24:24 -0000 1.1
+++ variable 20 Jun 2006 22:53:42 -0000 1.2
@@ -1,3 +1,204 @@
+
+In general terms, a <emphasis>variable</emphasis> is "that which is variable; that
+which varies, or is subject to change".
+</para><para>
+In computer terms, variables have a name most of the time, so that you can
+refer to them. For example, variable <literal>$amount</literal> might have
+a value of <literal>10</literal>, and that value may change over time.
+</para><para>
+Basically, all programs work with (a lot of) variables, be it to define
+their behavior or store intermediate results.
+</para><para>
+In &IC;, there are many kinds of variables. We have:
+
+<itemizedlist>
+<listitem><para>
+Global variables
+</para></listitem>
+<listitem><para>
+Catalog variables
+</para></listitem>
+<listitem><para>
+&glos-session; variables
+</para></listitem>
+<listitem><para>
+&glos-scratch; variables
+</para></listitem>
+<listitem><para>
+&glos-CGI; variables
+</para></listitem>
+<listitem><para>
+&glos-value; variables
+</para></listitem>
+</itemizedlist>
+
+Read the respective glossary entries.
+<emphasis role='bold'>This entry only deals with global and catalog
+variables.</emphasis>
+
+</para><para>
+Global and catalog variables are basic ways of storing variable information
+in &IC;.
+They are basically the same, but some of the definitions only make sense
+at global (&IC; server) level, and some only make sense at "local"
+(individual catalog) level. There's also a fallback mechanism available that
+can query the global setting if its instance at catalog level is not set.
+</para><para>
+Of those variables, we further (informally) distinguish between
+"core", "distribution"
+and "&std-catalog;" variables. Core variables are being honored by common,
+underlying &IC; code; distribution variables are honored in our
+<emphasis>out of the box</emphasis> configurations, and &std-catalog;
+variables are being honored in our &std-catalog; demo catalog that we
+ship along with &IC;.
+
+
+</para><para>
+Look up the &conf-Variable; configuration directive for instructions on
+<emphasis>setting</emphasis> variable values. Look up the &tag-var;
+tag for basic instructions on <emphasis>getting</emphasis> variable values.
+</para><para>
+Global and catalog variables are not normally modified dynamically (they
+keep their value as set in &gcf; or &ccf;). However, they can be
+manipulated at runtime, in which case you most probably want to do it before
+&IC; puts a requested page into processing. This is best done in an
+&conf-Autoload; routine.
+</para>
+
+<note><para>
+By the way, an &conf-Autoload; routine is what gives your catalog unlimited
+flexibility.
+It made my head spin in disbelief when I first saw some of the &conf-Autoload;
+tricks, and it continues to amuse me to this day.
+If you want to take a quick break from problem at hand, see &glos-configuration;
+glossary entry for an explanation of what happens with configuration directives
+on each page request, and &conf-Autoload; reference page for Autoload-specific
+discussion and examples.
+</para></note>
+
+
+<para>
+When accessing variables, we distinguish between three access types:
+from &glos-ITL; code, from embedded &PERL; code, and from &conf-GlobalSub;s or
+tags.
+</para><para>
+Here's a complete list of ways to access global or catalog variables:
+</para><para>
+
+
+<emphasis role='bold'>In ITL:</emphasis><sbr/>
+<informaltable pgwide='1' frame='none'>
+
+ <tgroup cols='2' align='left'>
+ <colspec colname='how'/><colspec colname='from'/>
+
+ <thead>
+ <row><entry>Access syntax</entry><entry>Place of definition</entry></row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>__<replaceable>VARNAME</replaceable>__</entry>
+ <entry>&ccf;</entry>
+ </row>
+ <row>
+ <entry>@_<replaceable>VARNAME</replaceable>_@</entry>
+ <entry>&ccf;, with fallback to &gcf;</entry>
+ </row>
+ <row>
+ <entry>@@<replaceable>VARNAME</replaceable>@@</entry>
+ <entry>&gcf;</entry>
+ </row>
+ <row>
+ <entry>[var <replaceable>VARNAME</replaceable>]</entry>
+ <entry>&ccf;</entry>
+ </row>
+ <row>
+ <entry>[var <replaceable>VARNAME</replaceable> 1]</entry>
+ <entry>&gcf;</entry>
+ </row>
+ <row>
+ <entry>[var <replaceable>VARNAME</replaceable> 2]</entry>
+ <entry>&ccf;, with fallback to &gcf;</entry>
+ </row>
+ </tbody>
+
+ </tgroup>
+</informaltable>
+
+
+
+<emphasis role='bold'>In embedded Perl:</emphasis><sbr/>
+<informaltable pgwide='1' frame='none'>
+
+ <tgroup cols='2' align='left'>
+ <colspec colname='how'/><colspec colname='from'/>
+
+ <thead>
+ <row><entry>Access syntax</entry><entry>Place of definition</entry></row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>$Variable-><replaceable>VARNAME</replaceable>}</entry>
+ <entry>&ccf;</entry>
+ </row>
+ <row>
+ <entry>$Tag->var('<replaceable>VARNAME</replaceable>')</entry>
+ <entry>&ccf;</entry>
+ </row>
+ <row>
+ <entry>$Tag->var('<replaceable>VARNAME</replaceable>', 1)</entry>
+ <entry>&gcf;</entry>
+ </row>
+ <row>
+ <entry>$Tag->var('<replaceable>VARNAME</replaceable>', 2)</entry>
+ <entry>&ccf;, with fallback to &gcf;</entry>
+ </row>
+ </tbody>
+
+ </tgroup>
+</informaltable>
+
+
+
+<emphasis role='bold'>In GlobalSub code or usertags:</emphasis><sbr/>
+<informaltable pgwide='1' frame='none'>
+
+ <tgroup cols='2' align='left'>
+ <colspec colname='how'/><colspec colname='from'/>
+
+ <thead>
+ <row><entry>Access syntax</entry><entry>Place of definition</entry></row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>$::Variable-><replaceable>VARNAME</replaceable>}</entry>
+ <entry>&ccf;</entry>
+ </row>
+ <row>
+ <entry>$Tag->var('<replaceable>VARNAME</replaceable>')</entry>
+ <entry>&ccf;</entry>
+ </row>
+ <row>
+ <entry>$Tag->var('<replaceable>VARNAME</replaceable>', 1)</entry>
+ <entry>&gcf;</entry>
+ </row>
+ <row>
+ <entry>$Tag->var('<replaceable>VARNAME</replaceable>', 2)</entry>
+ <entry>&ccf;, with fallback to &gcf;</entry>
+ </row>
+ <row>
+ <entry>$Global::Variable-><replaceable>VARNAME</replaceable>}</entry>
+ <entry>&gcf;, and only within &conf-GlobalSub; code</entry>
+ </row>
+ </tbody>
+
+ </tgroup>
+
+</informaltable>
+
<!--
TODO
LI1: Global program variables
More information about the docs
mailing list