smd_lib: The library

n: smd_lib | v: 0.36 | f: Development / Textpattern plugins

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.

Changelog

  • v0.1 07-02-25 Initial public release
  • v0.2 07-03-03 Added: MLP (Multi-Lingual Pack) library support
  • v0.21 07-03-06 Added: integer range functionality. smd_getAtts now takes a RegEx arg
  • v0.21a 07-03-21 Fixed: Character ranges ignored (thanks mrdale)
  • v0.21b 07-04-02 Fixed: Sticky article support in smd_getAtts (thanks pieman)
  • v0.21c 07-07-29 Fixed: Numeric ranges in categories (thanks wolle)
  • v0.21d 07-08-03 Fixed: Negation with multiple elements
  • v0.21e 07-09-14 Fixed: Ability to leave empty splitRange parameters intact
  • v0.22 07-09-20 Fixed: Undefined index warnings (thanks Ambitiouslemon). Enhanced matches so spaces are allowed in strings (thanks DrRogg)
  • v0.23 07-04-09 BETA : Added the FuzzyFind class and getWord function. getAtts() now allows ?q
  • v0.3 07-10-29 Rewrote smd_getAtts as smd_getOpts to allow replaced vars within text. Deprecated smd_getAtts, added smd_pregPos. Changed smd_splitRange as smd_split to allow ranges to be switched on or off. Deprecated smd_splitRange. Added generic MLP class support (smd_MLP). Deprecated smdMLP array, smd_gTxt and smd_getCaller. Made smd_FuzzyFind and smd_getWord official
  • v0.31 07-11-27 Removed smdMLP array, smd_gTxt and smd_getCaller. Deprecated smd_getSubCats. Added a few PHP4 helper functions
  • v0.32 08-03-29 Removed smd_getAtts and smd_getSubCats. Deprecated smd_getOpts and smd_split. Added smd_doList. Moved the smd_FuzzyFind class and smd_getWord into the smd_fuzzy_find plugin where they should have been all along
  • v0.33 08-12-02 Undeprecated(!) smd_split since it’s actually quite useful ; extended smd_doList to encompass $thisimage (for future) and $variable ; fixed bug in smd_doList when using subcats
  • v0.34 08-12-13 smd_doList uses a unicode regex
  • v0.35 09-02-24 smd_doList fixed ranges in ‘?’ variables (thanks koobs)
  • v0.36 09-04-02 smd_doList falls back to ASCII if Unicode not available (thanks RedFox / mlarino / decoderltd)

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 frolic in the raw code halls, you’ll need to step into the view source page.

Legacy software

If, for some inexplicable reason, you need last century's 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.