[[TOC]] = 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] || || '''keep_history''' || 0.1 || [yes|no] || If no argument given or yes, keep full history of form changes. Unless keep_history is specified, this defaults to false (no history recording). In contrast to track_fields history records mean essential revision support for !TracForms, required i.e. for incremental form reset/rollback, provided since 0.3 || || '''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/0.4 || name [content] [size] || Put an HTML form input field here. '''since 0.4''': If content is provided, it is used as a default. size, if specified, indicate the width of the input field in characters. Use {{{''}}} for content to specify the size of a blank area. || || '''tf.select''' || 0.2 || name value[//label]... || 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. Use {{{''}}} for content to specify the size of a blank area. || 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 == Within any command or operation, you can retrieve previously defined elements with %NAME% (case insensitive). These do NOT currently work within general text (use [tf:value] or [tf:quote] instead for these cases). 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.