Access all of Typerocket. Get Pro.
Forms
( v5 )
- # Getting Started
- # Working inside existing HTML forms
- # In summery
- # Creating a Form
- # Data Resource
- # Types of Resources
- # Model Resource
- # Shorthand Resource
- # Auto Resource
- # Data Collection & Arrays
- # Setting the Model
- # Action
- # Record ID
- # Setting the Record ID
- # Open & Close Forms
- # Adding a submit button
- # Changing the open tag defaults
- # Change Form URL
- # Fields
- # Built-In
- # Your Own Custom Fields
- # Form Encapsulation
- # Field Wrapper UI Only
- # Debug Status
- # Populating Fields
- # Groups
- # Getting the group
- # Groups - Dot Syntax
- # Example 1: No dots
- # Example 2: With dots
- # Append to Group
- # Extend Group
- # Text Content
- # Rows & Columns
- # Sections
- # Fieldsets
- # Use Old
- # Use Errors
- # How It Works
- # Arguments
- # Use AJAX
- # Use TypeRocket REST API
- # Require Confirmation
- # Translation
- # Clone
- # Macros
- # Allow File Uploads
- # Attributes
- # Basic attribute methods
- # Appending a string to the class attribute
Getting Started
It is IMPORTANT to keep in mind. You are creating an HTML form when using TypeRocket to create a form. All of the basic rules of HTML <form>
creation still apply when using TypeRocket. In many cases, you might not need TypeRocket to generate an open or close <form></form>
tags because the page already has form tags.
For example, when adding custom form fields to a post type edit page, you do not need to generate open and close tags for the form because those already exist in the document of that specific admin page.
Now, to get started creating custom forms and fields with TypeRocket, you need to create a Form
instance using tr_form()
and connect a data resource if you want to populate the form fields with information.
You can create a simple form that does not import information from a data source as follows:
// Bind no data to form
$form = tr_form([]);
echo $form->open(); // open <form> tag
echo $form->text('Post Title');
echo $form->editor('Post Content');
echo $form->close('Save'); // close </form> tag
Inversely, you can import data from a data source like so:
// Bind first blog post data to form
$form = tr_form('post', 1);
echo $form->open(); // open <form> tag
echo $form->text('Post Title');
echo $form->editor('Post Content');
echo $form->close('Save'); // close </form> tag
When TypeRocket generates your opening tag (you should not always echo opening and closing <form>
tags as mentioned before), it takes care of WordPress nonce creation for you. So, the output of the above example all the HTML you need to get things working.
Here is an abbreviated version of what you can expect if no data was passed into the Form
instance:
<form action="/my-url">
<input type="hidden" name="_method">
<input type="hidden" name="_tr_nonce_form" value="bca143cc000">
<input type="text" name="tr[post_title]">
<textarea type="text" name="tr[post_content]"></textarea>
</form>
Working inside existing HTML forms
In the case of a custom post type, the HTML <form>
is already created for you on the post edit page. All you want to do is add fields. You do not need to create a <form>
; nor should you. You cannot have a <form>
inside a <form>
.
Take a scenario where you want to add fields to a custom post type through setTitleForm()
method. Take a look at an example From
inside a custom post type, "book":
tr_post_type('Book')->setTitleForm(function(){
$form = tr_form();
echo $form->text('Author');
});
As you can see, when you are on the post edit page, you do need to use the methods open()
or close()
.
In summery
Now that you know the basics of making custom forms and fields with TypeRocket, we can begin to break down in greater detail how each part works. Then you can begin to make your powerful custom forms anywhere in WordPress.
A great place to start is understanding the tr_form()
function. Let us take a look at that now.
Creating a Form
To create a form or custom field, you need to instantiate a new Form
object. tr_form()
is used to create a Form
instance.
// Form instance
$form = tr_form($resource, $action, $id, $model_override);
// Field instance
$textField = $form->text('First Name');
This Form
object powers the creation of custom fields and the injection of field data from any resource: posts, comments, users, external APIs, you name it.
The tr_form()
method takes up to 4 arguments:
-
Data Resource -
Model
,shorthand
,auto
,DataCollection
, orarray
. The source of data to populate custom fields. -
Action -
string
values of:update
,delete
, orcreate
. The type of request to make when submitting the<form>
. For example,update
send a PUT request. -
Record ID -
int
value for the records ID. The record to look up in the database by ID. It only applies when using aModel
for the data resource. -
Model Override (optional) - This value overrides the
Model
used by ashorthand
orauto
resource.
Data Resource
Defining a data resource tells a Form
how to bind data to the Form
so that your custom fields display the correct information.
For example, do you want field data from a post, comment, user, or something else? The Form
"data resource" controls the flow of information to fields.
To get any data into your custom fields a Form
must have a data resource.
Types of Resources
There are a few ways to bind a data resource to a Form
instance:
-
Model - An instance of a
Model
or theModels
class name as a string. -
Shorthand - A short string value, like
post
, to locate the correctModel
class to be used. - Auto Resource - Automatically have TypeRocket bind the correct data resource based on the context of WordPress.
-
DataCollection - An instance of a
DataCollection
. -
Array - When passing an array, the array converts into a
DataCollection
.
Model Resource
A Model
is a class instance used to get data from the database. So, we can use a Model
instance to get data from the database and bind that model to our Form
.
$model = (new \App\Models\Post)->find(1);
$form = tr_form($model);
You can also use the class name of a model along with its record ID to do the same as the above:
$form = tr_form('\App\Models\Post', 1);
Shorthand Resource
A shorthand resource is a string value that matches the name of any model in your app/Models
directory. Shorthands are an abbreviation for the model's class name.
With a shorthand resource, the corresponding Model
loads. For example, a string of post
in the following example loads the \App\Models\Post
model.
// Shorthand resource - `post`
tr_form('post');
However, the above does not load any data because no record ID is defined. Like when passing the full model class name, you should also pass along the record ID:
$form = tr_form('post', 1);
- The shorthand
option
maps to\App\Models\Option
: - The shorthand
user
maps to\App\Models\User
: - The shorthand
comment
maps to\App\Models\Comment
: - The shorthand
tag
maps to\App\Models\Tag
- The shorthand
category
maps to\App\Models\Category
.
When adding custom post types, taxonomies, or another resource, remember a shorthand resource is a string value that matches the name of any model in your app/Models
directory.
Auto Resource
Auto resourcing allows you to add custom fields without needing to know how to bind a Model
to a Form
instance. In short, auto resourcing is the magic that makes binding a form and custom fields to a Model
automatic within specific contexts.
So with the following code, you can rest easy that your Form
just works in the WordPress admin:
$form = tr_form();
When you instance a new Form
it automatically tries to find the correct data resource for your context (context is discovered by looking for specific WP global variables). It detects if your Form
is within a post, user's profile, comment, term, or custom page.
For example, if you add create Form
instance using the tr_form()
method in the context of a post type in the admin, the Form
object automatically binds that post types data resource's Model
.
You to write the following code and remove the need to define a resource in the code because of context detection:
tr_post_type('Person')->setTitleForm(function() {
// Automatically binds the correct model
$form = tr_form();
});
Without auto resourcing you would need to write this:
tr_post_type('Person')->setTitleForm(function() {
global $post;
$model = (new \TypeRocket\Models\WPPost($post->post_type))->find($post->ID);
$form = tr_form($model, 'update');
});
Here are the default auto resource mappings:
- Post context uses
Post
Model. - Page context uses
Page
Model. - User context uses
User
Model. - Comment context uses
Comment
Model. - Category context uses
Category
Model. - Tag context uses
Tag
Model. - Custom page context uses
Option
Model (this is also the defaulted model when no context is found).
For custom resources, custom post types, and custom taxonomies, you need to create new models. However, if a custom post type does not have a custom model, it uses the TypeRocket WPPost
model. Taxonomies work in the same way, with the default being the WPTerm
model.
Data Collection & Arrays
If you are working with a third-party API or another external data source that is not apart of the database, you can use the DataCollection
class to bind data to a Form
.
$data = new \TypeRocket\Utility\DataCollection([
'first_name' => 'John Smith'
]);
$form = tr_form( $data );
echo $form->text('First Name');
You can pass an array to a Form
as the resource, and the form converts the array into a DataCollection
for you.
$data = [
'first_name' => 'John Smith'
];
$form = tr_form( $data );
echo $form->text('First Name');
Setting the Model
If you need to set the data resource after the a Form
obejct is initalized use the setModel()
method. You can pass and array
or Model
into this method. you can also pass the string
class name or a model.
$form->setModel(['first_name' => 'John']);
echo $form->text('First Name'); // value is 'John'
Action
To specify what action you want, the <form>
to take when it is submitted set the $action
argument of the Form
instance.
By default, TypeRocket tries to reason about the action you want to take based on the data resource that was used (including auto resources).
When you specify an action, you are effectively overriding the action TypeRocket chose automatically.
There are 3 actions you can choose from:
-
create
orpost
- Sends aPOST
request. -
update
orput
- Send aPUT
request. -
delete
- Sends aDELETE
request.
Take a look at instancing a Form
that is configured with the create
action:
// Sends a POST request
$form = tr_form('post', 'create');
You could also omit the create
action because TypeRocket automatically reasons about what you are trying to do.
// Also, sends a POST request with the
// action omited. TypeRocket magic.
$form = tr_form('post');
When using the update
or delete
options, you need to define the record ID.
Record ID
A record ID should be used when you want to read, update, or delete a specific record when using the shorthand
or Model
class name as a string. If you bind a Model
that already retrieved a record to the Form
you do not need to provide a record ID.
The record ID retrieves a specific record from the database. If your data resource already has data, then you do not need to retrieve any data.
// Sends a PUT request
$form = tr_form('post', 'update', 1);
You can also omit the action when using a record ID as long as the ID is an int
value. When doing this, the action automatically gets set to update
. TypeRocket automatically reasons for what you are trying to accomplish.
// Sends a PUT request
$form = tr_form('post', 1);
Important to note is the Option
model.
The Option
model does not need a record ID specified because it uses the key-value table wp_options
. Key-value tables are not used by an ID but are updated by the key column. Also, for key-value tables using update
and create
do the same action; so, you don't need to set the action when using the Option
model.
Setting the Record ID
You can override the record ID using setItemId()
but this method will not reload the model. You will need to use setModel()
after setting the record ID to load a new model.
Open & Close Forms
When are create TypeRocket forms within a post type, taxonomy, comment, or user profile, there will be an existing <form>
tag, and you will not need to create one using TypeRocket. However, you will not always be working inside another <form>
.
In the case of a custom admin page, you will want to echo the opening and closing <form></form>
tags.
Use the open()
method of the Form
object to get the opening tag and close()
to get the closing tag.
$form = tr_form('post');
echo $form->open();
echo '<p>My text</p>';
echo $form->close();
This will output the configured <form>
element.
<form
action="https://example.com/"
method="POST"
accept-charset="UTF-8"
class="tr-form-container"
>
<input type="hidden" name="_method" value="POST">
<input type="hidden" id="_tr_nonce_form" name="_tr_nonce_form" value="fe9a607216">
<p>My text</p>
</form>
Adding a submit button
To quickly add a submit button you can specify a string as a parameter in close()
$form = tr_form('post', 'create');
echo $form->open();
echo $form->close('Submit');
When you submit a form request using TypeRocket, it will send the request to the current URL.
Changing the open tag defaults
The open()
method for the Form
object takes 3 optional arguments.
-
Attributes
array
(optional) - You can change the form element attributes by passing anarray
. -
Request Params
array
(optional) - You append request params to the request URL. -
Method
string
(optional) - Override the request method. Options include:POST
,PUT
,DELETE
, andPATCH
.
Take a look at adding an id= "custom"
attribute, request params, and method override to a form element.
echo $form->open(
['id' => 'custom'],
['action' => 'doStuff'],
'PATCH'
);
Outputs,
<form
action="https://example.com/?action=doStuff"
method="POST"
accept-charset="UTF-8"
class="tr-form-container"
id="custom"
>
<input type="hidden" name="_method" value="PATCH">
...
Change Form URL
To change the base URL form action use the method toUrl()
method before using the open()
method.
$form->toUrl('https://example.com/my-path/');
echo $form->open(
['id' => 'custom'],
['action' => 'doStuff'],
'PATCH'
);
If you provide only the path, the URL will be relative to the WordPress site URL.
$form->toUrl('/my-path/');
You can also get the current URL setting.
$form->toUrl('/my-path/');
$url = $form->getFormUrl();
// return the url https://example.com/my-path/
To set the URL to a named route.
// Route with a named capture group of `id`
$form->toRoute('my.route', ['id' => 1]);
To set the URL to an admin page.
$form->toAdmin('themes.php', ['page' => 'theme_options']);
To set the URL to a custom TypeRocket page.
$form->toPage($resource, $action, $item_id);
Fields
A form's most powerful feature is the fields it can bind model properties too. There are a number of built-in field types that come out of the box and you can create your own if you like.
Built-In
There are 27+ different fields that the Form
object can create using the following methods:
-
text()
- Text field. -
input()
- Input field capable of HTML5 features. -
time()
- Input field set to the type of time. -
number()
- Input field set to the type of number. -
background()
- Background field. -
swatches()
- Swatches field. -
password()
- Password field. -
hidden()
- Hidden field. -
submit()
- Submit button. -
textarea()
- Textarea field. -
editor()
- Editor field. -
radio()
- Radio field. -
checkbox()
- Checkbox field. -
checkboxes()
- List of checkboxes. -
select()
- Select field. -
wpEditor()
- wpEditor field. -
color()
- Color field. -
date()
- Date field using jQuery UI. -
image()
- Image field. -
file()
- File field. -
gallery()
- Gallery field. -
items()
- Items field. -
matrix()
- Matrix field. -
repeater()
- Repeater field. -
builder()
- Builder field. -
search()
- Search field with multi select option. -
toggle()
- Toggle field. -
locaton()
- Location field with Google Maps API integration. -
textexpand()
- Text field that expands as you type.
Each field takes 4 arguments:
-
Name -
string
(required) - The name of the field. -
Attributes -
array
- The HTML attributes applied to the field. -
Settings -
array
-Custom settings that can vary between fields. -
Label -
boolean
- This is not for the label text. Setfalse
to remove the displaying of the label for the field entirely.
You can read more about each field under field types.
When you call any of the field methods from a Form
object the corresponding Field
object is returned (not the Form
object).
Your Own Custom Fields
If you create your field class, you can use the custom()
method to apply it to the form. The custom()
method takes 1 argument:
-
Field
Field
- This is anyField
object, including custom ones that you create.
$field = new \TypeRocket\Fields\Text('Name');
echo $form->custom($field);
Form Encapsulation
Instead of echoing each field, you can pass an array of fields into a Form
using the setFields()
method and then call the render()
method to echo the entire form.
$form = tr_form('post', 1);
$form->setFields([
$form->text('Post Title'),
$form->editor('Post Content')
]);
$form->render();
The render()
method has 4 optional arguments:
-
Attributes
array
(optional) - You can change the form element attributes by passing anarray
. -
Request Params
array
(optional) - You append request params to the request URL. -
Method
string
(optional) - Override the request method. Options include:POST
,PUT
,DELETE
, andPATCH
. -
Submit
string
(optional) - Set the submit button text value.
$form->render(
['id' => 'custom', 'class' => 'my-class'],
['action' => 'doStuff'],
'PATCH',
'Submit Changes'
);
Field Wrapper UI Only
Sometimes you might want to exclude the opening and closing <form>
tag when echoing fields. For example, when adding a form to a post type page. In those cases, use the fieldsWrapperString()
form method.
$form = tr_form('post', 1);
$form->setFields([
$form->text('Post Title'),
$form->editor('Post Content')
]);
echo $form->fieldsWrapperString();
Debug Status
You can control whether the Form
shows code hints but using the method setDebugStatus()
. You can set the value to false
to disable code hints for the form.
$form->setDebugStatus(false);
You can also get the debug status.
$status = $form->getDebugStatus();
Populating Fields
By default, forms populate fields with the data resource information. You can keep fields from being populated with that data by using the method setPopulate()
.
$form->setPopulate(false);
You can also get the population settings.
$populate = $form->getPopulate();
Groups
There are times when you want to have fields grouped when being saved. An exemplary case for this is when you are saving data to wp_options
using the OptionsController
.
Take a look at this Form
.
$form = tr_form('option');
echo $form->open();
echo $form->text('Address');
echo $form->text('Company Name');
echo $form->image('Company Logo');
echo $form->textarea('About the Company');
echo $form->close('Submit');
If you were to submit this form, it would save each field to a separate row in the wp_options
table. Grouping prevents this from happening.
You can group fields with the Form
method setGroup()
. This method groups all the fields so that only one record is created in wp_options
. When the record saves, the key
is the group name.
Take a look at grouping.
$form = tr_form('option');
// setting the group
$form->setGroup('company_info');
echo $form->open();
echo $form->text('Address');
echo $form->text('Company Name');
echo $form->image('Company Logo');
echo $form->textarea('About the Company');
echo $form->close('Submit');
Note: Groups can not be nested or used in the matrix, repeater, or builder fields. Also if a field has a group set it overrides the form's group.
Getting the group
You can also get the current group used with the method getGroup()
.
$group = $form->getGroup();
Groups - Dot Syntax
Groups and subgroups should be set to a string
using the TypeRocket "dot syntax". The TypeRocket dot syntax suggests that you use only lowercase case letters
and underscores
. When you use a dot
this tells the form to add a subgroup.
group_name.another.lowercase_underscore_only
Example 1: No dots
$form->setGroup('company_info');
$form->text('Name');
The above translates to,
<input name="tr[company_info][name]" />
Example 2: With dots
$form->setGroup('company_info.about');
$form->text('Name');
The above translates to,
<input name="tr[company_info][about][name]" />
Append to Group
You can append to a group using dot syntax with the appendToGroup()
method.
$form->setGroup('company_info');
$form->appendToGroup('about');
// Group is... company_info.about
Likewsie you can prependToGroup()
.
$form->setGroup('company_info');
$form->prependToGroup('about');
// Group is... about.company_info
Extend Group
You can clone a form and append to the group at the same time.
$form->setGroup('company_info');
$new = $form->extend('about');
// $form group... company_info
// $new group... company_info.about
Likewise you can super()
prepends.
$form->setGroup('company_info');
$form->super('about');
// $form group... company_info
// $new group... about.company_info
Text Content
You may want to generate some text content that uses the same markup as fields, so the design remains elegant. To add text content use the textContent()
method.
echo $form->textContent('Hello world!');
Rows & Columns
You can put fields into a row using the row()
method.
echo $form->row(
$form->text('First Name'),
$form->text('Last Name')
);
You can also add columns and titles to rows.
$row = $form->row();
$row->setTitle('A Row');
$column1 = $row->column(
$form->text('First'),
$form->text('Last')
);
$column2 = $row->column(
$form->image('Image')
);
echo $row;
You can also add columns fluently using withColumn()
. The method returns the row object instead of the column object.
echo $form->row()
->withColumn(
$form->text('First'),
$form->text('Last')
)->withColumn(
$form->image('Image')
);
Sections
In some cases, you want fields grouped into a <div>
. This can be for styling with CSS or when you want to toggle a group of fields with conditionals. To make a section use the section()
method.
echo $form->section([
$form->text('First'),
$form->text('Last')
])->setTitle('A Section');
Fieldsets
In some cases, you want fields grouped into a <fieldset>
. This can be for styling with CSS or when you want to toggle a group of fields with conditionals. To make a section use the fieldset()
method.
echo $form->fieldset('Title', 'A description.', [
$form->text('First'),
$form->text('Last')
]);
Use Old
When using a custom resource, you can load the old data submitted if the user with redirected with fields included.
$form->useOld();
Use Errors
The useErrors()
method provides a way of enabling inline error messages for fields.
This setting will not (and should not) work with post types, taxonomies, and a few other WordPress specific admin pages. For example, WordPress post types do not require particular fields (as a principle), and TypeRocket, therefore, does not have field validation for post types and other places.
If you want inline validation for WordPress post types and others, you should create your admin pages for editing them and disable the WordPress admin pages for those types of content.
Field validation can be used on any page you use a controller. Often, useErrors()
will be used in conjunction with useOld()
.
tr_form()->useOld()->useErrors();
How It Works
useErrors()
looks for the cookie tr_redirect_errors
and the tr_redirect_errors
WordPress transient. The tr_redirect_errors
cookie and transient can only be accessed once (after this is will be deleted).
If the tr_redirect_errors
cookie is found the form will use the field errors within that cookie to display inline field errors. The best way to set the tr_redirect_errors
cookie and apply fields to that cookie is to use HTTP fields or a validator redirect errors.
If you do not want to use cookies for the validation, you can provide an override array.
Arguments
-
$key
(string|optional) - The key to access the errors. -
$override
(array|optional) - Override array with a key that matches the key argument.
tr_form()->useOld()->useErrors('fields', [
'fields' => [
'my_field' => 'is required.'
]
]);
Use AJAX
Make the form use the TyperRocket AJAX response system.
$form->useAjax();
Or, disable the feature (this is the default).
$form->disableAjax();
Use TypeRocket REST API
You can tell forms to use the TypeRocket REST API using the useRest()
method. This method enables AJAX mode for the form as well.
$form->useRest();
// Or, override resource and/or record ID
$form->useRest($resource, $item_id);
Require Confirmation
Opens a confirmation alert when the form is submitted. Confirmation is required to submit the same.
$form->useConfirm();
Translation
If you are translating a form's field labels, localization, to another language, you can use the method setLabelTranslationDomain()
to set the translation domain for all the field labels attached to the form. The default translation domain is typerocket-profile
.
$form->setLabelTranslationDomain('my-domain');
$form->text('First Name'); // now localized with
Clone
To clone the form object use clone()
;
$form = $form->clone();
Macros
If you want to extend the form and add your methods, you can use macros. To add a macro to forms, use the setMacro()
method and the tr_form
hook.
add_action('typerocket_form', function($form) {
$form->setMacro('myFunction', function($your, $args) {
// do stuff...
return $this;
});
});
$form->myFunction('your', 'arg');
Macros do not override existing methods.
Allow File Uploads
Allow files uploads from the form. This will apply multipart/form-data
to the form element.
$form->allowFileUploads();
echo $form->open();
echo $form->close();
In the many cases WordPress provides its own form elements. The allowFileUploads()
does not apply to built-in WordPress form elements. You will need to use hooks to add the needed form attributes.
function add_form_multipart() {
echo ' enctype="multipart/form-data"';
}
add_action('post_edit_form_tag', 'add_form_multipart');
add_action( "{$taxonomy}_term_edit_form_tag", 'add_form_multipart');
add_action( "{$taxonomy}_term_new_form_tag", 'add_form_multipart');
add_action( "user_edit_form_tag", 'add_form_multipart');
add_action( "user_new_form_tag", 'add_form_multipart');
Note: Some places in WordPress do not allow for file uploads. Comments for example.
Attributes
Attributes are the HTML attributes set to the form's open tag.
-
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.
Basic attribute methods
Take a look at using some of the basic methods.
$args = $field->getAttributes();
$field->attrExtend( [ 'id' => 'names' ] );
$field->removeAttribute( 'id' );
$classes = $field->attr( 'class' );
$field->attr( 'class', $classes );
Appending a string to the class attribute
Here we use the attrClass()
method to extend the class attribute.
$field->attrClass('date-picker');
Found a typo? Something is wrong in this documentation? Fork and edit it!