Banner/Ad rotation

### Index Up << >>

## Banner/Ad rotation

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

The [banner ...] MML 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 you weight one banner `7`, one `2`, and one `1`, then a total of 10 pre-built banners will be made. The first will be displayed 70% of the time, the second 20%, and the third 10%, in random fashion. If you want all equal, place an equal weight of 1.

Each category may have separate weighting. If you place the above in category `tech`, then it will behave as above when you place `[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, then this should be a category specific code.

category
  If you 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).

Minivend 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 either:

        -- the catalog is reconfigured
        -- the file tmp/Banners/total_weight or
           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 MiniVend's demo:

        Database   banner   banner.txt   TAB
        Database   banner   NUMERIC      weight

Examples:

weighted, categorized
  To select categorized and weighted banners:

  Your banner table would look like:

          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% of the time.

categorized, not rotating

          [banner category="tech"]

  This is pretty much equivalent to:

          [data table=banner col=banner key=tech

  The differences are:

          -- not selected if "rotate" field is blank
          -- if not selected, the default banner is displayed

  Your banner table would look like:

          code    category   weight   rotate   banner
          tech               0        0        Tech banner

  You can put MiniVend tags in the category parameter if you wish:

          [banner category="[value interest]"]

categorized and rotating

          [banner category="tech"]

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

          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 you used the tag `[banner category=art]`, of course.

  You can put MiniVend tags in the category parameter if you wish:

          [banner category="[value interest]"]

multi-level categorized

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

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

          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

### Index Up << >>