1 Introduction
2 ------------
3
4 The MoinForms extension for MoinMoin provides a way of defining Web forms in
5 wiki pages that support elementary and extensible validation, replicated form
6 sections, and a framework for handling submitted forms. Each form is defined
7 using conventional wiki syntax together with macros that produce HTML form
8 elements and is encapsulated using the MoinMoin parsed region syntax. Thus,
9 each form appears as an integrated part of the page in which it is defined.
10
11 To handle submitted forms, MoinForms employs handler actions that support
12 basic manipulation and validation actions, along with the storage of submitted
13 form data, and such actions can be extended to perform enhanced validation and
14 other submission-related actions.
15
16 Installation
17 ------------
18
19 To install MoinForms, consider using the moinsetup tool. See the "Recommended
20 Software" section below for more information.
21
22 With moinsetup and a suitable configuration file, the installation is done as
23 follows with $MFDIR referring to the MoinForms distribution directory
24 containing this README.txt file:
25
26 python moinsetup.py -f moinsetup.cfg -m install_extension_package $MFDIR
27 python moinsetup.py -f moinsetup.cfg -m install_actions $MFDIR/actions
28 python moinsetup.py -f moinsetup.cfg -m install_macros $MFDIR/macros
29 python moinsetup.py -f moinsetup.cfg -m install_parsers $MFDIR/parsers
30
31 The first command above uses the setup.py script provided as follows:
32
33 python setup.py install --prefix=path-to-moin-prefix
34
35 The second, third and fourth commands install the actions, macros and parsers
36 respectively.
37
38 Additional Installation Tasks
39 -----------------------------
40
41 See the "Dependencies" section below for details of the software featured in
42 this section.
43
44 MoinForms depends on MoinSupport having been installed. This is because a lot
45 of useful functionality common to a number of MoinMoin extensions now resides
46 in the MoinSupport distribution.
47
48 The following command can be run with $MSDIR referring to the MoinSupport
49 distribution directory:
50
51 python moinsetup.py -f moinsetup.cfg -m install_extension_package $MSDIR
52
53 Useful Pages
54 ------------
55
56 The pages directory contains a selection of useful pages using a syntax
57 appropriate for use with MoinMoin 1.6 or later. These pages can be created
58 through the wiki and their contents copied in from each of the files. An
59 easier installation method is to issue the following commands:
60
61 python moinsetup.py -f moinsetup.cfg -m make_page_package $MFDIR/pages pages.zip
62 python moinsetup.py -f moinsetup.cfg -m install_page_package pages.zip
63
64 You may need to switch user in order to have sufficient privileges to copy the
65 page package into the wiki. For example:
66
67 sudo -u www-data python moinsetup.py -f moinsetup.cfg -m install_page_package pages.zip
68
69 Using MoinForms
70 ---------------
71
72 The HelpOnMoinForms page provided in the pages directory provides working
73 examples of the macros used to produce HTML form elements and the regions that
74 encapsulate such elements to make functioning HTML forms. Adding a form to a
75 page is as simple as the following example taken from the HelpOnMoinForms
76 page:
77
78 {{{#!form fragment=exampleform finishing=finish
79
80 || '''Name''' || <<FormField(name,ExampleFormDict)>> ||
81 || '''Address''' || <<FormField(address,ExampleFormDict)>> ||
82 || '''Country''' || <<FormField(country,ExampleFormDict)>> ||
83 || || <<FormField(finish,ExampleFormDict,label=Finish)>> ||
84
85 }}}
86
87 The ExampleFormDict page referenced in the above example is also provided in
88 the pages directory and is used to provide details for the named fields in the
89 form. There is also an ExampleFormCountryDict page which provides a choice of
90 countries for the country field; this is referenced by the ExampleFormDict
91 page.
92
93 In short, a form references various definitions which in turn can be built
94 upon other definitions, and thus a kind of common vocabulary for form fields
95 can be constructed.
96
97 Recommended Software
98 --------------------
99
100 See the "Dependencies" section below for essential software.
101
102 The moinsetup tool is recommended for installation since it aims to support
103 all versions of MoinMoin that are supported for use with this software.
104
105 See the following page for information on moinsetup:
106
107 http://moinmo.in/ScriptMarket/moinsetup
108
109 Contact, Copyright and Licence Information
110 ------------------------------------------
111
112 See the following Web page for more information about this work:
113
114 http://moinmo.in/ParserMarket/MoinForms
115
116 The author can be contacted at the following e-mail address:
117
118 paul@boddie.org.uk
119
120 Copyright and licence information can be found in the docs directory - see
121 docs/COPYING.txt and docs/LICENCE.txt for more information.
122
123 Dependencies
124 ------------
125
126 MoinForms has the following basic dependencies:
127
128 Packages Release Information
129 -------- -------------------
130
131 MoinSupport Tested with 0.4
132 Source: http://hgweb.boddie.org.uk/MoinSupport