Make Link

This page describes an internal function in PmWiki's engine called MakeLink(). The contents are not intended for those with a weak heart ;-)

admins (advanced)

Also see: PmWiki.Functions#MakeLink

Syntax:   MakeLink($pagename, $target, $text, $suffix, $fmt)

The function MakeLink($pagename, $target, $text, $suffix, $fmt) returns a string containing the HTML code for the link that corresponds to the target, text and format supplied. The primary purpose of this function is to convert markup such as 

 	[[ <text> -> <target> ]]

and 

 	[[ <target> | <text> ]]

into the appropriate HTML code.

The parameters have the following meaning:

  • $pagename — a string with the name of the page context in which the link is created, this is typically simply the name of the current page. For example, $pagename could be "Group.SomePage".
  • $target — a string with the target, i.e. <target> in the markup examples above. For example, $target could be "some page" which refers to <current-group>/SomePage.
  • $text — a string with the desired link text, i.e <text> in the markup examples above. If $text is NULL or not specified, the link text is computed automatically from $target after stripping anything in parenthesis.
  • $suffix — a string that will be appended to the link text. For example, the markup [[install]]ed will invoke MakeLink() with the string "ed" as the suffix.
  • $fmt — a format string that defines HTML code to be produced. If $fmt is NULL or not specified, the default format corresponding to the type of link will be used.
Inside the format string, the text "$LinkUrl" will be replaced by the resolved url of the link, while the text "$LinkText" will be replaced with the approriate text. Finally, the text "$LinkAlt" will be replaced by any "title" (alternate text) information associated with the link.
How is alternate text specified in markup format? → http://www.pmwiki.org/wiki/PmWiki/Images

Examples

Here are some examples of using MakeLink().

Invocation:MakeLink($pagename, "SomePage")
Result:"⚠ <a href='.../Group/SomePage'>SomePage⚠ </a>"
 
Invocation:MakeLink($pagename, "(Some) page")
Result:"⚠ <a href='.../Group/SomePage'> page⚠ </a>"
 
Invocation:MakeLink($pagename, "some page", "other text")
Result:"⚠ <a href='.../Group/SomePage'>other text⚠ </a>"
 
Invocation:MakeLink($pagename, "Attach:file.doc", "other text")
Result:"⚠ <a href='.../uploads/Group/file.doc'>other text⚠ </a>"
 
Invocation:MakeLink($pagename, "some page", "other text", "-suffix")
Result:"⚠ <a href='.../Group/SomePage'>other text-suffix⚠ </a>"
 
Invocation:MakeLink($pagename, "install(ation)", NULL, "ed")
Result:"⚠ <a href='.../Group/Installation'>installed⚠ </a>"
 
Invocation:MakeLink($pagename, "SomePage", , , "⚠ <a href='.../\$LinkUrl'>\$LinkText⚠ </a>")
Result:"⚠ <a href='.../Group/SomePage'>SomePage⚠ </a>"
 
Invocation:MakeLink($pagename, "Attach:foo.gif", , , $ImgTagFmt)
Result:"⚠ <img src='.../uploads/foo.gif' alt='' />"

Questions and answers

How does MakeLink() know the type of link?

The array $LinkFunctions contains a list of prefixes to recognize and subroutines to call when $target contains that prefix. The default settings for $LinkFunctions goes something like: 

   $LinkFunctions['http:'] = 'LinkIMap';
   $LinkFunctions['https:'] = 'LinkIMap';
   $LinkFunctions['mailto:'] = 'LinkIMap';
   # ...

Thus, any target that looks like a url is created using the LinkIMap() function. For attachments, we have 

   $LinkFunctions['Attach:'] = 'LinkUpload';

which calls the LinkUpload() function to handle attachment links.

If $target doesn't match any of the prefixes in $LinkFunctions, then MakeLink assumes the target is a page name and it uses the entry in $LinkFunctions['<:page>'], which by default says to call the LinkPage() function.

After that, it's up to the per-target function to figure out how the link is to be correctly formatted. Each target function has its own set of $...Fmt variables that control formatting for the target, but if MakeLink() is passed a value for $fmt then the target function is supposed to use that value in lieu of its default. This is how we're able to do inline images (see the "img" rule in scripts/stdmarkup.php), as well as use MakeLink() to get at other items of the resulting target link.

Category:


This page may have a more recent version on pmwiki.org: PmWiki:MakeLink, and a talk page: PmWiki:MakeLink-Talk.

PmWikiInternals