[docs] xmldocs - docelic modified 8 files
docs at icdevgroup.org
docs at icdevgroup.org
Fri Oct 15 16:54:56 EDT 2004
User: docelic
Date: 2004-10-15 20:54:56 GMT
Modified: . TODO
Added: glossary ad reconfig rotated-banner tab-delimited
Added: weighted-system
Added: howtos implement-banners
Added: refs banner
Log:
- documenting Banner Rotation
- added appropriate glossary entries, HOWTO and a tag reference page
(this will need polishing tomorrow)
- TODO: items
Revision Changes Path
1.35 +4 -1 xmldocs/TODO
rev 1.35, prev_rev 1.34
Index: TODO
===================================================================
RCS file: /var/cvs/xmldocs/TODO,v
retrieving revision 1.34
retrieving revision 1.35
diff -u -r1.34 -r1.35
--- TODO 14 Oct 2004 15:54:42 -0000 1.34
+++ TODO 15 Oct 2004 20:54:56 -0000 1.35
@@ -8,6 +8,9 @@
multiple times within +- of first occurence, we treat it like one context.
but the header says 'displaying 2/2 contexts', it doesn't remove
'duplicates'. fix that.
+- Parameter is positional, others are attributes
+- ./files/ directory is not properly referenced from chunked documents.
+ Either use entities or XML catalog to solve that.
- In iccattut:
- make a "translation map" of /etc/interchange/* to RPM-equivs.
@@ -28,7 +31,7 @@
tag, interpolation, reparse, symbol types
catalog/global variable, tag,ui,
action, form, unix inet socket, values,
-regex, flypage, sku
+regex, flypage, sku, ad, weighted display
HOWTOs:
- how to delete item from cart in all possible ways
1.1 xmldocs/glossary/ad
rev 1.1, prev_rev 1.0
Index: ad
===================================================================
<glossentry id="ad">
<glossterm>Ad</glossterm>
<glossterm>Banner Ad</glossterm>
<!--<acronym></acronym>-->
<!--<abbrev></abbrev>-->
<glossdef>
<para>
meek.
</para>
</glossdef>
</glossentry>
1.1 xmldocs/glossary/reconfig
rev 1.1, prev_rev 1.0
Index: reconfig
===================================================================
<glossentry id="reconfig">
<glossterm>Catalog Reconfiguration</glossterm>
<!--<acronym></acronym>-->
<!--<abbrev></abbrev>-->
<glossdef>
<para>
meek.
</para>
</glossdef>
</glossentry>
1.1 xmldocs/glossary/rotated-banner
rev 1.1, prev_rev 1.0
Index: rotated-banner
===================================================================
<glossentry id="rotated_banner">
<glossterm>Rotated banner</glossterm>
<!--<acronym></acronym>-->
<!--<abbrev></abbrev>-->
<glossdef>
<para>
meek.
</para>
</glossdef>
</glossentry>
1.1 xmldocs/glossary/tab-delimited
rev 1.1, prev_rev 1.0
Index: tab-delimited
===================================================================
<glossentry id="tab_delimited">
<glossterm>TAB-delimited data</glossterm>
<glossdef>
<para>
Meek meek.
</para>
</glossdef>
</glossentry>
1.1 xmldocs/glossary/weighted-system
rev 1.1, prev_rev 1.0
Index: weighted-system
===================================================================
<glossentry id="weighted_system">
<glossterm>Weighted system</glossterm>
<!--<acronym></acronym>-->
<!--<abbrev></abbrev>-->
<glossdef>
<para>
meek.
</para>
</glossdef>
</glossentry>
1.1 xmldocs/howtos/implement-banners
rev 1.1, prev_rev 1.0
Index: implement-banners
===================================================================
<chapter id="Implement Banners">
<chapterinfo>
<title>Implement Banner Ads</title>
<titleabbrev>implementbanners</titleabbrev>
<keywordset>
<keyword>banner</keyword>
<keyword>weight</keyword>
<keyword>random</keyword>
<keyword>rotate</keyword>
<keyword>ad</keyword>
<keyword>sequential</keyword>
</keywordset>
<!--<authorgroup>
<author>
<firstname>Davor</firstname>
<surname>Ocelic</surname>
<affiliation>
<email>docelic at icdevgroup.org</email>
</affiliation>
</author>
</authorgroup>-->
</chapterinfo>
<sect1 id='implementbanners_introduction'>
<title>Introduction</title>
<para>
Banners in &IC; are implemented using the <tag>banner</tag> tag.
For this tag to work, you'll need to have a
<database class='table'>banner</database> table. Here's an
example:
</para>
<programlisting>
<xi:include parse='text' href='../files/banner/banner.txt'/>
</programlisting>
<para>
Field descriptions follow:
<itemizedlist>
<listitem><para>
<database class='field'>code</database> - key for an item. If banners
are not weighted, this should be a category-specific code.
</para></listitem>
<listitem><para>
<database class='field'>category</database> - categorize weighted ads.
If empty, the banner will be placed in the default category.
</para></listitem>
<listitem><para>
<database class='field'>weight</database> - banner weight. Must be an
integer number equal or greater than 1 to include the banner for display.
0 or blank will ignore the banner when weighted ads are built.
</para></listitem>
<listitem><para>
<database class='field'>rotate</database> -
must contain a value if weighted banners are
<emphasis role='bold'>not</emphasis> used:
<itemizedlist>
<listitem><para>
Empty value will prevent the banner from being displayed.
</para></listitem>
<listitem><para>
Literal value of
<literal>0</literal> (zero) will cause the entire content of the banner
field to be displayed when the category is matched.
</para></listitem>
<listitem><para>
Non-zero value will cause the banner field to be split into segments
(using the specified or default delimiter, of course). For each
segment, the
banner will then rotate in sequence (for each website visitor
separately).
Obviously, the first banner in the sequence is more likely to be
displayed
than the last.
</para></listitem>
</itemizedlist>
</para></listitem>
<listitem><para>
<database class='field'>banner</database> - the field containing actual
banner content. Multiple banner texts (if this feature is used) need to be
separated using the specified or default delimiter.
</para></listitem>
</itemizedlist>
</para>
<para>
You might have noticed that the fields names and values in the tables
above are not properly aligned. This is an unfortunate nature of
<glossterm linkend="tab_delimited">TAB-delimited</glossterm> files.
</para>
<para>
To minimize the chance of confusion, you can download properly composed
<ulink url="files/banner/banner.txt">banner.txt</ulink>.
</para>
</sect1>
<sect1 id='implementbanners_solution'>
<title>Solution</title>
<para>
As usual, databases first need to be registered for use
with the catalog, and so is the case with the text database
from the <xref linkend="implementbanners_introduction"/>.
The following modification to your
<filename>catalog.cfg</filename> is needed (and a
<glossterm linkend="reconfig">catalog reconfiguration</glossterm>
afterwards):
<programlisting>
Database banner banner.txt TAB
Database banner NUMERIC weight
</programlisting>
</para>
<para>
Now that we have everything in place, we can start experimenting with the
<tag>banner</tag> tag.
</para>
<para>
To display weighted banners from a specific category (say,
<literal>tech</literal>), use
<code>[banner weighted=1 category=tech]</code>. The tag would look for
<emphasis>all</emphasis> banners where the
<database class='field'>weight</database> field is positive integer and
the <database class='field'>category</database> matches "tech", and
build them in the <filename class='directory'>tmp/Banners/tech/</filename>
directory.
</para>
<para>
To display weighted banners regardless of the category, use
<code>[banner weighted=1]</code>. The tag would look for
<emphasis>all</emphasis> banners where the
<database class='field'>weight</database> field is positive integer, and
build them in the <filename class='directory'>tmp/Banners/</filename>
directory. Note that the total sum of weights in our sample database
is 20, so each weight point is worth 100/20 = 5%. Therefore, the banners
with the weight of 7 would be displayed 35% of the time each.
</para>
<para>
To display categorized,
<glossterm linkend="rotated_banner">non-rotating</glossterm>
banners (from category
<literal>tech</literal>), use
<code>[banner category=tech]</code>, which is equal in effect to
<code>[data table=banner col=banner key=tech]</code>. <emphasis role='bold'>
Note that the
value of the <database class='field'>rotate</database> field must be
<literal>0</literal></emphasis>.
</para>
<para>
To display categorized,
<glossterm linkend="rotated_banner">rotating</glossterm>
banners (from category
<literal>tech</literal>), use
<code>[banner category=tech]</code>, which is equal in effect to
<code>[data table=banner col=banner key=tech]</code>. <emphasis role='bold'>
Note that the
value of the <database class='field'>rotate</database> field must be
<literal>1</literal></emphasis>.
</para>
<para>
To display multilevel-categorized banners (from say, the
<literal>tech -> hardware</literal> category), use
<code>[banner category=tech:hw]</code>. The colon will help &IC;
select the most specific banner available, so the difference in
respect to single-level categories is the fallback mechanism; if no
banners are found in the <literal>tech:hw</literal> category, the
<tag>banner</tag> will fallback to category <literal>tech</literal>.
</para>
</sect1>
</chapter>
1.1 xmldocs/refs/banner
rev 1.1, prev_rev 1.0
Index: banner
===================================================================
__NAME__ purpose
display banner ads or messages, based on category and optional weighting
__END__
__NAME__ synopsis
<row>
<entry>
<arg choice='plain'>category</arg>
</entry>
<entry>Yes</entry><entry></entry>
<entry><literal>default</literal></entry>
<entry>
For a <emphasis>weighted</emphasis> banner display, this field specifies
category name; only database entries where the
<database class='field'>category</database>
field matches this value are taken as possible candidates for display.
In an <emphasis>unweighted</emphasis> display, this field specifies
banner code; only one database entry with the matching value in the
<database class='field'>code</database> field should exist.
</entry>
</row>
<row>
<entry>
<arg choice='plain'>table</arg>
</entry>
<entry></entry><entry></entry>
<entry><literal>banner</literal></entry>
<entry>The banner table name. The default is reasonable and
rarely needs to be changed.</entry>
</row>
<row>
<entry>
<arg choice='plain'>r_field</arg>
</entry>
<entry></entry><entry></entry>
<entry><literal>rotate</literal></entry>
<entry>
Row in a banner table may include multiple banners in the <database
class='field'>banner</database> column (separated by specified delimiters).
The column specified by <database class='field'>r_field</database> is
consulted (expecting a boolean value) to determine whether to
sequentially rotate banners.
</entry>
</row>
<row>
<entry>
<arg choice='plain'>b_field</arg>
</entry>
<entry></entry><entry></entry>
<entry><literal>banner</literal></entry>
<entry>Banner descriptor field. In other words, name of the column that will
contain actual banner text to display. If a proper delimiter is used, and
the <arg choice='plain'>r_field</arg> column is true, this field may contain
multiple banner texts.
</entry>
</row>
<row>
<entry>
<arg choice='plain'>separator</arg>
</entry>
<entry></entry><entry></entry>
<entry><literal>:</literal></entry>
<entry>
Separator within the table key (the <database class='field'>code</database>
column), used for multilevel categorized ads.
This is only used with unweighted ads.
</entry>
</row>
<row>
<entry>
<arg choice='plain'>delimiter</arg>
</entry>
<entry></entry><entry></entry>
<entry><literal>{or}</literal></entry>
<entry>
Delimiter that sets different banner texts in the
<database class='field'>banner</database> field apart.
This is only used with unweighted ads.
</entry>
</row>
<row>
<entry>
<arg choice='plain'>weighted</arg>
</entry>
<entry></entry><entry></entry>
<entry>0</entry>
<entry>
Use weighted banner system? In a weighted system, the database is expected
to contain multiple entries with the same
<database class='field'>category</database>, and then the banners are
selected in regard to their relative weight (more weight = more
visibility).
</entry>
</row>
<row>
<entry>
<arg choice='plain'>once</arg>
</entry>
<entry></entry><entry></entry>
<entry>0</entry>
<entry>
Don't rebuild the banners until the appropriate
<filename>tmp/Banners/*/total_weight</filename> files are manually removed?
This is only used with weighted ads.
</entry>
</row>
<row>
<entry>
<arg choice='plain'>c_field</arg>
</entry>
<entry></entry><entry></entry>
<entry><literal>category</literal></entry>
<entry>
Specify the column containing banner category.
This is only used with weighted ads.
</entry>
</row>
<row>
<entry>
<arg choice='plain'>w_field</arg>
</entry>
<entry></entry><entry></entry>
<entry><literal>weight</literal></entry>
<entry>
Specify the table column containing banner weights.
This is only used with weighted ads.
</entry>
</row>
<row>
<entry>
<arg choice='plain'>interpolate</arg>
<arg choice='plain'>reparse</arg>
</entry>
<entry></entry><entry></entry>
<entry>0</entry>
<entry>.</entry>
</row>
__END__
__NAME__ see also
implement_banners
__END__
__NAME__ description
&IC; has a built-in banner rotation system designed to show
<glossterm linkend="ad">ads</glossterm> or other
messages, according to optional categories and
<glossterm linkend="weighting_system">weighting</glossterm>.
All this functionality is accessible using the <tag>banner</tag> tag.
</para><para>
The <glossterm linkend="weighted_system">weighting system</glossterm>,
if used, will pre-built banners in the directory
<filename class='directory'>Banners/*</filename> under the catalog temporary
directory (this will happen when the banners are first requested after
a catalog reconfiguration or Interchange daemon start).
It will build one copy of the banner for every value of <database
class='field'>weight</database>.
If one banner is weighted 7, one 2 and one 1 (in abstract points), then a
total of 10 pre-built banners will be made. The first will be displayed
70 percent of the time, the second 20 percent and the third 10 percent,
in random fashion. If all banners need to be equal, give each a weight of 1.
</para><para>
Each category has its own separate weighting if categorized display is
requested; otherwise all weights enter the same logical "pool".
__END__
__NAME__ example
<example>
<title>
</title>
<para>
</para>
<programlisting>
</programlisting>
</example>
<!--
To display weighted banners from a specific category (say,
<literal>tech</literal>), use
<code>[banner weighted=1 category=tech]</code>. The tag would look for
<emphasis>all</emphasis> banners where the
<database class='field'>weight</database> field is positive integer and
the <database class='field'>category</database> matches "tech", and
build them in the <filename class='directory'>tmp/Banners/tech/</filename>
directory.
</para>
<para>
To display weighted banners regardless of the category, use
<code>[banner weighted=1]</code>. The tag would look for
<emphasis>all</emphasis> banners where the
<database class='field'>weight</database> field is positive integer, and
build them in the <filename class='directory'>tmp/Banners/</filename>
directory. Note that the total sum of weights in our sample database
is 20, so each weight point is worth 100/20 = 5%. Therefore, the banners
with the weight of 7 would be displayed 35% of the time each.
</para>
<para>
To display categorized,
<glossterm linkend="rotated_banner">non-rotating</glossterm>
banners (from category
<literal>tech</literal>), use
<code>[banner category=tech]</code>, which is equal in effect to
<code>[data table=banner col=banner key=tech]</code>. <emphasis role='bold'>
Note that the
value of the <database class='field'>rotate</database> field must be
<literal>0</literal></emphasis>.
</para>
<para>
To display categorized,
<glossterm linkend="rotated_banner">rotating</glossterm>
banners (from category
<literal>tech</literal>), use
<code>[banner category=tech]</code>, which is equal in effect to
<code>[data table=banner col=banner key=tech]</code>. <emphasis role='bold'>
Note that the
value of the <database class='field'>rotate</database> field must be
<literal>1</literal></emphasis>.
</para>
<para>
To display multilevel-categorized banners (from say, the
<literal>tech -> hardware</literal> category), use
<code>[banner category=tech:hw]</code>. The colon will help &IC;
select the most specific banner available, so the difference in
respect to single-level categories is the fallback mechanism; if no
banners are found in the <literal>tech:hw</literal> category, the
<tag>banner</tag> will fallback to category <literal>tech</literal>.
</para>
-->
__END__
More information about the docs
mailing list