<div id="smd_help">

	<h1>smd_ plugin library</h1>

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

	<h2>Changelog</h2>

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

	<h2>Function Reference</h2>

	<p><strong>smd_addQSVar</strong><br />
<strong>smd_removeQSVar</strong></p>

	<p>Add or remove a query string variable to the given <span class="caps">URL</span>, taking into account any existing variables that may be in the <span class="caps">URL</span> already. &#8216;Add&#8217; takes three arguments, &#8216;Remove&#8217; just takes the first two:</p>

	<ol>
		<li>The <span class="caps">URL</span> string to add to/remove from</li>
		<li>The id of the querystring (the bit before the = sign)</li>
		<li>The value of the new querystring (the bit after the = sign)</li>
	</ol>

	<p>e.g. <code>smd_addQSVar($thisarticle[&#39;url_title&#39;], &#39;tpg&#39;, 15);</code> would add <code>tpg=15</code> to the current article&#8217;s <span class="caps">URL</span>. If there are no other variables currently in the <span class="caps">URL</span>, it is added with a question mark, otherwise it is appended with an ampersand.</p>

	<p><strong>smd_doList</strong></p>

	<p>Return an expanded list of items with the following properties:</p>

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

	<p>Args ( [*] = mandatory ) :
	<ol>
		<li>[*] lst = the list as a delimited string</li>
		<li>rng = whether to allow ranges or not (bool). Default = true</li>
		<li>sub = the type of subcategory to traverse (image, file, link, article, none=&#8221;&#8220;) and how many levels to go down (e.g. image:2). Default = &#8216;&#8217;</li>
		<li>qte = whether to quote each item in the array or not (bool). Default = true</li>
		<li>dlm = the delimiter (string). Default = &#8220;,&#8221;</li>
		<li>lax = Whether to be lax or strict about what characters constitute a field; primarily whether spaces are allowed in, say, custom fields. Default = &#8220;1&#8221;</li>
	</ol></p>

	<p><strong>smd_getOpts</strong></p>

	<p>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:</p>

	<ul>
		<li>?c = current global category (!c = not current category)</li>
		<li>?s = current section (!s = not current section)</li>
		<li>?t = current article title (!t = not current title)</li>
		<li>?id = current article ID, prepended with $idprefix (!id = not current ID)</li>
		<li>?q = current query term (!q = not current query term)</li>
		<li>?field = contents of the current article&#8217;s field (could be a comma-separated list)</li>
		<li>!field = not the contents of the current article&#8217;s field (could be a comma-separated list)</li>
	</ul>

	<p>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.</p>

	<p>Args ( [*] = mandatory ) :
	<ol>
		<li>[*] The string to search for matches</li>
		<li>[*] An array containing shortcuts that are &#8220;allowed&#8221; to be found in the string (?c, ?s, ?t, ?field etc)</li>
		<li>The prefix for ?id strings</li>
		<li>Boolean indicating whether to allow range expansion or not</li>
		<li>RegEx string to split options at (see smd_split)</li>
		<li>preg_split option (see smd_split)</li>
	</ol></p>

	<p><strong>smd_split</strong></p>

	<p>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 &#8216;expanding&#8217; first (and $allowRange is true), they are dealt with. Takes the following arguments ( [*] = mandatory args) :</p>

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

	<p><strong>smd_MLP</strong><br />
Instantiate one of these to handle <acronym title="Multi-Lingual Pack"><span class="caps">MLP</span></acronym> in your plugin like this:</p>

	<p>1) Declare a unique global variable, e.g. global $myPlug<br />
2) Define your default string replacement array (doesn&#8217;t need to be global), e.g:</p>

	<p>	$myStrings = array (&#8220;msg1&#8221; =&gt; &#8220;This is message 1&#8221;, &#8220;msg2&#8221; =&gt; &#8220;This is message 2&#8221;);</p>

	<p>3) Create an <span class="caps">MLP</span> handler:</p>

	<p>	$myPlug = new smd_MLP(&#8220;plugin_name&#8221;, &#8220;plugin_prefix&#8221;, $myStrings);</p>

	<p>4) That&#8217;s it! There are two optional args to smd_MLP:
	a) the default (full) language to use, e.g &#8220;da-dk&#8221;. Defaults to &#8220;en-gb&#8221;.
	b) the interface the strings are for. Choose from &#8220;public&#8221; (the default), &#8220;admin&#8221; or &#8220;common&#8221;</p>

	<p>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-&gt;gTxt(&#8220;messageID&#8221;); [ e.g. $myPlug-&gt;gTxt(&#8220;msg1&#8221;) ]
	c) If you want to replace any args in your message string, pass an associative array as the 2nd arg to gTxt()</p>

	<p><strong>smd_doDblQuote</strong></p>

	<p>Alternative to the core&#8217;s doQuote(). This one dbl-quotes instead of sgl-quotes</p>

	<p><strong>smd_pregPos</strong></p>

	<p>Lifted from one of the comments in the <span class="caps">PHP</span> manual, this just looks for a RegEx string within another, returning the matches it finds and the position of the first match.</p>

	<p><strong>array_combine</strong></p>

	<p>PHP4 equivalent of the standard PHP5 function, lifted from php.net</p>

	<p><strong>htmlspecialchars_decode</strong></p>

	<p>PHP4 equivalent of the standard PHP5 function, lifted from php.net</p>

</div>
<!-- --- BEGIN PLUGIN CSS --- -->
<style type="text/css">
#smd_help { line-height:1.3 ;}
#smd_help code { font-weight:bold; font: 105%/130% "Courier New", courier, monospace; background-color: #FFFFCC;}
#smd_help code.block { font-weight:normal; border:1px dotted #999; background-color: #f0e68c; display:block; margin:10px 10px 20px; padding:10px; }
#smd_help a:link, #smd_help a:visited { color: blue; text-decoration: none; border-bottom: 1px solid blue; padding-bottom:1px;}
#smd_help a:hover, #smd_help a:active { color: blue; text-decoration: none; border-bottom: 2px solid blue; padding-bottom:1px;}
#smd_help h1 { color: #369; font: 20px Georgia, sans-serif; margin: 0; text-align: center; }
#smd_help h2 { border-bottom: 1px solid black; padding:10px 0 0; color: #369; font: 17px Georgia, sans-serif; }
#smd_help h3 { color: #693; font: bold 12px Arial, sans-serif; letter-spacing: 1px; margin: 10px 0 0;text-transform: uppercase;}
#smd_help h4 { font: bold 11px Arial, sans-serif; letter-spacing: 1px; margin: 10px 0 0 ;text-transform: uppercase; }
#smd_help .att-name { font-weight:bold; }
#smd_help .mand { background:#eee; border:1px dotted #999; }
#smd_help table {width:100%; text-align:center; padding-bottom:1em;}
#smd_help td, #smd_help th {border:1px solid #999; padding:.5em 0;}
</style>
<!-- --- END PLUGIN CSS --- -->