Fields

In HivePress, field types are implemented as PHP classes with properties and methods that determine the validation and rendering of the field HTML. For example, the Email field type renders a text input that accepts email addresses only. You can use any of the existing field types in forms or even create a new one if required.

Creating field types

If you are developing a custom HivePress extension, you may need to create a new field type. To do this, create a new class-{field-type}.php file (use lowercase letters, numbers, and hyphens only) in the includes/fields extension subdirectory and HivePress will load it automatically.

It’s good practice to re-use the existing HivePress field types and avoid creating new ones if possible. For example, a new type may be required if you need a completely new UI element, or if it requires some custom logic.

Then, define the field type PHP class. The class name should be based on the file name but with underscores instead of hyphens and no lowercase restriction (e.g. Foo_Bar class for the class-foo-bar.php file). Pick a name that is unique enough to avoid conflicts with other HivePress field types.

<?php
namespace HivePress\Fields;

use HivePress\Helpers as hp;

// Exit if accessed directly.
defined( 'ABSPATH' ) || exit;

class Foo_Bar extends Field {

	// Declare the field properties.
	protected $max_length;

	// Set the property defaults.
	public function __construct( $args = [] ) {
		$args = hp\merge_arrays(
			[
				'max_length' => 123,
			],
			$args
		);

		parent::__construct( $args );
	}

	// Do something after the field is loaded.
	protected function boot() {
		if ( $this->max_length ) {
			$attributes['maxlength'] = $this->max_length;
		}

		parent::boot();
	}

	// Normalize the field value.
	public function normalize() {
		parent::normalize();

		if ( ! is_null( $this->value ) ) {
			$this->value = trim( wp_unslash( $this->value ) );
		}
	}

	// Sanitize the field value.
	public function sanitize() {
		$this->value = sanitize_text_field( $this->value );
	}

	// Validate the field value.
	public function validate() {
		if ( parent::validate() && strlen( $this->value ) > $this->max_length ) {
			$this->add_errors( 'Custom error message' );
		}

		return ! $this->errors;
	}

	// Render the field HTML.
	public function render() {
		return '<input type="text" name="' . esc_attr( $this->name ) . '" value="' . esc_attr( $this->value ) . '" ' . hp\html_attributes( $this->attributes ) . '>';
	}
}

The code example above implements a field type that normalizes values by trimming whitespace and removing slashes, then sanitizes them by removing HTML and special characters, and finally validates values based on its max_length property (set to 123 by default). The field itself is rendered as an HTML input of text type.

Also, a custom field type can be based on another type's PHP class, allowing you to re-use its properties and methods without repeating the code:

<?php
namespace HivePress\Fields;

use HivePress\Helpers as hp;

// Exit if accessed directly.
defined( 'ABSPATH' ) || exit;

class Foo_Bar extends Number {

	// Override properties and methods of Number type.
}

In the same way, you can create custom field types for your HivePress extension.

Customizing field types

You can customize any of the existing field types using hooks. For example, the code below changes the default date format for the Date field type.

add_filter(
	'hivepress/v1/fields/date',
	function( $field ) {
		$field['display_format'] = 'F j, Y';

		return $field;
	}
);

Similarly, you can customize any field type in HivePress or its extensions.