Changes between Version 17 and Version 18 of TracFormsPlugin/Syntax
- Timestamp:
- Aug 27, 2015, 10:11:59 AM (9 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
TracFormsPlugin/Syntax
v17 v18 1 [[ TOC]]1 [[PageOutline(2-5,Contents,pullout)]] 2 2 3 = TracFormsPlugin !TracForm Syntax =3 = TracFormsPlugin !TracForm Syntax 4 4 5 5 All !TracForm blocks are wrapped and formatted as follows: … … 29 29 (... and so on) 30 30 31 Comments are ignored and can be intermixed with commands until the first non-comment line. 31 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). 32 32 33 == !TracForm Configuration Commands ==33 == !TracForm Configuration Commands 34 34 35 35 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: 36 36 37 37 || '''Command''' || '''Version''' || '''Arguments''' || '''Meaning''' || 38 || '''page''' || 0.1 || page-context || Sets the page portion of the context used to store the form. 39 || '''subcontext''' || 0.1 || subcontext || Sets a subcontext within the page. 40 || '''default''' || 0.1 || operation || Specifies the default operation in [tf:args] blocks. 41 || '''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] ||42 || '''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 ||43 || '''submit_label''' || 0.1 || label || Set the label to use for the submit button at the end of the form. 44 || '''setenv''' || 0.1 || name value || Set the name to value in the form's environment (or any subforms therein). ||38 || '''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. || 39 || '''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. || 40 || '''default''' || 0.1 || operation || Specifies the default operation in [tf:args] blocks. Defaults to "checkbox" || 41 || '''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] || 42 || '''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 || 43 || '''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" || 44 || '''setenv''' || 0.1 || name value || Set the name to value in the form's environment or any subforms therein. || 45 45 || '''class''' || 0.2 || value || Set the CSS class for the form. || 46 46 || '''id''' || 0.2 || value || Set the CSS id for the form (defaults to the subcontext). || 47 47 || '''name''' || 0.2 || value || Set the CSS name for the form (defaults to the subcontext). || 48 48 49 == !TracForm Operations ==49 == !TracForm Operations 50 50 51 51 Within the !TracForm, you can use the following commands with [tf.OP:arg...] blocks. 52 52 53 === Form Field Operations === 53 === Form Field Operations 54 54 55 || '''Operation''' || '''Version''' || '''Argument(s)''' || '''Meaning''' || 55 || '''tf.checkbox''' || 0.1 || name [value] || Put an HTML checkbox here. Use value only if specified (simply"on" is default). ||56 || '''tf.radio''' || 0.1 || name value || Put an HTML radio button here. 57 || '''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. 58 || '''tf.select''' || 0.2 || name value[//label]... || Put a SELECT dropdown list here. 59 || '''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. ||56 || '''tf.checkbox''' || 0.1 || name [value] || Put an HTML checkbox here. Use value only if specified ("on" is default). || 57 || '''tf.radio''' || 0.1 || name value || Put an HTML radio button here. Use the name and value pair together. || 58 || '''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. || 59 || '''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) || 60 || '''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. || 60 61 61 62 Starting in 0.2, the form field operations all accept -class= or -id= to set the CSS class or ID for the field. 62 63 63 === Form Query Operations === 64 === Form Query Operations 65 64 66 || '''Operation''' || '''Version''' || '''Argument(s)''' || '''Meaning''' || 65 || '''tf.who''' || 0.1 || name || Show which user most recently affected the specified field. 66 || '''tf.when''' || 0.1 || name [strftime format string] || Show when the most change was made on the specified field. 67 || '''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. || 68 || '''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. || 67 69 || '''tf.form_updater''' || 0.1 || || Show the most recent updater of the form itself. || 68 70 || '''tf.form_updated_on''' || 0.1 || [strftime format string] || Show when the form was most recently updated. || … … 75 77 || '''sum''' || 0.2 || value... || Perform a floating-point sum on the arguments || 76 78 || '''sumif''' || 0.2 || criteria value... || Perform a floating-point sum of the arguments that match the criteria || 77 || '''sumprod''' || 0.2 || value... [-stride=n] || Using stride, add each group of n factors together. 79 || '''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) || 78 80 || '''value''' || 0.2 || source... || Return each source from the environment in the same manner as %...% below || 79 81 || '''quote''' || 0.2 || source... || Quote each source from the environment in the same manner as %...% below || … … 82 84 critiera can be a normal string, a wildcard in the UNIX form, or a regular expression if wrapped in /.../. 83 85 84 === Debugging Operations === 86 === Debugging Operations 87 85 88 || '''Operation''' || '''Version''' || '''Argument(s)''' || '''Meaning''' || 86 || '''env_debug''' || 0.2 || [criteria] || Display all keys and values from the environment. 89 || '''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 || 87 90 88 == !TracForm Arguments ==91 == !TracForm Arguments 89 92 90 93 Each arguments listed above are either: 91 94 92 * Separated by whitespace. Example:#!setenv VAR VALUE93 * Quoted with double-quotes. 94 * Quoted with single-quotes. 95 * Separated by whitespace. Example: #!setenv VAR VALUE 96 * Quoted with double-quotes. Example: #!submit_label "Hello World" 97 * Quoted with single-quotes. Example: [tf.input:'Big Text'] 95 98 96 == !TracForm Environment ==99 == !TracForm Environment 97 100 98 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:101 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: 99 102 100 103 || '''Variable''' || '''Version''' || '''Meaning''' || … … 102 105 || '''%NOW%''' || 0.1 || The current date and time. || 103 106 104 All substitutions may be applied to any argument within #! command or [tf:] operation sections. 107 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. 105 108 106 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:). 109 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:). 107 110 108 Environment lookups (via %...%, value, quote, etc) can have wildcards in the UNIX manner. 111 Environment lookups (via %...%, value, quote, etc) can have wildcards in the UNIX manner. Currently regular expressions are not supported for environment lookups.