TypeRocket v1 Pro users can now upgrade to TypeRocket v5 at their convenience.
Field Types
( v1 )
- # About Field Types
- # Field Types
- # Text
- # Input
- # Password
- # Hidden
- # Submit
- # Textarea
- # Text Expand
- # Editor - Redactor 3
- # Config & Plugins
- # Settings
- # Radio
- # Default Value
- # Radio Images
- # Checkbox
- # Checkboxes
- # Toggle
- # Default Value
- # Select
- # Multiple
- # Searchable
- # Default Value
- # Option Groups
- # WordPress Editor
- # Options
- # Color
- # Palette
- # Swatches
- # Date
- # Image
- # Button Text
- # Image Side - Admin
- # Dark Background
- # Background
- # File
- # Restricted Mime Types
- # Button Text
- # Gallery
- # Button Text
- # Items
- # Limit Items
- # Search & Relationship Field
- # Search Post Types
- # Search Taxonomies
- # Search Model
- # Search URL Endpoint
- # URL
- # Location
- # Repeaters
- # Fields
- # Titles
- # Limit Items
- # Tabs
- # Matrix and Builder
- # Components
- # Component Folders
- # Making a Component
- # Using a compnent
- # Repater, Builder, Matrix JavaScript Hook
About Field Types
There are 29+ different Fields
that the Form
object can create. Each field takes four arguments:
-
Name -
string
(required) - This will be the name of the field. -
Attributes -
array
- This will be the HTML attributes applied to the field. -
Settings -
array
- This will be 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.
Field Types
Assuming Form
is set to a variable called $form
, here is how to use the fields.
Text
$form->text('First Name');
Input
The input field can be any HTML5 input type. For example number
, datetime-local
, email
, date
, time
, tel
, url
and others.
$form->input('Number')->setType('number');
// or...
$form->input('Number')->setTypeNumber();
Keep in mind that you can also set attributes on an input field by passing an array as the attributes parameter.
Password
The password field will never return its value.
$form->password('Your Password');
Hidden
This field should always go at the top or bottom of a form to prevent formatting issues.
$form->hidden('Hidden Field');
Submit
$form->submit('Submit');
Textarea
$form->textarea('About Me');
Text Expand
This field is like the Text field but it will expand it fit the content contained within it.
$form->textexpand('Expand');
Editor - Redactor 3
The editor field uses Redactor 3.
$form->editor('Page Content');
Config & Plugins
You can configure redactor plugins and language under config/editor.php
.
Settings
If you need to set up your own settings for the field, use setEditorSettings()
.
$settings = (object) ['imageResizable' => false];
$form->editor('Page Content')->setEditorSettings($settings);
Radio
$options = [
'Male' => 'm',
'Female' => 'f',
'NA' => '0'
];
$radio = $form->radio('Gender')->setOptions($options);
Default Value
Radio buttons can have a default value. To set the default to "Male" specify the value 'm'
.
$radio->setDefault('m');
Radio Images
You can also make radio buttons images instead of the default browser buttons. To do this, use the useImages()
method and set your options as an array with src
and value
indexes.
$form->radio('Photo')->setOptions([
'One' => [
'src' => tr_assets_url('components/builder/content.png'),
'value' => 1
],
'Two' => [
'src' => tr_assets_url('components/builder/content.png'),
'value' => 2
]
])->useImages()->setDefault(2);
Checkbox
$form->checkbox('Email Me')->setText('Yes');
Checkboxes
Add multiple checkboxes.
$form->checkboxes('Settings')->setOptions([
'email_notifications' => 'Send me notifications by email.',
'email_marketing' => 'Send me marketing emails.',
]);
or, with advanced settings:
$form->checkboxes('Settings')->setOptions([
'email_notifications' => [
'text' => 'Send me notifications by email.',
'default' => true
]
'email_marketing'=> [
'text' => 'Send me marketing emails.',
'default' => false
]
]);
Toggle
$form->toggle('Toggle')->setText('Yes');
Default Value
Checkboxes can have a default value. Setting the default setting to true
will make the checkbox checked
.
$radio->setSetting('default', true);
Select
$options = [
'Male' => 'm',
'Female' => 'f',
'NA' => '0'
];
$select = $form->select('Gender')->setOptions($options);
Multiple
You can also set the select
field to multiple values using the multiple
method.
$form->select('Gender')->multiple();
Searchable
To have a select menu, use chosen.js
.
$form->select('Gender')->searchable();
Default Value
Select dropdowns can have a default value. To set the default to "Male" specify the value 'm'
.
$select->setDefault('m');
Option Groups
$options = [
'Group Label' => [
'Male' => 'm',
'Female' => 'f',
'NA' => '0'
]
];
$form->select('Gender')->setOptions($options);
WordPress Editor
Use the wpEditor()
at your own risk. This editor was never designed to work in a metabox, repeater, or matrix. Also, you should only have one WordPress editor per page.
$wpEditor = $form->wpEditor('Page Content');
Options
You can also set the WordPress editor internal settings. For example, turning off the media buttons.
$wpEditor->setSetting('options', ['media_buttons' => false])
Color
$form->color('Color');
Palette
Color fields can have a palette defined for the color picker. Five or six is best.
$form->color('Color')->setPalette(['#FFFFFF', '#000000']);
Swatches
$form->swatches('Site Color')->setOptions([
'Vibrant' => ['#333', '#0073aa'],
'Colorful' => ['#523f6d', '#a3b745'],
]);
Date
$form->date('Release Date');
Image
Images are saved by their attachment ID.
$image = $form->image('Photo');
Button Text
$image->setSetting('button', 'Insert Image');
Image Side - Admin
To set the image size to be used in the admin. This applies to the gallery()
and background()
fields as well.
$image->setAdminImageSize('thumbnail');
Dark Background
Set the image background to dark instead of white. This applies to the gallery()
field as well.
$image->setBackgroundDark();
Background
This field is like the image field but also includes X and Y coordinates.
$form->background('Background');
File
Files are saved by their attachment ID.
$file = $form->file('PDF');
Restricted Mime Types
When adding a file field, you can set the allowed mime types to be uploaded:
echo $form->file('File')->setSetting('type', 'text/csv');
echo $form->file('File')->setSetting('type', 'image/svg+xml');
Any of these mime types will work, and the following common use cases will also work:
echo $form->file('File')->setSetting('type', 'audio');
echo $form->file('File')->setSetting('type', 'video');
echo $form->file('File')->setSetting('type', 'pdf');
Button Text
$file->setSetting('button', 'Insert File')
Gallery
Galleries are groups of images saved by their attachment IDs.
$gallery = $form->gallery('Gallery');
Button Text
$gallery->setSetting('button', 'Insert Images')
Items
$form->items('List Movies');
Limit Items
You can also limit the number allowed using the setLimit()
method.
$form->items('Top 3 Movies')->setLimit(3);
Search & Relationship Field
the search field is the relationship field of TypeRocket. For a single value field,
$form->search('Search');
For a multi value field,
$form->search('Links')->multiple();
Search Post Types
You can search all post types - drafts will be included.
$form->search('Search')->setPostTypeOptions('any');
Also, you can search for a specific post type.
$form->search('Search')->setPostTypeOptions('post');
Search Taxonomies
You can search a taxonomy's terms.
$form->search('Search')->setTaxonomyOptions('post_tag');
Search Model
You can search a taxonomy's terms.
$model_class = '\TypeRocket\Models\WPPost';
$form->search('Search')->setModelOptions($model_class);
Search URL Endpoint
You can set a custom URL endpoint for your search too.
$example_url = site_url('my-api/fonts');
$form->search('Font')->setUrlOptions( $example_url )
Your custom endpoint should have the following return JSON in format simular to the following:
{
"search_type":"post_type",
"items": [ { "title":"<b>Hello world!</b> (post)", "id":1, "url": null } ],
"count": "1 in limit of 10"
}
URL
Like the search field the URL field can be used to look up the URL of a post or term record. The URL field supports the same features as the search field.
$form->url('URL')
Note: When using the URL field it will only search for a record if the input does not start with /
or #
.
Location
Full address field.
$form->location('Location');
To enable google maps add your Google Maps API key to your wp-config.php
file:
define('TR_GOOGLE_MAPS_API_KEY', 'yourapikeyhere')
You can also add your API key in the TypeRocket default theme options or under config/external.php
.
Repeaters
The repeater field lets you create groups of repeating fields.
For example, what if you're building an event listing site and need to list speakers for each event. A repeater field would be perfect for listing the speakers in an event post type since every speaker's information will be different even if they speak at multiple events.
The repeater could be a group of fields for a conference speaker's name, photo, and a link to their slides. Take a look at adding a meta box with the repeater.
$box = tr_meta_box('Speakers');
$box->addScreen( 'event' );
$box->setCallback(function() {
$form = tr_form();
$repeater = $form->repeater('Speakers')->setFields([
$form->image('Photo'),
$form->text('Name'),
$form->text('Slides URL')
]);
echo $repeater;
});
Fields
There are three methods for dealing with fields. These methods are: getFields()
, setFields()
and appendField()
.
-
getFields()
returns the fullarray
of field arrays. -
setFields()
takes anarray
of field arrays. -
appendField()
append a fieldarray
.
Titles
You can set a headline for each repeater item as well:
$repeater->setTitle('Speaker');
Limit Items
You can also limit the number allowed using the setLimit()
method.
$repeater->setLimit(10);
Tabs
You can add tabs to repeaters as well using the Tabs API.
$form = tr_form();
// Basic
echo $form->repeater('Speakers')->setFields([
$form->image('Photo'),
$form->text('Name'),
$form->text('Slides URL')
]);
// With Layout Tabs
$content = [
$form->textarea('Quote', ['maxlength' => 200]),
$form->row(
$form->text('First Name'),
$form->text('Last Name')
)
];
$image = [
$form->image('Avatar'),
$form->gallery('Gallery'),
];
$tabs = tr_tabs();
$tabs->tab('Content', 'pencil', $content);
$tabs->tab('Images', 'droplet', $image);
echo $form->repeater('Stories')
->setFields($tabs)
->setTitle('Story');
Matrix and Builder
Matrix and builder fields work a lot like repeater fields. However, they are not limited to the same field groups like repeaters are.
The matrix field lets you create modular sections. The Builder lets you create modular designs in an easy to use way. The main difference between the two fields is their front end design. A builder uses a slide deck style for creating field groups while the matrix field uses a simple select dropdown.
$form->matrix('Matrix List');
$form->builder('Page Builder');
As an example, the Page Builder Plugin uses the builder field.
Components
These fields use what are called "Components". Components are the field groups dynamically generated when a new item is added to the matrix or builder field list.
Component Folders
To start added components, there are three directories you need to work with. The directories are: resources/visuals
, resources/components
, and wordpress/assets/components
.
The resources/visuals
directory is for adding the HTML for each component's front-end design. The resources/components
directory is for adding the backend fields for each component. Finally, the wordpress/assets/components
directory is for the thumbnails of the components.
Note: Matrix fields do not require thumbnails.
Making a Component
To make components create a folder in each of the folder locations with the name of the field created. For example, a field named "Page Builder" would have this folder structure.
$form->builder('Page Builder');
-
resources/visuals/page_builder/
-
resources/components/page_builder/
-
wordpress/assets/components/page_builder/
To create a component under this field, add files with matching names. For example, a component named "Content" has the files:
-
resources/visuals/page_builder/content.php
- Front-end. -
resources/components/page_builder/content.php
- Backend fields. -
wordpress/assets/components/page_builder/content.png
- Thumbnail.
Here is an example of a component named "Banner":
-
resources/visuals/page_builder/banner.php
- Front-end. -
resources/components/page_builder/banner.php
- Backend fields. -
wordpress/assets/components/page_builder/banner.png
- Thumbnail.
Using a compnent
Once the files are created, you can begin adding code to the front end and backend files. For example, the "Content" component.
For the backend file, resources/components/page_builder/content.php
. The $form
variable will be created for you, and the <h1>
tag will be the component's label on the backend.
<h1>Content Component</h1>
<?php
echo $form->text('Headline');
echo $form->editor('Content');
For the front-end file, resources/visuals/page_builder/banner.php
. The $data
variable will be created for you can contain all the fields information for you.
<div class="builder-content">
<h2><?php echo esc_html($data['headline']); ?></h2>
<hr />
<?php echo wpautop( $data['content'] ); ?>
</div>
Repater, Builder, Matrix JavaScript Hook
You can also use the javascript hooks to do something when a repeater, matrix, or builder field group is added.
Found a typo? Something is wrong in this documentation? Fork and edit it!