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