For more information on usage, bugs, features etc, please visit the forum thread.
Requires smd_lib v0.22 to be installed and activated.
Randomly display banners on a page for cosmetic or advertising purposes. The concept is: what if you want to advertise other parts of your site (e.g. other products/services) using a banner ad? You want an image/animated gif/video/whatever to advertise the products or services and when people click on the banners, they should be taken to the correct part of the site. The crucial difference is that it looks very amateur to advertise the product the person is currently looking at on the same page as the product itself.
This plugin allows you to randomly include/exclude clickable images or files, based on fixed text strings or the contents of article fields. It can also be used to simply spruce up a page and show a random image each time.
Features:
In its base form, this mode functions exactly as dru_random_image, i.e. 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.
modeSwitches the plugin between this default image mode (pulling pictures from the image database) or file mode (from uploaded files).
imagefilecategoryA comma-separated list of image category names to choose from; either named explicitly or using one of the following variables:
?c!c?s!s?t!t?idID. This helps when creating per-article image categories and means you don't have to use category names that are simply numbers.!id?fieldname?custom1), it could also be any other field (or fields) from your articles (e.g. ?excerpt or ?category1 or ?keywords or ?authorid, etc). Be warned: if you use ?body or something equally outrageous, chances are the plugin will explodeTo negate any category selection, use !category or !field_name. If you list specific image categories (e.g. !mammals) those categories will be excluded. If you specify a field name such as !keywords or !custom1, 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 ?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.
subcatsAutomatically includes all sub-categories of the chosen image categories.
1match_textA comma-separated list of text strings to look for in the image. As with the category option, you can specify the following special options:
?c?s?t?id?fieldnameavoid_textExactly the same as match_text except it defines words that must not be found in the image. Any images that do not contain the word(s) are fair game.
?c?s?t?id?fieldnameNote 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_toAll 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:
nameidcaptionaltcategoryid_prefixThe string which will be prefixed before every article ID. Defaults to "article-". In other words, if you are currently viewing article 75 and use match_text="?id" the plugin will look for any images that contain "article-75" and add them to the list of available files in the pool.
If you prefer something else before the ID, specify it with this option. If you wish the article ID to be used without any prefix, use id_prefix="".
limitThe maximum number of images to display from the pool. 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. Default: 1.
always_displayIf no matching images are found the plugin usually returns nothing. This forces it to try again without any match_text/avoid_text. Default: off.
01thumbTo display thumbnails instead of fullsize images. Default: omitted (i.e. off).
1link_inMakes the banner image clickable. In the current implementation of Textpattern we are limited to putting a URL link either in the alt or the caption. For accessibility, the caption is probably a better choice but it's your call. Specify which part of the image the URL is stored with this option. It can be either alt or caption in this mode (file mode is different). 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.
captionaltlink_prefixString 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 caption/alt text. Default: omitted (no text).
Again, as with link_in if link_prefix 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.
referer (sic!)Each image has ?bid=imageID added to it, so clicks can be tracked in the 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 (when link_in is used). Note that the option is mis-spelled exactly the same way as the HTTP spec was all those years ago :-)
imgclassCSS class for each banner image displayed. Default: empty (i.e. no class).
raw_urlInstead of linking and making a full image tag, using this option just outputs the URL directly to the page. This can be used in <style> declarations to, for example, set a random CSS object background. Default: off.
1targetSpecifies 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).
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.
<txp:smd_random_banner category="animals" limit="4" subcats="1" />
That would pull out four pictures of any animal to show on your front page; maybe arranged into a neat square!
<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.
<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.
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.
<txp:smd_random_banner category="animals, !c" subcats="1" link_in="caption" />
Slightly more useful, this one. It tells the plugin to select any animal image but not one from the current category that is being viewed. So it'll effectively 'advertise' other categories for you.
<txp:smd_random_banner category="reptiles, ?custom1" link_in="caption" subcats="1" />
This example gives you a random image chosen from the 'reptiles' image category 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 all four categories (and their sub-categories in this case). 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="1" />
So that would choose an image from any of the animals except ones that were in any categories listed in custom1.
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. So we can do this:
<txp:smd_random_banner category="animals" subcats="1" 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'.
If your filenames were a little unstructured, maybe you'd want to check the alt text and caption text for a match as well. Use compare_to for this:
<txp:smd_random_banner category="animals" subcats="1" link_in="caption"
avoid_text="croc, crocodile, alligator" compare_to="name, alt, caption" />
<txp:smd_random_banner category="animals" subcats="1" avoid_text="?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 article 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.
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 random banner as a 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 if you choose) and renders it as best it can.
There is one crucial difference in this mode: since we are 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 rule; except the tools 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.
First things first: once a file has been selected based on your options, the plugin looks at its file extension. Based on that it uses a lookup table to determine the correct MIME type and <object> tag template. The MIME type is overridable on a per-file basis but the templates are all hard-coded for now. The next revision of the plugin will allow them to be extended/modified via plugin options and to also add in custom MIME types. With luck.
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 allowing overridable 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. See example 1 and 2 for more.
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:
data= the URL to the file itself. Takes the file's URL from the TXP database by default, or it may be overridden by youtype= the MIME type of the file. Again, uses the lookup table. If it chooses wrongly or you want a fanciful type not included, override itwidth= 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 thisheight= the vertical screen real estate the object takes up. MLP-aware, as aboveid= The unique ID for the object. If not overriden, will default to "id" plus a random number.The other options are too numerous to list, but W3Schools 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> tag within the object itself. Use this facility to specify any extra options your chosen file type requires to operate correctly.
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':
The following option is ignored in this mode:
And these options work differently, or are specific to this mode:
compare_to (file mode)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:
filenamedescriptionstatussizecategorylink_in (file mode)Makes the banner file clickable by specifying which field of the file the URL is stored. Can currently only be description. Default: omitted (no link)
descriptionlink_url=http://my.domain.com/place/to/visit.php;
imgclass (file mode)Although slightly misleading as a named option, this gives an overall CSS class applied 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.
count_downloadsBy default 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 <object> tag to not only have a data= option 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!
10files_dirWhen 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 option. The default is files.
To highlight the features, we are going to use the same zoo web site as in the Image mode examples. This time 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.
<txp:smd_random_banner mode="file" category="animals" avoid_text="?keywords"
compare_to="filename, description" subcats="1" />
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>
Using the same example 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" />
<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.
<txp:smd_random_banner mode="file" category="animals" match_text="cheetah"
subcats="1" link_in="description" imgclass="flobjects" />
If one of the rows in the description field of the cheetah_chasing_deer.wmv file is url_link=/animals/cheetah-chasing-deer then clicking on the embedded movie will take the visitor to that article. 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.
This plugin was originally based on dru_random_image and plagiarises 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.