[[PageOutline(2-5,Contents,pullout)]] = Add forms for ticket description and wiki pages == Description This plugin allows you to add forms anywhere where there is a field with Trac wiki syntax. The similar WikiFormsPlugin aims at providing even more flexibility with a sightly more complex wiki markup incompatible with that of this plugin. Additional features from this plugin have been requested here too (see #8715). For a comparison between the two plugins, see [wiki:TracFormsPlugin/Dev here]. === Example and [wiki:TracFormsPlugin/Docs Documentation] Also see the online [wiki:TracFormsPlugin/Tutorial tutorial] or the [wiki:TracFormsPlugin/Docs documentation] (docs still in need of some corrections and updates to 0.4). Let's start by looking at a simple laundry list. This list will be automatically bound to whatever page it appears in by default (this can be configured). Once the plugin is installed, simply edit a new wiki resource called `Sandbox/LaundryList` and add this: {{{ == Laundry list example {{{ #!TracForm # # An example of a TracForm. The first lines can be commentary or #! commands. # #! track_fields || || '''Who''' || '''When''' || '''What''' || || [tf:wash] || [tf.who:wash] || [tf.when:wash] || Wash Clothes || || [tf:dry] || [tf.who:dry] || [tf.when:dry] || Dry Clothes || || [tf:fold] || [tf.who:fold] || [tf.when:fold] || Fold Clothes || }}} }}} Once saved, you should see something like this: [[Image(LaundryList.jpg)]] From here, you can click "Submit Query" and you will see the fields change. After a few clicks it might look like this: [[Image(LaundryList2.jpg)]] Now, if you thought that was neat, make sure you have the IncludeMacro installed and fire up a new wiki page Sandbox/LaundryListUser with the following: {{{ [[Include(Sandbox/LaundryList)]] }}} Note that the form is blank and you can play with the results again. This is because the default context for the form is the page URL itself! That means that as long as a form is included on a different page (and the default context is not overridden), then each page including gets its '''own''' version of the form's results. This works particularly well with !PageTemplates. Now, for more fun, do the same thing in a ticket. Once submitted, every ticket including the template will contain its own checklist. One obvious use for this is when creating a svn commit checklist. Simply put the checklist in the appropriate wiki location, create tickets that include the location, and voila, instant commit step-by-step. Once enough of the form becomes exposed, we should be able to work this into the workflow too (no resolving before at least paying lip service to the checklist). There is much more planned for this plugin than simply checklists. See [wiki:TracFormsPlugin/Docs] for more information on the various ways to use this tool. == Bugs/Feature Requests Existing bugs and feature requests for TracFormsPlugin are [report:9?COMPONENT=TracFormsPlugin here]. If you have any issues, create a [/newticket?component=TracFormsPlugin new ticket]. [[TicketQuery(component=TracFormsPlugin&group=type,format=progress)]] == Download and Source || Stable Version || [source:tracformsplugin/tags/tracforms-0.4.1] || [export:tracformsplugin/tags/tracforms-0.4.1 download] || [/svn/tracformsplugin/tags/tracforms-0.4.1 subversion] || Under Development || [source:tracformsplugin/trunk] || [export:tracformsplugin/trunk download] || [/svn/tracformsplugin/trunk subversion] The current stable version is usable with Python 2.6; older Python versions require [http://simplejson.github.com/simplejson/ simplejson] to be installed. Revision [10011] and above requires some dedicated permissions assigned to use new features (such as Search) as well as known !TracForms features (such as the 'Update Form' button). You can also download the entire project [export:tracformsplugin here], or checkout a copy using [/svn/tracformsplugin Subversion]. == Installation Once you have downloaded the source, do the following (the actual directory names depend on what you downloaded): {{{#!sh cd tracformsplugin cd trunk cd 0.11 }}} For older versions or ones still in development, go to the tags directory and then to the desired version, for example: {{{#!sh cd tracformsplugin cd tags cd release-0.1 cd 0.11 }}} === Method 1: Lay an egg From here, you can do one of two things. The first is building an egg to drop into your project's plugins directory or your master project's plugins directory (replace or define $TRACENV_DIR with your project's base directory): {{{#!sh python setup.py bdist_egg cp dist/TracForms-0.1-*.egg $TRACENV_DIR/plugins/ }}} === Method 2: Full installation Or, you can build and install and enable the right bit in the configuration file (replace or define $TRACENV_DIR with your project's base directory): {{{#!sh python setup.py install vi $TRACENV_DIR/conf/trac.ini }}} Within here, locate (or create) your [components] section and add the following: {{{#!ini [components] tracforms.* = enabled }}} === Upgrading the database Either of the above methods require a database upgrade: {{{#!sh trac-admin $TRACENV_DIR upgrade }}} == Configuration Since `tracforms-0.4` you must grant form-related permissions to the relevant groups and/or users. Otherwise only users with `TRAC_ADMIN` permission will be able to see details and use forms. These are the permission actions available: `FORM_VIEW`:: view form details, similar to ticket or wiki change history. `FORM_EDIT_VAL`:: enable submission of form content changes - these users will be able to see and use 'Update Form' buttons. `FORM_RESET`:: enable incremental and full form version clean-up by using additional action buttons on form details pages. `FORM_ADMIN`:: inherits all previous permissions, nothing more yet. == About i18n/l10n support This plugin is prepared for localization.[[BR]] But English message texts are still the (POSIX) default. If this isn't your preferred language, you can 1. check if it is already available from the [TracPluginTranslation Trac plugin l10n project] at [https://www.transifex.net/projects/p/Trac_Plugin-L10N/resource/tracforms Transifex] or 2. do it yourself (see the [http://trac.edgewall.org/wiki/CookBook/PluginL10N#Dotranslatorswork l10n cookbook page for Trac plugins] for more details). You've done a new translation? Superb! Contributing your translation is highly appreciated.[[BR]] You could send it to the plugin's maintainer or contribute to [TracPluginTranslation Trac plugin l10n project] via [http://www.transifex.net/projects/p/Trac_Plugin-L10N/ Transifex]: Top translations: Trac_Plugin-L10N ยป [http://www.transifex.net/projects/p/Trac_Plugin-L10N/resource/tracforms/ tracforms][[BR]] [[Image(http://www.transifex.net/projects/p/Trac_Plugin-L10N/resource/tracforms/chart/image_png, title=Go to Trac_Plugin-L10N project page on Transifex.net, link=http://www.transifex.net/projects/p/Trac_Plugin-L10N/resource/tracforms/)]] Kindly provided by [[Image(https://ds0k0en9abmn1.cloudfront.net/static/charts/images/tx-logo-micro.png, link=http://www.transifex.net/, title=the open translation platform, valign=bottom)]] Preparing the plugin from source requires '''no additional steps''' for compiling message catalog files. Only to include translations marked as `# fuzzy` by the translator, you'll want to do a manual message catalog compilation with the extra `-f` argument before packaging: {{{#!sh cd tracformsplugin/ python ./setup.py compile_catalog -f python ./setup.py bdist_egg }}} Complaints about missing `locale` directory are often a side-effect of failure to compile any message catalog for inclusion into Python egg, hence the whole path is missing. Due to a know Trac issue Babel has to be installed prior to Trac, to get it all working as expected.[[BR]] Again, for more details see the [t:wiki:CookBook/PluginL10N#Compileanduseit l10n cookbook page for Trac plugins]. == Recent Changes [[ChangeLog(tracformsplugin, 3)]] == Author/Contributors '''Author:''' [wiki:rharkins] [[BR]] '''Maintainer:''' [[Maintainer]] [[BR]] '''Contributors:''' anderson, [wiki:andrewbates], [wiki:jrcutler], [wiki:nelsojost], hasienda