$oScreen
$oScreen : object
Stores the screen object.
Provides methods to add form elements with WordPress Settings API.
registerSettings() : void
Registers the setting sections and fields.
This methods passes the stored section and field array contents to the add_settings_section() and add_settings_fields() functions. Then perform register_setting().
The filters will be applied to the section and field arrays; that means that third-party scripts can modify the arrays. Also they get sorted before being registered based on the set order.
finalizeInPageTabs() : void
Finalizes the in-page tab property array.
This finalizes the added in-page tabs and sets the default in-page tab for each page. Also this sorts the in-page tab property array. This must be done before registering settings sections because the default tab needs to be determined in the process.
setSettingNotice(string $strMsg, string $strType, string $strID, integer $fOverride) : void
Sets the given message to be displayed in the next page load.
This is used to inform users about the submitted input data, such as "Updated successfully." or "Problem occurred." etc. and normally used in validation callback methods.
if ( ! $fVerified ) {
$this->setFieldErrors( $arrErrors );
$this->setSettingNotice( 'There was an error in your input.' );
return $arrOldPageOptions;
}
| string | $strMsg | the text message to be displayed. |
| string | $strType | ( optional ) the type of the message, either "error" or "updated" is used. |
| string | $strID | ( optional ) the ID of the message. This is used in the ID attribute of the message HTML element. |
| integer | $fOverride | ( optional ) false: do not override when there is a message of the same id. true: override the previous one. |
addSettingSections(array $arrSection1, array $arrSection2, array $_and_more) : void
Adds the given form section items into the property.
The passed section array must consist of the following keys.
Section Array
$this->addSettingSections(
array(
'strSectionID' => 'text_fields',
'strPageSlug' => 'first_page',
'strTabSlug' => 'textfields',
'strTitle' => 'Text Fields',
'strDescription' => 'These are text type fields.',
'numOrder' => 10,
),
array(
'strSectionID' => 'selectors',
'strPageSlug' => 'first_page',
'strTabSlug' => 'selectors',
'strTitle' => 'Selectors and Checkboxes',
'strDescription' => 'These are selector type options such as dropdown lists, radio buttons, and checkboxes',
)
| array | $arrSection1 | the section array. |
| array | $arrSection2 | ( optional ) another section array. |
| array | $_and_more | ( optional ) add more section array to the next parameters as many as necessary. |
removeSettingSections(string $strSectionID1, string $strSectionID2, string $_and_more) : void
Removes the given section(s) by section ID.
This accesses the property storing the added section arrays and removes the specified ones.
$this->removeSettingSections( 'text_fields', 'selectors', 'another_section', 'yet_another_section' );
| string | $strSectionID1 | the section ID to remove. |
| string | $strSectionID2 | ( optional ) another section ID to remove. |
| string | $_and_more | ( optional ) add more section IDs to the next parameters as many as necessary. |
addSettingFields(array $arrField1, array $arrField2, array $_and_more) : void
Adds the given field array items into the field array property.
The passed field array must consist of the following keys.
label tag so the passed HTML string should not contain block elements.label tag so the passed HTML string should not contain block elements.120.Each field type uses specific array keys.
_WP_Editors class defined in the core.
For more information, see the argument section of this page.
array( 'px' => 'px', '%' => '%', 'em' => 'em' )
Default: array( 'px' => 'px', '%' => '%', 'em' => 'em', 'ex' => 'ex', 'in' => 'in', 'cm' => 'cm', 'mm' => 'mm', 'pt' => 'pt', 'pc' => 'pc' )
audio/*|video/*|image/*|MIME_typeaudio/*|video/*|image/*|MIME_typeimport'arrCaptureAttributes' => array( 'id', 'caption', 'description' )'arrCaptureAttributes' => array( 'id', 'caption', 'description' )array( 'revision', 'attachment', 'nav_menu_item' )$this->addSettingFields(
array( // Single text field
'strFieldID' => 'text',
'strSectionID' => 'text_fields',
'strTitle' => __( 'Text', 'admin-page-framework-demo' ),
'strDescription' => __( 'Type something here.', 'admin-page-framework-demo' ), // additional notes besides the form field
'strType' => 'text',
'numOrder' => 1,
'vDefault' => 123456,
'vSize' => 40,
),
array( // Multiple text fields
'strFieldID' => 'text_multiple',
'strSectionID' => 'text_fields',
'strTitle' => 'Multiple Text Fields',
'strDescription' => 'These are multiple text fields.', // additional notes besides the form field
'strType' => 'text',
'numOrder' => 2,
'vDefault' => array(
'Hello World',
'Foo bar',
'Yes, we can.'
),
'vLabel' => array(
'First Item: ',
'Second Item: ',
'Third Item: '
),
'vSize' => array(
30,
60,
90,
),
)
);
| array | $arrField1 | the field array. |
| array | $arrField2 | ( optional ) another field array. |
| array | $_and_more | ( optional ) add more field arrays to the next parameters as many as necessary. |
removeSettingFields(string $strFieldID1, string $strFieldID2, string $_and_more) : void
Removes the given field(s) by field ID.
This accesses the property storing the added field arrays and removes the specified ones.
$this->removeSettingFields( 'fieldID_A', 'fieldID_B', 'fieldID_C', 'fieldID_D' );
| string | $strFieldID1 | the field ID to remove. |
| string | $strFieldID2 | ( optional ) another field ID to remove. |
| string | $_and_more | ( optional ) add more field IDs to the next parameters as many as necessary. |
setFieldErrors(array $arrErrors, string $strID, integer $numSavingDuration)
Sets the field error array.
This is normally used in validation callback methods. when submitted data have an issue. This method saves the given array in a temporary area( transient ) of the options database table.
public function validation_first_page_verification( $arrInput, $arrOldPageOptions ) { // valication_ + page slug + _ + tab slug
$fVerified = true;
$arrErrors = array();
// Check if the submitted value meets your criteria. As an example, here a numeric value is expected.
if ( isset( $arrInput['first_page']['verification']['verify_text_field'] ) && ! is_numeric( $arrInput['first_page']['verification']['verify_text_field'] ) ) {
// Start with the section key in $arrErrors, not the key of page slug.
$arrErrors['verification']['verify_text_field'] = 'The value must be numeric: ' . $arrInput['first_page']['verification']['verify_text_field'];
$fVerified = false;
}
// An invalid value is found.
if ( ! $fVerified ) {
// Set the error array for the input fields.
$this->setFieldErrors( $arrErrors );
$this->setSettingNotice( 'There was an error in your input.' );
return $arrOldPageOptions;
}
return $arrInput;
}
| array | $arrErrors | the field error array. The structure should follow the one contained in the submitted $_POST array. |
| string | $strID | this should be the page slug of the page that has the dealing form field. |
| integer | $numSavingDuration | the transient's lifetime. 300 seconds means 5 minutes. |
setRootMenuPage(string $strRootMenuLabel, string $strURLIcon16x16, string $intMenuPosition) : void
Sets to which top level page is going to be adding sub-pages.
$this->setRootMenuPage( 'Settings' );
$this->setRootMenuPage(
'APF Form',
plugins_url( 'image/screen_icon32x32.jpg', FILE )
);
| string | $strRootMenuLabel | If the method cannot find the passed string from the following listed items, it will create a top level menu item with the passed string. ( case insensitive ) Dashboard, Posts, Media, Links, Pages, Comments, Appearance, Plugins, Users, Tools, Settings, Network Admin |
| string | $strURLIcon16x16 | ( optional ) the URL or the file path of the menu icon. The size should be 16 by 16 in pixel. |
| string | $intMenuPosition | ( optional ) the position number that is passed to the $position parameter of the add_menu_page() function. |
setRootMenuPageBySlug(string $strRootMenuSlug) : void
Sets the top level menu page by page slug.
The page should be already created or scheduled to be created separately.
$this->setRootMenuPageBySlug( 'edit.php?post_type=apf_posts' );
| string | $strRootMenuSlug | The page slug of the top-level root page. |
addSubMenuPage(string $strPageTitle, string $strPageSlug, string $strScreenIcon, string $strCapability, integer $numOrder, boolean $fShowPageHeadingTab, boolean $fShowInMenu) : void
Adds a single sub-menu page.
$this->addSubMenuPage( 'My Page', 'my_page', 'edit-pages' );
| string | $strPageTitle | The title of the page. |
| string | $strPageSlug | The slug of the page. |
| string | $strScreenIcon | ( optional ) Either a screen icon ID, a url of the icon, or a file path to the icon, with the size of 32 by 32 in pixel. The accepted icon IDs are as follows. edit, post, index, media, upload, link-manager, link, link-category, edit-pages, page, edit-comments, themes, plugins, users, profile, user-edit, tools, admin, options-general, ms-admin, generic Note: the generic ID is available since WordPress 3.5. |
| string | $strCapability | ( optional ) The access level to the page. |
| integer | $numOrder | ( optional ) the order number of the page. The lager the number is, the lower the position it is placed in the menu. |
| boolean | $fShowPageHeadingTab | ( optional ) If this is set to false, the page title won't be displayed in the page heading tab. Default: true. |
| boolean | $fShowInMenu | ( optional ) If this is set to false, the page title won't be displayed in the sidebar menu while the page is still accessible. Default: true. |
showPageHeadingTabs(boolean $fShow, string $strPageSlug)
Sets whether page-heading tabs are displayed or not.
$this->showPageHeadingTabs( false ); // disables the page heading tabs by passing false.
| boolean | $fShow | If false, page-heading tabs will be disabled; otherwise, enabled. |
| string | $strPageSlug | The page to apply the visibility setting. If not set, it applies to all the pages. |
showInPageTabs(boolean $fShow, string $strPageSlug)
Sets whether in-page tabs are displayed or not.
Sometimes, it is required to disable in-page tabs in certain pages. In that case, use the second parameter.
| boolean | $fShow | If false, in-page tabs will be disabled. |
| string | $strPageSlug | The page to apply the visibility setting. If not set, it applies to all the pages. |
setPageHeadingTabTag(string $strTag, string $strPageSlug)
Sets page-heading tab's HTML tag.
$this->setPageHeadingTabTag( 'h2' );
| string | $strTag | The HTML tag that encloses the page-heading tab title. Default: h2. |
| string | $strPageSlug | The page slug that applies the setting. |
addInPageTab(string $strPageSlug, string $strTabTitle, string $strTabSlug, integer $numOrder, boolean $fHide, string $strParentTabSlug) : void
Adds an in-page tab.
| string | $strPageSlug | The page slug that the tab belongs to. |
| string | $strTabTitle | The title of the tab. |
| string | $strTabSlug | The tab slug. Non-alphabetical characters should not be used including dots(.) and hyphens(-). |
| integer | $numOrder | ( optional ) the order number of the tab. The lager the number is, the lower the position it is placed in the menu. |
| boolean | $fHide | ( optional ) default: false. If this is set to false, the tab title will not be displayed in the tab navigation menu; however, it is still accessible from the direct URL. |
| string | $strParentTabSlug | ( optional ) this needs to be set if the above fHide is true so that the parent tab will be emphasized as active when the hidden page is accessed. |
addInPageTabs(array $arrTab1, array $arrTab2, array $_and_more) : void
Adds in-page tabs.
The parameters accept in-page tab arrays and they must have the following array keys.
$this->addInPageTabs(
array(
'strTabSlug' => 'firsttab',
'strTitle' => __( 'Text Fields', 'my-text-domain' ),
'strPageSlug' => 'myfirstpage'
),
array(
'strTabSlug' => 'secondtab',
'strTitle' => __( 'Selectors and Checkboxes', 'my-text-domain' ),
'strPageSlug' => 'myfirstpage'
)
);
| array | $arrTab1 | The in-page tab array. |
| array | $arrTab2 | Another in-page tab array. |
| array | $_and_more | Add in-page tab arrays as many as necessary to the next parameters. |
addHelpTab(array $arrHelpTab) : void
Adds the given contextual help tab contents into the property.
$this->addHelpTab(
array(
'strPageSlug' => 'first_page', // ( mandatory )
// 'strPageTabSlug' => null, // ( optional )
'strHelpTabTitle' => 'Admin Page Framework',
'strHelpTabID' => 'admin_page_framework', // ( mandatory )
'strHelpTabContent' => __( 'This contextual help text can be set with the addHelpTab() method.', 'admin-page-framework' ),
'strHelpTabSidebarContent' => __( 'This is placed in the sidebar of the help pane.', 'admin-page-framework' ),
)
);
| array | $arrHelpTab | The help tab array. The key structure is explained in the description part. |
setHelpTab( $strID, $strTitle, $arrContents, $arrSideBarContents)
Sets the contextual help tab.
On contrary to other methods relating to contextual help tabs that just modify the class properties, this finalizes the help tab contents. In other words, the set values here will take effect.
| $strID | ||
| $strTitle | ||
| $arrContents | ||
| $arrSideBarContents |
getPressedCustomSubmitButtonSiblingValue( $arrPostElements, $strTargetKey) : mixed
Retrieves the target key's value associated with the given data to a custom submit button.
This method checks if the associated submit button is pressed with the input fields.
| $arrPostElements | ||
| $strTargetKey |
Returns null if no button is found and the associated link url if found. Otherwise, the URL associated with the button.
getFilteredOptions( $arrInput, $strPageSlug, $strTabSlug, $strPressedFieldID, $strPressedInputID) : array
Apples validation filters to the submitted input data.
| $arrInput | ||
| $strPageSlug | ||
| $strTabSlug | ||
| $strPressedFieldID | ||
| $strPressedInputID |
The filtered input array.
getPageOptions( $strPageSlug) : array
Retrieves the stored options of the given page slug.
Other pages' option data will not be contained in the returning array. This is used to pass the old option array to the validation callback method.
| $strPageSlug |
the stored options of the given page slug. If not found, an empty array will be returned.
getOtherTabOptions( $strPageSlug, $arrSectionKeysForTheTab) : array
Retrieves the stored options excluding the currently specified tab's sections and their fields.
This is used to merge the submitted form data with the previously stored option data of the form elements that belong to the in-page tab of the given page.
| $strPageSlug | ||
| $arrSectionKeysForTheTab |
the stored options excluding the currently specified tab's sections and their fields. If not found, an empty array will be returned.
getOtherPageOptions( $strPageSlug) : array
Retrieves the stored options excluding the key of the given page slug.
This is used to merge the submitted form input data with the previously stored option data except the given page.
| $strPageSlug |
the array storing the options excluding the key of the given page slug.