FmtDirectives

Description
This page lists some important directives you can use on the fmt-template (that is, on a template used in the 'fmt=' part of a PmForm).
Notes:
  • In the (:template defaults:)/(:template requires:) the 's' letter at the end is optional and is insignificant.

The list of directives:

  • (:template defaults where=above:)
This should be used if you want the results of a form appended to some page in some way. In such a situation, the contents of the fmt-template will have all {$$name}-fields filled with values, and will be pasted into the destination page, which can be specified via the saveto= directive
  • Currently implemented values for where are: above, above#anchor, below, below#anchor, top, bottom, new (the default value).
  • Note: if where=new, the page is written only if it didn't exist before!
  • Note: the default where=new option is executed before savevars, so you can create a page filled using fmt-template (executed only at first time) and fill it with variables using savevars (works many times) in one click.
  • Note: where=above and where=below place the result above or below the (:pmform...:) directive in the page, so they only work when the page where the form is posted contains this directive.
  • The where=above#here and where=below#here arguments can be used to place the results below or above a [[#here]] anchor in the target page. The target page does not need to contain a (:pmform...:) directive which can be in another page or in a group header or footer.
  • The where= argument can be overridden by a parameter in the directive like (:pmform target where=below:).
  • (:template require field errmsg="message":) - the field must not be empty
  • (:template require field match=pattern errmsg="message":) - pattern is interpreted as a pagelist-like wildcard - special chars: *, ?, [, ], others?
  • (:template require field if=expression errmsg="message":) - expression is whatever would be good for a regular (:if:) (probably)
All of the above cancel form processing if the validation fails, and display message in the (:messages:) box. The field can be both a PTV-style one and a regular one.
  • {$$field-name}
Gets replaced with a value of a field named field-name sent from the form. Can the PTV fields be accessed by prepending them with ptv_? Or maybe there's no need for that?
DaveG: In the target template fields need to be referenced with {$$ptv_XXX} -- other formats ($:, $$) don't work.
  • (:template defaults savevars=$:var1,$:var2,...:)
Saves the PTV-type form fields as PageTextVariables into the page specified by the saveto= option. If the PTVs exist in destination page, their values are changed according to form contents, and their markup style is preserved (that is: hidden / definition-list / name:value )
  • (:template defaults successpage={$$saveto}:)
  • (:template defaults saveto=page:)
Specifies a page where the data from the form should be saved.
Note: saveto can be specified in fmt-template or in the $PmForm in target description. Both methods apparently allow for different effects:
  • The fmt-template variant can be used with variables submitted via form, so you can write, say, saveto='Friend-{$$friend-name}' See: ClientForm, ClientTemplates
  • The $PmForm variant can be used with standard PmWiki:PageVariables (and other FmtPageName() markup?). Therefore, you can write saveto={*$FullName} or saveto={SomePage$:somePTV}.
Which of the variants has higher priority (overrides the other one)?
 0: 00.00 00.00 config start
 1: 00.01 config end
 2: 00.21 MarkupToHTML begin
 3: 00.25 MarkupToHTML end
 4: 00.25 MarkupToHTML begin
 5: 00.26 ReadApprovedUrls SiteAdmin.ApprovedUrls begin
 6: 00.26 ReadApprovedUrls SiteAdmin.ApprovedUrls end
 7: 00.27 MarkupToHTML end
 8: 00.27 MarkupToHTML begin
 9: 00.28 MarkupToHTML end
10: 00.28 now