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)?