Home

Former

Anatomy of Former

• Former
  • Field
    • Hidden
    • Input
    • Select
    • Textarea
    • Uneditable
  • Checkable
    • Checkbox
    • Radio
  • Config
  • ControlGroup
  • Form
  • Framework
  • Helpers

Description of each method

Former\Former

This class is the main class - it is your interface for everything in Former. Now of course, Former makes you interact with its subclasses which means you can not only use its methods but the methods of each class used by Former.

Options

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

Former::config('translate_from', [string]) ('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::config('required_class', [string]) ('required')

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

Former::config('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::config('fetch_errors', [boolean]) (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::config('automatic_label', [boolean]) (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::config('live_validation', [boolean]) (true)

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

Former::config('push_checkboxes', [boolean]) (true)

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

Helpers

Former::populate([array|Eloquent])

Populates the fields with an array of values or an Eloquent object.

Former::withErrors([Validator])

If you have an $errors variable from a failed validation, Former will automatically fetch it from Session and set the corresponding fields as incorrect and display the error message right next to them. This is if you're calling withErrors in your view. If you're in the controller, you can simply pass the $validator object to Former and it will work just the same.

Former::withRules([array])

Let you pass an array of Laravel rules to Former, to let it try and apply those rules live with HTML attributes such as pattern, maxlength, etc.

Former::framework([bootstrap|zurb|null])

Select which CSS framework Former should use for its syntax – each gives you more or less access to the available methods. Per example you can't use Bootstrap's ->blockHelp method while using Zurb, etc.

$error = Former::getErrors([string])

Equivalent to $error = isset($errors) ? $errors->first('field') : null.

Form builders

Former::legend([string])

Opens a Bootstrap <legend> tag in your form – the string passed to Former can be a translation index since Former will attempt to translate it.

Former::open()

The open method mirrors Laravel's, which means you can refer to the doc for it on Laravel's website. But it also support the magic methods introduced by Bootstrapper for backward compatibility :

Former::horizontal_open()
Former::secure_open()
Former::open_for_files()
Former::secure_vertical_open_for_files()

You can mix it up however you want as long as each block remain intact (ie. you can't do secure_files_open_for_vertical because that makes no fucking sense).

Former::close()

Pretty straightforward, simply prints out a </form> tag. No argument or nothing.

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

// Buttons class from Bootstrapper
Former::actions( Buttons::submit('Submit'), Buttons::reset('Reset') )

Field builders

And the one class you'll be using the two thirds of the time :

Former::[classes]_[field]

This method analyze whatever unknown method you're trying to call and creates a field with it. It decomposes it as [classes]_[field] or [field]. As classes you can call all Bootstrap classes working on fields : span1 to span12 and mini to xxlarge.

Former\Field

This class is what you actually get when you create a field, which means the method listed underneath are only accessible as chained methods after a field was created. To put it simply :

// Here you're using Former
Former::populate($project)

// Here you're actually using the Field class wrapped in Former
Former::text('foo')

A Former class stops being a field the second that field is printed out. Which means that you can do this :

$textField = Former::text('foo');
$textField->class('myclass')

But can't do this :

echo Former::text('foo')
Former::class('myclass')

Because fields are like little birds and once they fly away you can't get take care of them anymore.

Interactions with the attributes

Former::text('foo')->addClass([string])

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.

Former::text('foo')->forceValue([string])

Sets the field value to something. This will be overwritten by POST data, but will overwrite calls to Former::populate.

Former::text('foo')->value([string])

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

Former::text('foo')->[attribute]([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([string], [string])

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([associative array])

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(array( '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 in order to stay DRY.

Former::text('foo')->label([string])

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.

Helpers

$textField = Former::text('foo')->require()
$textField = $textField->isRequired() // Returns "true"

Checks if a field has been set to required, be it by yourself or when transposing Laravel rules.

Former\Checkable

Checkable is a subset of Field, which means all methods available with Field are available with Checkable. The latter just offers a few more methods related to radios and checkboxes.

Former::radios('foo')->inline()
Former::checkboxes('foo')->stacked()

Set the current radios and checkboxes as inline, or stacked (vertical)

Former::checkbox('foo')->text('bar')

If you're printing only a single checkbox/radio, it's easier to use this method to set the text that will be appended to it.

Former::checkbox('foo')->check()
Former::radio('foo')->check()

Former::checkboxes('foo')->checkboxes('foo', 'bar')->check('foo_0')

Former::radios('foo')->checkboxes('foo', 'bar')->check(0)

The check method allows you to check a one-off checkable element, or to check one in a group of checkable elements. Now for single elements you just call check() without arguments – but when you're using a group you need to specify which element is going to be checked. This is done differently if you're creating radios or checkboxes. Why ? Because checkboxes can only be differentiated by their field name, while radio elements can only be differentiated by their value. So that's it, for checkboxes you specify the name of the one you want to see checked, and for radios you specify its value.

Former\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([string])
Former::text('foo')->blockHelp([string])

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([string, ...])
Former::text('foo')->prepend([string, ...])

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('@', '$')

Former\Fields\Input

All classes related to Input-type fields.

Former::text('foo')->useDatalist([array])

Former::text('foo')->useDatalist([Query], [string], [string (id)])

Creates a <datalist> tag and links it to the field in order to create a select/text mix.

Former\Fields\Select

All classes related to Select-type fields (select, multiselect, etc)

Former::select('foo')->options([array], [selected])

Populates a <select> field with an array of options, where key will be the option's value and value will be its text. It sounds retarted explained like that but it means the following :

Former::select('clients')->options(array(
    1  => 'Max',
    3  => 'Clémence',
    12 => 'Jean Valjean'
));

<select name="foo">
    <option value="1">Max</option>
    <option value="3">Clémence</option>
    <option value="12">Jean Valjean</option>
</select>

Which looks really natural : you select a client's name and get it's ID in return. The second parameters allows to preselect one option, per example if in the above example we'd done ->options($clients, 3) then Clémence would have been selected.

Former::select('foo')->select(3)

Alias for ->value(), selects an option.

Former::select('foo')->fromQuery([array], [string], [string (id)])

Populates a <select> field with the results of a Fluent/Eloquent query. Second argument is the attribute used by Former for the options text, third argument is the attribute used by Former for the options value (defaults to the id attribute). Second argument defaults to the model's __toString() method, thirds defaults to the model's get_key() method.

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

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