Form Builder Usage

Overriding default element types

The form builder will only, by default create text inputs and textareas. Textareas will be returned if the column is defined as a text, smalltext, longtext, etc. Any other column type returns a simple text input. You can override this by setting a new map array.

<?php
// The default column map looks like this
/*
$map = [
    'text'=>'textarea',
    'tinytext'=>'textarea',
    'mediumtext'=>'textarea',
    'longtext'=>'textarea',
];
*/

$myMap = [
    'enum'=>'select'
]

$builder->setMap($myMap);
// Now, the form will use a select type for any ``ENUM`` columns. Note that this is
// database-specific

Setting Column Options

You can get even more control over input types by setting the columnOptions array. This defines column options by column name.

<?php
$builder = $form->getBuilder();

$columnOptions = [
    'title'=>[
        'type'=>'textarea'
    ]
];

$builder->setColumnOptions($columnOptions);

You can also specify that any data passed to the builder to populate the element should not be escaped. Be default, all values on form elements are escaped.

<?php
$builder = $form->getBuilder();

$columnOptions = [
    'title'=>[
        'type'=>'textarea',
        'raw'=>true
    ]
];

$builder->setColumnOptions($columnOptions);

Finally, you can also specify a callback to further modify the elements.

<?php
$builder = $form->getBuilder();

$columnOptions = [
    'title'=>[
        'type'=>'textarea'
        'callback'=>function ($element) {
            $element->class('my-css')->data('foo', 'bar')->placeholder('Lorem ipsum');
        }
    ]
];

$builder->setColumnOptions($columnOptions);

After the builder creates the element and applies defaults, such as required, maxlength, etc., it will run the callback and apply the customizations.

Default Element Classes

If you want to specify a CSS class to be applied to every element of a particular type, you can use the setDefaultClasses() method.

<?php
$builder = $form->getBuilder();

$defaultClasses = [
    'textarea'=>'form-control',
    'text'=>'form-control'
];

$builder->setDefaultClasses($defaultClasses);

Textarea Cols and Rows

The default textarea cols is 10 and rows is 5. If you want to override that, use the setTextareaCols($cols) and setTextareaRows($rows) methods respectively.

<?php
$builder->setTextareaCols(20);
$builder->setTextareaRows(8);

Blacklisting Columns

If necessary, you can blacklist any column name if you don’t want a form element created for it.

<?php
$blacklist = [
    'id',
    'created'
];

$builder->setBlackList($blacklist);

Form Labels

Every element will automatically get a label created for it. By default, the label text will be the column name turned into upper case words. Each label is identified and retrieved by prefixing label_ to the column name. You can choose to use the labels or not. You can also modify the labels as you retrieve them.

<?php
echo $form->getElement('label_title');
echo $form->getElement('title');

Or, modify the label’s text and wrap it around an element.

<?php
echo $form->getElement('label_title')->text('Your title')->wrap($form->getElement('title'));

Assumptions

The form builder will make some assumptions based on the database table column definitions.

• Any column defined as NOT NULL will have a required attribute.

• CHAR and VARCHAR columns with a size will have a maxlength attribute to match.

• If you specify a column as password, you can not set it’s value via the callback.

• Columns that are autoinc will be hidden by default.

• Buttons and Submits will use the column name in upper case words as the default text. You can override this using the text() method on the element.

• Any column with a default value will have that value set initially. If you pass data as a third argument to the builder, that value will be overridden. Checkboxes and radios are a special case.

• Checkboxes and radios do not get maxlength or required attributes.

Note

Checkboxes and Radio types will use a database-defined default as their value. When passing an array of data as values to the builder, values for checkboxes and radios will be used to set the checked attribute and not the value.

Miscellaneous

You can pass a customized Aura.SqlSchema object if you want to override the one that is created by default. This aims to prevent dependency injection issues.

<?php
// sqlschem must implement Aura\SqlSchema\SchemaInterface.
$builder->setSchema($sqlschema);

Reset the builder

You can reset the builder back to default settings using the reset() method. This sets the map, columnOptions, defaultClasses, textareaRows, and textareaCols back to initial values.