[docs] xmldocs - docelic modified 3 files
docs at icdevgroup.org
docs at icdevgroup.org
Sat Oct 16 08:26:53 EDT 2004
User: docelic
Date: 2004-10-16 12:26:52 GMT
Modified: docbook xmldocs.css
Modified: howtos implement-banners
Modified: refs banner
Log:
- howtos/implement-banners, refs/banner: completed banner documentation
- docbook/xmldocs.css: nicer display for <database> elements
Revision Changes Path
1.17 +3 -1 xmldocs/docbook/xmldocs.css
rev 1.17, prev_rev 1.16
Index: xmldocs.css
===================================================================
RCS file: /var/cvs/xmldocs/docbook/xmldocs.css,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -r1.16 -r1.17
--- xmldocs.css 3 Oct 2004 19:05:05 -0000 1.16
+++ xmldocs.css 16 Oct 2004 12:26:52 -0000 1.17
@@ -293,7 +293,9 @@
.database {
border: dotted 1px #cee7f6;
- padding-left: 3mm;
+ border-left: 3px solid #cee7f6;
+ padding-left: 1.2mm;
+ padding-right: 0.5mm;
}
a {
1.2 +56 -17 xmldocs/howtos/implement-banners
rev 1.2, prev_rev 1.1
Index: implement-banners
===================================================================
RCS file: /var/cvs/xmldocs/howtos/implement-banners,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- implement-banners 15 Oct 2004 20:54:56 -0000 1.1
+++ implement-banners 16 Oct 2004 12:26:52 -0000 1.2
@@ -1,4 +1,4 @@
-<chapter id="Implement Banners">
+<chapter id="implementbanners">
<chapterinfo>
<title>Implement Banner Ads</title>
@@ -29,8 +29,38 @@
<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
+ Banner display in &IC; is implemented using the <tag>banner</tag> tag.
+ There are two terms which need to be understood first:
+ </para>
+ <itemizedlist>
+ <listitem><para>
+ Banner display - term referring to general banner display. Actual code
+ behavior might be affected by the
+ <arg choice='plain'>category</arg> or
+ <arg choice='plain'>weighted</arg> attributes passed to the tag.
+ </para></listitem>
+ <listitem><para>
+ Banner rotation - term referring to selecting exactly one banner, if
+ there are multiple banners defined in the
+ <database class='field'>banner</database> database field. Those
+ multiple banners are displayed in sequential order, with a separate
+ counter kept for each client.
+ </para></listitem>
+ </itemizedlist>
+ <para>
+ Additionally, we need to clarify the difference between
+ <emphasis>categorized</emphasis>
+ and <emphasis>rotated</emphasis> display.
+ Categorized display (mostly used in combination with weighting) makes
+ all banners matching a category to be displayed the appropriate
+ ammount of time (adding weight gives the banner more visibility).
+ Rotated display makes multiple banners from the same
+ <database class='field'>banner</database> database field to be selected
+ <emphasis>in sequential order, for each client separately</emphasis>.
+ Both categorized/weighted and rotating techniques can be used together.
+ </para>
+ <para>
+ For the <tag>banner</tag> tag to work, you'll need to have a
<database class='table'>banner</database> table. Here's an
example:
</para>
@@ -38,20 +68,38 @@
<xi:include parse='text' href='../files/banner/banner.txt'/>
</programlisting>
<para>
+ You might notice 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>
+ <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.
+ <database class='field'>code</database> - key for an item (of course,
+ the key has to be unique). In a <glossterm linkend='weighted_system'>
+ weighted</glossterm> display, the value of this field is not that
+ important because the choice
+ is made by selecting all database rows (or optionally, only taking
+ a subset of those matching specific <arg choice='plain'>category</arg>).
+ In default, non-weighted display, the <arg choice='plain'>category</arg>
+ attribute is expected to contain an unique code, so this is where the
+ <database class='field'>code</database> value is expected to have a
+ more meaningful value.
</para></listitem>
<listitem><para>
<database class='field'>category</database> - categorize weighted ads.
- If empty, the banner will be placed in the default category.
+ If empty, the banner will be placed in category
+ <literal>default</literal>.
</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.
+ integer number equal or greater than 1 to consider 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> -
@@ -84,15 +132,6 @@
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>
1.2 +15 -58 xmldocs/refs/banner
rev 1.2, prev_rev 1.1
Index: banner
===================================================================
RCS file: /var/cvs/xmldocs/refs/banner,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- banner 15 Oct 2004 20:54:56 -0000 1.1
+++ banner 16 Oct 2004 12:26:52 -0000 1.2
@@ -145,7 +145,7 @@
__NAME__ description
-&IC; has a built-in banner rotation system designed to show
+&IC; has a built-in banner display system designed to show
<glossterm linkend="ad">ads</glossterm> or other
messages, according to optional categories and
<glossterm linkend="weighting_system">weighting</glossterm>.
@@ -153,7 +153,7 @@
</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
+<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
@@ -161,74 +161,31 @@
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.
+in random fashion. If all banners need to be equal (that is, displayed
+randomly with the same probability), 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".
+</para><para>
+Note that the term <firstterm>rotation</firstterm> refers to sequentially
+selecting and displaying banners from the same
+<database class='field'>banner</database> field (keeping a separate counter
+for each client). This, of course, makes sense in a context where
+<database class='field'>banner</database> contains multiple banner
+entries, separated by chosen delimiters.
__END__
__NAME__ example
<example>
<title>
+ Banner Ads
</title>
<para>
+ For the relevant supplemental description and all ready-to-use examples,
+ see the <olink targetdoc='howtos' targetptr='implementbanners'>
+ Implement Banner Ads</olink> HOW-TO.
</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