# Essentials Fields
Essentials for YOOtheme Pro introduces some new fields that may be helpful when building new features in the customizer.
This is the growing list of fields.
# Summary
- Info
- File
- ContentItems
- Repeatable
- RepeatableMulti
- SettingsPanel
- SettingsPanels
- InputDrop
- SelectDrop
- Number
- SimpleQuery
- ButtonModal
- ButtonPanel
- SourceSelect
# Info Field
Displays a simple <div>
containing a predefined text or html. Useful for adding some extra information to the
customizer.
Usage:
{
...
"fields": {
"your-field": {
"type": "yooessentials-info",
"description": "Some extra info to display"
}
}
...
}
# File Field
A file picker field. Allows for selecting either a file or a folder. Uses the core YOOtheme pro file picker UI.
Extra Configuration Options
mode
: can be eitherfile
orfolder
.
Usage:
{
...
"fields": {
"your-field": {
"label": "Pick a File",
"type": "yooessentials-file",
"mode": "file"
}
}
...
}
# Content Items field
This field is one of the most powerful and flexible ones. It's used a lot in our tools. It allows to create a list of items. The items can be a list of the same field type, or even a mix of different fields (for example our input types in the form addon)
Extra Configuration Options
button
: the label of the button that allows to add the itemsemptyMsg
: the label to display when no items are presentmodalTitle
: Title of the modal used to add the fieldsicon
: true or false to display an icon for the fieldtitle
: a javascript expression that evaluates the single item's titlefilter.group
: when a filter group is specified, the items available will be any field type that matches the field group, like "form".filter.name
: can be a regular expression that allows for filtering the field type name.item
: the name of another field type to use as the content item.
Usage:
{
...
"fields": {
"your-field": {
"label": "Items",
"type": "yooessentials-content-items",
"title": "title || link",
"button": "Add Item",
"emptyMsg": "No items Yet",
"icon": true,
"modalTitle": "Items",
"filter": {
"group": "form",
"name": "yooessentials_social_sharing_(.*)"
}
}
}
...
}
# Repeatable field
With this field you can create a repeatable list of other field types. For example you can make a list of "text fields", where the user can add / remove / reorder them in any way.
Extra Configuration Options
repeat
: The type of the field that needs to be addedbutton
: the label of the button that allows to repeat the field
...
"emails": {
"label": "Email List",
"type": "yooessentials-repeatable",
"repeat": "text",
"button": "Add Email"
},
...
# Repeatable Multi field
Similar to the Repeatable Field, this one allows you to repeat a set of fields. Basically, it
allows you create a list of repeatable sub-config options, for example a list of name
and email
fields. This list
can be ordered as well.
Extra Configuration Options
type
: The type of the field that needs to be addedbutton
: the label of the button that allows to repeat the fieldmsgEmpty
: The empty message to show when no fields are presentorderable
: if the list can be ordered or notfields
: a json object of the fields to use. Can of course be mixed up with any other field.
Here's a complex example, taken from our codebase
{
"table_relations": {
"label": "Relations",
"type": "yooessentials-repeatable-multi",
"msgEmpty": "Add Relation",
"orderable": false,
"fields": {
"relation_name": {
"label": "Name",
"description": "The name to associate the relation with."
},
"_relation": {
"type": "grid",
"width": "1-2",
"description": "The relation type and the related table to make the relation with. <b>One to One</b> relation, also known as BelongsTo, allows relating an entry with another single entry, e.g. <i>Article belongs to an Author</i>. <b>One to Many</b> relation, also known as HasMany, allows relating an entry with multiple entries, e.g. <i>Article has many Categories</i>. You can create multiple relations of different types.",
"fields": {
"relation_type": {
"label": "Relation Type",
"type": "select",
"default": "1-1",
"options": {
"One to One": "1-1",
"One to Many": "1-n"
}
},
"related_table": {
"label": "Related Table",
"type": "yooessentials-input-drop",
"endpoint": "yooessentials/source/database/tables"
}
}
},
"_related_table": {
"type": "grid",
"width": "1-2",
"fields": {
"main_table_key": {
"label": "Main Table Key",
"description": "The main table key to make the relation from.",
"type": "yooessentials-input-drop",
"endpoint": "yooessentials/source/database/fields",
"params": {
"table_field_path": "table"
}
},
"related_table_key": {
"label": "Related Table Key",
"description": "The related table key to make the relation to.",
"type": "yooessentials-input-drop",
"endpoint": "yooessentials/source/database/fields",
"params": {
"table_field_path": "table_relations.__index__.related_table"
}
}
}
}
}
}
}
# Settings Panel Field
This field is an extended version of the Content Items Field. Items in this field can be sorted, and the fields inside of this field are declared in a dedicated panel.
It's mostly used in the Settings Panels Field
Extra Configuration Options
panel
The name of the panel to displayemptyMsg
Message to display to the user when no items are setbutton
The label of the button used to add items
Example usage:
{
"fields": {
"columns": {
"label": "Columns",
"type": "yooessentials-settings-panel",
"panel": "forms-action-save-csv-column",
"emptyMsg": "No columns yet.",
"button": "Add Field",
"description": "List of columns to compose the CSV. Defaults to all fields."
}
},
"panels": {
"forms-action-save-csv-column": {
"title": "CSV Column",
"fields": {
"title": {
"label": "Title"
},
"field": {
"label": "Field",
"type": "yooessentials-form-control-select"
}
}
}
}
}
# Settings Panels Field
This is an extended version of the Setting Panel Field, where the panels can be more than one, and can be opened in a dedicated model.
This is widely used in all YOOessentials Addons, and it's very versatile. It powers the "Create actions" panel in the Form Addon, and the "Create new Source" settings in the Sources Addon.
Extra Configuration Options
Same as the Setting Panel Field plus:
modal
Set this to true if the settings should be opened in a dedicated panel instead of in the sidebar as per defaultoptions
: List of the various panels, see example below
{
"fields": {
"after_submit_actions": {
"label": "After Submit Actions",
"button": "Add Action",
"options": {
"action-name-1": {
"title": {
"default": "Action Name 1",
"prop": "name"
},
"panel": "action-panel-1"
},
"action-name-2": {
"title": {
"default": "Action Name 2",
"prop": "name"
},
"panel": "action-panel-2"
}
},
"emptyMsg": "Add Action",
"modal": true,
"type": "yooessentials-settings-panels",
"description": "Set the actions to be executed after a form has been successfully submitted."
},
"panels": {
"action-panel-1": {
"title": "CSV Column",
"fields": {
"title": {
"label": "Title"
},
"field": {
"label": "Field",
"type": "yooessentials-form-control-select"
}
}
},
"action-panel-2": {
"title": "CSV Column",
"fields": {
"title": {
"label": "Title"
},
"field": {
"label": "Field",
"type": "yooessentials-form-control-select"
}
}
}
}
}
}
← Fields