Access all of Typerocket. Get Pro.
( v5 )
Field class is used to create custom fields. A
Field can be anything you want, from a field for a person's "First Name" to a matrix of information. You can decide what you want your fields to be.
Instancing a Field
Fields are most commonly instanced or created through a
Form object. For example, when you use the
// Form instance as $form $form = tr_form(); // Text Field as $textField $textField = $form->text('First Name'); // Image Field as $imageField $imageField = $form->image('Photo');
You can instance fields on their own too. When you instance a
Field on your own, you need to connect it to a
Form by passing the
Form object as the last argument.
$form = tr_form(); $textField = new \TypeRocket\Fields\Text('First Name', $form); $imageField = new \TypeRocket\Fields\Image('Photo', $form);
When you use the
Form object to instance a new
$form->text(), this connection is made for you.
Note: You can pass the
Form object into a
Field during construction as any argument position you like.
Each field takes four standard arguments:
string(required) - This will be the name of the field.
array- This will be the HTML attributes applied to the field.
array- This will be custom settings that can vary between fields.
boolean- This is not the label text. Set
falseto disable the label.
Each field also accepts a
Form object as the last parameter no matter how many other arguments here are.
$attributes = [ 'class' => 'last-name-field' ]; $settings = [ 'help' => 'Enter your first name only' ]; $useLabel = true; $form = tr_form(); $fieldFirst = new \TypeRocket\Fields\Text( 'First Name', $attributes, $settings, $useLabel, $form ); $fieldLast = new \TypeRocket\Fields\Text( 'Last Name', $form );
To set the field's name after it has been instanced, use
$field->setName( 'Last Name' );
To get the name use
$name = $field->getName();
When setting a field's name, the label will be set to the exact text provided. However, the HTML name attribute will be converted to lowercase and all sequences of none-alphanumeric values converted to
_. For example,
'Last Name' becomes the HTML name attribute of
tr[last_name]. This is also true when using field and form groups.
Note: Field and From groups are independent.
There are times when you want to have fields grouped together when being saved. A great case for this is when you are saving data to
wp_options using the
setGroup() to group fields together. If you are using grouping with a
Form you might want to merge the
Form group with the
Field group; to nest
Field group with the
$formGroup = $form->getGroup(); $fieldFirst = new \TypeRocket\Fields\Text( 'First', $form ); $fieldLast = new \TypeRocket\Fields\Text( 'Last', $form ); $fieldLast->setGroup( $formGroup . '.name' ); $fieldLast->setGroup( $formGroup . '.name' );
Getting the group
You can also get the current group being used with the method
$group = $field->getGroup();
$form = tr_form(); $form->text('First Name')->extend('my_group'); // name will be `my_group.first_name`
$form->text('my_group.First Name'); // name will be `my_group.first_name`
Apply to all fields in the form.
$form = tr_form()->setGroup('my_group'); $form->text('First Name'); // name will be `my_group.first_name` $form->text('Last Name'); // name will be `my_group.last_name` $form->text('Last Name')->setGroup('calling'); // name will be `my_group.calling.last_name`
Field is connected to a
Field will populate with the data from the forms
Model. You can keep a field from being populated by using the method
You can also get the population settings.
$populate = $field->getPopulate();
Models save fields as either "meta" or "builtin". If a field's name corresponds to a Model's builtin field they will be saved to main resource table columns in the database.
To help you identify what fields are builtin, debug mode adds a table icon to the field's label.
Example: Posts builtin fields
For example, the primary resource
table for posts is called
wp_posts. The builtin fields for the posts resource correspond to the
A few of these are
When a field's name matches a column, it is saved to the column.
Take a look at a few ways of setting a field to
$field = new \TypeRocket\Fields\Text('Post Content', $form); $field->setName('Post Content');
Attributes are the HTML attributes set to the
Field when it is converted to a string. Attributes are not always compatible with a
Field, but common fields like
There are seven methods for working with
These methods are:
getAttributes()returns the full array of attributes.
attrReset()takes an array of attributes and replaces the old.
attrExtend()takes an array of attributes and merges the old.
getAttribute()return an attribute by its key.
setAttribute()sets an attribute by a key.
removeAttribute()removes an attribute by its key.
attrClass()appends a string to the class attribute.
attr()sets and gets values.
getNameAttributeString()returns the value for HTML
Basic attribute methods
Take a look at using some of the basic methods.
$args = $field->getAttributes(); $field->attrExtend( [ 'class' => 'names' ] ); $classes = $field->attr( 'class' ); $field->removeAttribute( 'class' ); $field->attr( 'class', $classes );
Note: TypeRocket needs to control the ID attribute so it does not give access to the ID attribute.
Appending a string to the class attribute
Here we use the
attrClass() method to extend the class attribute.
Field name attribute
Field generates a string that from the dot notation. This is most handy when building your own custom fields.
$field->setName('First')->setGroup('group_name'); echo $field->getNameAttributeString(); // outputs... tr[group_name][first]
There are five methods for dealing with
These methods are:
getSettings()returns the full array of settings.
setSettings()takes an array of settings.
getSetting()return an setting by its key.
setSetting()sets an setting by a key.
removeSetting()removes an setting by its key.
maybeSetSetting()set value only if index does not exist.
Take a look at using all the methods.
$args = $field->getSettings(); $args = array_merge( $args, [ 'render' => 'raw' ] ); $field->setSettings( $args ); $render = $field->getSetting( 'render' ); $field->removeSetting( 'render' ); $field->setSetting( 'render', $render );
The setting key
help set to any string of text will add help text to the field with it is connected to a
$field->setHelp('Enter your first name');
You can set the label of a
setLabel(). By default, the
Field name is used as the label. This method lets you set the label manually.
$field = new \TypeRocket\Fields\Text( 'Name', $form ); echo $field->setLabel('First Name');
<div class="control-section typerocket-fields-text"> <div class="control-label"> <span class="label">First Name</span> <div> <div class="control"> <input type="text" name="tr[name]" value=""> </div> </div>
Get the label
You can also get the label with
$label = $field->getLabel();
You can set the label option with the method
setLabelOption(). The label option lets the
Form know if it should include the label or not. Setting the option to
false will disable the label.
$field = new \TypeRocket\Fields\Text( 'Name', $form ); echo $field->setLabelOption(false);
<div class="control-section typerocket-fields-text"> <div class="control"> <input type="text" name="tr[name]" value=""> </div> </div>
Get the label option
You can also get the label option with
$option = $field->getLabelOption();
Getting the value
To get the value of a
Field use the
getValue() method. This method requires that the field is connected to a
Form so that it can access the form's
Model. If populate is set to
false on the
Field or the
Form no value will be returned.
$value = $field->getValue();
It is best not to make fields required using HTML5 when a form is long or complex. In almost all cases, the backend should be used for validation.
To visually mark fields as required, TypeRocket provides a
markLabelRequired() method that will mark a field's label with an asterisk:
To make a field required with HTML5 use the
Set Display Capability
setDisplayCapability() method you can disable the output of a field based on the current user's WordPress capabilities. When disabling the output of a field ensure the model saving using the submitted field accounts for instances when that field is missing.
echo $form->text("Editor's Field")->setDisplayCapability("editor");
Found a typo? Something is wrong in this documentation? Fork and edit it!