6.8. Banner/Ad rotation

Interchange has a built-in banner rotation system designed to show ads or other messages according to category and an optional weighting.

The [banner ...] ITL tag is used to implement it.

The weighting system pre-builds banners in the directory 'Banners,' under the temporary directory. It will build one copy of the banner for every one weight. If one banner is weighted 7, one 2 and one 1, 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.

Each category may have separate weighting. If the above is placed in category tech, then it will behave as above when placed in [banner category=tech] in the page. A separate category, say art, would have its own rotation and weighting.

The [banner ...] tag is based on a database table, named banners by default. It expects a total of five (5) fields in the table:

code

This is the key for the item. If the banners are not weighted, this should be a category specific code.

category

To choose to categorize weighted ads, this contains the category to select. If empty, it will be placed in the default (or blank) category.

weight

Must be an integer number 1 or greater to include this ad in the weighting. If 0 or blank, the ad will be ignored when weighted ads are built.

rotate

If the weighted banners are not used, this must contain some value. If the field is empty, the banner will not be displayed. If the value is specifically 0 (zero), then the entire contents of the banner field will be displayed when this category is used. If it is non-zero, then the contents of the banner field will be split into segments (by the separator {or}). For each segment, the banners will rotate in sequence for that user only. Obviously, the first banner in the sequence is more likely to be displayed than the last.
Summary of values of rotate field:

            non-zero, non-blank: Rotating ads
            blank:               Ad not displayed
            0:                   Ad is entire contents of banner field

banner

This contains the banner text. If more than one banner is in the field, they should be separated by the text {or} (which will not be displayed).

Interchange expects the banner field to contains the banner text. It can contain more than one banner, separated by the string '{or}.' To activate the ad, place any string in the field rotate.

The special key "default" is the banner that is displayed if no banners are found. (Doesn't apply to weighted banners.)

Weighted banners are built the first time they are accessed after catalog reconfiguration. They will not be rebuilt until the catalog is reconfigured or the file tmp/Banners/total_weight and tmp/Banners/<category>/total_weight is removed.

If the option once is passed (i.e., [banner once=1 weighted=1], then the banners will not be rebuilt until the total_weight file is removed.

The database specification should make the weight field numeric so that the proper query can be made. Here is the example from Interchange's demo:

   Database   banner   banner.txt   TAB
   Database   banner   NUMERIC      weight

Examples:

weighted, categorized

To select categorized and weighted banners:
The banner table would look like this:

            code    category   weight   rotate   banner
            t1      tech       1                 Click here for a 10% banner
            t2      tech       2                 Click here for a 20% banner
            t3      tech       7                 Click here for a 70% banner
            a1      art        1                 Click here for a 10% banner
            a2      art        2                 Click here for a 20% banner
            a3      art        7                 Click here for a 70% banner

Tag would be:

            [banner weighted=1 category="tech"]

This will find *all* banners with a weight >= 1 where the category field is equal to tech. The files will be made into the director tmp/Banners/tech.

weighted

To select weighted banners:

            [banner weighted=1]

This will find *all* banners with a weight >= 1. (Remember, integers only.) The files will be made into the director tmp/Banners.

            code    category   weight   rotate   banner
            t1      tech       1                 Tech banner 1
            t2      tech       2                 Tech banner 2
            t3      tech       7                 Tech banner 3
            a1      art        1                 Art banner 1
            a2      art        2                 Art banner 2
            a3      art        7                 Art banner 3

Each of the above with a weight of 7 will actually be displayed 35 percent of the time.

categorized, not rotating

            [banner category="tech"]

This is equivalent to:

            [data table=banner col=banner key=tech

The differences are that it is not selected if "rotate" field is blank; if not selected, the default banner is displayed.
The banner table would look like this:

            code    category   weight   rotate   banner
            tech               0        0        Tech banner

Interchange tags can be inserted in the category parameter, if desired:

            [banner category="[value interest]"]

categorized and rotating

            [banner category="tech"]

The difference between this and above is the database.
The banner table would look like this:

            code    category   weight   rotate   banner
            tech               0        1        Tech banner 1{or}Tech banner 2
            art                0        1        Art banner 1{or}Art banner 2

This would rotate between banner 1 and 2 for the category tech for each user. Banner 1 is always displayed first. The art banner would never be displayed unless the tag [banner category=art] was used, of course.
Interchange tags can be inserted in the category parameter, if desired:

            [banner category="[value interest]"]

multi-level categorized

            [banner category="tech:hw"] or [banner category="tech:sw"]

If have a colon-separated category, Interchange will select the most specific ad available. If the banner table looks like this:

            code    category   weight   rotate   banner
            tech               0        1        Tech banner 1{or}Tech banner 2
            tech:hw            0        1        Hardware banner 1{or}HW banner 2
            tech:sw            0        1        Software banner 1{or}SW banner 2

This works the same as single-level categories, except that the category tech:hw will select that banner. The category tech:sw will select its own. But, the category tech:html would just get the "tech" banner. Otherwise, it works just as in other categorized ads. Rotation will work if set non-zero/non-blank and it will be inactive if the rotate field is blank. Each category rotates on its own.

Advanced

All parameters are optional since they are marked with an asterisk (*).
Tag syntax:

            [banner
                weighted=1*
                category=category*
                once=1*
                separator=sep*
                delimiter=delim*
                table=banner_table*
                a_field=banner_field*
                w_field=weight_field*
                r_field=rotate_field*
            ]

Defaults are blank except:

            table       banner    selects table used
            a_field     banner    selects field for banner text
            delimiter   {or}      delimiter for rotating ads
            r_field     rotate    rotate field
            separator   :         separator for multi-level categories
            w_field     weight    rotate field