input()

Since: 1.0 Last Updated: Version: 1.2.12
Back to Main Index

input() is one of 5 default helper functions defined in the Layers_Form_Elements class used specifically for defining form inputs such as text fields, select drop-downs and textareas.

Location: /core/helpers/forms.php

Usage

A basic example of a form input being generated follows. Here we are instantiating the form elements class then adding an input with the name my_input_name . We’re also using a ternary operator to pass a value to the input.

Instantiate the class:

Add inputs:

See how it is used within the form() function of a builder widget

Parameters

The input function accepts one parameter as an array, the function then decodes the array as needed.

Default arguments are:

  • type – Type of input to output, see Input Types below.
  • name – Input name.
  • id – Input ID.
  • placeholder  – (Optional) Input placeholder, used to make suggestions for users.
  • data  – (Optional) An array of data elements, eg: array( 'related_list' => '#mylist' ); will output data-related_list="#mylist"
  • value  – The input’s value. We use isset  here to ensure data is only returned when it exists.
  • class  – CSS classes to pass to the input.  Each Layers framework class is referenced in each type example below and allows you to take advantage of pre-existing styles.
  • options  – Used with radio buttons and select types, an array of value => label options, eg: array( '1' => 'One' , '2' => 'Two' , '3' => 'Three' )
  • label  – Used to set the field label in widgets. See the end of the article for how to add <labels>  for custom fields in the post editor.

Input Types

The input();  function supports the following input types:

button

Deprecated. See link-group below.

text

Adds a text field.

text-field

number

Very similar to the text input, but is limited to numbers and has +/- buttons.

Additional arguments:

  • min – Minimum number allowed.
  • max – Maxinum number allowed.
  • step – Number increments (eg. If set to 10, the numbers will count up 10 at a time, 10, 20, 30, etc.)

number-field

range

Accepts identical arguments to the number input. A range  HTML element adds a slider control to your number input in widgets.

  • min – Minimum number allowed.
  • max – Maxinum number allowed.
  • step – Number increments (eg. If set to 10, the numbers will count up 10 at a time, 10, 20, 30, etc.)

checkbox

Adds a single checkbox input.

In addition to the standard arguments, this input accepts the label argument.

  • 'label'  – Wraps your checkbox with a <label>  HTML element.

checkbox

select

Adds a select box ( drop-down ). The placeholder will be treated as a blank input, like leaving a text field blank.

select-field

See how select is used in the Layers Post Widget

select-icons

Adds a Layers UI icon or custom image to your option, (for an example, see the customizer under Header → Layout.) Each option value is added as a class to the icon, prefixed with icon-, allowing you to add an icon font to each option. This is like a select menu or checkbox, where the user chooses an option by pressing the icon or image.

In the following case, each select icon in the control will have the class icon-full-width  and icon-boxed . An example of how you might add custom select icons is in adding layout controls to your child theme for a custom page template.

The above example will output the following HTML:

rte

Adds a text area with the Rich Text Editor toolbar.

ret-field

The rte field type is used exclusively to add rich-text editing in Layers widgets where the TinyMCE editor is not compatible.

See How to Add Post Custom Meta for how to use wp_editor in place of input if you need a TinyMCE field in the backend.

textarea

Adds standard multi-line textarea input field.

textarea

image

Adds the Layers image select button, allowing users to search for an image from their media library or upload a new image.

Additional arguments:

  • button_label  – Adds a label to the Choose an Image call to action.

image-field

upload

Adds a Layers upload button allowing users to search for a file from their media library or upload a new file.

Additional arguments:

  • button_label  – Adds a label to the Upload a File call to action.

upload

color

Adds a WP color picker used in the standard customizer color controls and widgets.

color-picker

link-group

Added in 1.2.12, the link-group input field will pull in the dynamic linking function for allowing custom or post/page search and new tab toggling. This field should replace any previous use of the button field type.

The following example demonstrates how to convert a widget button link and text fields to the new link group.

insertlink

trbl-fields

Adds a group of fields with the intention of using them in CSS. trbl  refers to Top / Right / Bottom / Left. We use this input in our margin and padding controls in the Advanced section of the design bar. This type is available to widgets only.

Wrappers & Labels

Each input can be wrapped in a layers-form-item and given a label, if the input type does not use a label argument.

Line 2: (optional) Set your field wrapper. Using a paragraph tag with the layers-form-item  class will render your field full width like the Video URL field. If you do not use a wrapper, the fields will simply sit next to one another:

meta-box4

Line 3: When building Custom Fields, the label is defined outside of the input array.  See this example of labels in the Post Widget.

In either case, label text strings should be wrapped in __().

Adding Custom Attributes

The following demonstrates how you would add a custom attribute to an input field, shown here as 'data'

See Developer Tutorials: Layers Builder Widgets for a detailed overview of using these class helpers in widget building.

Similar to:
$form_elements->input