Sortable

The Sortable controller allows users to rearrange the order of a list of options by dragging and dropping an option.

Demonstration

 
Handy::control( 'sortable', [
    'id'          => 'sortable_id',
    'section'     => 'layout_section',
    'label'       => esc_html__( 'Sortable Control', 'textdomain' ),
    'description' => esc_html__( 'Description Here', 'textdomain' ),
    'priority'    => 1,
    'choices'     => [
        'one'   => esc_html__( 'One', 'textdomain' ),
        'two'   => esc_html__( 'Two', 'textdomain' ),
        'three' => esc_html__( 'Three', 'textdomain' ),
        'four'  => esc_html__( 'Four', 'textdomain' ),
        'five'  => esc_html__( 'Five', 'textdomain' ),
    ]
]);

TIP

Here's an example using the default parameter. Note the default values must exist in defined choices and if a certain item from choices doesn't exist in the default value it will set as a disabled item.

 
Handy::control( 'sortable', [
    'id'          => 'sortable_id',
    'section'     => 'layout_section',
    'default'     => [ 'one', 'two', 'three' ],
    'label'       => esc_html__( 'Sortable Control', 'textdomain' ),
    'description' => esc_html__( 'Description Here', 'textdomain' ),
    'priority'    => 1,
    'choices'     => [
        'one'   => esc_html__( 'One', 'textdomain' ),
        'two'   => esc_html__( 'Two', 'textdomain' ),
        'three' => esc_html__( 'Three', 'textdomain' ),
        'four'  => esc_html__( 'Four', 'textdomain' ),
        'five'  => esc_html__( 'Five', 'textdomain' ),
    ]
]);

TIP

Here's an example using the enable_handle parameter. Note the enable_handle value only accepts a boolean data type.

 
Handy::control( 'sortable', [
    'id'          => 'sortable_id',
    'section'     => 'layout_section',
    'default'     => [ 'one', 'two', 'three' ],
    'label'       => esc_html__( 'Sortable Control', 'textdomain' ),
    'description' => esc_html__( 'Description Here', 'textdomain' ),
    'priority'    => 1,
    'enable_handle' => true,
    'choices'     => [
        'one'   => esc_html__( 'One', 'textdomain' ),
        'two'   => esc_html__( 'Two', 'textdomain' ),
        'three' => esc_html__( 'Three', 'textdomain' ),
        'four'  => esc_html__( 'Four', 'textdomain' ),
        'five'  => esc_html__( 'Five', 'textdomain' ),
    ]
]);

Basic Usage

 
// Return an array.
$values = get_theme_mod( 'sortable_id' );

Parameters

Name	Description
id	`string` `required` The unique slug like string used as an ID and also as an index name in storing data in a database.
section	`string` `required` The ID of the section in which the control will be displayed.
default	`array` `optional` The predetermined value of the control. The `default` values must exist in defined `choices` and if a certain item from `choices` doesn't exist in the `default` value it will marked as a disabled item. Default empty `array`.
choices	`array` `required` The array-based list of predetermined items or choices.
enable_handle	`boolean` `optional` The flag that indicates whether to show the handler icon. Default `false`.
label	`string` `optional` The label or title of the control to show in the UI. Default empty.
description	`string` `optional` The description of the control to show in the UI. Default empty.
priority	`integer` `optional` The order of control appears in the section. Default `0`.
validations	`array` `optional` The set of validations used to validate the value of the control. For further details, read validations. Default empty.
active_callback	`callable` `optional` A callback function that determines the visibility of a control, whether to show or hide depending on a condition. For further details, read active_callback. Default empty.
sanitize_callback	`callable` `optional` A callback function that sanitizes the value of control before storing it in the database. Note that this is only optional since each control is already well sanitized. For further details, read sanitize_callback. Default empty.