version=pmwiki-2.2.0-beta44 ordered=1 urlencoded=1
agent=Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.8.1.3) Gecko/20070309 Firefox/2.0.0.3
author=Anno
charset=ISO-8859-1
csum=summary
ctime=1138225546
host=85.125.178.31
name=PmWiki.MakeLink
rev=38
targets=PmWiki.Functions,Category.PmWikiInternals
text=(:Summary:Describes an internal function in PmWiki's engine called MakeLink():)%0aThis page describes an internal function in PmWiki's engine called [@MakeLink@](). The contents are not intended for those with a weak heart ;-) %0a%0a%25audience%25 admins (advanced)%0a%0aAlso see: [[PmWiki.Functions#MakeLink]]%0a%0a'''Syntax:'''   [@MakeLink@]($pagename, $target, $text, $suffix, $fmt)%0a%0aThe function @@MakeLink@@($pagename, $target, $text, $suffix, $fmt) returns a%0astring containing the HTML code for the link that corresponds to the target,%0atext and format supplied. The primary purpose of this function is to convert%0amarkup such as%0a 	'''[=[[=]''' ''%3ctext>'' '''->''' ''%3ctarget>'' ''']]'''%0aand%0a 	'''[=[[=]''' ''%3ctarget>'' '''|''' ''%3ctext>'' ''']]'''%0ainto the appropriate HTML code.%0a%0aThe parameters have the following meaning:%0a%0a* $pagename — a string with the name of the page context in which the%0a  link is created, this is typically simply the name of the current page.%0a  For example, $pagename could be @@"Group.SomePage"@@.%0a%0a* $target — a string with the target, i.e. %3ctarget> in the markup%0a  examples above. For example, $target could be @@"some page"@@ which%0a  refers to @@%3ccurrent-group>/SomePage@@.%0a%0a* $text — a string with the desired link text, i.e %3ctext> in the%0a  markup examples above. If $text is NULL or not specified, the link text is%0a  computed automatically from $target after stripping anything in%0a  parenthesis.%0a%0a* $suffix — a string that will be appended to the link text.%0a  For example, the markup [@[[install]]ed@] will invoke @@MakeLink@@()%0a  with the string @@"ed"@@ as the suffix.%0a%0a* $fmt — a format string that defines HTML code to be produced.  If%0a  $fmt is NULL or not specified, the default format corresponding to the%0a  type of link will be used.%0a** For page links, one of $LinkPageExistsFmt or $LinkPageCreateFmt is used.%0a** For intermap-style links, the format is taken from an entry in the%0a   array $IMapLinkFmt, or from $UrlLinkFmt.%0a-> Inside the format string, the text "$LinkUrl" will be replaced by the%0a   resolved url of the link, while the text "$LinkText" will be replaced%0a   with the approriate text. Finally, the text "$LinkAlt" will be replaced%0a   by any "title" (alternate text) information associated with the link.%0a%0a---> %25red%25 How is alternate text specified in markup format?%0a%0a!!! Examples%0a%0aHere are some examples of using @@MakeLink@@().%0a%0a||Invocation:||MakeLink($pagename, "SomePage")			||%0a||Result:    ||@@"%3ca href='.../Group/SomePage'>SomePage%3c/a>"@@	||%0a||	     ||%0a||Invocation:||MakeLink($pagename, "(Some) page")		||%0a||Result:    ||@@"%3ca href='.../Group/SomePage'> page%3c/a>"@@	||%0a||	     ||%0a||Invocation:||MakeLink($pagename, "some page", "other text")	||%0a||Result:    ||@@"%3ca href='.../Group/SomePage'>other text%3c/a>"@@||%0a||	     ||%0a||Invocation:||MakeLink($pagename, "Attach:file.doc", "other text") ||%0a||Result:    ||@@"%3ca href='.../uploads/Group/file.doc'>other text%3c/a>"@@ ||%0a||	     ||%0a||Invocation:||MakeLink($pagename, "some page", "other text", "-suffix") ||%0a||Result:    ||@@"%3ca href='.../Group/SomePage'>other text-suffix%3c/a>"@@ ||%0a||	     ||%0a||Invocation:||MakeLink($pagename, "install(ation)", NULL, "ed") ||%0a||Result:    ||@@"%3ca href='.../Group/Installation'>installed%3c/a>"@@ ||%0a||	     ||%0a||Invocation:||MakeLink($pagename, $pagename, "SomePage", '', '', \%0a			"%3ca href='.../\$LinkUrl'>\$LinkText%3c/a>")	||%0a||Result:    ||@@"%3ca href='.../Group/SomePage'>SomePage%3c/a>"@@		||%0a||	     ||%0a||Invocation:||MakeLink($pagename, "Attach:foo.gif", '', '', $ImgTagFmt) ||%0a||Result:    ||@@"%3cimg src='.../uploads/foo.gif' alt='' />"@@	||%0a%0a%0a%0a!! Questions and answers%0a%0a!!! How does @@MakeLink@@() know the type of link?%0a%0aThe array $LinkFunctions contains a list of prefixes to recognize and%0asubroutines to call when $target contains that prefix.  The default settings%0afor $LinkFunctions goes something like:%0a%0a   $LinkFunctions['http:'] = 'LinkIMap';%0a   $LinkFunctions['https:'] = 'LinkIMap';%0a   $LinkFunctions['mailto:'] = 'LinkIMap';%0a   # ...%0a%0aThus, any target that looks like a url is created using the LinkIMap()%0afunction.  For attachments, we have%0a%0a   $LinkFunctions['Attach:'] = 'LinkUpload';%0a%0awhich calls the LinkUpload() function to handle attachment links.%0a%0aIf $target doesn't match any of the prefixes in $LinkFunctions, then%0aMakeLink assumes the target is a page name and it uses the entry in%0a$LinkFunctions['%3c:page>'], which by default says to call the LinkPage() %0afunction.%0a%0aAfter that, it's up to the per-target function to figure out how%0athe link is to be correctly formatted.  Each target function has%0aits own set of $...Fmt variables that control formatting for%0athe target, but if MakeLink() is passed a value for $fmt then%0athe target function is supposed to use that value in lieu of its%0adefault.  This is how we're able to do inline images (see the%0a"img" rule in scripts/stdmarkup.php), as well as use MakeLink()%0ato get at other items of the resulting target link.%0a%0aCategory: [[!PmWikiInternals]]%0a
time=1176887567