MakeLink
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(
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
$pagename
, $target, $text, $suffix, $fmt)
[[<text> -> <target>]]
and
[[<target> | <text>]]
into the appropriate HTML code.
The parameters have the following meaning:
— 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
$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 invokeMakeLink()
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.- For page links, one of
$LinkPageExistsFmt
or$LinkPageCreateFmt
is used. - For intermap-style links, the format is taken from an entry in the
array
$IMapLinkFmt
, or from$UrlLinkFmt
.
- For page links, one of
- How is alternate text specified in markup format? → https://www.pmwiki.org/wiki/PmWiki/Images
Examples
Here are some examples of using MakeLink()
.
Invocation: | MakeLink( |
Result: | "<a href='.../Group/SomePage'>SomePage</a>" |
Invocation: | MakeLink( |
Result: | "<a href='.../Group/SomePage'> page</a>" |
Invocation: | MakeLink( |
Result: | "<a href='.../Group/SomePage'>other text</a>" |
Invocation: | MakeLink( |
Result: | "<a href='.../uploads/Group/file.doc'>other text</a>" |
Invocation: | MakeLink( |
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
This page may have a more recent version on pmwiki.org: PmWiki:MakeLink, and a talk page: PmWiki:MakeLink-Talk.