[docs] xmldocs - docelic modified 4 files
docs at icdevgroup.org
docs at icdevgroup.org
Tue Feb 1 16:33:13 EST 2005
User: docelic
Date: 2005-02-01 21:33:13 GMT
Modified: glossary ITL price
Added: glossary discount variables
Log:
- Small modifications and a little bigger additions
Revision Changes Path
1.7 +87 -46 xmldocs/glossary/ITL
rev 1.7, prev_rev 1.6
Index: ITL
===================================================================
RCS file: /var/cvs/xmldocs/glossary/ITL,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- ITL 3 Jan 2005 20:43:54 -0000 1.6
+++ ITL 1 Feb 2005 21:33:12 -0000 1.7
@@ -42,6 +42,21 @@
useful only if some content is provided in their <emphasis>body</emphasis>
(the place between the opening and corresponding ending tag).
</para>
+<para>
+Additionally, container tags for which you do not provide any
+<emphasis>body</emphasis> can be closed using "XML-style", but make sure to
+add an extra space, to unambiguously separate <literal>/]</literal> from the
+tag arguments. The following two lines are identical in effect:
+<programlisting>
+[forum top="[item-code]" display_page="forum/display"][/forum]
+[forum top="[item-code]" display_page="forum/display" /]
+</programlisting>
+</para>
+<para>
+It's probably also useful to mention that there must be no whitespace
+between the left bracket ([) and the tag name; <code>[forum]</code> is
+valid, <code>[ forum]</code> is not!
+</para>
</section>
@@ -69,14 +84,11 @@
<code>[page <replaceable>href</replaceable>]
<replaceable>Link text</replaceable>
[/page]</code>, but &tag-page; is <emphasis>not</emphasis> a container
-tag, and link text is not treated as the corresponding body text.
+tag, and link text is not treated as the corresponding body text. Finally,
+since <code>[/page]</code> only adds unnecessary burden on the parser,
+simply writing <code></a></code> is preferred.
</para></note>
-</para><para>
-When using the <code>[<replaceable>tagname</replaceable>
-<replaceable>...</replaceable>]</code> syntax, there must be no whitespace
-between the left bracket ([) and the tag name.
-
</para>
<important>
@@ -92,6 +104,13 @@
<code>[item-list]...[/item_list]</code> is
<emphasis role='bold'>not</emphasis>.
</para>
+<para>
+This is a very convenient feature. It is a common standard to use dashes
+(<literal>-</literal>) in &glos-ITL;, and underscores (<literal>_</literal>)
+in &PERL; code (because in Perl, dashes would be interpreted as minus operators,
+which is not what you'd expect).
+
+</para>
</important>
</section>
@@ -168,17 +187,20 @@
compact:
<programlisting>
-[value variable_name]
+[value <replaceable>variable_name</replaceable>]
</programlisting>
Positional syntax, however, requires support by each tag individually. That
-is, set of arguments that can be specified in positional notation as
-well as their position in the set are fixed determined in advance. You can
+is, set of arguments that can be specified in positional notation (as
+well as their position in the set) are fixed and determined in advance. You can
see a list of accepted positional arguments (and their implicit order) in
each tag's SYNOPSIS reference section; try &tag-value; for example.
</para><para>
Additionally, <emphasis role='bold'>you cannot mix named and positional
parameters in the same tag</emphasis>; use either all named, or all positional.
+<emphasis role='bold'>It seems I cannot stress this enough, this is a common
+beginners' mistake, especially when you copy/paste foreign code and combine
+with your own!</emphasis>
</para><para>
In any case, positional syntax is appropriate for simpler tags and
&IC; interprets positional arguments somewhat faster (but don't let your
@@ -187,15 +209,15 @@
once said, "Premature optimization is the root of all programming evil").
</para><para>
In most cases, tag parameters specified in the positional fashion work
-the same as named parameters. However, there are a few situations where
-you must use named parameters:
+the same as named parameters. However, <emphasis role='bold'>there are a few
+situations where you must use named parameters</emphasis>:
<itemizedlist>
<listitem><para>
When you want to specify a parameter that comes positionally after a
parameter that you want to omit, e.g. omit the first parameter but specify
the second. The parser would have no way of knowing which is which, so
- you must switch to named syntax. This rarely happens, though, because the
+ you must revert to named syntax. This rarely happens, though, because the
first positional parameter is usually required for a given tag anyway, and
can't be omitted.
</para></listitem>
@@ -203,11 +225,12 @@
<listitem><para>
When there is some ambiguity as to which parameter is which, usually
due to whitespace. If the argument value contains any whitespace
- (even if it's enclosed in quotes!), you must use named syntax.
+ (<emphasis role='bold'>even if it is enclosed in quotes!</emphasis>), you
+ must use named syntax.
</para></listitem>
<listitem><para>
- When you need to use the output of a tag as the input argument for
+ When you need to use the output of a tag as <emphasis>argument</emphasis> for
another tag.
</para></listitem>
</itemizedlist>
@@ -256,19 +279,25 @@
never run into trouble.
</para>
<para>
+The other answer says, "omitting quotes earns you a bonus for style and achieves
+small parser speed improvement". However, if the value contains a whitespace,
+you must quote it.
+<!-- TODO whitespace and/or weird chars too? or it's matched by \S ? -->
To quote values, you can use double quotes (<literal>"</literal>),
single quotes (<literal>'</literal>) and
-pipes (<literal>|</literal>). Pipes have the additional functionality of
+pipes (<literal>|</literal>) interchangeably.
+<!-- TODO mention `` -->
+Pipes have the additional functionality of
removing leading and trailing whitespace, but generally you can use
-them in combination to do three levels of quoting with ITL; for
+all types in combination to do three levels of quoting with ITL; for
more deeply nested constructs, use direct &PERL; code.
</para>
<para>
-The above trivial answer to the quoting problem, however, is not the best
-you can get in terms of speed or
-style. In general, looping <emphasis>subtags</emphasis> (covered some lines
-below) do not need quotes because they are parsed in a separate pass, before
-the general parser takes on.
+The above answers to the quoting problem, however, are still not all there is
+to know about quoting.
+In general, <emphasis>loop subtags</emphasis>, which we explain some lines
+below, do not need quotes (even though they sometimes contain whitespace)
+because they are parsed in a separate pass, before the general parser takes on.
</para><para>
Here's an example that would work properly with quotes omitted. (Pay attention
to <code>[item-field url]</code> which, at first sight, looks like it is
@@ -283,7 +312,8 @@
<para>
<code>[page [value mypage]]</code>, however, would <emphasis>not</emphasis>
work, because the &tag-value; tag shown is not one of the looping subtags
-which receive special treatment.
+(for the record, it's not even close). But as we said, we'll get back to
+subtags and their availability in a minute.
</para>
</section>
@@ -312,17 +342,14 @@
</para><para>
With container tags, the <arg choice='plain'>interpolate</arg> attribute
-specifies whether the tag body will be &glos-interpolate;d before being
-passed to the tag.
-
-</para><para>
+specifies whether the <emphasis>tag body</emphasis> will be
+&glos-interpolate;d before being passed to the tag.
+<!-- </para><para> -->
With stand-alone tags, the <arg choice='plain'>interpolate</arg> attribute
-specifies whether the output of the tag will be &glos-reparse;d.
-This feature "overlap"
-between the two options occurred because <arg choice='plain'>interpolate</arg>
-already existed (and functioned as described) when the new
-<arg choice='plain'>reparse</arg> was added to &IC;.
-
+specifies whether the <emphasis>output</emphasis> of the tag will be
+&glos-interpolate;d. This is very confusing because it's not intuitive, but
+once you get to remember it a few times in practice, it will stop being a
+problem.
</para><para>
Output of most of the stand-alone tags is not interpolated by default.
Exceptions to this rule would include, for example, the &tag-include; tag.
@@ -378,8 +405,8 @@
&glos-interpolate;d. This is basically the same as the
<arg choice='plain'>interpolate</arg> attribute for stand-alone tags, but a
new name had to be invented because <arg choice='plain'>interpolate</arg>
-performs a different function with container tags (it refers to interpolation
-of the tag <emphasis>body</emphasis> instead of the tag output).
+already performed a different function with container tags, when
+this functionality was to be added.
</para><para>
Most container tags will have their output re-parsed for more
@@ -414,7 +441,9 @@
</para><para> <sbr/><sbr/>
-The <arg choice='plain'>send</arg> attribute is deprecated.
+The third attribute, <arg choice='plain'>send</arg>, was deprecated long ago
+and will only be described for historical reference.
+<!-- TODO -->
</para>
</section>
@@ -427,6 +456,11 @@
Each tag may accept additional arguments which vary from tag to
tag. For each tag individually, you need to consult the
appropriate reference page to learn tag-specific parameters and attributes.
+Note, however, that the tag arguments do not necessarily have to be announced
+in the tag definition header; sometimes they're used pretty much
+<emphasis>ad-hoc</emphasis>, but we are making sure to keep the documentation
+up to date. We kindly ask you to inform us of any errors or omissions in the
+documentation.
</para>
</section>
@@ -437,8 +471,10 @@
<para>
-Some tags allow you to pass a &PERL; &glos-array; or &glos-hash; as the
-value of an attribute. For an ordinary tag, the syntax is as follows:
+Instead of just plain values, for some tags it would be particularly convenient
+if they accepted &glos-array;s or &glos-hash;es of argument values, much like
+you could do if you used &PERL; directly. Fortunately, &glos-ITL; supports
+that too! For an ordinary tag, the syntax is as follows:
<programlisting>
<replaceable>attribute</replaceable>.<replaceable>ARRAY_INDEX</replaceable>=<replaceable>value</replaceable>
@@ -560,7 +596,8 @@
arbitrary prefix that is used in that looping tag; this is needed to be able
to support nesting in arbitrary order and to arbitrary level.
<emphasis>All of the
-subtags are only interpreted within their container and only accept
+subtags are only interpreted within their container tags (they can only
+appear inside their parent tags' bodies) and they only accept
positional parameters</emphasis>. The default prefixes follow:
@@ -636,14 +673,17 @@
</para>
<important><para>
-Subtags are parsed during evaluation of the enclosing loop; that means
-<emphasis>before any regular tags within the loop</emphasis>.
+As we've said already, subtags are parsed before the standard parsing routine
+takes on; that means <emphasis>before any regular tags within the
+loop</emphasis>. This has a subtle effect; it can, for example, prevent the
+usual tags from accepting looping tags' values as attributes. In such cases,
+look for "subtag" (prefixed) variants of the usual tags.
+<!-- TODO example -->
</para></important>
<para>
-Going back to &PERL; again,
-there are two types of records that &IC; can return with looping lists:
-ARRAY and HASH.
+Speaking of loops and &PERL;, there are two types of records that &IC; can
+return with looping lists: ARRAY and HASH.
</para><para>
An array list is the normal output of the &tag-query; and &tag-loop; tags,
@@ -653,8 +693,7 @@
The two queries below are essentially identical:
<programlisting>
-[query sql="select foo, bar from products"]
-[/query]
+[query sql="select foo, bar from products" /]
[loop search="
ra=yes
@@ -666,7 +705,9 @@
Both will return an array of arrays consisting of the
<database class='field'>foo</database> and
<database class='field'>bar</database> columns.
-The corresponding &PERL; data structure would look like this:
+The corresponding &PERL; data structure would look like this
+(familiarity with the output from <classname>Data::Dumper</classname> Perl
+module helps here):
<programlisting>
[
1.2 +35 -21 xmldocs/glossary/price
rev 1.2, prev_rev 1.1
Index: price
===================================================================
RCS file: /var/cvs/xmldocs/glossary/price,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- price 3 Jan 2005 20:48:34 -0000 1.1
+++ price 1 Feb 2005 21:33:12 -0000 1.2
@@ -50,7 +50,7 @@
<listitem><para>
If &conf-CommonAdjust; is set to <emphasis>any</emphasis> value (so, be it a
valid &CAs; or not), extended price
-adjustments are enabled.
+adjustments are enabled
<!-- TODO clarify: It may also hold the default pricing scheme. -->
</para></listitem>
@@ -58,25 +58,25 @@
If the <database class='field'>price</database> field in the
<database>products</database> database contains a
&CAs;, it takes
-precedence over the default set with &conf-CommonAdjust;.
+precedence over the default set with &conf-CommonAdjust;
</para></listitem>
<listitem><para>
If the value of the &conf-CommonAdjust; directive is set to a valid &CAs;,
and the <database class='field'>price</database> field is empty or
specifically <literal>0</literal>, then the &CAs;
-will be used to set the price of the item.
+will be used to set the price of the item
</para></listitem>
<listitem><para>
If no &CAs;s are found, then the price will be <literal>0</literal>, and
-subject to any later application of discounts.
+subject to any later application of discounts
</para></listitem>
<listitem><para>
If, as a result of &CAs; application, another &CAs; is found,
it will be re-parsed and the result applied. Chaining is retained; a
-fallback may be passed and will take effect.
+fallback may be passed and will take effect
</para></listitem>
</itemizedlist>
@@ -86,13 +86,14 @@
<title>CommonAdjust Strings, Atoms and Settors</title>
<para>
-Using &CAs;, prices may be adjusted in several ways, but we first need to
+Using valid &CAs;s, prices may be adjusted in several ways, but we first
+need to
define "&CAs;" as we've promised in the introduction. &CAs;s are price
definition strings which consist of individual actions called
<emphasis>atoms</emphasis>. Atoms in turn consist of
<emphasis>settors</emphasis>.
Roughly, we could say atoms convey "control information" — they
-define <emphasis role='bold'>when</emphasis> is the containing settor
+define <emphasis role='bold'>when</emphasis> are contained settors
applied, and settors define <emphasis role='bold'>what</emphasis> is applied.
</para>
<para>
@@ -102,7 +103,7 @@
<orderedlist>
<listitem><para>
- <emphasis>Final</emphasis> price atom is always applied if it does not
+ <emphasis>Final</emphasis> price atom is applied if it does not
evaluate to zero
</para></listitem>
<listitem><para>
@@ -119,12 +120,12 @@
A chained atom ends with a comma. A fallback atom has a
leading semi-colon. Final atoms have no comma appended or semi-colon prepended.
Atoms themselves are separated by whitespace and may be quoted, although there
-should normally be no whitespace in a setting and therefore quotes are
-not necessary.
+should normally be no whitespace in a setting and therefore no quotes
+necessary.
</para>
<para>
A <emphasis>settor</emphasis> is a mean by which the price is set. In other
-words, it is an expression contained in an atom, and when evaluated, it
+words, it is an expression contained in an atom which, when evaluated,
affects the item price.
Just as there are different types of atoms, there are different types of settors
as well. Be aware that all settor types can yield new &CAs;s, and it's
@@ -147,7 +148,8 @@
<para>
Let's take a look at available settor types. Settor types do not have
distinguishable symbolic names, but their type is recognizable from the
-syntax used.
+syntax used. Note that bold elements are required, while the rest are
+optional.
</para>
<!--
@@ -198,7 +200,7 @@
<literal>price</literal> unless you changed &conf-PriceField; or have
some interesting ideas in mind.
<!-- TODO what means "key is item code except in attribute-based lookup?-->
- Key argument defaults, of course, to the item code (except in a special
+ Key, of course, defaults to the item code (except in a special
case of attribute-based lookup). The database value returned is treated
as settor again, and is re-parsed accordingly.
</para></listitem>
@@ -248,8 +250,9 @@
<emphasis role='bold'><literal>==</literal><replaceable>attribute</replaceable><literal>:</literal></emphasis><replaceable>table</replaceable><literal>:</literal><replaceable>column</replaceable><literal>:</literal><replaceable>key</replaceable>
</para><para>
<!-- TODO what's default table for attribute based lookup?-->
- Performs <emphasis>attribute-based</emphasis> lookup. The table the attribute
- is looked up in. Column default to the same value as attribute.
+ Performs <emphasis>attribute-based</emphasis> lookup. Table
+ specifies the table for lookup. Column defaults to the name of the
+ attribute being looked for.
</para></listitem>
<listitem><para>
@@ -272,7 +275,7 @@
$Vend::Interpolate::item is the current item
$Vend::Interpolate::item->{code} gives key for current item
$Vend::Interpolate::item->{mv_ib} gives database ordered from
-$Vend::Interpolate::item->{...} gives attribute value
+$Vend::Interpolate::item->{...} gives specified attribute's value
]]></programlisting>
</para></listitem>
@@ -315,12 +318,13 @@
<emphasis role='bold'><replaceable>word</replaceable></emphasis>
</para>
<para>
- The value <literal><replaceable>word</replaceable></literal> which must
- be unique (must not match any other settors) is available as a key only for
+ The value <literal><replaceable>word</replaceable></literal> (which must
+ <!-- TODO settors ? -->
+ be unique — not match any other settors) is available as a key only for
the next lookup.
If that next settor is a database lookup and it contains
a dollar sign (<literal>$</literal>),
- <literal><replaceable>word</replaceable></literal> will will be substituted
+ <literal><replaceable>word</replaceable></literal> will be substituted
for it.
<!-- TODO above, are we talking settors or atoms? what means "must not
match any other settors" ? (does that mean its the same namespace as >>word
@@ -335,7 +339,7 @@
as key for the next lookup.
If that next settor is a database lookup and it contains
a dollar sign (<literal>$</literal>),
- <literal><replaceable>word</replaceable></literal> will will be substituted
+ <literal><replaceable>word</replaceable></literal> will be substituted
for it.
<!-- TODO is this only if next is db lookup, or $ will always be
substituted and db lookup is just an example? -->
@@ -343,8 +347,18 @@
</orderedlist>
+ <para>
+ For actual examples, please see the &conf-CommonAdjust; reference page.
+ </para>
+
+</section>
+
+<section>
+ <title>Product discounts</title>
+ <para>
+ For product discount settings, see the &glos-discount; glossary entry.
+ </para>
</section>
<para>
-For actual examples, please see the &conf-CommonAdjust; reference page.
1.1 xmldocs/glossary/discount
rev 1.1, prev_rev 1.0
Index: discount
===================================================================
Product discounts in &IC; can be set at any time. The discounts
apply only to the customer receiving them, and are of following types:
<itemizedlist>
<listitem><para>
Discount on a specific item - a discount for one particular item.
Key to use with the &tag-discount; tag is the product's &glos-SKU;
</para></listitem>
<listitem><para>
Discount on all items - a discount applying to all items.
Key to use with the &tag-discount; tag is <literal>ALL_ITEMS</literal>
</para></listitem>
<listitem><para>
Discount on a particular item at particular time -
a discount for an individual line item, applied if the <mv>mv_discount</mv>
attribute is set (usually with embedded &PERL;)
</para></listitem>
<listitem><para>
Order discount - a discount applied not on individual products, but on a
total order.
Key to use with the &tag-discount; tag is <literal>ENTIRE_ORDER</literal>
</para></listitem>
</itemizedlist>
The discounts are specified using a formula. The formula is scanned for
the <varname>$q</varname> and <varname>$s</varname> variables which are
first substituted for with the item quantity and subtotal respectively.
The variable <varname>$s</varname> is saved between
iterations, so that the discounts can be cumulative.
</para><para>
In case of individual item discounts, the formula must be defined in a way
that it produces a subtotal which includes <emphasis>all items</emphasis> of
the same SKU that are found in the user's basket.
In case of an entire order discount, the formula is usually simpler
and defines a flat discount ammount or percentage.
</para><para>
<emphasis role='bold'>
Discounts are applied to the <emphasis>effective</emphasis> price of the
<!-- TODO does this include taxing or not -->
product, that is — the price obtained after applying &glos-price;
adjustments.
</emphasis>
</para><para>
For examples, see the &tag-discount; reference page.
1.1 xmldocs/glossary/variables
rev 1.1, prev_rev 1.0
Index: variables
===================================================================
<!--
TODO
LI1: 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 C<$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.
-->
More information about the docs
mailing list