PTVLinkText

Summary: Use a page text variable for link text, when available
Version: 2019-07-10
Prerequisites: PmWiki 2
Status: works so far
Maintainer: RandyB
Categories: Links, Markup, PHP55, PHP72
Users: (view / edit)
Discussion: PTVLinkText-Talk

Questions answered by this recipe

  • How do I use a page's Summary, instead of its title, as link text?
  • How do I make a link that automatically includes a page's Summary or other page text variable following the link text?

All sections are optional, you can remove those that do not apply to your recipe, and add new ones.

Description

This recipe provides markup that will create a link whose link text is a page text variable on the target page. If the variable is not defined, the link text will default to the page's $Title. This allows you to easily use meaningful text, such as the page's Summary, for links to pages whose names are meaningless.

Installation

Put this in your configuration file:

function PTVLinkText ($pn) {
    $ptv = PageTextVar($pn,'Summary');
    if (strlen($ptv)) {
         return $ptv;
    } else {
         return PageVar($pn, '$Title');
    }
}

You will also need one of the following:

  • For PmWiki versions 2.2.58 and later, add this:
  Markup('[[|~', '<[[|',
    "/(?>\\[\\[([^|\\]]+))\\|\\s*\\~\\s*]]/",
    "mu_PTVLinkText");
  function mu_PTVLinkText($m) {
    extract($GLOBALS['MarkupToHTML']);
    return Keep(
      MakeLink( $pagename, $m[1], PTVLinkText(
          MakePageName($pagename,$m[1]) )
      ),
    'L');
  }                      
  • For PmWiki versions prior to 2.2.56, add this instead:
 Markup('[[|~', '<[[|',
  "/(?>\\[\\[([^|\\]]+))\\|\\s*\\~\\s*]]/e",
  "Keep(MakeLink(\$pagename, PSS('$1'),
    PTVLinkText(MakePageName(\$pagename,PSS('$1')))
    ),'L')");

Configuration

In the code shown above, "Summary" is the page text variable used for the link text. To use a different variable, change "Summary" in the PTVLinkText function to your preferred variable.

Usage

Use a tilde character as your link text in markup. For example:

[[Cookbook.PTVLinkText|~]]

would create the following link:

Use a page text variable for link text, when available

Notes

A variation of this is to modify a link so that it is automatically followed by a page text variable. Here's an example of appending the page's $:Summary in a smaller font (for versions 2.2.56 and later):

Markup_e('[[|$', '<[[|',
   "/(?>\\[\\[([^|\\]]+))\\|\\s*\\$\\s*]]/", 
   "Keep(MakeLink(\$pagename, \$m[1],
     PTVLinkTextSummaryAfterAndSmaller(MakePageName(\$pagename,\$m[1]))
     ),'L').PRR('&nbsp; [-'.PageTextVar(\$m[1],'Summary').'-]')"); 

function PTVLinkTextSummaryAfterAndSmaller ($pn) {
    $title = PageVar($pn, '$Title');
    return $title;
}

The markup for the above variation would look like this:

[[Cookbook.PTVLinkText|$]]

and it would create the following link plus text:

PTVLinkText  Use a page text variable for link text, when available

Change log / Release notes

If the recipe has multiple releases, then release notes can be placed here. Note that it's often easier for people to work with "release dates" instead of "version numbers".

See also

Contributors

Comments

See discussion at PTVLinkText-Talk

User notes : If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.