smd_lib: The library

n: smd_lib | v: 0.37 | f: /

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

Plugin list buttonPlugin download buttonCompressed plugin download button

smd_ plugin library

Offers no public textpattern tags. It is simply a shared library of common functions used by smd_ plugins.

Function Reference

smd_addQSVar
smd_removeQSVar

Add or remove a query string variable to the given URL, taking into account any existing variables that may be in the URL already. ‘Add’ takes three arguments, ‘Remove’ just takes the first two:

  1. The URL string to add to/remove from
  2. The id of the querystring (the bit before the = sign)
  3. The value of the new querystring (the bit after the = sign)

e.g. smd_addQSVar($thisarticle['url_title'], 'tpg', 15); would add tpg=15 to the current article’s URL. If there are no other variables currently in the URL, it is added with a question mark, otherwise it is appended with an ampersand.

smd_doList

Return an expanded list of items with the following properties:

  1. Anything containing ‘?’ or ‘!’ is checked for a match with a TXP field (<txp:variable />, image, file, link, global article, url POST/GET/SERVER, or individual article, in that order)
  2. Any ranges of items are expanded (e.g. 4-7 => 4,5,6,7) if the rng option permits it
  3. TXP fields may themselves be lists or ranges
  4. Anything that is not a TXP field is used verbatim
  5. The items are returned as 2 lists; inclusion and exclusion

Args ( [*] = mandatory ):

  1. [*] lst = the list as a delimited string
  2. rng = whether to allow ranges or not (bool). Default = true
  3. sub = the type of subcategory to traverse (image, file, link, article, none=”“) and how many levels to go down (e.g. image:2). Default = ‘’
  4. qte = whether to quote each item in the array or not (bool). Default = true
  5. dlm = the delimiter (string). Default = “,”
  6. lax = Whether to be lax or strict about what characters constitute a field; primarily whether spaces are allowed in, say, custom fields. Default = “1”

smd_getOpts

Deprecated as it is mostly superseded by smd_doList; this one is clunkier but has $idprefix so it remains for now. It searches the passed string for predetermined sequences of characters and, if that sequence is in the given $allowed array, replaces it as follows:

  • ?c = current global category (!c = not current category)
  • ?s = current section (!s = not current section)
  • ?t = current article title (!t = not current title)
  • ?id = current article ID, prepended with $idprefix (!id = not current ID)
  • ?q = current query term (!q = not current query term)
  • ?field = contents of the current article’s field (could be a comma-separated list)
  • !field = not the contents of the current article’s field (could be a comma-separated list)

Integer ranges (e.g. 1-5) will be expanded into their individual values if the $allowRange option is true; anything else is returned verbatim. It outputs two arrays: the 1st contains items for inclusion, the 2nd contains items for exclusion.

Args ( [*] = mandatory ):

  1. [*] The string to search for matches
  2. [*] An array containing shortcuts that are “allowed” to be found in the string (?c, ?s, ?t, ?field etc)
  3. The prefix for ?id strings
  4. Boolean indicating whether to allow range expansion or not
  5. RegEx string to split options at (see smd_split)
  6. preg_split option (see smd_split)

smd_split

Returns an array of items from a string of (usually) comma-separated values. If any values contain ranges of numbers like 1-5 that need ‘expanding’ first (and $allowRange is true), they are dealt with. Takes the following arguments ( [*] = mandatory args) :

  1. [*] The string to split
  2. Boolean indicating whether to allow range expansion or not (i.e. 1-5 becomes 1,2,3,4,5)
  3. The regular expression character classes to match. If a full RegEx starting and ending with ‘/’ characters is supplied, the expression is used verbatim. Without the ‘/’ characters, the expression is treated as a list of character classes to find. Defaults to “/(,|,\s)+/” which is a comma, or comma and a whitespace character.
  4. preg_split option constant as defined in the php manual

smd_MLP

Instantiate one of these to handle MLP in your plugin like this:

1) Declare a unique global variable, e.g. global $myPlug
2) Define your default string replacement array (doesn’t need to be global), e.g:

$myStrings = array (“msg1” => “This is message 1”, “msg2” => “This is message 2”);

3) Create an MLP handler:

$myPlug = new smd_MLP(“plugin_name”, “plugin_prefix”, $myStrings);

4) That’s it! There are two optional args to smd_MLP: a) the default (full) language to use, e.g “da-dk”. Defaults to “en-gb”. b) the interface the strings are for. Choose from “public” (the default), “admin” or “common”

5) To use a replacement string in your code: a) Make sure to import the unique global variable: e.g. global $myPlug; b) Call $myPlug->gTxt(“messageID”); [ e.g. $myPlug->gTxt(“msg1”) ] c) If you want to replace any args in your message string, pass an associative array as the 2nd arg to gTxt()

smd_doDblQuote

Alternative to the core’s doQuote(). This one dbl-quotes instead of sgl-quotes

smd_pregPos

Lifted from one of the comments in the PHP manual, this just looks for a RegEx string within another, returning the matches it finds and the position of the first match.

array_combine

PHP4 equivalent of the standard PHP5 function, lifted from php.net

htmlspecialchars_decode

PHP4 equivalent of the standard PHP5 function, lifted from php.net

Source code

If you’d rather scrabble amid the ones and noughts, you’ll need to step into the view source page.

Legacy software

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

Experimental software

If you’re feeling brave, or fancy chucking your keys in the bowl, you can test out some of my beta code. It can be found on the plugin beta page.