[[PageOutline(2-5,Contents,pullout)]]

= Provides forms anywhere where there is a wiki

== Description

This plugin allows you to add a form on any Trac wiki page. This is meant to provide a more flexible version of TracFormsPlugin. For a comparison between the two plugins, see [wiki:TracFormsPlugin/Dev here].

This plugin can be used in the following ways:

{{{

Normal wiki formatted stuff...

{{{
#!WikiForms

== Selects

|| '''Description''' || '''Example'''                                      || '''Value'''
|| simple select     || <tf>select:simple_select:1 2 3 4</tf>              || <tf>value:simple_select</tf>
|| labeled select    || <tf>select:labeled_select:1=l1 2=l2 3=l3 4=l4</tf> || <tf>value:labeled_select</tf>
|| quoted select     || <tf>select:quoted_select:'"a"' "'b'" 'c c'</tf>    || <tf>value:quoted_select</tf>
|| complex select    || <tf>select:complex_select:
#
# keep in mind that 
#  - comments are removed
#  - newlines are replaced with '' (empty string)
# prior to parsing. After all those the preformatting the 
# fields still have to be separated by whitespace to be distinguishable.
# Further cfg-options are:
#   default 
#   class
#   id
value0                            # label = value
 'v a l u e 1'                    # label = value, both containing whitespace
        value2='l a b e l 2'      # 
 'v a l u e 3'=label3             # 
 'val ue4'="lab el4"
 class=my_css_class
 id=my_css_id
 default=value2                   # this is the cfg option (not an entry for the selector-list)...
 :                                # separator, from now on everything becomes a selector-list entry even if the name matches a cfg-option
</tf>                                                                      || <tf>value:complex_select</tf>

== Checkboxes

|| '''Description''' || '''Example'''                                      || '''Value'''
|| simple checkbox   || <tf>checkbox:simple_checkbox</tf>                  || <tf>value:simple_checkbox</tf>
|| complex checkbox  || <tf>checkbox:complex_checkbox:
# Further cfg-options are:
# checked  : flag ('1','true' 'on' 'yes') used if there is no database entry available...
# value    : value stored when checkbox is checked
# class 
# id 
value=value_if_checked
checked=true
</tf>                                                                      || <tf>value:complex_checkbox</tf>

== Inputs

|| '''Description''' || '''Example'''                                      || '''Value'''
|| simple input      || <tf>input:simple_input</tf>                        || <tf>value:simple_input</tf>
|| complex input     || <tf>input:complex_input:
# Further cfg-options are:
# value    : default value if no database entry is available
# size     : width in characters (defaults to 22)
# class 
# id 
value="   'foo'   "'"bar" 'baz  
size=30
</tf>                                                                      || <tf>value:complex_input</tf>

== Radios

|| '''Description''' || '''Example'''                                                                                                                                     || '''Value'''
|| simple radio      || <tf>radio:simple_radio:value='beer'</tf> [[BR]]<tf>radio:simple_radio:value=milk checked=true</tf> [[BR]] <tf>radio:simple_radio:value=water</tf> || <tf>value:simple_radio</tf>
|| complex radio     || <tf>radio:complex_radio:
# Further cfg-options are:
# checked  : flag ('1','true' 'on' 'yes') used if there is no database entry available...
# value    : value stored when this radio is selected
# class 
# id 
value=dummy1  
size=30
</tf> [[BR]] <tf>radio:complex_radio:
value=dummy2</tf>                                                                                                                                                         || <tf>value:complex_radio</tf>

== Text areas

|| '''Description''' || '''Example'''                 || '''Value'''
|| simple text       || <tf>textarea:simple_text</tf> || <tf>value:simple_text</tf>
|| complex text      || <tf>textarea:complex_text:
# Further cfg-options are:
# rows     : defaults to 2
# cols     : defaults to 10
# value    : default value if no database entry is available, defaults to ''
# class 
# id 
cols=30 rows=5 value='Please fill your
approval
comment
in here'</tf>                                          || <tf>value:complex_text</tf>

== Submit Buttons

|| '''Description''' || '''Example'''
|| simple button     || <tf>submit</tf>
|| complex button    || <tf>submit:
# label    : label on the button, defaults to 'Send'
# class 
# id 
label='Commit'</tf>

== Query Stuff

<tf>
# to have a value which is always there...
set:to_be_queried:magic_value</tf>

=== Without Formatting

|| '''Value'''  || <tf>value:to_be_queried</tf>
|| '''Who'''    || <tf>who:to_be_queried</tf>
|| '''When'''   || <tf>when:to_be_queried</tf>

=== With Formatting

|| '''Value''' (in bold)  || '''<tf>value:to_be_queried</tf>'''
|| '''Who''' (underlined) || __<tf>who:to_be_queried</tf>__
|| '''When''' (in italic) || ''<tf>when:to_be_queried</tf>''

<tf>lastmodified</tf>

== Debug Stuff

<tf>
# set an relative field
set:rel_name:rel_value
</tf>

<tf>
# set an absolute field
set:/abs_name:abs_value
</tf>

<tf>delete:/abs_name</tf>

<tf>
# dump fields...
dump:.*
</tf>
}}}

Normal wiki formatted stuff...
}}}

=== New Include Feature

Let's assume you have a wiki page named 'sandbox':
{{{
{{{
({{a}})

({{b}})

({{x}})

({{a}})

({{ c }})

({{d}})
}}}

}}}

If you call it like this:
{{{
[[WikiFormInclude(sandbox:a=1 b=2 c=' " ' d='a b c d')]]
}}}

all defined values are replaced and the resulting page is rendered as usual. 

=== New Permission Feature

Think of an example like this:
||         || admin[[BR]]user || normal[[BR]]user || other[[BR]]user
|| region1 || rw              || r                || /
|| region2 || rw              || /                || /
|| region3 || /               || /                || r

{{{
{{{
#!WikiForms

<f>permission:change:                                            # default access is none                          </f>
<f>permission:change: +rw     : user in admin_user1,admin_user2  # admin user gets additionally read/write access  </f>
<f>permission:change: +r      : user in user1 , user2            # normal user get additionally read access        </f>
<f>permission:alias : region1                                    # save this as permission for region 1            </f>


<f>permission:change:                                            # default access is none                          </f>
<f>permission:change: +rw     : user in admin_user1,admin_user2  # admin user gets read/write access               </f>
<f>permission:alias : region2                                    # save this as permission for region 2            </f>


<f>permission:change:  r                                         # default access is read                          </f>
<f>permission:change: -r      : user in admin_user1,admin_user2  # admin user should not see default message       </f>
<f>permission:change: -r      : user in user1 , user2            # normal user should not see default message      </f>
<f>permission:alias : region3                                    # save this as permission for region 3            </f>


<f>permission:alias:region1</f>
<f>checkbox:approval1</f>  This is region 1 (rw for admin-user, r for normal-user, hidden for others)


<f>permission:alias:region2</f>
<f>checkbox:approval2</f>  This is region 2 (rw for admin-user, hidden for normal-user and others)


<f>permission:alias:region3</f>
<f>checkbox:approval3</f>  This is region 3 (hidden for admin- and normal-user, r for others)
}}}
}}}

Permissions might be based on the state of a ticket or milestone like this:
{{{
{{{
#!WikiForms

<f>permission:change:rw</f>
<f>permission:change:-w:ticket_state 42 in closed         # ticket with id=42 has to exist!    </f>

|| <f>checkbox:approval:checked=true</f>                             || (read-only if #42 is in closed state)
|| <f>input:comment:value='Please fill in your comment' size=50</f>  || (read-only if #42 is in closed state)


<f>permission:change:rw</f>
<f>permission:change:-w:milestone_is_complete 'my next milestone'   # milestone with name='my next milestone' has to exist!              </f> 

<f>checkbox:approval:checked=true</f>  (read-only if milestone is completed)
}}}
}}}

=== New Notification feature

Sometimes users want to be informed via email if a form is updated, eg when form is at review checklist.

The new notify-tag supports this:
{{{
<tf>notify:mail_to="comma separated list of mail addresses to be notified" subject="subject of notification e-mail"    body="optional information included into the notification e-mail"</tf>
}}}

A real life example:
The svn-post-commit hook appends the following review checklist call to the check-in comment:
{{{
[[WikiFormInclude(checklists/commit_review/v1:mail_to=foo@bar revision=r1234)]]
}}}

The called checklist contains the following notify-tag:
{{{
<tf>notify:mail_to={{mail_to}} subject="Commit Review {{revision}} Updated"</tf>
}}}

== Bugs/Feature Requests

Existing bugs and feature requests for WikiFormsPlugin are 
[report:9?COMPONENT=WikiFormsPlugin here].

If you have any issues, create a 
[/newticket?component=WikiFormsPlugin new ticket].

[[TicketQuery(component=WikiFormsPlugin&group=type,format=progress)]]

== Download

Download the zipped source from [export:wikiformsplugin here].

== Source

You can check out WikiFormsPlugin from [/svn/wikiformsplugin here] using Subversion, or [source:wikiformsplugin browse the source] with Trac.

== Installation

General instructions on installing Trac plugins can be found on the [TracPlugins#InstallingaTracplugin TracPlugins] page.

== Recent Changes

[[ChangeLog(wikiformsplugin, 3)]]

== Author/Contributors

'''Author:''' [wiki:asic_druide] [[BR]]
'''Maintainer:''' [[Maintainer]] [[BR]]
'''Contributors:'''