version=pmwiki-2.2.4 ordered=1 urlencoded=1
agent=Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.8.1.19) Gecko/20081216 Ubuntu/8.04 (hardy) Firefox/2.0.0.19
author=Petko
charset=ISO-8859-1
csum=fix links
host=86.69.109.9
name=PmWiki.Functions
rev=84
targets=PmWiki.CustomMarkup,PmWiki.Variables,PmWiki.Internationalizations,PmWiki.FmtPageName,PmWiki.ConditionalMarkup,PmWiki.Drafts
text=(:Summary: How some of the functions in pmwiki.php work:)%0a(:Audience: admins (advanced) :)%0a%0aThis page describes some of the internal workings of PmWiki by explaining how some of the functions in pmwiki.php work. For a more brief list/overview on functions useful to for instance cookbook writers, see Cookbook:Functions. %0a%0aTo use this functions you have to make sure that all relevant internal variables have been initialized correctly. See [[Custom Markup]] and [[(PmWiki:)Custom Actions]] for more information on how these functions are typically called via [@Markup()@] or [@$HandleActions[]@].%0a%0a%0a!![[#PSS]] [@PSS($string)@]%0a%0aThe PSS() function removes the backslashes that are%0aautomatically inserted in front of quotation marks by%0athe /e option of PHP's preg_replace function.  PSS() is%0amost commonly used in replacement arguments to Markup(),%0awhen the pattern specifies /e and one or more of the %0aparenthesized subpatterns could contain a quote or backslash.  %0a("PSS" stands for "PmWiki Strip Slashes".)%0a-->From PM: PmWiki expects PSS() to always occur inside of double-quoted strings and to contain single quoted strings internally.  The reason for this is that we don't want the $1 or $2 to accidentally contain characters that would then be interpreted inside of the double-quoted string when the PSS is evaluated.%0a--->@@Markup('foo', 'inline', '/(something)/e', 'Foo(PSS("$1"))');  # wrong@@%0a--->@@Markup('foo', 'inline', '/(something)/e', "Foo(PSS('$1'))");  # right@@%0a%0a!!! Example%0aThis is a fictitious example where PSS() should be used.%0aLet us assume that you wish to define a directive [@(:example:)@]%0asuch that [@(:example "A horse":)@] results in the HTML%0a-> [@%3cdiv>"A horse"%3c/div>@].%0aHere is how the markup rule can be created:%0a-> [@%0aMarkup('example', 'directives',%0a       '/\\(:example\\s(.*?):\\)/e',%0a       "Keep('%3cdiv>'.PSS('$1').'%3c/div>')");%0a@]%0aWe need to use PSS() around the '$1' because the matched text%0acould contain quotation marks, and the /e will add backslashes%0ain front of them.%0a%0a!![[#stripmagic]] [@stripmagic($string)@]%0a%0aThis function should be used when processing the contents of [@$_POST@] or [@_GET@] variables when they could contain quotes or backslashes. It verifies [@get_magic_quotes()@], if true,%0astrips the automatically inserted escapes from the string.%0a%0a!![[#FmtPageName]] [@FmtPageName@]($fmt, $pagename)%0a%0a[[#FmtPageName-desc]]Returns [@$fmt@], with $variable and [=$[internationalisation]=] substitutions performed, under the assumption that the current page is [@pagename@]. See [[PmWiki.Variables]] for an (incomplete) list of available variables, [[PmWiki.Internationalizations]] for internationalisation.  Security: not to be run on user-supplied data.%0a%0aThis is one of the major functions in PmWiki, see [[PmWiki.FmtPageName]] for%0alots of details.%0a%0a%0a!![[#Markup]] [@Markup@]($name, $when, $pattern, $replace)%0a%0a[[#Markup-desc]]Adds a new markup to the conversion table.  Described in greater detail at PmWiki.CustomMarkup.%0a%0aThis function is used to insert translation rules into the PmWiki's%0atranslation engine. The arguments to [@Markup()@] are all strings, where:%0a%0a:[@$name@]: The string names the rule that is inserted.  If a rule of the same name already exists, then this rule is ignored.%0a:[@$when@]: This string is used to control ''when'' a rule is to be applied relative to other rules.  A specification of "[@%3cxyz@]" says to apply this rule prior to the rule named "xyz", while "[@>xyz@]" says to apply this rule after the rule "xyz".  See [[(PmWiki:)CustomMarkup]] for more details on the order of rules.%0a:[@$pattern@]: This string is a [[regular expression -> http://www.php.net/preg_replace]] that is used by the translation engine to look for occurences of this rule in the markup source.%0a:[@$replace@]: This string will replace the matched text when a match occurs.%0a%0aAlso see: [[PmWiki.CustomMarkup]] and [[Cookbook:Functions#Markup]]%0a%0a!![[#MarkupToHTML]] [@MarkupToHTML@]($pagename, $str)%0a%0a[[#MarkupToHTML-desc]] Converts the string [@$str@] containing PmWiki markup into the corresponding HTML code, assuming the current page is [@$pagename@].%0a%0aAlso see: [[Cookbook:Functions#MarkupToHTML]]%0a%0a!![[#mkdirp]] [@mkdirp@]($dir)%0a%0aThe function [@mkdirp@]($dir) creates a directory, [@$dir@], if it doesn't%0aalready exist, including any parent directories that might be needed.  For%0aeach directory created, it checks that the permissions on the directory are%0asufficient to allow PmWiki scripts to read and write files in that%0adirectory.  This includes checking for restrictions imposed by PHP's%0asafe_mode setting.  If [@mkdirp@]() is unable to successfully create a%0aread/write directory, [@mkdirp@]() aborts with an error message telling the%0aadministrator the steps to take to either create $dir manually or give%0aPmWiki sufficient permissions to be able to do it.%0a%0a!![[#MakeLink]] [@MakeLink@]($pagename, $target, $txt, $suffix, $fmt)%0a%0aThe function [@MakeLink@]($pagename, $target, $txt, $suffix, $fmt) returns a ???. Its arguments are as follows:%0a $pagename is the source page%0a $target is where the link should go%0a $txt is the value to use for '$LinkText' in the output %0a $suffix is any suffix string to be added to $txt%0a $fmt is a format string to use%0a%0aIf $txt is NULL or not specified, then it is automatically computed from $target.%0a%0aIf $fmt is NULL or not specified, then MakeLink uses the default%0aformat as specified by the type of link.  For page links this%0ameans the $LinkPageExistsFmt and $LinkPageCreateFmt variables,%0afor intermap-style links it comes from either the $IMapLinkFmt%0aarray or from $UrlLinkFmt.  Inside of the formatting strings,%0a$LinkUrl is replaced by the resolved url for the link, $LinkText%0ais replaced with the appropriate text, and $LinkAlt is replaced%0aby any "title" (alternate text) information associated with the%0alink.%0a%0aAlso see: [[PmWiki:MakeLink]] and [[Cookbook:Functions#MakeLink]]%0a%0a!![[#MakeUploadName]] [@MakeUploadName@]($pagename, $x)%0a%0a@@MakeUploadName()@@ simply takes a string @@$x@@ (representing an attachment's%0aname) and converts it to a valid name by removing any unwanted characters.%0aIt also requires the name to begin and end with an alphanumeric character,%0aand as of 2.0.beta28 it forces any file extensions to lowercase.%0aThis function is defined in @@scripts/upload.php@@ and only used when uploads%0aare enabled.%0a%0a!![[#SessionAuth]] [@SessionAuth@]($pagename, $auth=NULL)%0a%0a@@SessionAuth()@@ manages keeping authentication via cookie-sessions. Session contains%0aever password or vaidated id and associated groups from previous calls.It adds%0aelements passed by @@$auth@@ to session. It also writes every element%0asaved in session to @@$AuthPw@@(passwords) and @@$AuthList@@(ids and groups).%0a%0a!![[#IsAuthorized]] [@IsAuthorized@]($chal, $source, &$from)%0a@@IsAuthorized@@ takes a pageattributesstring (e. g. "id:user1 $1$Ff3w34HASH...") in @@$chal@@.%0a@@$source@@ is simply returned and used for building the authcascade (pageattributes - groupattributes - %0a@@$DefaultPassword@@). @@$from@@ will be returned if @@$chal@@ is empty, because it is not checked %0abefore calling @@IsAuthorized()@@, this is needed for the authcascade. @@IsAuthorized()@@ returns an array%0awith three values: @@$auth@@ @@1@@ - authenticated, @@0@@ - not authenticated, @@-1@@ - refused; @@$passwd@@; %0a@@$source@@ from the parameter list.%0a%0a!![[#CondAuth]] [@CondAuth@] ($pagename, 'auth level')%0a[@CondAuth@] implements the [[ConditionalMarkup]] for [@(:if auth level:)@]. For instance [@ CondAuth($pagename,'edit')@] is true if authorization level is 'edit'. Use inside local configuration files to build conditionals with a check of authorization level, similar to using [@(:if auth level:)@] on a wiki page.%0a%0aNote that CondAuth() should be called after all authorization levels and passwords have been defined. For example, if you use it with [[Drafts]], you should include the draft.php script before calling CondAuth():%0a[@%0a   $EnableDrafts = 1;%0a   $DefaultPasswords['publish'] = crypt('secret');%0a   include_once("$FarmD/scripts/draft.php");%0a   if (! CondAuth($pagename, 'edit')) { /* whatever */ }%0a@]%0aBest is to use CondAuth() near the bottom of your config.php script.%0a%0a!! [[#RetrieveAuthPage]] @@RetrieveAuthPage($pagename, $level, $authprompt=true, $since=0)@@%0a%0aUse e.g. [@$page = @RetrieveAuthPage('Main.MyPage', 'read')@] to obtain a page object that contains all the information of the correspondent file in separate keys, e.g. [@$page['text']@] will contain a string with the current wiki markup of Main.MyPage. Use this generally in preference to the alternative function [@ReadPage($pagename, $since=0)@] since it respects the authorisation of the user, i.e. it checks the authorisation level before loading the page, or it can be set to do so. [@ReadPage()@] reads a page regardless of permission.%0a%0a!! [[#UpdatePage]] @@UpdatePage($pagename, $old (page object), $new (page object));@@%0a''[[PmWiki:UpdatePage|More Technical Notes]]''%0a%0a[@UpdatePage()@] allows cookbook recipes to mimic the behavior of editing wiki pages via the browser. Internally, PmWiki does several house keeping tasks which are accessible via this function (preserving history/diff information, updating page revision numbers, updating RecentChanges pages, sending email notifications, etc._%0a* "Page object" refers to an array pulled from [@ReadPage($pagename); @] Note that $new['text'] should contain all page data for the new version of the page. %0a* If a page doesn't exist, UpdatePage() will attempt to create it.%0a* Ignoring $old (e.g. [@UpdatePage($pagename, '', $new);@]) will erase all historical page data---a ''tabula rasa''.%0a@@UpdatePage()@@ cannot be called directly from config.php because there are necessary initializations which occur later in pmwiki.php.  It is not enough to just load stdconfig.php.  If you want to use @@UpdatePage()@@ you will need to do it within a [[PmWiki:CustomMarkup | custom markup]], a [[Cookbook:MarkupExpressionSamples | custom markup expression]], or a [[PmWiki:CustomActions | custom action]].
time=1251046348