Multi-line textbox [=] …

A multi-line textbox is a form feature that enables readers to enter text on the webpage. Multi-line textboxes are used in contact or comment forms for example.

Use a single-line textbox, if you do not want your readers to enter multiple lines of text.

How to

[=] at the start of a line creates a multi-line textbox. That is a left square bracket, an equals sign and a right square bracket. You can add a space character and text after the right square bracket to label the textbox. See the second example below.

You can optionally put a placeholder text of your choice between a colon and the right square bracket [=:placeholder]. The placeholder text is displayed whenever the textbox is empty.

An exclamation mark immediately after the right square bracket [=]! makes input obligatory. So the form can not be submitted then as long as the textbox is empty. Use this for required information such as the comment field in a comment form.

You can set a default text for the multi-line textbox: add an arrow [=]-> composed of a hyphen and a greater-than sign followed by the filename of a text file immediately after the right square bracket or exclamation mark. The file’s content will be loaded into the textbox as default.

There can be multiple consecutive textboxes in one block, each placed at the start of a new line. The first textbox can be preceded by a question, task or topic to summarize what the textboxes are for.

Examples

The first example shows a simple multi-line textbox. Browsers usually offer readers a means to resize multi-line textboxes. Try to grab its lower right corner and to move the border …

Take a note!
[=]

The second example demonstrates that multiple textboxes can be combined in one block. In this case a multi-line textbox and a single-line textbox are used together and both are marked as required. The multi-line textbox also links to a file that contains a default text as input suggestion.

[=]!->/stuff/excuse.txt your excuse
[_]! your name

Note that the textbox mark [=] for the multi-line textbox and [_] for the single-line textbox always come before their label in Aneamal. Yet the labels are displayed above their textboxes on the webpage in this example. The placement of labels on the webpage is a design choice that is independent of the order in Aneamal. It can be configured in a stylesheet.

For developers

When Aneamal is translated to HTML, a block that contains multi-line textboxes is turned into an HTML fieldset element. Inside there will be a textarea element wrapped in an HTML span element for each mutli-line textbox. A question, task or topic above the first textbox is wrapped in an HTML legend element. The first example becomes:

<fieldset>
<legend>Take a note!</legend>
<span><textarea id='_1' name='_1' form='_f1'></textarea></span>
</fieldset>

The textarea element is directly followed by a label element inside the wrapping span element, if the textbox is labeled. Multiple textboxes are separated by br elements. If a multi-line textbox is marked as required, its corresponding textarea gets a required attribute. It would get a placeholder attribute, if it had a placeholder. Default text for a multi-line textbox is added between the HTML textarea tags. So the second example becomes:

<fieldset>
<span><textarea id='_2' name='_1' form='_f2' required>I did not do my homework because …</textarea> <label for='_2'>your excuse</label></span><br>
<span><input id='_3' name='_2' form='_f2' type='text' required> <label for='_3'>your name</label></span>
</fieldset>

CSS can be used to style textboxes and their surrounding. The following stylesheet causes the labels to be displayed above instead of after the textboxes and also stretches the textboxes horizontally to fill the available space.

fieldset > span {
	display: flex;
	flex-direction: column-reverse;
}
fieldset > span + br {
	display: none;
}

In the form API

When a form is submitted, the Aneamal Translator supplies modules that use the form API with posted data. There is a PHP array in the $_['post'] array for each block with textboxes or other form fields.

The array for a textbox block always has an index block. It can also have an index topic that contains the optional question, task or topic from before the first textbox. The value for block is an array where each item, itself an array, corresponds to one textbox that contained text when the form was posted. Each textbox array has an index input whose value is the posted content of the textbox and optionally an index label. The value for label is the label of the textbox or, if the textbox does not have a label but a placeholder, its placeholder.

The data provided to modules for the first example could look like this:

$_['post'] => [
    [
        'topic' => 'Take a note!',
        'block' => [
            [
                'input' => 'Do not forget Kevin at home!',
            ],
        ],
    ],
];

The posted data provided to modules that use the form API could look like this in the second example:

$_['post'] => [
    [
        'block' => [
            [
                'input' => 'I did not do my homework because my dog already did.',
                'label' => 'your excuse',
            ],
            [
                'input' => 'Charlie',
                'label' => 'your name',
            ],
        ],
    ],
];