Documentation updates.

pull/7/head
Ferry Boender 9 years ago
parent 937a8b6706
commit f8e96de85a
  1. 117
      doc/MANUAL.md

@ -4,7 +4,8 @@ This is the manual for version %%VERSION%%.
## Table of Contents
1. [Terminology](#terminology)
1. [Introduction](#introduction)
- [Terminology](#terminology)
1. [Invocations](#invocations)
- [Shell foreground](#invocations_foreground)
- [Daemon](#invocations_daemon)
@ -37,7 +38,18 @@ This is the manual for version %%VERSION%%.
- [Custom CSS](#cust_css)
1. [Security](#security)
## <a name="terminology">Terminology</a>
## <a name="intro">Introduction</a>
Scriptform is a stand-alone webserver that automatically generates forms from
JSON to serve as frontends to scripts.
ScriptForm takes a JSON file which contains form definitions. It then
constructs web forms from this JSON and serves these to users over HTTP. The
user can select a form and fill it out. When the user submits the form, it is
validated and the associated script is called. Data entered in the form is
passed to the script through the environment.
### <a name="intro_terminology">Terminology</a>
Scriptform uses various terminology to distinguish between different components
of the application.
@ -72,6 +84,11 @@ Sriptform can be run directly from the shell in the foreground with the `-f`
$ /usr/bin/scriptform -p8000 -f ./formdef.json
You can specify the `-r` option to automatically reload the JSON file upon each
request:
$ /usr/bin/scriptform -p8000 -r -f ./formdef.json
### <a name="invocations_daemon">Daemon</a>
If you do not specify the `-f` option, Scriptform will go into the background:
@ -109,6 +126,12 @@ Finally, start it:
### <a name="invocations_apache">Behind Apache</a>
Scriptform does not support HTTPS / SSL, so for production environments you
might want to run it behind an Apache server that has SSL enabled. To do so,
you start Scriptform as a daemon and then forward requests to it from Apache:
$ sudo /etc/init.d/scriptform start
Enable Apache modules mod_proxy and mod_proxy_http:
$ sudo a2enmod proxy
@ -248,16 +271,19 @@ For example, here's a form config file that contains two forms:
"name": "username",
"title": "Username",
"type": "string"
"required": true
},
{
"name": "password1",
"title": "Password",
"type": "password"
"type": "password",
"required": true
},
{
"name": "password2",
"title": "Password (Repear)",
"type": "password"
"type": "password",
"required": true
}
]
}
@ -268,6 +294,10 @@ Many more examples can be found in the `examples` directory in the source code.
## <a name="field_types">Field types</a>
Scriptform supports multiple field types. Field types determine what users may
enter in the field, how they are validated and how they are passed to callback
scripts.
### <a name="field_types_string">String</a>
The `string` field type presents the user with a single line input field.
@ -278,6 +308,21 @@ The `string` field type supports the following additional options:
- **`maxlen`**: The maximum allowed length for the field.
- **`size`**: The size (in characters) of the input field.
For example:
...
"fields": [
{
"name": "my_string",
"title": "My string",
"type": "string",
"minlen": 12,
"maxlen": 30,
"size": 30
}
]
...
### <a name="field_types_integer">Integer</a>
The `integer` field type presents the user with an input box in which they may
@ -289,6 +334,20 @@ The `integer` field type supports the following additional options:
- **`min`**: The minimum allowed value for the field.
- **`max`**: The maximum allowed value for the field.
For example:
...
"fields": [
{
"name": "uid",
"title": "UID",
"type": "integer",
"min": 1000,
"max": 2000
}
]
...
### <a name="field_types_float">Float</a>
The `float` field type presents the user with an input box in which they enter
@ -299,9 +358,24 @@ The `float` field type supports the following additional options:
- **`min`**: The minimum allowed value for the field.
- **`max`**: The maximum allowed value for the field.
For example:
...
"fields": [
{
"name": "ammount",
"title": "Ammount",
"type": "float",
"min": 10.0,
"max": 2000.0
}
]
...
Please note that some real numbers cannot be represented exactly by a computer
and validation may thus be approximate. E.g. 0.499999999999999 will pass the
test for a maximum value of 0.5.
and validation may thus be approximate. E.g. 0.500000000001 might pass the
test for a maximum value of 0.5. Whether it does depends on the value given,
the platform, your browser, and many other factors.
### <a name="field_types_date">Date</a>
@ -317,6 +391,20 @@ The `date` field type supports the following additional options:
- **`min`**: The minimum allowed date (format: a string YYYY-MM-DD)
- **`max`**: The maximum allowed date (format: a string YYYY-MM-DD)
For Example:
...
"fields": [
{
"name": "birthdate",
"title": "Birthdate",
"type": "date",
"min": "1900-01-01",
"max": "2015-01-01",
}
]
...
### <a name="field_types_radio">Radio</a>
### <a name="field_types_checkbox">Checkbox</a>
@ -329,6 +417,23 @@ Otherwise, '`off`' is passed. Unlike HTML forms, which send no value to the
server if the checkbox was not checked, Scriptform always sends either 'on' or
'off'.
The `checkbox` field type supports the following additional options:
- **`checked`**: Whether the checkbox should be checked by default (boolean)
For Example:
...
"fields": [
{
"name": "receive_newsletter",
"title": "Do you want to receive our newsletter?",
"type": "checkbox",
"checked": true
}
]
...
### <a name="field_types_select">Select</a>
### <a name="field_types_text">Text</a>

Loading…
Cancel
Save