wiki:TracFormsPlugin/Syntax

Version 11 (modified by rharkins, 6 years ago) (diff)

--

TracFormsPlugin TracForm Syntax

All TracForm blocks are wrapped and formatted as follows:

{{{
#!TracForm
#
# comments
#
#! command 
#! command arg1 arg2
#
# more comments...
#
#! more_commands "quoted argument"
#

[tf.checklist:field]
[tf.who:field]

}}}

(... and so on)

Comments are ignored and can be intermixed with commands until the first non-comment line. [tf] operations are intermixed with other Trac wiki entities and the results can in some cases cause other wiki entities to take place (but only where it makes sense).

TracForm Configuration Commands

In the header section of the form, several commands can be used to control the rendering and configuration of the form in the form of "#!command [arg...]" lines before the first non-comment line:

Command Version Arguments Meaning
page 0.1 page-context Sets the page portion of the context used to store the form. This defaults to the page the user is currently on.
subcontext 0.1 subcontext Sets a subcontext within the page. For example, a SVN checklist could have a "#!subcontext SVN" to differentiate it from other forms on the page.
default 0.1 operation Specifies the default operation in [tf:args] blocks. Defaults to "checkbox"
track_fields 0.1 [yes|no] If no argument given or yes, keep track of field changes in this form. Unless track_fields is specified, this defaults to false (no field changes tracked). This affects [tf.who] and [tf.when]
submit_label 0.1 label Set the label to use for the submit button at the end of the form. The default is "Submit Form"
setenv 0.1 name value Set the name to value in the form's environment (or any subforms therein).
class 0.2 value Set the CSS class for the form.
id 0.2 value Set the CSS id for the form (defaults to the subcontext).
name 0.2 value Set the CSS name for the form (defaults to the subcontext).

TracForm Operations

Within the TracForm, you can use the following commands with [tf.OP:arg...] blocks.

Form Field Operations

Operation Version Argument(s) Meaning
tf.checkbox 0.1 name [value] Put an HTML checkbox here. Use value only if specified (simply "on" is default).
tf.radio 0.1 name value Put an HTML radio button here. Use the name and value pair together.
tf.input 0.1 name default Put an HTML form input field here.
tf.select 0.2 name valuelabel... Put a SELECT dropdown list here. The values are by default used as labels but can be added if label is used (the is removed)
tf.textarea 0.2 name [content] [cols] [rows] Add a textarea of the specified label. If content is provided, it is used as a default. cols and rows if specified indicate the size the textarea should occupy.

Starting in 0.2, the form field operations all accept -class= or -id= to set the CSS class or ID for the field.

Form Query Operations

Operation Version Argument(s) Meaning
tf.who 0.1 name Show which user most recently affected the specified field. This requires track_fields to be set in the commands section.
tf.when 0.1 name [strftime format string] Show when the most change was made on the specified field. This requires track_fields to be set in the commands section.
tf.form_updater 0.1 Show the most recent updater of the form itself.
tf.form_updated_on 0.1 [strftime format string] Show when the form was most recently updated.

Calculation Operations

Operation Version Argument(s) Meaning
filter 0.2 criteria value... [-quote] Apply criteria to each value and only emit those values that match, quoting results if -quote is provided.
count 0.2 value... Return a count of the values provided
countif 0.2 criteria value... Count only those that match the criteria
sum 0.2 value... Perform a floating-point sum on the arguments
sumif 0.2 criteria value... Perform a floating-point sum of the arguments that match the criteria
sumprod 0.2 value... [-stride=n] Using stride, add each group of n factors together. Thus [tf.sumprod: a b c d e f] = (ab) + (cd) + (ef)
value 0.2 source... Return each source from the environment in the same manner as %...% below
quote 0.2 source... Quote each source from the environment in the same manner as %...% below
zip 0.2 source... Intermingle results from the specified environment variable names in the same manner as %...% below

critiera can be a normal string, a wildcard in the UNIX form, or a regular expression if wrapped in /.../.

Debugging Operations

Operation Version Argument(s) Meaning
env_debug 0.2 [criteria] Display all keys and values from the environment. If criteria is provided, it is used as a filter on the keys

TracForm Arguments

Each arguments listed above are either:

  • Separated by whitespace. Example: #!setenv VAR VALUE
  • Quoted with double-quotes. Example: #!submit_label "Hello World"
  • Quoted with single-quotes. Example: [tf.input:'Big Text']

TracForm Environment

Using the #!setenv command above, you can retrieve previously defined elements with %NAME% (case insensitive). Other environment variables are also defined by the system:

Variable Version Meaning
%USER% 0.1 The currently active user.
%NOW% 0.1 The current date and time.

All substitutions may be applied to any argument within #! command or [tf:] operation sections. Use [tf.value] or [tf.quote] to extract environment variables within general text.

All form variables appear in the environment in three ways: prefixed with the whole context (page:subcontext:), prefixed with the page (page:), and prefixed with the subcontext if defined (subcontext:).

Environment lookups (via %...%, value, quote, etc) can have wildcards in the UNIX manner. Currently regular expressions are not supported for environment lookups.