WordPress.org

Plugin Directory

Admin Page Framework

Facilitates WordPress plugin and theme development.

Other Notes

Use Unique Page Slug

The framework internally uses the add_submenu_page() function to register sub menu pages. When the same page slug is registered for multiple root pages, only the last registered callback gets triggered. The other ones will be ignored.

This means if you choose a very simple page slug such as about for your plugin/theme's information page and then if there is another plugin using the same page slug, your users will get either of your page or the other.

To avoid this, make sure to use a unique page slug. One way to do that is to add a prefix like apf_about.

Use the files generated with the component generator

There is one thing you need to be careful when you include the framework: the framework version conflicts. Imagine you publish a plugin using the framework v3.4.6 and your plugin user installs a plugin using the framework v3.0.0 which is below your framework version. If the other plugin loads earlier than yours, your plugin may not work properly and vice versa.

There is a way to avoid such a conflict: change the PHP class names of the framework you include. All the class names have the prefix AdminPageFramework so just change it to something like MyPlugin_AdminPageFramework.

Go to Dashboard -> Admin Page Framework -> Tools -> Generator. Set the prefix in the option field and download the files.

If you do not modify the framework class names, you are supposed to extend the AdminPageFramework factory class.

class MyAdminPage extends AdminPageFramework {
    ...
}

When you modify the framework class names, make sure you extend the class with the modified name.

class MyAdminPage extends MyPlugin_AdminPageFramework {
    ...
}

For more detailed instruction, go to Dashboard -> Admin Page Framework -> About -> Getting Started.

By the time WordPress's minimum required PHP version becomes 5.3 or higher, we can use name spaces then this problem will be solved.

Change Framework's System Messages

The default messages defined by the framework can be changed. For example, when you import a setting with the framework, the setting notice "The options have been updated." will be displayed.

If you want to change it to something else, modify the oMsg object. It has the aMessages public property array holding all the messages that the framework uses.

Get comfortable with the 'attributes' array argument

In each field definition array, you can set the attributes arguments which defines the HTML attributes of the field so that you can modify the output of the field by passing attribute values.

The argument accepts the values as an array. Each element represents the attribute's name and value. The array key corresponds to the name of the attribute and the value to the attribute value.

For example,

array(    
    'field_id'      => 'interval',
    'title'         => __( 'Interval', 'task-scheduler' ),
    'type'          => 'number',
    'attributes'    => array(
        'min'   => 0,
        'step'  => 1,
        'max'   => 24,
    ),
),

In addition, you can change the attributes of the following container elements by setting their key and passing a nested attribute array.

  • fieldrow - the td tag element containing the field output.
  • fieldset - the fieldset tag element containing the field output.
  • fields - the div tag element containing the sub-fields and the main field.
  • field - the div tag element containing each field.

This submit button will float right.

array(    
    'field_id'          => 'submit',
    'type'              => 'submit',
    'label'             => __( 'Save', 'task-scheduler' ),
    'label_min_width'   => 0,
    'attributes'        => array(
        'field' => array(
            'style' => 'float:right; clear:none; display: inline;',
        ),
    ),                    
)

For meta boxe and widget form fields (as they have a sligtly different styling than generic admin pages),

array(
    'field_id'          => 'submit_in_meta_box',
    'type'              => 'submit',
    'show_title_column' => false,
    'label_min_width'   => 0,
    'attributes'        => array(
        'field' => array(
            'style' => 'float:right; width:auto;',
        ),                   
    ),
),

Change Preview Image Size of the 'image' Field Type

To specify a custom size to the preview element of the image field type, set an attribute array like the below, where 300px is the max width.

array(
    'field_id'      => 'my_image_field_id',
    'title'         => __( 'Image', 'admin-page-framework-demo' ),
    'type'          => 'image',
    'attributes'    => array(
        'preview' => array(
            'style' => 'max-width: 200px;',
        ),
    ),
),

Display items of 'radio' field type one per line

To display radio button items one per line, set the label_min_width to 100%.

array(
    'field_id'          => 'my_radio_field_id',
    'title'             => __( 'Radio Button', 'admin-page-framework-demo' ),
    'type'              => 'radio',
    'label_min_width'   => '100%',
    'label'             => array(
        'a' => __( 'This is a.', 'admin-page-framework-demo' ),
        'b' => __( 'This is b.', 'admin-page-framework-demo' ),
        'c' => __( 'This is a.', 'admin-page-framework-demo' )c
    ),
),

Set default field value

To set the initial value of a field, use the default argument in the field definition array.

array(
    'field_id'  => 'my_text_field_id',
    'title'     => __( 'My Text Input Field', 'admin-page-framework-demo' ),
    'type'      => 'text',
    'default'   => 'This text will be displayed for the first time that the field is displayed and will be overridden when a user set an own value.',
),

Always display a particular value in a field

The value argument in the definition array can suppress the saved value. This is useful when you want to set a value from a different data source or create a wizard form that stores the data in a custom location.

array(
    'field_id'  => 'my_text_field_id',
    'title'     => __( 'My Text Input Field', 'admin-page-framework-demo' ),
    'type'      => 'text',
    'value'     => 'This will be always set.',
),

If it is a repeatable field, set the value in the sub-fields.

array(
    'field_id'      => 'my_text_field_id',
    'title'         => __( 'My Text Input Field', 'admin-page-framework-demo' ),
    'type'          => 'text',
    'repeatable'    => true,
    'value'         => 'the first value',
    array(
        'value' => 'the second value',
    ),
    array(
        'value' => 'the third value',
    ),    
),

Alternately, if it is in a framework's generic pages (not post meta box fields) you may use the options_{instantiated class name} filter to suppress the options so that setting the value argument is not necessary. See examples, https://gist.github.com/michaeluno/c30713fcfe0d9d45d89f, https://gist.github.com/michaeluno/fcfac27825aa8a35b90f,

Roadmap

Check out the issues on GitHub labeled enhancement.

Requires: 3.3 or higher
Compatible up to: 4.1.1
Last Updated: 2015-3-15
Active Installs: 200+

Ratings

5 out of 5 stars

Support

2 of 2 support threads in the last two months have been resolved.

Got something to say? Need help?

Compatibility

+
=
Not enough data

0 people say it works.
0 people say it's broken.

100,1,1 100,1,1 100,1,1 100,1,1 100,1,1
100,1,1
100,2,2 100,1,1 100,1,1
100,1,1 100,1,1 100,1,1
100,1,1
100,1,1
100,1,1 100,1,1 100,1,1 100,1,1
100,1,1 100,1,1
100,3,3 100,1,1 100,1,1
100,1,1
100,1,1 100,1,1 100,1,1
100,1,1 100,1,1
100,1,1 100,1,1 100,1,1 100,1,1 100,1,1 100,1,1 100,1,1 100,1,1
100,1,1 100,1,1 100,1,1 100,1,1 100,1,1
100,2,2 100,1,1 100,1,1 100,1,1 100,1,1
100,1,1 100,1,1 100,1,1