From f8e96de85a8e69e799659984e61429646e23320a Mon Sep 17 00:00:00 2001 From: Ferry Boender Date: Thu, 9 Jul 2015 09:30:59 +0200 Subject: [PATCH] Documentation updates. --- doc/MANUAL.md | 117 +++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 111 insertions(+), 6 deletions(-) diff --git a/doc/MANUAL.md b/doc/MANUAL.md index a7e9a2c..e1ab175 100644 --- a/doc/MANUAL.md +++ b/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) -## Terminology +## Introduction + +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. + +### Terminology 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 + ### Daemon If you do not specify the `-f` option, Scriptform will go into the background: @@ -109,6 +126,12 @@ Finally, start it: ### Behind Apache +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. ## Field types +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. + ### String 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 + } + ] + ... + ### Integer 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 + } + ] + ... + ### Float 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. ### Date @@ -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", + } + ] + ... + ### Radio ### Checkbox @@ -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 + } + ] + ... + ### Select ### Text