wiki:TracFormsPlugin

News

22-Jul-2011
TracForms 0.4.1 is out. (open: 13)
18-May-2011
TracForms 0.4 is out. (open: 14)
04-Dec-2010
Maintainership handed over from rharkins to hasienda
26-Oct-2010
Starting ticket list cleanup and triaging (open: 25)
ToDo

Provides forms for ticket description and wiki pages

Description

This plugin aims to allow for forms anywhere there is a field with Trac wiki syntax. This is meant to supersede the previously limited-scope ChecklistPlugin.

WikiFormsPlugin aims at providing even more flexibility with a sightly more complex wiki markup incompatible to that of TracFormsPlugin. Additional features from this plugin have been requested here too (see #8715).

Release Status and Download

Stable Version tracformsplugin/tags/tracforms-0.4.1 download subversion
Under Development tracformsplugin/trunk download subversion

The current stable version is usable with Python2.6; an older Python requires simplejson to be installed.
Revision [10011] and above requires some dedicated permissions assigned to use new (search) as well as known TracForms features ('Update Form' button).

You can also download the entire project here, or checkout a copy using subversion.

See installation below for details on how to install and configure the plugin.

Example and Documentation

Also consider viewing the online tutorial or the 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 chuck this in:

== 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 get something looking like this:

Example of blank laundry list

From here, you can check some things and click "Submit Query" you'll see the fields change. After a few clicks it might look like this:

Example after a few checks.

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 it's 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 TracFormsPlugin/Docs for more information on the various ways to use this tool.

Bugs/Feature Requests

Existing bugs and feature requests for TracFormsPlugin are here.

If you have any issues not covered by the existing tickets (including closed ones), create a new ticket.

Installation

Once you have downloaded the source, do the following (your mileage may vary on the actual directory names depending on what you downloaded):

cd tracformsplugin
cd trunk
cd 0.11

For older versions or ones still in development, cd into tags and then into the desired version. For example, to use the 0.1 version:

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

python setup.py bdist_egg

cp dist/TracForms-0.1-*.egg $TRACENV_DIR/plugins/

Method 2: Full install

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

python setup.py install
vi $TRACENV_DIR/conf/trac.ini

Within here, locate (or create) your [components] section and add the following:

 [components]
 tracforms.* = enabled

Upgrading the database

Either of the above methods require a database upgrade...

trac-admin $TRACENV_DIR upgrade

Grant user persmissions

Since tracforms-0.4 you must grant form-related permissions to the relevant groups and/or users. Otherwise only users with 'TRAC_ADMIN' permision 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
just inherits all previous permissions, nothing more yet

About i18n/l10n support

The this plugin is prepared for localization.
But English message texts are still the (POSIX) default. If this isn't your preferred language, you can

  1. look, if it's already available from the Trac plugin l10n project at Transifex or
  2. do it yourself (see the l10n cookbook page for Trac plugins for more details).

You've done a new translation? Superb! Contributing your translation is highly appreciated.
You could send it to the plugin's maintainer or contribute to Trac plugin l10n project via Transifex:

Top translations: Trac_Plugin-L10N » tracforms-messages

http://www.transifex.net/projects/p/Trac_Plugin-L10N/resource/tracforms-messages/chart/image_png

Kindly provided by https://sw.transifex.net/4/static/charts/images/tx-logo-micro.png

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:

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.
Again, for more details see the l10n cookbook page for Trac plugins.

Recent Changes

[11562] by hasienda on 2012-05-14 23:55:10
TracFormsPlugin: (i18n) Update message catalog and German translation.
[11561] by hasienda on 2012-05-14 23:54:12
TracFormsPlugin: Move datetime rendering into template.

This way time stamp format is choosen per request according to preferences
of the user session, while it has been tied to server locale setting before.

[11283] by hasienda on 2012-02-19 23:18:45
TracFormsPlugin: Add optional write protection to input fields, refs #3264, #5353, #8715 and #9640.

A new keyword argument '-mode', for now exclusive to tf.input and tf.textarea,
with value to choose from the following list:

  • ro - input blocked, like static text, but in non-editable form field
  • rd - same as 'ro', but don't display stored value but default instead
  • rw - regular input behavior at all times (default)
  • once - initially 'rw', but blocked ('ro') after first form submission

It's an optional argument, retaining full backwards-compatibility
with existing field definitions by choosing -mode=rw as implicit default.

Author/Contributors

Author: rharkins
Maintainer: hasienda
Contributors: anderson, andrewbates, jrcutler, nelsojost

Last modified 4 months ago Last modified on Jun 18, 2014 10:22:01 PM

Attachments (2)

Download all attachments as: .zip