Forms
In HivePress, forms are implemented as PHP classes with specific properties, such as the form action URL and fields. For example, the
User_Register
form contains fields required for registering a new user and sends requests to the user_register_action
URL route.If you are developing a custom HivePress extension, you may need to create a new form. To do this, create a new
class-{form-name}.php
file (use lowercase letters, numbers, and hyphens only) in the includes/forms
extension subdirectory and HivePress will load it automatically.Then, define the form 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 forms.The following form parameters are available:
- action - URL for sending requests on submission;
- method - the request HTTP method (e.g.
POST
,GET
); - redirect -
true
to refresh or URL to redirect on success; - reset -
true
to clear the fields on success; - description - text displayed before the form;
- message - text displayed on success;
- attributes - an array of HTML attributes;
- button - submit button's parameters.
The code example below implements a form with a single required text field with the
custom_field
name and "Custom field" label. The form's submit button has the "Custom button" label. Once submitted, it sends a request to the custom_action
URL route via the POST
method, displaying the "Custom text" message on success and resetting fields.<?php
namespace HivePress\Forms;
use HivePress\Helpers as hp;
// Exit if accessed directly.
defined( 'ABSPATH' ) || exit;
class Foo_Bar extends Form {
public function __construct( $args = [] ) {
$args = hp\merge_arrays(
[
// Set the form parameters.
'action' => hivepress()->router->get_url( 'custom_action' ),
'method' => 'POST',
'message' => 'Custom text',
'reset' => true,
// Set the field parameters.
'fields' => [
'custom_field' => [
'label' => 'Custom field',
'type' => 'text',
'required' => true,
'_order' => 123,
],
],
// Set the button parameters.
'button' => [
'label' => 'Custom button',
],
],
$args
);
parent::__construct( $args );
}
}
Also, a custom form can be based on another form's PHP class, allowing you to re-use its properties and methods without repeating the code:
<?php
namespace HivePress\Forms;
use HivePress\Helpers as hp;
// Exit if accessed directly.
defined( 'ABSPATH' ) || exit;
class Foo_Bar extends Listing_Search {
public function __construct( $args = [] ) {
$args = hp\merge_arrays(
[
// Override the listing search form parameters.
],
$args
);
parent::__construct( $args );
}
}
If a form is based on a HivePress model, you can use the
Model_Form
class to inherit the model fields without repeating them in the form. For example, the code below implements a form based on the Listing
model with the title
and description
fields inherited from it.<?php
namespace HivePress\Forms;
use HivePress\Helpers as hp;
// Exit if accessed directly.
defined( 'ABSPATH' ) || exit;
class Foo_Bar extends Model_Form {
public static function init( $meta = [] ) {
$meta = hp\merge_arrays(
[
// Set the model name.
'model' => 'listing',
],
$meta
);
parent::init( $meta );
}
public function __construct( $args = [] ) {
$args = hp\merge_arrays(
[
// Set the fields to inherit.
'fields' => [
'title' => [
'_order' => 123,
],
'description' => [
'_order' => 321,
],
],
],
$args
);
parent::__construct( $args );
}
}
In the same way, you can create custom forms for your HivePress extension.
You can customize any of the existing forms using hooks. For example, the code below makes the First Name and Last Name fields required in the user profile form:
add_filter(
'hivepress/v1/forms/user_update',
function( $form ) {
$form['fields']['first_name']['required'] = true;
$form['fields']['last_name']['required'] = true;
return $form;
}
);
Similarly, you can customize any form in HivePress or its extensions.
Last modified 7mo ago