smd_random_banner

n: smd_random_banner | v: 0.42 | f: /

Documentation for the Textpattern plugin smd_random_banner by Stef Dawson follows this short message from our sponsor ;-)

Plugin list buttonPlugin download buttonCompressed plugin download button

smd_random_banner

Contents

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 tag to not only have a data parameter but also a movie parameter when serving Flash content. With only one of these specified, the file will not play; yet with both the file is downloaded twice and the download counter goes up by two. So the number of visitors you have using this browser may skew your download stats. If your boss likes to rely on such values it might be best to turn the option off and keep quiet! When using count_downloads="0", you may require use of the files_dir attribute if you have changed your default textpattern directory structure
  • files_dir : when the count_downloads attribute is turned off, files are served by directly accessing the URL of the files directory. This is usually http://yourdomain.com/files. If you have changed your directory structure and the files directory is
    somewhere else or called something else, specify it with this attribute. The default is files
  • no_plug_text : if a browser plugin is not available to a user, this text will be displayed instead. It could direct them to a site from which to download the plugin. You can either put plain text/html in here or specify a textpattern form by using no_plug_text="txpform:name_of_form". This saves you having to use the asy_wondertag plugin to enable tags-in-tags functionality
  • Article field codes

    Use these codes to grab items from the currently displayed article and inject them into tag attributes. When using field codes, the tags can be combined with fixed text (e.g. category="mycat-?article_image_?s" might choose images from the category “mycat-12_lion” if the current article was in section ‘lion’ and had an article image of ‘12’). Note that any article or custom fields — including those utilising glz_custom_fields — may contain lists of items.

    • ?c : use the current global (article) category
    • !c : uses everything except the current global category
    • ?s : use the current TXP section
    • !s : uses everything except the current section
    • ?t : use the current article’s url-title
    • !t : uses all url-titles except the current article (probably not much use!)
    • ?id : use the current article’s ID as the name of an image category. Useful to make a per-article image gallery (e.g. category="article-?id")
    • !id : uses all image IDs except the current article
    • ?fieldname : looks in the given fieldname of the current article. Designed primarily for use with custom fields (e.g. id="?custom1"), it can also be any other field from your article. Common fields are ?excerpt @?category1@ ?keywords @?article_image@ or ?authorid.

    To negate any category selection, use !category or !field_name. If you list specific image categories (e.g. category="!landscape, !birds") those categories will be excluded. If you specify a field name such as !keywords, the contents of that field will be read and the list of image categories found there will be excluded.

    Note that if you specify a field name and that field in the article is empty, the name will be treated as if it was an actual image category. So if you specified category="?keywords" and the ‘keywords’ field in the current article was empty, it would look for an image category named “keywords”.

    Also note that, regardless of the order you list them, all ‘positives’ will be processed first, then any exclusions applied.

    Examples

    To highlight the features, we are going to use an example of a zoo web site. On this site you have three sections: “about”, “animals” and
    “tours”. You have images of various animals under an image category called “animals”. Below that they are separated into “mammals”, “reptiles”, and “birds”. Your alt text holds suitable alternate descriptions of the animals and the caption text is a url to an article about each animal. You also have other image categories for the rest of your site.

    Image mode examples

    Example 1: Simple banner images

    <txp:smd_random_banner category="animals" limit="4"
         subcats="all" />
    

    That would pull out four pictures of any animal to show on your front page; maybe arranged into a neat square!

    Example 2: Linked banner image

    <txp:smd_random_banner category="mammals, reptiles"
         link_in="caption" />
    

    Would display a random picture from either the mammals or reptiles categories. The image would be clickable and the link would take you to the URL given in the caption field of that image. If the caption field happened to be empty, the link would be supressed.

    Example 3: Random CSS background

    <style type="text/css">;
    #myDiv {
      background: url(<txp:smd_random_banner category="animals"
         subcats="1" raw_url="1" />) no-repeat top;
    }
    </style>
    

    This kind of syntax can be used if you only wanted the background of a specific div tag to hold your random image.

    Example 4: Banner linked to article category

    If you arranged your site so that you had article categories such as “mammals” and “reptiles” (mirroring your image categories), you could do this:

    <txp:smd_random_banner category="?c"
         link_in="caption" />
    

    The ? tells the plugin you don’t know what the (image) category is going to be when you code the form, but you want it to be read from the current article that a visitor is viewing. Since our article categories mimic our image categories in this case, ?c means “read the article category and use that as the image category”.

    So if your visitor was viewing a page about a reptile, the random image displayed on the page would be of another reptile (possibly the
    same one). There are many other options.

    Example 5: Image from any other category

    <txp:smd_random_banner category="animals, !c"
         subcats="1" link_in="caption" display_url="0" />
    

    Slightly more useful, this one. It tells the plugin to select any animal image from the top level and first sub-category level but not one from the current category that is being viewed. So it’ll effectively ‘advertise’ other categories for you. The display_url is turned off this time so the URL in the caption field does not appear as the title attribute to the image; the alt text is used instead.

    Example 6: Images from custom field data

    <txp:smd_random_banner category="reptiles, ?custom1"
         id="4-8, 12" link_in="caption" subcats="all" />
    

    Gives you a random image chosen from the ‘reptiles’ image category, images 4, 5, 6, 7, 8 or 12 and also any categories listed in custom1 of the currently viewed article. If you put “mammals, birds, penguins” in custom_1 when you wrote the article you would get an image chosen from those image IDs plus all four categories (and their sub-categories in this case). Incidentally, this sort of idea could be used with category="?keywords" to get a list of “related image categories”…

    Note you can simply negate the choice like this:

    <txp:smd_random_banner category="animals, !custom1"
         link_in="caption" subcats="all" />
    

    So that would choose an image from any of the animals except ones that were in any categories listed in custom1. You can negate image IDs and ranges as well (e.g. id="14-20, 24, !19, 5, !10-16" would give an image pool of 5, 17, 18, 20, 24).

    Example 7: Text matching

    Categories on their own only tell half the story. There are times you might want to include or exclude specific pieces of text found in your images. The text could be in the filename, the id, the caption, the alt text, or the category name.

    Imagine your visitor clicked a picture of a crocodile and they are viewing the grisly details on an article page. You might want to put “If you liked this, find out about these animals too:” and show a few random images that allow them to see stuff about other animals. Obviously, we don’t want a picture of a crocodile to show up. And maybe we don’t want to show alligators either because they’re quite similar (sorry any reptile-lovers who may disagree!)

    So we can do this:

    <txp:smd_random_banner category="animals" subcats="all"
         link_in="caption" avoid_text="croc, crocodile, alligator" />
    

    That would choose any picture from the animals category (and all its sub-categories) as long as the name of the image didn’t contain ‘croc’ or ‘crocodile’ or ‘alligator’.

    Example 8: matching alt and caption

    If your filenames were a little unstructured, maybe you’d want to check both the alt text and caption text for a match as well as the filename. Use compare_to for this:

    <txp:smd_random_banner category="animals" subcats="all"
         link_in="caption" avoid_text="croc, crocodile, alligator"
         compare_to="name, alt, caption" />
    

    Example 9: Article field matching

    <txp:smd_random_banner category="animals" subcats="all"
         avoid_text="?s, ?c" compare_to="name, alt, caption, category" />
    

    On an article page, hard-coding lists of things to include/exclude is acceptable. But if you’re using a form you don’t want to do that, so just like the category option you can use ? placeholders that will read stuff from the current article. This example will pick any random animal except ones from the current section or global category. Note that, to be on the safe side, it checks in four locations to help ensure it won’t find anything related to the current category.

    File mode examples

    To highlight the features, we are going to use the same zoo web site as in the Image mode examples. But this time, assume you have uploaded a few Shockwave Flash documents about various animals and a couple of short movies about cheetahs under a file category called “animals”. The movies are sub-categorised as before. The description field of each file holds a url to an article about each animal using link_url=/animals/animalName;

    You can do all the same things as in image mode to choose which files match what text/categories so we’ll not cover that here. Only the
    new options are covered or where an option differs significantly.

    Example 1: Simple file banner

    <txp:smd_random_banner mode="file" category="animals"
         avoid_text="?keywords" compare_to="filename, description"
         subcats="all" />
    

    Fairly straightforward. Picks any file in the category called ‘animals’ that does not contain any of the current article’s keywords in its filename or description fields.

    Assuming it selects a shockwave flash file, the tag it outputs might be:

    <object data="http://mygreatzoo.com/file_download/2"
           type="application/x-shockwave-flash"
           width="300" height="75" id="id7465893">
    <param name="movie"
         value="http://mygreatzoo.com/file_download/2" />
    </object>
    

    Example 2: Enhanced control of Flash banners

    Using the same options as in Example 1, if you go to the Files tab, select the Flash file it chose and edit the description field to read:

    loop=false;
    width=450;
    codebase=http://mygreatzoo.com/;
    id="zoobject";
    standby="loading...";
    bgcolor=#006800;
    

    Then you would get an object tag that resembled this:

    <object data="http://mygreatzoo.com/file_download/2"
           type="application/x-shockwave-flash"
           width="450" height="75" id="zoobject">
    <param name="movie"
         value="http://mygreatzoo.com/file_download/2" />;
    <param name="loop" value="false" /&gt;
    <param name="codebase" value="http://mygreatzoo.com/" />
    <param name="standby" value="loading..." />
    <param name="bgcolor" value="#006800" />
    </object>
    

    Hopefully you can see that it’s quite flexible and should allow you to tweak any content to play in most browsers.

    Example 3: Changing the delimiter

    Using the same options as in Example 1, but adding one option nv_delim="::" means that in the description field you would have to specify the name-value pairs with a double colon between them, i.e.

    loop::false;
    width::"450";
    codebase::http://mygreatzoo.com/;
    id::zoobject;
    standby::"loading...";
    FlashVars::"myVar=http://mygreatzoo.com/lions";
    bgcolor::#006800;
    

    Note the addition of FlashVars. If you wish to send FlashVars to your application, they have to be delimited with an = so you must change nv_delim to something else. Any other character(s) will do, but using a single colon would cause grief because that character is used in URLs.

    Incidentally, passing a FlashVar in this manner may help make your banner clickable without resorting to using wmode=transparent; because you can simply place a button in your movie and pass the URL in from the description field via a FlashVar instead of using link_url.

    Example 4: Clickable file banners

    <txp:smd_random_banner mode="file" category="animals"
         match_text="cheetah" subcats="all" link_in="description"
         class="flobjects" />
    

    If one of the rows in the description field of the cheetah_chasing_deer.wmv file is link_url=/animals/cheetah-chasing-deer then clicking on the embedded movie will take the visitor to that article. You may also add an onclick handler in a similar manner, for example onclick=javascript:pageTracker._trackPageview('/advertiser/bannerad_name');. That would allow you to track page banner impressions using Google Analaytics. Note that there’s no need to specify the quotes around the onclick parmeter, but in this instance you would need to use the row_delim attribute to stop the plugin from using the default ; which is actually part of the onclick’s string. A good one for this might be row_delim=#~#. The onclick is only honoured if there is a destination link_url given in your chosen link_in field.

    In addition to the usual attributes, this and all objects displayed by the plugin will take on a class="flobjects" attribute. This can be overridden on a file-by-file basis by adding class="anotherClassName"; as an entry in the description field.

    Note that if your chosen media plugin captures click events before they are passed to the DOM, the link will not be honoured. For Flash, you can bypass this in most browsers (Linux is currently an exception) by passing wmode=transparent; or using a FlashVar as in Example 3

    Example 5: Enhanced matching and output control

    <txp:smd_random_banner mode="file" category="animals"
         avoid_text="?keywords" compare_to="filename, description"
         subcats="2" nv_delim="::"
         global_params="playerversion::9;width::75;height:500;" />
    

    In the Files tab, if you select one of the Flash files that the plugin might choose and edit its description field to read:

    mime_type::swo;
    uid::sob;
    quality::high;
    wmode::transparent;
    elementid::myFlashContent;
    FlashVars::linky=http://mygreatzoo.com/tigers&amp;pic=tiger.jpg;
    width::200;
    

    Then you might get output that resembled this:

    Note the ‘defer’ option. This is an attempt to prevent IE from crashing (which it sometimes does) with an “operation aborted” dialog.

    Changelog

    • v0.1 Initial public release
    • v0.11 Added PFX to query (thanks mercury)
    • v0.12 Fixed help to include trailing slashes (thanks vittorio)
    • v0.13 Unreleased. Added look_in=category and referer
    • v0.14 Added match_text and use_alt (thanks lukepermsn)
    • v0.15 Added always_display and limit (thanks lukepermsn)
    • v0.15a Bugfix for linkcaption (thanks mercury)
    • v0.16 Tightened image() params for txp v4.0.4 compliance
    • v0.17 Added thumb, linkprefix and linkalt options
    • v0.17a bid option now works with existing url params (thanks Papuass)
    • v0.18 Added imgclass option (thanks DigitalRealm)
    • v0.2 Major overhaul. Added subcategory support (thanks lukepermsn and santheo). Uses smd_lib. Enhanced match_text/avoid_text so look_in is no longer needed; dropped use_alt and added compare_to; replaced linkcaption/linkalt with link_in; added id_prefix; linkprefix is now link_prefix
    • v0.21 Added MLP support
    • v0.22 Added raw_url option
    • v0.23 Against better judgement, added target option (thanks jstubbs, cdtavijit)
    • v0.3 Added support for files as well as images – finally, video/swf banners are a reality!
    • v0.3a Fixed: if category=”?field” is empty/returns no results, plugin will no longer display a random image from the full pool
    • v0.31 Extended always_display. Added nv_delim to specify name=value delimiter in file mode params. Fixed: define() warning
    • v0.32 Added no_plug_text and global_params
    • v0.33 Uses smd_lib v0.3. Added swfObject support. Can now override mime type.
    • v0.34 Added static image support to files mode(!)
    • v0.4 Refactored code to take advantage of new smd_lib functionality (subcats, category and matching) ; added id, changed imgclass to class ; added display_url (thanks Andrew Blevins) ; can now link_in file name ; fixed swfobject bug in file mode ; removed id_prefix
    • v0.41 Fixed MLP string bug
    • v0.42 Added file title as a possible location ; added row_delim ; added onclick handler to file mode (thanks renobird) ; added SMD_UNIQUE (thanks Scott Girvan)

    Credits

    This plugin was originally based on dru_random_image and plagiarised ideas from Rob Sable’s rss_thumbpop and various TXPers in the community who have suggested features and improvements. Many thanks to all who have helped craft this plugin and of course Team TextPattern for the coolest CMS on the planet.

    Source code

    If you’d rather wander aimlessly through thousands of lines of PHP source code, you’ll need to step into the view source page.

    Legacy software

    If, for some inexplicable reason, you need an old version of a plugin, it can probably be found on the plugin archive page.

    Experimental software

    If you’re feeling brave, or fancy going bareback, you can test out some of my beta code. It can be found on the plugin beta page.