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$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.
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, " 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: PmWikiInternals
