Usage and Examples

vlakoff edited this page Jul 8, 2017 · 13 revisions

Former element types

Open

    <?=
        Former::open([
           'url' => 'foo/bar',
           'method' => 'put',
           'route' => 'route.name',
           'action' => 'Controller@method',
           'files' => true,
        ])
    ?>

Open also support some magic methods:

    <?= Former::horizontal_open() ?>         # class="form-horizontal"
    <?= Former::open_for_files() ?>          # enctype="multipart/form-data"
    <?= Former::vertical_open_for_files() ?> # combines both

You can mix it up however you want as long as each block remain intact (ie. you can't do files_open_for_vertical because that makes no sense). Former will also output the CSRF token automatically with the open tag.

Close

    <?= Former::close() ?> # Prints out a `</form>` tag.

Standard elements

Note that the first argument specifies the name attribute. If no label is given, Former will use ucfirst($name) to generate a label.

    <?= Former::open() ?>
    <?= Former::hidden('foo')->value(1) ?>
    <?= Former::text('foo')->label('My field') ?>
    <?= Former::textarea('foo')->value('My value') ?>
    <?= Former::select('foo')->options(['value1' => 'Label 1', ...])->select('value1') ?>
    <?= Former::multiselect('foo[]')->options(['value1' => 'Name 1', ...]) ?>
    <?= Former::checkbox('foo')->check() ?>
    <?= Former::radio('foo')->check() ?>
    <?= Former::close() ?>

Grouped checkboxes and radios

Grouped checkboxes and radios allow you to specify multiple elements in a single element definition:

    # Short format of $label => $name
    <?= Former::checkboxes('foo[]')
        ->checkboxes(['A' => 'foo[1]', 'B' => 'foo[2]'])
        ->check('foo[1]') ?> # Check grouped checkboxes by their name attribute
    <?= Former::radios('foo[]')
        ->radios(['A' => 'foo[1]', 'B' => 'foo[2]'])
        ->check(0) ?> # Check grouped radios by their value attribute

    # Long format
    <?= Former::checkboxes('foo[]')
        ->checkboxes([
            'A' => ['name' => 'foo[1]', 'value' => 1],
            'B' => ['name' => 'foo[2]', 'value' => 1]
        ])
        ->check('foo[1]') ?> # Check grouped checkboxes by their name attribute
    <?= Former::radios('foo[]')
        ->radios([
            'A' => ['name' => 'foo[1]', 'value' => 0],
            'B' => ['name' => 'foo[2]', 'value' => 1]
        ])
        ->check(0) ?> # Check grouped radios by their value attribute

Note that when using ->check(), for checkboxes you specify the name of the one you want to see checked, and for radios you specify the value.

Actions / Buttons

    <?= Former::actions([string, ...]) ?>

Creates a <div class='form-actions'> tag to wrap your submit/reset/back/etc buttons. To output multiple buttons simply use multiple arguments

    // Button class from Bootstrapper
    <?= Former::actions( Button::submit('Submit'), Button::reset('Reset') ) ?>

Common utilities for all elements

Label

    <?= Former::text('foo')->label('My label') ?>

Sets the label of a field to a string. If you're using Bootstrap this has a specific meaning since the label that will be created will automatically have the class control-label.

Bootstrap classes

On any form element, you can add Bootstrap classes such as small/large/span1/span6/etc:

    <?= Former::small_text('foo') ?>
    <?= Former::span1_large_select('bar') ?>

You can use all Bootstrap classes from span1 to span12 and mini to xxlarge.

Add class

    <?= Former::text('foo')->addClass('my_class') ?>

Adds a class to the current field without overwriting any existing one. This differs front ->class() will — just like any attribute setter — overwrite any existing value.

To add a class or other attribute on the Bootstrap form-group containing div, use the onGroup prefix:

    <?= Former::text('foo')->onGroupAddClass('my_class') ?>
    <?= Former::text('foo')->onGroupDataFoo('my_data') ?>

Force value

    <?= Former::text('foo')->forceValue('my_value') ?>

Forces the field value to a particular value, ignoring both POST data and Former::populate() values.

Value

    <?= Former::text('foo')->value('my_value') ?>

Sets a default value for a field — a text present in it but that will get overwritten by calls to Former::populate, POST data, or ->forceValue data.

Select placeholders

    <?= Former::select('foo')->placeholder('Select one option...') ?>

Create a ghost option set as disabled by default to serve as placeholder for the select.

Arbitrary attributes

    <?= Former::text('foo')->foo([value]) ?>
    <?= Former::text('foo')->data_foo([value]) ?>

Sets the value of any attribute. Attributes containing dashes have to be replaced with an underscore, so that you'd call data_foo('bar') to set data-foo="bar".

    <?= Former::text('text')->setAttribute('my_attribute', 'my value') ?>

Can be used as a fallback to magic methods if you really have to set an attribute that contains an underscore.

    <?= Former::text('foo')->setAttributes(['my_attribute' => 'my value', ...]) ?>

Allows you to mass-set a couple of attributes with an array. So the following examples do the exact same thing.

    <?= Former::text('foo')->class('foo')->foo('bar') ?>
    <?= Former::text('foo')->setAttributes(['class' => 'foo', 'foo' => 'bar']) ?>

The second way is not the cleanest per say but is still useful if you have to set the same attributes for a group of fields, you can then just create an array with the attributes you want and assign it to each field.

ControlGroup

Helpers and methods related to Bootstrap's control groups. If you set the $useBootstrap option to false earlier, this class is not accessible, nor are any of its methods.

    <?= Former::text('foo')->state([error|warning|info|success]) ?>

Set the state of a control group to a particular Bootstrap class.

    <?= Former::text('foo')->inlineHelp('bar') ?>
    <?= Former::text('foo')->blockHelp('bar') ?>

Adds an inline/block help text to the current field. Both can be called (meaning you can have both an inline and a block text) but can only be called once (which means if you call inlineHelp twice the latter will overwrite whatever you typed in the first one).

    <?= Former::text('foo')->append('bar') ?>
    <?= Former::text('foo')->prepend('bar') ?>

Prepends one or more icons/text/buttons to the current field. Those functions use func_get_args() so you can per example do that:

    <?= Former::text('foo')->prepend('@', '$') ?>

Add group class

    <?= Former::text('foo')->addGroupClass('bar') ?>

Adds specified class attributes to the parent control-group.

Options

This is a set of options that can be set to modify Former's behavior.

    Former::setOption('translate_from', 'validation.attributes') ('validation.attributes')

By default Former tries to translate most labels, legends and help texts. For that it first tries to translate the string passed as is, and then it tries to look in a special place that can be defined with this variable - defaulting to 'validation.attributes.mykey'.

    Former::setOption('required_class', 'required') ('required')

A class to add to fields that are set as required.

    Former::setOption('default_form_type', [horizontal|vertical|inline|search]) ('horizontal')

By default when you call Former::open a fallback form type gets assigned to the form – this is the option that says which one is that type. It can be any of those values, or null if you want don't want to use Bootstrap's form classes.

    Former::setOption('fetch_errors', true) (true)

Whenever you call the open method, if this option is set to true, Former will look into the Session array for a Message objects that would have been created by the ->with_errors() method of Redirect. Which means that if on failed validation you do Redirect::to()->with_errors(), Former will automatically fetch said errors and display them on the corresponding fields without having to type anything.

    Former::setOption('automatic_label', true) (true)

Allows the user to turn on or off the automatic labeling feature. When it's on, if you give per example foo as a field name and no label, Former will assume foo is also to be used as label. Former will then attempt to translate it, capitalize it, and use it as label. With this option turned off, if no label is specific, no label tag will be printed out.

    Former::setOption('live_validation', true) (true)

Whether Former should try to apply Laravel's Validator rules as live validation attributes.

    Former::setOption('push_checkboxes', true) (true)

Whether checkboxes should always be present in the POST data, no matter if you checked them or not

    Former::setOption('TwitterBootstrap3.labelWidths', ['large' => 2, 'small' => 3])

Set the Bootstrap label width for your form.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.