[pmwiki-users] Getting an URL from a cookbook recipe

Patrick R. Michaud pmichaud at pobox.com
Wed Jan 25 17:03:30 CST 2006


On Wed, Jan 25, 2006 at 10:46:07PM +0100, christian.ridderstrom at gmail.com wrote:
> On Wed, 25 Jan 2006, Patrick R. Michaud wrote:
> 
> I do have some questions though... especially since I think I'll be using
> MakeLink() shortly. So I might as well document it now... it seems this
> will expand to need its own page though. I'll place it on:
> 
> 	http://pmwiki.org/wiki/PmWiki/MakeLink

Yes, it will deserve its own page.

> To start with, what does MakeLink()  return? Is it the HTML code of the
> link pointing to $target?

MakeLink returns the HTML code corresponding to whatever target, text,
and format were supplied.

> > The general form of MakeLink is
> >     MakeLink($pagename, $target, $txt, $suffix, $fmt)
> > where
> >     $pagename is the source page
> 
> I guess 'source page' would normally be the current page, and more 
> generally the it defines the context for the link?

Yes.

> >     $target is where the link should go
> 
> What kind of things can $target be? Must it be a string with a URI?

$target is generally what one would expect to find in [[ target | text ]]
or [[ text -> target ]].  

> >     $txt is the value to use for '$LinkText' in the output 
> >     $suffix is any suffix string to be added to $txt
> >     $fmt is a format string to use
> > 
> > If $txt is NULL or not specified, then it is automatically computed
> > from $target.
> 
> Ok... I think I need some examples ;-)

    MakeLink($pagename, "SomePage")
      returns  "<a href='.../Group/SomePage'>SomePage</a>"

    MakeLink($pagename, "(Some) page")
      returns  "<a href='.../Group/SomePage'> page</a>"

    MakeLink($pagename, "some page", "other text")
      returns  "<a href='.../Group/SomePage'>other text</a>"

    MakeLink($pagename, "Attach:file.doc", "other text")
      returns  "<a href='.../uploads/Group/file.doc'>other text</a>"


> > If $fmt is NULL or not specified, then MakeLink uses the default format
> > as specified by the type of link.  For page links this means the
> > $LinkPageExistsFmt and $LinkPageCreateFmt variables, for intermap-style
> > links it comes from either the $IMapLinkFmt array or from $UrlLinkFmt.
> 
> How does MakeLink() know the type of the link? Is $target matched to 
> various regexps?

Warning: this gets a little tricky.  :-)

The $LinkFunctions array 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.

Does that help, or just confuse things further?

Pm




More information about the pmwiki-users mailing list