1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/README.txt Tue Jul 16 16:57:20 2013 +0200
1.3 @@ -0,0 +1,132 @@
1.4 +Introduction
1.5 +------------
1.6 +
1.7 +The MoinForms extension for MoinMoin provides a way of defining Web forms in
1.8 +wiki pages that support elementary and extensible validation, replicated form
1.9 +sections, and a framework for handling submitted forms. Each form is defined
1.10 +using conventional wiki syntax together with macros that produce HTML form
1.11 +elements and is encapsulated using the MoinMoin parsed region syntax. Thus,
1.12 +each form appears as an integrated part of the page in which it is defined.
1.13 +
1.14 +To handle submitted forms, MoinForms employs handler actions that support
1.15 +basic manipulation and validation actions, along with the storage of submitted
1.16 +form data, and such actions can be extended to perform enhanced validation and
1.17 +other submission-related actions.
1.18 +
1.19 +Installation
1.20 +------------
1.21 +
1.22 +To install MoinForms, consider using the moinsetup tool. See the "Recommended
1.23 +Software" section below for more information.
1.24 +
1.25 +With moinsetup and a suitable configuration file, the installation is done as
1.26 +follows with $MFDIR referring to the MoinForms distribution directory
1.27 +containing this README.txt file:
1.28 +
1.29 + python moinsetup.py -f moinsetup.cfg -m install_extension_package $MFDIR
1.30 + python moinsetup.py -f moinsetup.cfg -m install_actions $MFDIR/actions
1.31 + python moinsetup.py -f moinsetup.cfg -m install_macros $MFDIR/macros
1.32 + python moinsetup.py -f moinsetup.cfg -m install_parsers $MFDIR/parsers
1.33 +
1.34 +The first command above uses the setup.py script provided as follows:
1.35 +
1.36 + python setup.py install --prefix=path-to-moin-prefix
1.37 +
1.38 +The second, third and fourth commands install the actions, macros and parsers
1.39 +respectively.
1.40 +
1.41 +Additional Installation Tasks
1.42 +-----------------------------
1.43 +
1.44 +See the "Dependencies" section below for details of the software featured in
1.45 +this section.
1.46 +
1.47 +MoinForms depends on MoinSupport having been installed. This is because a lot
1.48 +of useful functionality common to a number of MoinMoin extensions now resides
1.49 +in the MoinSupport distribution.
1.50 +
1.51 +The following command can be run with $MSDIR referring to the MoinSupport
1.52 +distribution directory:
1.53 +
1.54 + python moinsetup.py -f moinsetup.cfg -m install_extension_package $MSDIR
1.55 +
1.56 +Useful Pages
1.57 +------------
1.58 +
1.59 +The pages directory contains a selection of useful pages using a syntax
1.60 +appropriate for use with MoinMoin 1.6 or later. These pages can be created
1.61 +through the wiki and their contents copied in from each of the files. An
1.62 +easier installation method is to issue the following commands:
1.63 +
1.64 + python moinsetup.py -f moinsetup.cfg -m make_page_package $MFDIR/pages pages.zip
1.65 + python moinsetup.py -f moinsetup.cfg -m install_page_package pages.zip
1.66 +
1.67 +You may need to switch user in order to have sufficient privileges to copy the
1.68 +page package into the wiki. For example:
1.69 +
1.70 + sudo -u www-data python moinsetup.py -f moinsetup.cfg -m install_page_package pages.zip
1.71 +
1.72 +Using MoinForms
1.73 +---------------
1.74 +
1.75 +The HelpOnMoinForms page provided in the pages directory provides working
1.76 +examples of the macros used to produce HTML form elements and the regions that
1.77 +encapsulate such elements to make functioning HTML forms. Adding a form to a
1.78 +page is as simple as the following example taken from the HelpOnMoinForms
1.79 +page:
1.80 +
1.81 +{{{#!form fragment=exampleform finishing=finish
1.82 +
1.83 +|| '''Name''' || <<FormField(name,ExampleFormDict)>> ||
1.84 +|| '''Address''' || <<FormField(address,ExampleFormDict)>> ||
1.85 +|| '''Country''' || <<FormField(country,ExampleFormDict)>> ||
1.86 +|| || <<FormField(finish,ExampleFormDict,label=Finish)>> ||
1.87 +
1.88 +}}}
1.89 +
1.90 +The ExampleFormDict page referenced in the above example is also provided in
1.91 +the pages directory and is used to provide details for the named fields in the
1.92 +form. There is also an ExampleFormCountryDict page which provides a choice of
1.93 +countries for the country field; this is referenced by the ExampleFormDict
1.94 +page.
1.95 +
1.96 +In short, a form references various definitions which in turn can be built
1.97 +upon other definitions, and thus a kind of common vocabulary for form fields
1.98 +can be constructed.
1.99 +
1.100 +Recommended Software
1.101 +--------------------
1.102 +
1.103 +See the "Dependencies" section below for essential software.
1.104 +
1.105 +The moinsetup tool is recommended for installation since it aims to support
1.106 +all versions of MoinMoin that are supported for use with this software.
1.107 +
1.108 +See the following page for information on moinsetup:
1.109 +
1.110 +http://moinmo.in/ScriptMarket/moinsetup
1.111 +
1.112 +Contact, Copyright and Licence Information
1.113 +------------------------------------------
1.114 +
1.115 +See the following Web page for more information about this work:
1.116 +
1.117 +http://moinmo.in/ParserMarket/MoinForms
1.118 +
1.119 +The author can be contacted at the following e-mail address:
1.120 +
1.121 +paul@boddie.org.uk
1.122 +
1.123 +Copyright and licence information can be found in the docs directory - see
1.124 +docs/COPYING.txt and docs/LICENCE.txt for more information.
1.125 +
1.126 +Dependencies
1.127 +------------
1.128 +
1.129 +MoinForms has the following basic dependencies:
1.130 +
1.131 +Packages Release Information
1.132 +-------- -------------------
1.133 +
1.134 +MoinSupport Tested with 0.4
1.135 + Source: http://hgweb.boddie.org.uk/MoinSupport