premise_field()

deprecated since v2.0.0 – Please use pwp_field() instead.

This function creates an HTML field and echoes it or returns it as a string.

It takes 3 parameters – type | arguments | echo. All parameters are optional; by default this function echoes a basic text field.

Here is a quick example for a text field with the name attribute ‘my_option’.

premise_field( 'text', array( 'name' => 'my_option' ) );

The code above would echo the following HTML

<div class="premise-field premise-field-type-text premise-field-name premise-field-id">
	<div class="premise-field-text">
		<input type="text" name="my_option" id="my_option">
	</div>
</div>

Notice that Premise WP inserts the id attribute based on the name attribute you passed; this is to ensure that label tags and other basic HTLM elements work properly. You’re welcome 😉

@param string  type  Default text

What’s your type? this param accepts a string with any valid HTML input type attribute. HTML5 only attributes are fully supported in functionality, though some may be too new and require additional css.

Built-in types create fields with a little more functionality. See the list below for all built-in types.

  • wp_media – use the WordPress default media uploader.
    Note: This field will allow the upload of images and other files (videos, pdfs, etc), as of now, previews are only supported for images.
  • wp_color – use WordPress default color picker.
  • fa_icon – choose from over 500 Font Awesome icons.
  • video – Save a video using a url or video ID (Youtube, Viemo or Wistia)
@param array  arguments  Default array()

All of our field’s information (other than the type) is passed to this param as an associative array. Below is a list of default arguments that this param takes; any argument included in addition to the defaults will be inserted as a HTML attribute on our field.

/**
 * Defaults for each field
 *
 * Reserved Arguments - The following arguments are reserved and should not be used as your own
 * arguments but as they were intended. Please read the list of reserved arguments below to avoid
 * using any of them in your own code. These arguments either serve a specific purpose within this
 * class and will not be added to the field as other attributes are added.
 *
 * Public Arguments - These aregumets you can use as your own because they are directly passed to the 
 * field itself.
 *
 * @var array
 *
 * @since 1.2 Moved type oustide of arguments and other changes
 */
public $defaults = array(
	/**
	 * Reseved Arguments
	 */
	'label'      => '',      // Adds label attribute
	'tooltip'    => '',      // Adds a tooltip and tooltip functionality to field.
	'context'    => '',      // Used to let Premise know where to retrieve values from ( post, user ).
	'wrapper_class' => '',   // Add additional classes to the fields wrapper.
	'default'    => '',      // If value is empty and premise_get_value() returns false we use this as the value
	'value_att'  => '',      // print a value attribute on the field. Used for checkboxes and radio.
	'attribute'  => '',      // HTML attributes to add to element i.e. onchange="doSomethingCool()".
	'options'    => array(), // Options for select fields in this format ( 'Option Text' => 'Option Value' ).
	'add_filter' => array(), // Add filter(s) to this field.
	/**
	 * Public Arguments
	 */
	'name'       => '',      // Name attribute. if empty fills from id.
	'id'         => '',      // ID attribute. if empty fills from name (if name not empty).
	'value'      => '',      // Value attribute. by default tries to premise_get_value( name ).
);

 

Reserved Arguments have a specific purpose and cannot be used as your own arguments.

Public Arguments Are added to the field as HTML attributes, any other argument you include is considered public.

@param boolean  echo  Default true

Whether to echo the HTML or return it as a string.

Examples

Allow users to upload an image and preview it!

Use the type wp_media. Since we load the WordPress default media uploader users are immediately familiar with the interface.

[insert_php]echo ‘yo!’;premise_field( ‘text’, array(
‘name’ => ‘my_option[in_an_array]’,
‘multiple’ => true,
‘preview’ => true
) );[/insert_php]

/**
 * This will create a media field that takes only one file and does not
 * display a preview of the images uploaded.
 */
premise_field( 'wp_media', array(
 'name' => 'my_option[in_an_array]'
) );



/**
 * This will create a media field that takes multiple files and does not
 * display a preview of the images uploaded.
 */
premise_field( 'wp_media', array(
 'name' => 'my_option[in_an_array]',
 'multiple' => true 
) );



/**
 * This will create a media field that takes multiple files and displays
 * a preview of the images uploaded.
 */
premise_field( 'wp_media', array(
 'name' => 'my_option[in_an_array]',
 'multiple' => true,
 'preview' => true 
) );
Allow users to choose from FontAwesome icons.

Premise WP comes equipped with FontAwesome icons out of the box. So why not leverage that to allow users to insert icons anywhere? Well, you can easily do that with the fa_icon type. This type name will display a clean interface for the user to search or scroll through icons.

premise_field( 'fa_icon', array(
 'name' => 'my_option[in_an_array]'
));
No need to retrieve the value from the database, we got you!

When building themes and plugins there are 3 tables in the WordPress database that are most commonly used to save data – the post_meta table which saves data related to a specific post, the users table which saves data related to a specific user, and the options table which is used to save our theme or plugin options. Because these options are saved in different tables in the database WordPress uses different functions to save and retrieve data from these tables. By using the argument context we can let premise_field() know where it should save our data and retrieve it from. By default this function will use the options table, to use the post_meta or users table the context argument value should be post or user respectively. See below for an example..

premise_field( 'text', array(
    'name' => 'my_option[in_an_array]',
    'context' => 'post' // Grab value for current post
) );

Send us your comments..

Your email address will not be published. Required fields are marked *