Custom Control - 10quality/wpmvc-addon-administrator GitHub Wiki

Create custom controls that can later be used as field types, allowing you to expand the capabilities of your fields.

Create control class

Create a new class that extends from WPMVC\Addons\Administrator\Abstracts\Control, i.e. example:

<?php
namespace [MyNamespace]/Controls;

use WPMVC\Addons\Administrator\Abstracts\Control;

class DuplicatorControl extends Control
{
    // TODO
}

Define the control type with a constant and use it to define the value of property $type, like this:

// Namespace and use statements...
class DuplicatorControl extends Control
{
    /**
     * Control type.
     * @var string
     */
    const TYPE = 'duplicator';
    /**
     * The control type, acts like ID identifier.
     * @var string
     */
    protected $type = self::TYPE;
}

Enqueue assets

Use method enqueue() if the control needs to enqueue a script or styles before being rendered in the settings page:

// Namespace and use statements...
class DuplicatorControl extends Control
{
    // Other properties...
    /**
     * Enqueues styles and scripts especific to the control.
     */
    public function enqueue()
    {
        wp_enqueue_style(
            'my-control-style',
            assets_url( 'css/duplicator.css', __FILE__ ),
            [],
            '1.0.0'
        );
    }
}

Render

Use method render() to render and print the control, this method will be called by the add-on the moment needed to display a field:

// Namespace and use statements...
class DuplicatorControl extends Control
{
    // Other properties and methods...
    /**
     * Renders output.
     * @param array $args
     */
    public function render( $args = [] )
    {
        // In the following example, a view, within the
        // plugin or theme, is used to render the custom
        // control
        get_bridge( 'MyNamespace' )->view( 'administrator.controls.my-control', $args );
    }
}

Render args

By default, the following arguments will always be present:

Array key	Array value
`id`	The field ID.
`value`	The value to be displayed in the control. This will be the value wanted to be saved, the value saved or the default value for the field.
`html_attributes`	HTML attributes defined for the control.

Other arguments will be passed depending on the configuration set in the model's fields.

For example, if the following field is defined:

class Settings extends Model
{
    // Class properties...
    protected function init()
    {
        // Other properties...
        $this->tabs = [
            'tab' => [
                'fields' => [
                    'duplicator' => [
                        'type' => 'duplicator',
                        'options' => [...],
                        'title' => __( 'Duplicator', 'my-domain' ),
                        'control' => [...],
                    ],
                ],
            ],
        ];
    }
}

$args['options'] and $args['control'] will also be passed by.

Render using a view

The control does not need to render the title nor the description of the field, these are already being rendered by the add-on.

Following the examples above, the view administrator.controls.my-control could look like:

<input type="text"
    id="<?php echo esc_attr( $id ) ?>"
    name="<?php echo esc_attr( $id ) ?>"
    value="<?php echo esc_attr( $value ) ?>"
    <?php echo $html_attributes ?>
/>
<?php foreach ( $options as $key => $label ) : ?>
    <span id="<?php echo esc_attr( $key ) ?>"><?php echo esc_attr( $label ) ?></span>
<?php endforeach ?>
<?php if ( isset( $control ) ) : ?>
    <!-- DO something with control data -->
<?php endif ?>

Register control

Use the following filter hook to register your control:

use [MyNamespace]\Controls\DuplicatorControl;

add_filter( 'administrator_controls', function( $controls ) {
    $controls[DuplicatorControl::TYPE] = DuplicatorControl::class;
    return $controls;
} );