Form Component

The form component provides functionality of building and managing forms.

All the factory classes except the post type factory class provide means of building forms and the form component is part of them.

Adding Form Fields

To add form fields, in the setUp() or load() method of the class extending a factory class, use AdminPageFramework_Factory_Controller::addSettingField() method. For arguments, see the link of the method.

$this->addSettingFields(
    array(
        'field_id'  => 'my_field_a',
        'title'     => 'Field A',
        'type'      => 'text',
    ),
    array(
        'field_id'  => 'my_field_b',
        'title'     => 'Field B',
        'type'      => 'text',
    ),
    array(
        'field_id'  => '_submit',
        'type'      => 'submit',
        'save'      => false,
    )
);

Adding Form Sections

If you want to group fields, use the AdminPageFramework_Factory_Controller::addSettingSections() method to put certain fields into a section. For arguments, see the link of the method.

$this->addSettingSections(
    array(
        'section_id'        => '_my_post_meta_section',
        'title'             => 'My Post Meta Section',
    )
);
$this->addSettingFields(
    'my_post_meta_section', // section id
    array(
        'field_id'          => 'textarea',
        'title'             => __( 'Text Area', 'admin-page-framework-loader' ),
        'type'              => 'textarea',
        'rich'              => true,
    ),
    array(
        'field_id'          => 'color',
        'title'             => __( 'Color', 'admin-page-framework-loader' ),
        'type'              => 'color',
    )
);

Repeating and Sorting Form Sections

With the repeatable and sortable arguments, sections can be repeated or sorted. For the sortable arguments to take effect, the repeatable argument must be true.

$this->addSettingSections(
    array(
        'section_id'    => 'my_section_id',
        'title'         => 'Repeatable & Sortable Sections',
        'repeatable'    => true,
        'sortable'      => true,
    )
);

With the min and max arguments, you can limit the maximum and minimum number of repeatable elements.

array(
    'section_id'    => 'my_section_id',
    'title'         => 'Repeatable & Sortable Sections',
    'repeatable'    => array(
        'max' => 5,
        'min' => 2,
    ),
    'sortable'      => true,
)

Tabbing Sections

With the section_tab_slug argument, you can group sections and make them tabbed.

array(
    'section_id'        => 'my_section_a',
    'section_tab_slug'  => 'tabbed_sections',   // <-- set a unique tab slug
    'title'             => 'Section Tab A',
),
array(
    'section_id'        => 'my_section_b',
    'section_tab_slug'  => 'tabbed_sections',   // <-- use the same tab slug with the above
    'title'             => 'Section Tab B',
),*

With the combination of the repeatable and section_tab_slug argument, you can create a repeatable tabbed section.

array(
    'section_id'        => 'my_repeatable_tabbed_section',
    'section_tab_slug'  => 'repeatable_tabbed_section_tab',
    'title'             => 'Section Tab',
    'repeatable'        => true,
    'sortable'          => true,
)

Creating Collapsible Sections

With the collapsible argument, you can make the section collapsible and toggle the visibility.

array(
    'section_id'        => 'collapsible_section_a',
    'title'             => 'Collapsible Section A',
    'collapsible'       => array(
        'toggle_all_button' => 'top-right',
    ),
),
array(
    'section_id'        => 'collapsible_section_b',
    'title'             => 'Collapsible Section B',
    'collapsible'       => array(
        'is_collapsed'     => false,
    ),
),
array(
    'section_id'        => 'collapsible_section_c',
    'title'             => 'Collapsible Section C',
    'collapsible'       => array(
        'collapse_others_on_expand' => false,
    ),
),
array(
    'section_id'        => 'collapsible_section_d',
    'title'             => 'Collapsible Section D',
    'collapsible'       => array(
        'collapse_others_on_expand' => false,
        'toggle_all_button' => 'bottom-right',
    ),
),

With the combination of the repeatable and collapsible argument, you can create repeatable & collapsible sections.

array(
    'section_id'        => 'repeatable_and_collapsible',
    'title'             => 'Repeatable and Collapsible',
    'repeatable'        => true,
    'sortable'          => true,
    'collapsible'       => array(
        'toggle_all_button' => array( 'top-left', 'bottom-left' ),
        'container'         => 'section',
    ),
)

Repeating and Sorting Form Fields

With the repeatable and sortable arguments, fields can be repeated or sorted.

$this->addSettingFields(
    array(
        'field_id'          => 'some_color',
        'title'             => 'Some Color',
        'type'              => 'color',
        'repeatable'        => true,            // <-- this part
        'sortable'          => true,            // <-- this part
    )
);

Nesting Form Fields

By setting an array holding field definitions to the content argument, you can nest fields. The fields set in the content argument will be nested.

$this->addSettingFields(
    array(
        'field_id'      => 'Y',
        'title'         => __( 'Y', 'admin-page-framework-loader' ),
        'content'       => array(
            array(
                'field_id'      => 'i',
                'title'         => __( 'i', 'admin-page-framework-loader' ),
                'type'          => 'textarea',
            ),
            array(
                'field_id'      => 'ii',
                'title'         => __( 'ii', 'admin-page-framework-loader' ),
                'type'          => 'color',
            ),
            array(
                'field_id'      => 'iii',
                'title'         => __( 'iii', 'admin-page-framework-loader' ),
                'repeatable'    => true,
                'sortable'      => true,
                'content'       => array(
                    array(
                        'field_id'      => 'a',
                        'title'         => __( 'a', 'admin-page-framework-loader' ),
                        'type'          => 'image',
                        'attributes'    => array(
                            'preview' => array(
                                'style' => 'max-width: 200px;',
                            ),
                        ),
                    ),
                    array(
                        'field_id'      => 'b',
                        'title'         => __( 'b', 'admin-page-framework-loader' ),
                        'content'       => array(
                            array(
                                'field_id'      => 'first',
                                'title'         => __( '1st', 'admin-page-framework-loader' ),
                                'type'          => 'color',
                                'repeatable'    => true,
                                'sortable'      => true,
                            ),
                            array(
                                'field_id'      => 'second',
                                'title'         => __( '2nd', 'admin-page-framework-loader' ),
                                'type'          => 'size',
                            ),
                            array(
                                'field_id'      => 'third',
                                'title'         => __( '3rd', 'admin-page-framework-loader' ),
                                'type'          => 'select',
                                'label'         => array(
                                    'x' => 'X',
                                    'y' => 'Y',
                                    'z' => 'Z',
                                ),
                            ),
                        ),
                    ),
                    array(
                        'field_id'      => 'c',
                        'title'         => __( 'c', 'admin-page-framework-loader' ),
                        'type'          => 'radio',
                        'label'         => array(
                            'a' => __( 'Apple', 'admin-page-framework-loader' ),
                            'b' => __( 'Banana', 'admin-page-framework-loader' ),
                            'c' => __( 'Cherry', 'admin-page-framework-loader' ),
                        ),
                        'default'       => 'b',
                    ),
                )
            ),
        ),
    )
);

Mixing Form Fields

To repeat and sort a set of fields, it is useful to create an inline-mixed fields. For that use the inline_mixed field type and pass an array of field definitions to the content argument.

$this->addSettingFields(
    array(
        'field_id'      => 'checkbox_number_select',
        'type'          => 'inline_mixed',
        'title'         => __( 'Checkbox, Number & Select', 'admin-page-framework-loader' ),
        'content'       => array(
            array(
                'field_id'        => 'enable',
                'type'            => 'checkbox',
                'label_min_width' => '',
                'label'           => __( 'Do something in', 'admin-page-framework-loader' ),
            ),
            array(
                'field_id'        => 'interval',
                'type'            => 'number',
                'label_min_width' => '',
                'default'         => 3,
                'attributes'      => array(
                    'style'     => 'width: 80px',
                ),
            ),
            array(
                'field_id'        => 'interval_unit',
                'type'            => 'select',
                'label_min_width' => '',
                'label'           => array(
                    'hour'    => __( 'hours', 'admin-page-framework-loader' ),
                    'day'     => __( 'days', 'admin-page-framework-loader' ),
                    'week'    => __( 'weeks', 'admin-page-framework-loader' ),
                ),
                'default'         => 'day',
            ),
            array(
                'field_id'      => '_text',
                'content'       => __( 'to do something else.', 'admin-page-framework-loader' ),
            ),
        ),
    ),
    array(
        'field_id'      => 'text_number',
        'type'          => 'inline_mixed',
        'title'         => __( 'Text & Number', 'admin-page-framework-loader' ),
        'repeatable'    => true,
        'content'       => array(
            __( 'Server', 'admin-page-framework-loader' ),
            array(
                'field_id'        => 'server',
                'type'            => 'text',
                'default'         => 'www.wordpress.org',
                'attributes'      => array(
                    'fieldset'  => array(
                        'style'     => 'min-width: 400px;',
                    )
                ),
            ),
            __( 'Port', 'admin-page-framework-loader' ),
            array(
                'field_id'        => 'port',
                'type'            => 'number',
                'label_min_width' => '',
                'default'         => 3,
                'attributes'      => array(
                    // 'style'     => 'width: 80px',
                ),
            ),

        ),
    ),
    array(
        'field_id'      => 'shipping_address',
        'title'         => __( 'Shipping Information', 'admin-page-framework-loader' ),
        'type'          => 'inline_mixed',
        'repeatable'    => true,
        'sortable'      => true,
        'content'       => array(
            array(
                'field_id'      => 'first_name',
                'type'          => 'text',
                'title'         => __( 'First Name', 'admin-page-framework-loader' ),
                'attributes'    => array(
                    'fieldset'  => array(
                        'style'  => 'width: 48%; padding-right: 2%;',
                    ),
                ),
            ),
            array(
                'field_id'      => 'last_name',
                'type'          => 'text',
                'title'         => __( 'Last Name', 'admin-page-framework-loader' ),
                'attributes'    => array(
                    'fieldset'  => array(
                        'style'  => 'width: 48%; padding-right: 2%;',
                    ),

                ),
            ),
            array(
                'field_id'      => 'mailing_address',
                'type'          => 'text',
                'title'         => __( 'Street Address', 'admin-page-framework-loader' ),
                'attributes'    => array(
                    'fieldset'  => array(
                        'style'  => 'width: 98%; padding-right: 2%;',
                    ),
                ),
            ),
            array(
                'field_id'      => 'city',
                'type'          => 'text',
                'title'         => __( 'City/Town', 'admin-page-framework-loader' ),
                'attributes'    => array(
                    'fieldset'  => array(
                        'style'  => 'width: 36%; padding-right: 2%;',
                    ),
                ),
            ),
            array(
                'field_id'      => 'state',
                'type'          => 'text',
                'title'         => __( 'State/Province', 'admin-page-framework-loader' ),
                'attributes'    => array(
                    'fieldset'  => array(
                        'style'  => 'width: 36%; padding-right: 2%;',
                    ),
                ),
            ),
            array(
                'field_id'      => 'zip',
                'type'          => 'text',
                'title'         => __( 'Zip/Postal Code', 'admin-page-framework-loader' ),
                'attributes'    => array(
                    'fieldset'  => array(
                        'style'  => 'width: 22%; padding-right: 2%;',
                    ),
                ),
            ),
            array(
                'field_id'      => 'telephone',
                'type'          => 'text',
                'title'         => __( 'Tel. No.', 'admin-page-framework-loader' ),
                'attributes'    => array(
                    'fieldset'  => array(
                        'style'  => 'width: 31%; padding-right: 2%;',
                    ),
                ),
            ),
            array(
                'field_id'      => 'fax',
                'type'          => 'text',
                'title'         => __( 'Fax No.', 'admin-page-framework-loader' ),
                'attributes'    => array(
                    'fieldset'  => array(
                        'style'  => 'width: 31%; padding-right: 2%;',
                    ),
                ),
            ),
            array(
                'field_id'      => 'email',
                'type'          => 'text',
                'title'         => __( 'Email', 'admin-page-framework-loader' ),
                'attributes'    => array(
                    'fieldset'  => array(
                        'style'  => 'width: 32%; padding-right: 2%;',
                    ),
                ),
            ),
        ),
    )
);

Form Specific Common Hooks

Except the Post Type factory class, all the other factory classes have the ability to build form element.

There are hooks that are specific to the tasks of dealing with forms.

Filter Hooks

field_types_{instantiated class name} – receives the field type definition array. The first parameter: the field type definition array.
section_head_{instantiated class name}_{section ID} – receives the title and the description output of the given form section ID. The first parameter: the output string.
field_{instantiated class name}_{field ID} – receives the form input field output of the given input field ID. The first parameter: output string. The second parameter: the array of option.
field_{instantiated class name}_{field ID} – receives the form input field output of the given input field ID that does not have a section. The first parameter: output string. The second parameter: the array of option.
field_{instantiated class name}_{section id}_{field ID} – [3.0.0+] receives the form input field output of the given input field ID that has a section. The first parameter: output string. The second parameter: the array of option.
sections_{instantiated class name} – receives the registered section arrays. The first parameter: sections container array.
fields_{instantiated class name} – receives the registered field arrays. The first parameter: fields container array.
fields_{instantiated class name}_{section id} – [3.0.0+] receives the registered field arrays which belong to the specified section. The first parameter: fields container array.
field_types_admin_page_framework – [3.5.0+] receives a field type definitions array. The first parameter: a field type definitions array.
field_types_{instantiated class name} – receives a field type definitions array. The first parameter: a field type definitions array.
field_definition_{instantiated class name} – [3.1.0+] receives all the form field definition arrays of set in the class. The first parameter: the field definition arrays.
field_definition_{instantiated class name}_{field ID} – [3.0.2+] receives the form field definition array of the given input field ID that does not have a section. The first parameter: the field definition array.
field_definition_{instantiated class name}_{section id}_{field ID} – [3.0.2+] receives the form field definition array of the given input field ID that has a section. The first parameter: the field definition array. The second parameter: the integer representing sub-section index if the field belongs to a sub-section.
validation_{instantiated class name} – receives the form submission values as array. The first parameter: submitted input array. The second parameter: the original array stored in the database.
validation_{instantiated class name}_{field id} – [3.0.0+] receives the form submission value of the field that does not have a section. The first parameter: ( string|array ) submitted input value. The second parameter: ( string|array ) the old value stored in the database. The third parameter: ( object ) [3.1.0+] the caller object.
validation_{instantiated class name}_{section_id}_{field id} – [3.0.0+] receives the form submission value of the field that has a section. The first parameter: ( string|array ) submitted input value. The second parameter: ( string|array ) the old value stored in the database. The third parameter: ( object ) [3.1.0+] the caller object.
validation_{instantiated class name}_{section id} – [3.0.0+] receives the form submission values that belongs to the section.. The first parameter: ( array ) the array of submitted input values that belong to the section. The second parameter: ( array ) the array of the old values stored in the database. The third parameter: ( object ) [3.1.0+] the caller object.
validation_saved_options_{instantiated class name} – [3.1.2+] receives the saved form options as an array. The first parameter: the stored options array. The second parameter: the caller object.
validation_saved_options_without_dynamic_elements_{instantiated class name} – [3.4.1+] receives the saved form options as an array without dynamic elements such as repeatable and sortable fields. The first parameter: the stored options array. The second parameter: the caller object.
options_{instantiated class name} – [3.1.0+] receives the option array.

Callback Methods

To register callbacks to those hooks, use the add_filter function.

function validateMyClassForm( $aInputs, $aOldInputs, $oFactory, $aSubmitInfo ) {
     // parse the $aInputs array and check errors.
     return $aInputs;
}
add_filter( 'validation_MyClass', 'validateMyClassForm', 10, 4 );

Or define a method with the hook name.

class MyClass extends AdminPageFramework {

     ...

     public function validation_MyClass( $aInputs, $aOldInputs, $oFactory, $aSubmitInfo ) {
         // do validation here.
         return $aInputs;
     }

     ...

}

Sub-packages

AdminPageFramework\Common\Form\FieldType

Packages

Classes

Resources