PowerTools

Summary: markup expressions for multi page processing incl. plist, pagelist, rename, pagecount, wordcount, trail, serialname, serial, newticket, sumdata, allptvs, random
Version: 2022-11-01
Prerequisites: PmWiki 2.2.0
Status: stable
Maintainer: HansB
License: GPL2+
Users: +7 (View / Edit)
Discussion: PowerTools-Talk

Description

Various markup expression for multi page processing. powertools.phpΔ contains a number of markup expressions which can be used on multiple or single page operations.

The script contains these expressions:

plist

returns a comma-separated list of full page names from page names given as parameters. Pagenames can contain wiki wildcards * and ? and names with negative prefix. Wildcards will be expanded into a list. Negative prefixed names will be excluded from the list.
General syntax: (plist PageName1 PageName2 .... -PageName3 -PageName4 ....)

(plist ... sep=\n)
returns list separated by line feeds. sep=LF or sep=CRLF can also be used, plus any string sep='STRING'.
fmt=groups
output only list of group names.
groups=GROUPPATTERN
as group=GROUPPATTERN but with fmt=groups output:
groups=*
will give a list of all group names.
sep=SEPARATOR
character or string inserted between each full pagename. Default is a comma. CR or \n makes new line separations.
pre=PREFIX
PREFIX string is put in front of every name.
suf=SUFFIX
SUFFIX string is put behind every name.

Syntax examples:

  • {(plist Cookbook.* -Cookbook.*Skin*)} - pagelist of all pages in group Cookbook less any page which contains 'Skin' in its name.

plist can be used to feed pagelists to other markup expressions (see pagecount and wordcount below), or as input in form processing, for instance in Fox forms to provide a list of target pages, to add wiki wildcard target capabilities.

pagelist

returns a comma separated list of pagenames. Any PageList directive parameters are allowed, but the default output format is a comma-separated list of pagenames (fmt=csv). Note that this expression processes pages significantly slower (3 to 4 times) than plist above.

Syntax examples:

  • {(pagelist group=PmWiki)} - list of pages in group PmWiki

rename

  • Syntax: (rename PAGELIST group=GROUP pre=PREFIX suf=SUFFIX)

With input from plist or pagelist returns new pagelist with new Group.PageNames GROUP.PREFIX.PageName.SUFFIX if parameters are specified. Use for page backup forms.

pagecount

returns count of pages from input of comma-separated pagelist (delivered by expression plist).

Syntax examples:

  • {(pagecount (plist PmWiki.*))} number of pages in PmWiki group.

wordcount

returns count of words from either a string provided, or a PageName or comma-separated page list.

Syntax examples:

  • {(wordcount)} - number of words on current page.
  • {(wordcount Cookbook.PowerToools)} - number of words on page Cookbook.PowerToools.
  • {(wordcount (plist PmWiki.*))} - number of words of all pages in the PmWiki group.
  • {(wordcount "this is a string")} - number of words in string "this is a string" (4).

trail

returns either previous or next link for wiki trail. If no trailpage is given, all page in current group are used. Syntax: {(trail [next|prev] linktext TrailPageName)}

  • {(trail prev Back TrailPage)} - link to pevious page on trail layed out on TrailPage, link is named "Back".
  • {(trail next Forward )} - link to next in current group (alphabetically sorted list), named "Forward".

serialname

  • {(serialname Group Name)} - Creates a new serial pagename of format Group.Name0001 (appended 4-digit number defined by variable $SerialStart), incrementing the ending number part of pages like Group.Name1234. So if you got a page Group.Name0010 the markup expression will return Group.Name0011. If Name is omitted it will create a purely numeric page name. If Group is omitted it will act in the current group.
  • Example for link creating new serial pages:
    [[{(serialname)}?action=edit|New serial page]]

serial

  • {(serial Group Name)} - As above, but returns only the new numeric part: So for a page Group.Name0010 it returns 0011. $SerialStart is set as default to 0001 and can be changed in config.php.

newticket

  • {(newticket Group)} - Creates a new serial page name of format Group.20071113001 (date and 3 digit number). With new pages being added the 3-digit serial number will increase on the day, but on the next day the date part increases and the serial 3-digit part starts at 001 again. If group is omitted it will look in the current group.

sumdata

{(sumdata PAGE|PAGELIST data=PTVLIST)}
returns sum of PTVs listed from pages in PAGELIST. Input arguments: PageName or comma-separated list of pagenames [use (plist) or (pagelist) to provide pagelist]; PTV or comma-separated PTVLIST as value for data= parameter. The function will convert, if necessary, PTV values to floating-point numbers.

allptvs

  • {(allptvs PAGE|PAGELIST)} - show all PTVs as name: value. Input argument: PageName or comma-separated list of pagenames, for instance using (plist) or (pagelist) expressions.
    Note that no attempt is made to defuse any markup which may be part of a PTV's value. If markup is present this may potentially cause undesired side effects.

random

  • {(random LIST)} - returns item selected at random from comma-separated list provided. Doubles are prevented.
  • sep= to specify a custom list item separator, default is comma.

Installation

  • Download powertools.phpΔ and copy the file into your /cookbook/ directory
  • Add to local/config.php
             include_once("$FarmD/cookbook/powertools.php");

Notes

Example for creating serial pages with Fox

The following form will display just a button. When clicked the form will create a new serial page in group ToDo using the Name part prefix of Jack-, basing the new page on a template page Site.ToDoTemplate. The user will be redirected to the new page.

(:messages:)
(:fox newtodo template=Site.ToDoTemplate redirect=1:)
(:input hidden target '{$$(serialname ToDo Jack- )}':)
(:input submit post "Create New ToDo Page":)
(:foxend newtodo:)

Note that the serialname expression is enclosed in hyphens, and that it is used here as a replacement variable {$$(serialname ...)} and not as a normal markup expression {(serialname ....)}. Normally markup expressions will be evaluated when the page is loaded, whereas the expression written as a replacement variable will only be evaluated when the form is processed, thereby overcoming possible conflicts of page names if another user is creating a page at about the same time.

Release Notes

  • 2022-11-01: Some fixes for PHP 8
  • 2017-12-21: Fixed (pagelist), made PHP72 compatible. ChuckG
  • 2011-03-08: Fixed (pagelist), thanks to SteP's suggestion on parameter parsing.
  • 2010-09-17: Fixed (random), removed debugging trace.
  • 2009-09-03: Added (sumdata)
  • 2008-07-31: Fixed pagecount 0 bug (was showing 1).
  • 2008-07-22: Added (random), (allptvs)
  • 2008-07-10: Added (serialname), (serial) and (newticket), previously in serial.php
  • 2008-06-22: fixed sep=\n for (pagelist ...) to deliver newline separations.
  • 2008-05-06: modified (pagelist) so extra newlines are removed on output (as happened with 'wrap=inline fmt=#simple' and 'fmt=#title')
  • 2008-04-01: removed extra "," at end of (plist) output (crept into yesterdays release)
  • 2008-03-31: added to (plist) options groups= , fmt=groups, pre= , suf= . Fixed bug in comma-separated name= and group= arguments.
  • 2008-03-29: added (trail) for wiki trail links. Added option sep= to (plist), so plist can output other than comma-separated list.
  • 2008-02-16: Added (rename)
  • 2008-02-11a: Modification to (pagelist) to use Keep() for harmonising with WikiSh. Function rename.
  • 2008-02-11: Modified (pagelist) to work essentially like the pagelist directive, accepting all standard pagelist parameters. Improved (plist) for better input handling, with addition of group= and name= parameters like (pagelist)
  • 2008-02-04: Initial release.

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

  • MarkupExpressions -
  • MarkupExprPlus - Extends {(...)} expression markups
  • MarkupExpressionSamples - custom markup expression samples
  • TextExtract - search, grep, and extract text from other pages or groups with search terms and regular expressions, using search form or markup expression.
  • WikiSh - Wiki-based script language roughly emulating linux shell tools

Contributors

Comments

See discussion at PowerTools-Talk

The serialname link above could be a problem if a second user clicks on it before the first user saved the page. It's probably more save to generate the pagename when saving the page, like in the secound example.nos?

User notes +7: 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.