form.md

Form

• Opening a form
• Labels
• Text, password, email, number, date, hidden inputs
• Textarea
• Checkbox and radio inputs
• Select field
• Buttons
• Miscellaneous inputs

Opening a form

{!! Form::open() !!}
    // Form inputs
{!! Form::close() !!}

Form::open($action = null, $method = 'POST', $ssl = false, $attributes = [])

• $action: string The action attribute for the opening form tag.
• $method: string The method attribute. Default to 'post'.
• $ssl: boolean Tell the form to change the method protocol to https if using ssl. Default to false.
• $attributes: array Extra attributes and properties for the form.

By default, the form sets the method attribute to POST and its action attribute to the current URL.

The open() method returns the opening form HTML tag and the close() method returns the closing form tag.

When using the Form::open() method, it automatically adds WordPress nonce and http referer hidden fields into your form. The nonce field uses the _themosisnonce nonce and form action to populate its value. Check below on how to check for nonce values when form is submitted.

Define custom nonce values.

You can overwrite the default custom nonce fields used inside the Form::open() method.

In order to add your custom nonce, simply add them to the $attributes argument of the Form::open() method like so:

{!! Form::open('', 'post', false, [
    'nonce'        => 'action',
    'nonce_action' => 'edit-something'
]) !!}
    // Inputs
{!! Form::close() !!}

Make sure to use the nonce key for the nonce field name and the nonce_action key for its value.

Set a custom action attribute

In order to set a custom action attribute, simply fill in the first parameter of the open form method:

// This will output <form action="http://www.my-website.com/register/">
{!! Form::open(home_url('/register/')) !!}
    // Form inputs
{!! Form::close() !!}

Change the form method attribute

Specify the second parameter of the open() method. Only get and post values are accepted.

{!! Form::open('', 'get') !!}
    // Form inputs
{!! Form::close() !!}

Set the first parameter as empty string or null will set the action attribute to the current URL.

Make sure to submit your data to a SSL page

By setting the third parameter of the open() method to true, the action attribute will change its protocol to https.

{!! Form::open('contact', 'post', true) !!}
    // Form inputs
{!! Form::close() !!}

Add custom attributes to the opening form tag

You can pass as the fourth parameter an array in order to add custom attributes.

{!! Form::open(null, 'post', false, [
    'data-message' => 'The form message.',
    'enctype'      => 'multipart/form-data',
    'id'           => 'register-form'
]) !!}
    // Form inputs
{!! Form::close() !!}

Check nonce values when a form is submitted

When you use the Form::open() method, it automatically outputs an opening form tag populated with WordPress nonce values. It is considered "best-practice" to check for those nonce values when your form is submitted before proceeding to some other actions.

If you check your page source code, you'll find two hidden fields:

• The first one is a NONCE value
• The second one is the HTTP REFERER value

As explained in the open() method, it uses the _themosisnonce name and form action.

Let's verify the nonce value regarding those two constants:

// A form is submitted using the POST method.
if (wp_verify_nonce(Input::get('_themosisnonce'), 'form')) {
    // Proceed with data
}

The nonce value is the nonce field name attribute. The action value is the nonce action string. Check wp_verify_nonce() function in the codex.

The example above is working in a front-end example. If you have a custom form on a custom page in the admin, check also the check_admin_referer function in the codex

Note: In the previous example, we use the Input class to grab POST data. Check the validation guide for the Input class use.

Labels

Output a label tag:

// This will output <label>Display text</label>
{!! Form::label('Display text') !!}

Add attributes to a label:

// This will output <label for="my-input" class="super">Display text</label>
{!! Form::label('Display text', [
    'class' => 'super',
    'for'   => 'my-input'
]) !!}

Text, password, email, number, date, hidden inputs

Output a text input:

// This will output <input type="text" name="name">
{!! Form::text('name') !!}

Set the input value:

// <input type="text" name="name" value="Text value"> 
{!! Form::text('name', 'Text value') !!}

Add attributes to the text input:

{!! Form::text('name', 'Default value', [
    'class'       => 'super',
    'placeholder' => 'Insert your name here'
]) !!}

The Form::password(), Form::email(), Form::number(), Form::date() and Form::hidden() methods use the same signature.

Textarea

The Form::textarea() method will output a <textarea></textarea> tag.

{!! Form::textarea('name') !!}

Set the textarea "value" by passing data to the second parameter:

{!! Form::textarea('name', 'Text content') !!}

Add attributes to the textarea tag by passing an array as the third parameter to the method:

{!! Form::textarea('name', 'Text content', ['class' => 'regular-text']) !!}

Checkbox and radio inputs

The Form::checkbox() helps you define one or multiple checkbox inputs.

Output one checkbox:

// This will output <input type="checkbox" name="toggle[]" value="toggle">
{!! Form::checkbox('toggle', 'toggle') !!}

When checking for submitted data, the checkbox method register an array of values even for one checkbox.

Add custom attributes:

{!! Form::checkbox('toggle', 'enabled', [], [
    'class' => 'super'
]) !!}

Multiple checkboxes and radio

In order to specify multiple checkboxes, simply pass an array of choices like so:

{!! Form::checkbox('colors', [
    'red',
    'green',
    'blue'
]) !!}

The first parameter is the common name of your checkboxes. The second parameter is an array of choices/options for your checkbox input.

By default, when you define multiple options/choices for your checkbox, the API is using the value as display text beside the checkbox. In order to define a custom display text for your checkbox options, define an array of key/value pairs like so:

{!! Form::checkbox('colors', [
    'red'   => 'Select red color',
    'green' => 'Choose the green',
    'blue'  => 'Use the blue color'
]) !!}

In order to set values or default values, pass an array as a third parameter to your checkbox method:

{!! Form::checkbox('colors', [
    'red',
    'green',
    'blue'
], [
    'green'
]) !!}

The above example will check the green checkbox by default.

Add attributes to your checkbox by passing an array as the fourth parameter:

{!! Form::checkbox('colors', [
    'red', 
    'green',
    'blue'
], [], [
    'class' => 'super'
]) !!}

This code adds attributes to the checkbox inputs. When you create a checkbox, the displayed text beside each checkbox is rendered within a label tag. You can define the attributes for these label tags by passing a label property to the checkbox attributes like so:

{!! Form::checkbox('colors', ['red', 'green', 'blue'], [], [
    'label'	=> [
        'class' => 'label-class'
    ]
]) !!}

The example above will add the label-class class to each labels inside your checkbox input.

The Form::radio() method uses the same signature as Form::checkbox()

Output a radio input:

{!! Form::radio('gender', [
    'woman',
    'man'
]) !!}

Select field

Generate a select tag with indexed options values:

{!! Form::select('country', [
    [
        'belgium',
        'france',
        'usa'
    ]
]) !!}

This will output the following <select> tag:

<select name="country">
    <option value="0">Belgium</option>
    <option value="1">France</option>
    <option value="2">Usa</option>
</select>

Generate a select tag with custom options values:

{!! Form::select('country', [
    [
        'be' => 'belgium',
        'fr' => 'france',
        'us' => 'usa'
    ]
]) !!}

This will output the following <select> tag:

<select name="country">
    <option value="be">Belgium</option>
    <option value="fr">France</option>
    <option value="us">Usa</option>
</select>

Generate a select tag with grouped options values:

{!! Form::select('country', [
    'Europe' => [
        'belgium',
        'france'
    ],
    'America' => [
        'usa'
    ]
]) !!}

The code above will output <optgroup> tags with indexed options values:

<select name="country">
    <optgroup label="Europe">
        <option value="0">Belgium</option>
        <option value="1">France</option>
    </optgroup>
    <optgroup label="America">
        <option value="2">Usa</option>
    </optgroup>
</select>

Same select tag but with custom options values:

{!! Form::select('country', [
    'Europe' => [
        'be' => 'belgium',
        'fr' => 'france'
	],
    'America' => [
        'us' => 'usa'
    ]
]) !!}

Pass default value(s)

You can pass a default value by filling in the third parameter of the select() method:

{!! Form::select('country', [
    [
        'belgium',
        'france',
        'usa'
    ]
], 0) !!}

This set the default value to indexed value 0 (belgium). For custom options, simply pass the custom value. When using multiple selection, pass in an array as default values.

Add custom attributes

Like other form fields, pass an array as the fourth parameter for custom attributes.

{!! Form::select('countries', [
    [
        'belgium',
        'france',
        'usa'
    ]
], null, [
    'class'    => 'super',
    'multiple' => 'multiple'
]) !!}

Buttons

Generate a button tag:

{!! Form::button('toggle', 'Click me!') !!}

This will output the following html:

<button type="button" name="toggle">Click me!</button>

Generate a submit button:

{!! Form::submit('register', 'Sign up') !!}

This will output the following html:

<button type="submit">Sign up</button>

Add custom attributes by passing an array as a third parameter:

{!! Form::button('toggle', 'Click me!', ['class' => 'super']) !!}
{!! Form::submit('register', 'Sign up', ['id' => 'awesome']) !!}

Miscellaneous inputs

The Form class provides an input() method in order to create any type of input tags.

Form::input($type, $name, $value = null, array $attributes = [])

• $type: string The input type
• $name: string The input name attribute
• $value: mixed A default or registered value
• $attributes: array Extra attributes

Generate a text input:

{!! Form::input('text', 'your-name') !!}

Generate a password input:

{!! Form::input('password', 'your-password') !!}

Generate a color input:

{!! Form::input('color', 'my-color') !!}

Other resources:

Check the validation and input guide for documentation on how to retrieve and sanitize submitted data.

• Validation and input