smd_random_banner

Contents

• Features
• Author
• Installation / Uninstallation
• Tag usage
  • Image mode
    • Attributes
  • File mode
    • Mime types
    • Attributes
  • Article field codes
• Examples
  • Image mode
  • File mode
• Changelog
• Credits

Features

• Randomly display one or more banners on a page for cosmetic or advertising purposes
• Reduce the pool of potential banners based on category/id or some text that matches something in the current article
• Subcategory support
• Banners can be images or files to display static or moving content (includes swfobject support)
• Optionally link banners to URLs and (kind of) track which banners received most clicks via TXP’s logs

Author

Stef Dawson. For other software by me, or to make a donation, see the software page.

Installation / Uninstallation

Requires smd_lib to be installed and activated. Requires TXP 4.3.0+ to utilise file title

Download the plugin from either textpattern.org, or the software page, paste the code into the TXP Admin->Plugins pane, install and enable the plugin. Visit the forum thread for more info or to report on the success or otherwise of the plugin.

To remove the plugin, simply delete it from the Admin->Plugins tab. If you are no longer using smd_lib with any other plugins, this can also be removed.

Usage

If you want to either display ‘intelligent’ banners on your page that somehow relate to the currently-viewed content; or perhaps display some banners that advertise other parts of your site (e.g. “While you are here, how about…”) then this plugin will help you achieve that. It can also be used to simply spruce up a page and show a random image or two each time.

The plugin can function in two distinct modes; image or file.

Image mode

In its base form, this mode functions exactly as dru_random_image, i.e. it picks one random image from the entire database of images and displays it. But it can do a whole lot more. Each option whittles the images down further, based on various criteria, until you are left with a potential pool of images, from which the plugin then randomly chooses one or more pictures.

Image mode attributes

Switches the plugin between this default image mode (pulling pictures from the image database) or file mode (from uploaded files).

Filters

• category : a list of image categories. By default the list should be comma-separated but this can be changed with the delim option. This attribute may take any of the special field codes by giving its name after a ? (to include that field) or ! (to exclude that field)
• id : a list of image IDs. Takes exactly the same syntax as the category attribute. Can be used in combination with category to produce a full set of images to choose from. You may also specify ranges of image IDs, e.g. id="10-15, 42" would make images with IDs 10 through 15 and ID 42 available. A special value exists for those circumstances when you want to use multiple banners on a page but don’t want them to duplicate any images. Specify SMD_UNIQUE as one of your parameters and the plugin will ignore any images already chosen by other smd_random_banner tags on the same page
• subcats : how far ‘down’ to traverse image sub-categories. Takes an integer value or ‘all’. 0 (the default) means no child categories; 1 uses the main categories and the first level of children; 2 uses the main categories and up to two child sub-categories; and so on
• limit : the number of banners to show per page. Default: 1. Note that if the pool contains fewer items than the number specified here, the plugin can only display the maximum number it has found that match your criteria

Image selection

• match_text : a comma-separated list of text strings to look for in the image details. As with the category and id attributes, you can specify field codes to match against something in the current article
• avoid_text : the opposite of match_text; a comma-separated list of text strings that must not appear in the image details. You can also specify field codes to match against something in the current article. Note that any images matching stuff in the ‘positive’ match_text list will be chosen first, before some of them are then excluded from the list in avoid_text
• compare_to : all this talk of comparing words to images is fine, but what exactly is it comparing to? This is where you declare where the plugin looks. By default it uses just the image file name, but it can be extended to encompass any of the following:
  • name : look at the filename of the image and if it contains any of the words in match_text then add it to the pool. Conversely, if it contains any of the words in avoid_text then ignore the image
  • id : look at the id of the image and include/exclude it based on the numbers given in match_text / avoid_text
  • caption : if the caption contains words found in match_text and words not found in avoid_text, include/exclude this image from the pool
  • alt : if the alt text contains or does not contain the specified words, include/exclude this image from the
  • category : although not really of much use (the category attribute can be used instead), you may specify the category as a place to look for particular words

Link handling

• link_in : makes the banner image clickable. In the current implementation of TXP we are limited to putting a URL link either in the alt, caption or name fields. Simply use this attribute to specify which part of the image details contain the destination URL. It can be either alt, caption or name. Default: omitted (no link)
  If the link is a full URL starting with http:// it will be used verbatim for the image link. If it starts with a / it will be hung off the root site_url directly. If it starts with anything else it is assumed a ‘relative’ (or ‘local’) link and inherits the current section.
• link_prefix : a string to prepend to every URL when using link_in. Useful if you reorganise your site: use this instead of visiting each image and altering the name/caption/alt text. Default: omitted (no text). As with link_in, if this attribute begins with http:// it is assumed a full URL to another site; if it begins with / it is a root link; anything else is assumed relative to the current section. Note that if you use an http:// full URL in the image itself, any link_prefix will be ignored
• display_url : since this plugin can hijack the caption/alt text for a destination URL, you may wish to not show this to visitors (as the default tooltip popup title) or screen readers/search engine crawlers (the alt text). Using display_url="0" will simply use the details from whichever element you are not using for link_in. For example, if your alt text is “Spud gun” and your caption is “http://spudguns.com/”, setting display_url to 0 will make both alt and title attributes both “Spud gun”
• referer : [sic!] when link_in is used, each clickable image has ?bid=imageID added to it, so clicks can be tracked in the TXP admin logs to see which are the most effective ads. Change the bid text here to something of your choosing, or use referer="" to disable tracking. Default: bid. Note that the attribute is mis-spelled exactly the same way as the HTTP spec was all those years ago :-p

Formatting

• raw_url : instead of linking and making a full image tag, using this option just outputs the banner URL directly to the page. This can be used in <style> declarations to, for example, set a random CSS object background. Default: off
• target : specifies the anchor target window (e.g. “blank”) which will cause a popup effect when a linked banner is clicked. _NB: if using the XHTML 1.1 DOCTYPE with this option, your page will not validate since target is deprecated by the W3C. Default: not set (links open in same window)
• class : CSS class for each banner image displayed. Default: empty (i.e. no class). Note that this attribute was formerly called imgclass
• thumb : set this to 1 to display thumbnails instead of full size images. Default: 0 (or omitted)

Plugin customisation

• mode : switches the plugin between this default mode="image" for pulling banners from TXP’s Images page, or mode="file" to choose banners from files uploaded to TXP Files page.
• always_display : if no matching images are found the plugin usually returns nothing. Setting always_display="1" forces it to try again without any match_text or avoid_text (i.e. just any category / id you specified). If you really, really want an image regardless, use always_display="2" to pull an image from the entire database. Default: 0 (i.e. off)
• delim : if you prefer to set the delimiter to something other than a comma when specifying fields, use this attribute. Very useful if using the glz_custom_fields plugin; you can set this to delim="|" to use select or radio buttons in custom fields

File mode

Similar in many respects to the image mode the plugin can choose random files from those uploaded to the Files tab in the TXP interface. This gives you the option of using a randomly selected piece of Flash or a video file if you want. In theory, if there’s a browser plugin available for it, you can play it (but note the caveats later: support for everything isn’t built in natively).

As with the image mode, most of the options work to whittle down the choices to a pool of files that match your specific criteria. The plugin then randomly chooses one (or more) of those and renders it as best it can.

There is one crucial difference in this mode: since TXP is limited to one field of customisable content with Files and there are a lot of potential idiosyncracies in embedding playable content, only the core functionality is specified as plugin options. Customisation above and
beyond that goes in the description field as a catch-all for many extra options.

Unfortunately, using one field for many purposes implies sticking to some conventions. To this end, when specifying options in the description field, use the following format:

optionName1=optionValue1;
optionName2=optionValue2;
...

No quotes are necessary around the option values as the plugin will put them in for you, though it does no harm to include them. And although spaces and newlines are also optional, it’ll help keep your sanity if you do things this way! Just note that every option=value pair ends with a semicolon (;). It is probably best to set aside a specific category/sub-category file tree for your banners since we are going to be hijacking the description field for purposes other than it was intended.

MIME types

MIME types rule in Files mode. Unfortunately, the tools browsers and servers employ to accurately determine which file is of what type are often extensions and cannot be guaranteed to be installed on every server. So we have to use the next best thing: the file extension. Yes it can be misleading, but we’re stuck with it.

Once a file has been selected based on your chosen attributes, the plugin looks at its file extension. Based on that it uses a lookup table to determine the correct MIME type and template. The MIME type is overridable on a per-file basis but the templates are all hard-coded for now. I’m hoping to one day allow them to be extended/modified via plugin options, but it’s a way off yet.

For now, the most common things like Flash files, AVI/MOV/MPG/WMV movies and even some audio formats like WAV/OGG/OPTIMFROG/FLAC are supported (audio banners anyone?!) And the good news is it should be fairly automatic (if it isn’t, please get in touch and suggest better templates for the next revision).

The key to it is overriding the default options. The HTML object tag contains a host of attributes, all of which you can override by specifying them as option=value pairs in the description field of that particular file. Any attributes that match the names in the HTML spec can be used. These are the core ones that the plugin will select for you if you do
not specify your own in the description field or the global_params attribute:

• data : the URL to the file itself. Takes the file’s URL from the TXP database by default, or it may be overridden by you
• type : the MIME type of the file, determined from the internal lookup table. If it chooses wrongly or you want a fanciful type not included, override it
• width : the horizontal screen real estate that the object will occupy. By default it takes the values on a per-language basis (if MLP is installed) because content often varies from country to country. Without MLP it’s 300px so you probably should override this
• height : the vertical screen real estate the object takes up. MLP-aware, as above
• id : the unique ID for the object. If not overriden, the default is “id” plus a random number

Overriding MIME types / swfobject

If you wish to override the auto-detected mime type for any reason, specify mime_type=UseThisFileExtensionInstead (e.g. mime_type="avi"). That will then use the template for an avi file regardless of the file’s real extension.

Some people prefer to embed movies using the 3rd party library swfobject. Random_banner supports this library but it does not load the library for you: incorporate it onto your page prior to calling smd_random_banner.

Overriding the MIME type is currently how swfobject mode works: it’s a hack because the plugin cannot differentiate between a .swf you want to embed with the object tag and one you want to embed using swfobject. In this case, specify the special attribute mime_type="swo", either in the description field of the relevant file or as a global_param.

When using swfobject there are a few more options you can specify:

• playerversion : the minimum version of flash player you require users to have before they can see the content. Default is 8
• backcolor : a hex string like #007412 to set the color of the background of the swfobject. Note it’s called backcolor to distinguish it from the object tag’s bgcolor. Default is white
• elementid : the unique identifier which the movie replaces. This is normally an empty div with an id of flashcontent but since this plugin can output more than one banner on the page, the default behaviour is to add a random number on the end of it
• uid : the javascript identifier that is used to identify the SWFObject instance. In all the examples on the swfobject
  web site this is so but again, since the plugin can output more than one banner, the default behaviour adds a random number on the end of it

In both standard object and swfobject modes, the other options are too numerous to list, but W3Schools, Adobe or Google will help you find them if you need them.

Any option=value pair specified in the description field that is not part of the core spec is assumed to be a <param> within the object itself. Use this facility to specify any extra options your chosen file type requires to operate correctly. If you need to use a delimiter other than = between name-value pairs, use the nv_delim attribute.

When using swfobject mode, standard parameters and FlashVars are differentiated and passed to your application using addParam() and addVariable() respectively. Note that expressinstall is currently not supported.

File mode attributes

The following attributes work in exactly the same way as they do in image mode with the exception that everywhere it mentions ‘image’ you can substitute ‘file’:

mode, category, id, subcats, match_text, avoid_text, limit, always_display, link_prefix, referer, raw_url, target, delim

The following options are ignored in File mode:

thumb, display_url

And these options work differently, or are specific to this mode:

File selection

• compare_to : declare which fields of the file the plugin looks when matching or avoiding text. By default it uses just the file name, but it can be extended to encompass any of the following:
  • filename : look at the filename of the file and if it contains any of the words in match_text then add it to the pool. Conversely, if it contains any of the words in avoid_text, ignore the file
  • title : look at the file’s title and if it contains any of the words in match_text then add it to the pool. If it contains any of the words in avoid_text, ignore the file
  • id : look at the id of the file and include/exclude it based on the numbers given in match_text / avoid_text
  • description : look at the description of the file and include/exclude it based on the words in match_text / avoid_text
  • status : if the numeric display status of the file matches (for match_text) or does not match (for avoid_text) any given numbers, include/exclude this file from the pool
  • size : (of limited use) if the file is of a particular size (for match_text) or not of a particular size (for avoid_text), include/exclude this file from the pool
  • category : as with image mode, this may not be of much use (the category attribute can be used instead), but you may specify the category as a place to look for particular words

Link handling

• link_in : makes the banner file clickable by specifying which field of the file the URL is stored. This can currently only be description or title. Default: omitted (no link). The destination URL in the description field of the file is a name=value pair like this: link_url=http://my.domain.com/place/to/visit
  A full URL beginning http:// will be used verbatim, anything beginning with a / will assume to be relative to the site root and everything else will be relative to the current section/article. Note that depending on the plugin mode, the link may not be honoured because the chosen browser plugin (e.g. shockwave flash) may capture mouse clicks. In flash, this can be circumvented (currently on platforms except Linux) by specifying the param wmode=transparent;

Parameter definitions

• nv_delim : when specifying name-value pairs in the description field, you may be faced with the problem that you want to use the = sign elsewhere; this is most notable when using FlashVars because they require name=value to be used. The line: FlashVars="myVar=Jim"; will cause the plugin problems because it will split the line up into 3 parts, instead of the two you require.
  To avoid this, you may specify nv_delim and set the first delimiter to anything else you like. It could be a single character, a sequence of characters, a word, anything as long as it’s unique. Normally nv_delim="::" works well so your variables in the description field become: FlashVars::myVar=Jim;
• row_delim : occsionally the default ; is insufficient because you wish to use it inside your name-value pairs (perhaps in the onclick attribute). If this is the case, specify an alternative end-of-row delimiter here
• global_params : specify any global name-value pairs in this option that you sih to apply to all banners. Very useful for things like codebase or specifying a global width and height. The values are overridable on a file by file basis using values in the description field as usual. The parameters work for both the standard object tag and the swfobject javascript. Note that you specify parameters in exactly the same way as you do in the description field — each separated by semicolons — and that the nv_delim attribute governs which delimiter will be used. IMPORTANT : the last value in the list must also be terminated with a semicolon

Formatting

• class : apply an overall CSS class to each banner file’s <object> tag. Default: empty (i.e. no class). Can be overridden on a file-by-file basis by specifying the value class=myClassName; in the description field of any file.

Plugin customisation

• count_downloads : by default (count_downloads="1") every time a banner file is served, the associated counter for that file is incremented. This may or may not be desirable so it can be turned off here. The reason it is an option is because it can in some circumstances lead to misleading results. For example, a certain browser that shall remain nameless requires an