This guide starts with general usage instructions, followed by form-wide
options available in the blueprint. In the middle part you learn about
options specific to dynamic and static forms. Towards the end you find the
sections that document how to use the two currently existing question/answer
types(text and select).
Here is an overview of Zeroform's general usage flow:
Specify your form inside a plaintext file with the extension .whisp (the blueprint), for instance: example_form.whisp
Once you have defined your form (see the rest of this guide as reference), you call zeroform with the blueprint path, for instance:
zeroform example_form.whisp
By default, zeroform generates your form (= the resulting, deployable files) inside a hidden directory adjacent to the blueprint file.
For instance, if your blueprint is at ~/my_forms/example_form.whisp, the output will be at ~/my_forms/.zeroform_build/.
This can be overridden with the option --build-dir, but please be extra
careful where you point it, as this directory gets WIPED on each build:
zeroform example_form.whisp --build-dir [DANGER_THIS_PATH_WILL_BE_WIPED]
Upload your form to your webspace (or open it locally) - it is instantly usable
If you want to test a dynamic form build locally you don't need an entire production ready server setup. Instead you can install the PHP command line interface and use its built-in server to quickly test your form, for instance:
php -S localhost:8080 -t ~/my_forms/.zeroform_build/
With title you set the form title, for instance:
title My demo form
With intro you set an intro text that comes after the title, for instance:
intro This is a form for demonstration purposes
You can also use a multiline syntax for the intro field, for instance:
intro This is a form for demonstration purposes and its intro spans multiple lines This second paragraph shows the posssibility of paragraphs. intro
If you want to add a small visual accent to your form you can set an icon.
The icon is shown on the form page, just left to the title. Use a square
image that is optimized for the small display size - the icon is only shown
about as tall as the form heading next to it.
icon my-icon.png
The icon supports jpg/jpeg, png, webp and svg files.
Zeroform builds static forms by default. With build dynamic you enable
dynamic functionality (which is PHP-based).
build dynamic
With build static you can explicitly specify static mode (but again, this is
the default anyhow).
Use the password option to set a password for the admin interface, for
instance:
password 12!str908.ELPMAXE
The admin interface lives in a php file adjacent to your form - admin.php - so if your form is online at example.com/form/, the admin interface is available at example.com/form/admin.php.
If you don't set a password, no admin interface is rendered (submissions are
stored nontheless - inside the form-adjacent files questions.php and submissions.php,
which are created at runtime).
If you're facing spam problems, the captcha, captcha.code and
captcha.prompt options can be used to set one or multiple
(hard-coded) access codes to the form, for instance:
captcha code captcha.prompt Please enter one of the two captcha codes I shared alongside the link to the form. captcha.code unlock-code-1 captcha.code unlock-code-2
With captcha code you declare code mode (in the future I want to add
pattern-based captchas as well). The captcha.prompt option allows
customizing the message displayed above the captcha code input field - if not
provided a generic default text is used. With each captcha.code option you
set a permitted code - you can use as many as you like.
An entered captcha code is also saved alongside its form submission so you can for example use this to track the origin of submissions by handing out different captcha codes in different places, or to different people.
The confirmation.heading and confirmation.text options allow you to customize
the screen that is shown when a user successfully submits a form, for instance:
confirmation.heading Thank you for your submission! confirmation.text I will promptly get in touch with you.
The confirmation page only exists for dynamic forms - in a static form build the submission takes place elsewhere (whereever you ask for).
In a static form you merely inform people how/where to submit their answers - for
instance via email or direct message - as they cannot do it right on the form
page. For this you can use the submission.text option to provide your custom
instructions (otherwise a generic text is displayed as a fallback). In tandem
with this you can use the submission.format option to set the format(s) in which
the answers should be submitted:
submission.format pasted presents a button for copying the answers to the clipboardsubmission.format text presents a button for exporting the answers to a .txt filesubmission.format csv presents a button for exporting the answers to a .csv filesubmission.format json presents a button for exporting the answers to a .json fileIf you don't specify anything, the pasted and text options are enabled.
Usually you will want to specify only a single option, e.g. pasted if you
want people to send the text straight in a message, or text if you want
people to attach their answers in emails, or csv or json if you plan on
machine-evaluating the results.
To give a practical example using both options:
submission.text Please either download your answers as a textfile and attach them in an email to ALICE AT EXAMPLE DOT ORG or copy the answers to your clipboard and send them to me in a private message on BarFooChat. submission.text submission.format text submission.format pasted
This documents the types of questions you can ask in your form. Currently, text and select fields are available. More will likely be added in the future.
This will be demonstrated entirely by example. For instance, to specify a required single choice select:
select single select.required yes select.title Sanity check select.prompt How surreal is this question? select.option Yes select.option No
Or, to specify an optional multiselect where, when answered, at least 2 options must be selected:
select multiple select.min 2 select.title Food choice select.prompt Pick your favorites select.option Banana select.option Apple select.option Cherry select.option Peach
Take extra note here that setting min ("minimum selections") does not
imply that this question must be answered, it merely says that if an answer
is given, at least two selections must be made. A required
select field thus always requires the select.required yes option.
Lastly, to specify an optional multiselect with three maximum choices, where two choices are already preselected when the form is opened:
select multiple select.max 3 select.title Transportation preference select.prompt Which modes of transporation shall be considered? select.selected_option Skateboard select.selected_option Train select.option Bicycle select.option Tricycle select.option Unicycle
This too shall be demonstrated entirely by example. For instance, to specify a required single line text input with 42 characters maximum that asks for a name:
text line text.required yes text.title Name text.prompt Please enter your name: text.max 42
Or, to specify an optional multiline text input that, when filled out, demands at least 100 characters:
text block text.title License preference text.prompt What is your favorite software license and why? text.min 100
Take extra note here that setting min ("minimum characters") does not
imply that the field is required, it merely says that if the field is
filled out, it must provide that minimum amount of characters. A required
text field thus always requires the text.required yes option.
Lastly, to specify a multiline text input that is visually sized (on the rendered form page) to look like it expects 300 characters (the length that you visually "nudge" people towards through the input's appearance), but will accept anywhere between 50 and 700 characters:
text block text.title A random question text.prompt Tell me about your life! text.min 50 text.max 700 text.nudge_length 300
If anything is unclear or does not work as advertised you are warmly invited to open an issue about it in the issue tracker - reporting these things greatly helps to turn this project into a usable asset for everyone and is thus a very valuable contribution - thank you in advance already.