smd_random_text

Choose random text strings from a variety of sources. Could be used as a quote-of-the-day system, random tag lines, or something more elaborate.

Features

• Pull the item list from either: a given delimited string, a file, a database column, a <txp:variable />, user-submitted form data, or a Textpattern field
• Grab as many random items as you like from your chosen list
• Pass each to a form/the container if you wish to format them

Author

Stef Dawson. Combines ideas from dru_random_text by Drew McLellan and simple_random_text by Manuel Ebert, plus some sprinklings of my own. Many thanks to the authors of those works.

Installation / Uninstallation

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 uninstall, simply delete from the Admin -> Plugins page.

Usage

Use the tag in any page, form or article/file/image/link context.

smd_random_text

There are two mandatory attributes: type and source. The others are used to control how the information is extracted and/or presented.

Attributes

• type : where to look for the pool of text strings. Can be one of string (the default), field, txpvar, urlvar, database, or file
• source : further refinement of where to find the strings using the following rules:
  • string : a delimited list of text (e.g. source="my|cracking|words|of|the|day|in a natty little|list")
  • field : the name of the Textpattern field to look in (e.g. source="article_image" or source="my_custom_field_name")
  • txpvar : the name of a <txp:variable /> that has been defined in (e.g. source="my_list")
  • urlvar : the name of a URL variable (via GET or POST) that will be passed to the page (e.g. source="property_list")
  • database : the table and column name, separated by delim (e.g. source="txp_category|title")
  • file : a file name relative to the root of your site, with or without leading slash (e.g. source="files/my_strings.txt")
• delim : the delimiter to use between words/attribute options. Default: pipe |
• file_delim : the delimiter to use when parsing files. If each word or phrase is on its own line then the default newline (\n) is sufficient. If you wish to have all your text strings on one line of the file delimited by some other character, set your own delimiter here
• limit : the number of items to pull from the list. Defaults to 1. If you specify more than the available number of items in the pool, the entire pool will be used and presented in a random order
• item_num : show this particular item from the pool. If it doesn’t exist, you get the first item. But wait?! This is a random_text plugin, why would anybody want to specify which item to use? Two uses spring to mind: Firstly, if you have already randomized your items externally you might wish to always pick, say, the first item. Secondly — and far more subtly — if you wish to pull more than one item from any randomly chosen place, you can nest smd_random_text tags and make the inner tags always use the same row/position number as the randomly chosen outer tag. See example 7 for an example
• shuffle : perhaps a little pointless, this adds an extra layer of randomness to proceedings by shuffling the chosen items again. So if you had asked for 6 items in your list of 20 and the plugin had randomly chosen them in this order: 4, 17, 2, 5, 13, 11, using shuffle="1" might reorder them to 17, 5, 2, 11, 4, 13
• count : whether to count up (the default) or down for each random piece of text
• trim : whether to remove whitespace from around each list item (1) or not (0). Default: 1
• escape : escape HTML entities such as <, > and & in any text items. Use escape="" to turn it off. Default: html
• form : the form to use to format the text. If not supplied, will try the container. If that’s not used either, the plugin will simply output the chosen text on its own
• wraptag : the (X)HTML tag with which to wrap the chosen strings, eg wraptag="ul". Default: unset
• break : the (X)HTML tag to put between successive items of text, eg break="li". Default: unset
• class : the CSS class to apply to the item wraptag, eg class="random_strings". Default: unset
• debug : set to 1 to show the pool, the file name (if applicable) and the chosen items. Use 2 to see what fields are available

Replacement tags

When using a form or container, use the following replacement tags to insert the relevant piece of information wherever you want it:

{smd_rnd_txt} : the text string itself
{smd_rnd_txt_rows} : the number of items in total
{smd_rnd_txt_thisrow} : the current row number
{smd_rnd_txt_thisindex} : the current row index (zero-based)
{smd_rnd_txt_chosen_item} : the zero-based index number of the actual item selected by the plugin (see example 7

Examples

Example 1: Quote of the day

Read from a database, the table (that has been added to the TXP database; the connection must already be open) is called “quotes” and the column containing the quotes is called “text”:

<txp:smd_random_text type="database"
     source="quotes|text">
  <div class="qotd">Quote of the day: <br />{smd_rnd_txt}</div>
</txp:smd_random_text>

Example 2: Five random comments

<txp:smd_random_text type="database"
     source="txp_discuss|message" limit="5"
     wraptag="ul" break="li" />

Example 3: Top 10 words

Top ten random silly words from a list in a file in the textpattern root folder, counting down from 10 to 1. Each word must be on a separate row of the file unless you specify the delim attribute to be something else; in which case the words must all appear on the first row of the file. If there aren’t 10 items in the file, the count begins from however high it can go.

<txp:smd_random_text type="file"
     source="words.txt" limit="10"
     form="wordout" count="down" />

and in form wordout:

#{smd_rnd_txt_thisrow} : {smd_rnd_txt} <br />

Example 4: Random e-mail address

Use a <txp:variable /> to hold a list of random e-mail addresses from which one will be selected to be sent via a zem_contact_reborn form:

<txp:variable name="emails"
     value="Aldous.Huxley|William.Shakespeare|John.Betjeman" />
<txp:zem_contact
     to='<txp:smd_random_text type="txpvar"
     source="emails" />@writers.com'>
  // Other zem_contact options
</txp:zem_contact>

Example 5: Random image selection

Indirectly, not just for text! Choose two random image IDs from a comma-separated list given in the custom field labelled “my_images” and display them via the built-in <txp:image /> tag.

<txp:smd_random_text type="field"
     source="my_images" limit="2" delim=",">
  <txp:image id="{smd_rnd_txt}" />
</txp:smd_random_text>

Example 6: Item from a fact file

Add this to your files form to display a random fact about each file from a pipe-delmiited list defined in the file’s description field:

<txp:smd_random_text type="field"
     source="description">
<br />FACT: {smd_rnd_txt}
</txp:smd_random_text>

Example 7: Keeping items in sync

Say you have a database that holds employee information and you want to give three random employees a 10% bonus. You need to publish the list on the web site but you want to make sure you get the right employees coming forward. So you need to publish their name, employee ID, and department (i.e. 3 columns from the table).

With smd_random_text you can only grab one column at a time so how do you ensure you get the three columns that correspond with the correct row for each employee? Like this:

<txp:smd_random_text type="database"
     source="employees:name" limit="3" wraptag="ul"
     break="li">
   {smd_rnd_txt}
   (<txp:smd_random_text type="database"
     source="employees:ID"
     item_num="{smd_rnd_txt_chosen_item}" />)
   from the <txp:smd_random_text type="database"
     source="employees:department"
     item_num="{smd_rnd_txt_chosen_item}" />
   department
</txp:smd_random_text>

As you can see, the first smd_random_text chooses three random employee names from the database. Then, for each of the chosen employee names, the second (inner) smd_random_text goes back to the database and gets the ‘ID’ column _from the same row as the one just chosen. It uses {smd_rnd_txt_chosen_item} to force the plugin to read the current row. The third smd_random_text does exactly the same: grabs the ‘department’ column from the row we randomly selected at the start.

OK, that’s a contrived example because you’d never use smd_random_text for this type of thing — for a start it’s a waste of bandwidth and the three calls are not atomic. You could, however, apply the same logic to three <txp:variables /> containing linked information. In this manner you can build up complex interactions between sources; they don’t even have to be of the same type!

Changelog

• 10 Oct 08 | 0.1 | Initial release
• 17 Mar 09 | 0.11 | Added trim and escape
• 26 Jul 09 | 0.12 | Added item_num, shuffle and the replacement tag {smd_rnd_txt_chosen_item}