Fork me on GitHub

Introduction

formit is an open-source tool converting plain text to HTML form for web writers. Just like the way we use Markdown, formit provides an easy and readable way to write HTML forms.

Thus, formit is 1) a plain text format to write readable form; 2) a conversion tool written in Python converting formit forms to real HTML forms.

Like Markdown, the goal of designing formit is to make form in plain text as readable as possible. Even without any knowledge of the syntax of formit, you can still understand each form fields easily.

Nowadays, Web development has become more and more popular. For beginners, formit can be the bridge connecting the idea of a form in brain with semantic-followed webpage. For those who are proficient on HTML, formit saves the time of composing a Web form with handy packages and extensions.

Syntax

Basic

Label

Labels are text describing the following input(s). In HTML, labels are represented using <label> tag, and in formit, they are represented by a tailing colon (:). We will show the use of labels in all of the following example.

Text

For the most used input type, formit uses a very intuitive format, like this:

Username:   [          ]

There can be zero or more white spaces between : and [. But there must be at least 3 white spaces inside the brackets ([ and ] ). Then it will be interpreted as the following HTML snippet:

<label>Username</label>
<input type="text" name="username">

Also, you may want to add a placeholder for the text input, and that is quite easy in formit. Just write the placeholder text inside the brackets:

Username:   [ No more than 20 characters ]

And you will get:

<label>Username</label>
<input type="text" name="username" placeholder="No more than 20 characters">

Password

A password field is like a text field, only that it hides input with round dots. So we write like this:

 Password:  [ ******** ]

and it will be interpreted as:

<label>Password</label>
<input type="password" name="password">

You need to add at least 3 straight asterisks (*) inside the brackets ([ and ]) to make it a password field. Make sure you only contains continuous *, otherwise it will be interpreted as text field. It doesn’t matter whether or not you add white spaces between * and brackets.

Radio

Let’s do some choices by adding the radio components:

Gender:  (*) Male  ( ) Female

Rendered as:

<label>Gender</label>
<input type="radio" name="gender" checked> Male 
<input type="radio" name="gender"> Female 

We can set the option as selected by adding a * inside the parentheses (( and )), or we can leave a white space inside to indicate a non-selected option. You cannot omit the white space inside!

Checkbox

Similar as radio, we write checkbox which allows multiple choices like this:

Favorite Sports: [x] Soccer [ ] Basketball [ ] Tennis [ ] Swimming

and then interpreted as:

<label>Favorite Sports</label>
<input type="checkbox" name="favorite sports" checked> Soccer 
<input type="checkbox" name="favorite sports"> Basketball 
<input type="checkbox" name="favorite sports"> Tennis 
<input type="checkbox" name="favorite sports"> Swimming

Different from the radio, we use brackets ([ and ]) here to represent a checkbox. Also, x is used to mark the selected ones instead of *.

Select

Another widely-used Web form element is <select>, which is shown as a dropdown list in browsers. In formit, we create a select element like this:

Grade:  | (Select a grade) | Freshman | Sophomore | Junior | Senior |

and interpret it to:

<labelt>Grade</label>
<select>
  <option value="" disabled selected>Select a grade</option>
  <option value="freshman">Freshman</option>
  <option value="sophomore">Sophomore</option>
  <option value="junior">Junior</option>
  <option value="senior">Senior</option>
</select>

We use pipeline symbol (|) as the boundary and separators of options in the select list. For the first item in the list, we will add a selected attribute for it. Also, you can wrap it with a pair of parentheses, meaning it will be interpreted as a placeholder, so it will has empty value and an additional disabled attribute.

Textarea

If we want to have a textarea for multiple lines input, we can write like:

Description:    {               }

and you will get:

<label>Description</label>
<textarea name="description"></textarea>

Same as text input, it also supports placeholder. So write

Note:    {  Tell us more about yourself  }

will be interpreted to:

<label>Note</label>
<textarea name="note" placeholder="Tell us more about yourself"></textarea>

Fieldset

Sometimes we may want to group some of the fields in a form, so we can create a <fieldset> in formit like this:

----Group 1--------------------
Label1: [            ]
Radio1: (*) Option1 ( ) Option2
-------------------------------
--Group 2----------------------
Label2: [            ]
Checkbox1:   [ ] Option1   [ ] Option2
-------------------------------

And this will turn out to the following output in a browser:

<fieldset>
<legend>Group 1</legend>
<p>
<label>Label1</label>
<input type="text" name="label1" >
</p>
<p>
<label>Radio1</label>
<input type="radio" name="radio1" value="option1 " checked> Option1
<input type="radio" name="radio1" value="option2"> Option2
</p>
</fieldset>
<fieldset>
<legend>Group 2</legend>
<p>
<label>Label2</label>
<input type="text" name="label2" >
</p>
<p>
<label>Checkbox1</label>
<input type="checkbox" name="checkbox1" value="option1"> Option1
<input type="checkbox" name="checkbox1" value="option2"> Option2 
</p>
</fieldset>

We use two lines of dashes (-) as the boundaries of a group. For the starting boundary, you need to add a group name in the middle of the line, that is, there must be some dashes after both left and right ends of the group name. There must be more than 3 dashes to form a boundary of fieldset, but the starting line and ending line are not required to have the same length.

Function

Apart from the basic elements of what we need to create a form, formit also provides some handy functions for quickly generate number ranges and preset lists.

Range

Sometimes, we may want to use a range of continuous numbers as the option, for example, if we want to have a select of rank, which has integer options from 0 to 10, we can write like this:

Rank:   |@'0..10'|

We will get:

<label>Rank</label>
<select>
  <option value="0">0</option>
  <option value="1">1</option>
  <option value="2">2</option>
  <option value="3">3</option>
  <option value="4">4</option>
  <option value="5">5</option>
  <option value="6">6</option>
  <option value="7">7</option>
  <option value="8">8</option>
  <option value="9">9</option>
  <option value="10">10</option>
</select>

Here, we use the format @'a..b' as a shorthand to output numbers from a to b, they must both be integers, and a should be smaller than b.

Preset Lists

We also have some preset lists in formit. You can use the format @'list_name' to include them as the options for radio, checkbox or select. Just like this:

Available Day:    [ ] @'day'

Will output:

<label>Available Day</label>
<input type="checkbox" name="available-day" value="sunday"> Sunday
<input type="checkbox" name="available-day" value="monday"> Monday
<input type="checkbox" name="available-day" value="tuesday"> Tuesday
<input type="checkbox" name="available-day" value="wednesday"> Wednesday
<input type="checkbox" name="available-day" value="thursday"> Thursday
<input type="checkbox" name="available-day" value="friday"> Friday
<input type="checkbox" name="available-day" value="saturday"> Saturday 

The complete preset lists can be seen here.

Sorting

formit allows you to sort the options in ascending, descending or random order. To use ascending order, add << after the @( ); to use descending order, add >> after that; to use random order, add >< or <>.

Thus, if we want to output radio options from 5 to 1, we can write:

Star:  ( ) @'1..5'>>

This will rendered as:

<label>Star</label>
<input type="radio" name="star" value="5"> 5 
<input type="radio" name="star" value="4"> 4 
<input type="radio" name="star" value="3"> 3 
<input type="radio" name="star" value="2"> 2 
<input type="radio" name="star" value="1"> 1 

Other

Escape

formit allows you to use backslash escapes to generate literal characters which would otherwise have special meaning in formit’s formatting syntax. For example, if you wanted to add a colon : in the label, you can do like this in formit:

Do you sleep earlier than 11\:00: ( ) Yes  ( ) No  ( ) Maybe

The following is the list of functional characters that are provided escape in formit:

• : -- colon
• [ and ] -- square brackets
• ( and ) -- parentheses
• { and } -- curly braces
• \ -- backslash
• @ -- at
• * -- asterisk

formit uses a lazy escaping strategy, that is, if one line doesn’t match any of the patterns, the functional characters will remain literal in the output. But you can always add a backslash to explicitly escape the following character. Backslash symbols that are not followed by a functional character will be removed during interpreting.

Submit

After creating all these fields introduced above, we need to link the form to a back-end script to process it. In formit, we can use the line:

[Submit]->process_form.php

to add a submit button named submit at the bottom of the form. Then formit will set the action attribute of the form to process_form.php, with POST method.

Feedback

formit is still under development, some syntax may be modified in the future. Please have a try, and tell me your feedback on formit. Also, any suggestions or bug reports are welcomed.

Needless to say, let me create a feedback form like that:

Your email:    [  Or just a nickname    ]
Feedback:    { Comment? Suggestion? Bug report? }
[Send the feedback]->feedback.php

License

formit is free software, available under the terms of MIT License.