michaeluno /
admin-page-framework
| 1 | <?php |
||
| 18 | abstract class AdminPageFramework_Controller extends AdminPageFramework_View { |
||
|
1 ignored issue
–
show
|
|||
| 19 | |||
| 20 | /** |
||
| 21 | * Called when one of the added admin page starts loading. |
||
| 22 | * |
||
| 23 | * Alternatively the user may use the `load_{instantiated class name}` action hook and its auto-callback method. |
||
| 24 | * |
||
| 25 | * @since 3.7.12 |
||
| 26 | * @return void |
||
| 27 | */ |
||
| 28 | public function load() {} |
||
| 29 | |||
| 30 | /** |
||
| 31 | * The method for all the necessary set-ups. |
||
| 32 | * |
||
| 33 | * The users should override this method to set-up necessary settings. To perform certain tasks prior to this method, use the `start_{instantiated class name}` hook that is triggered at the end of the class constructor. |
||
| 34 | * |
||
| 35 | * <h4>Example</h4> |
||
| 36 | * <code>public function setUp() { |
||
| 37 | * $this->setRootMenuPage( 'APF Form' ); |
||
| 38 | * $this->addSubMenuItems( |
||
| 39 | * array( |
||
| 40 | * 'title' => 'Form Fields', |
||
| 41 | * 'page_slug' => 'apf_form_fields', |
||
| 42 | * ) |
||
| 43 | * ); |
||
| 44 | * }</code> |
||
| 45 | * @abstract |
||
| 46 | * @since 2.0.0 |
||
| 47 | * @since 3.3.1 Moved from `AdminPageFramework`. |
||
| 48 | * @remark This is a callback for the `wp_loaded` hook. |
||
| 49 | * @remark In v1, this is triggered with the `admin_menu` hook; however, in v2, this is triggered with the `wp_loaded` hook. |
||
| 50 | * @access public |
||
| 51 | * @return void |
||
| 52 | */ |
||
| 53 | public function setUp() {} |
||
| 54 | |||
| 55 | /* |
||
| 56 | * Help Pane Methods |
||
| 57 | */ |
||
| 58 | |||
| 59 | /** |
||
| 60 | * Adds the given contextual help tab contents into the property. |
||
| 61 | * |
||
| 62 | * <h4>Example</h4> |
||
| 63 | * <code> $this->addHelpTab( |
||
| 64 | * array( |
||
| 65 | * 'page_slug => 'first_page', // (required) |
||
| 66 | * // 'page_tab_slug' => null, // (optional) |
||
| 67 | * 'help_tab_title' => 'Admin Page Framework', |
||
| 68 | * 'help_tab_id' => 'admin_page_framework', // (required) |
||
| 69 | * 'help_tab_content' => __( 'This contextual help text can be set with the `addHelpTab()` method.', 'admin-page-framework' ), |
||
| 70 | * 'help_tab_sidebar_content' => __( 'This is placed in the sidebar of the help pane.', 'admin-page-framework' ), |
||
| 71 | * ) |
||
| 72 | * );</code> |
||
| 73 | * |
||
| 74 | * @since 2.1.0 |
||
| 75 | * @since 3.3.1 Moved from `AdminPageFramework`. |
||
| 76 | * @remark Called when registering setting sections and fields. |
||
| 77 | * @param array The help tab array. |
||
| 78 | * <h4>Contextual Help Tab Array Structure</h4> |
||
| 79 | * <ul> |
||
| 80 | * <li>**page_slug** - (required) the page slug of the page that the contextual help tab and its contents are displayed.</li> |
||
| 81 | * <li>**page_tab_slug** - (optional) the tab slug of the page that the contextual help tab and its contents are displayed.</li> |
||
| 82 | * <li>**help_tab_title** - (required) the title of the contextual help tab.</li> |
||
| 83 | * <li>**help_tab_id** - (required) the id of the contextual help tab.</li> |
||
| 84 | * <li>**help_tab_content** - (optional) the HTML string content of the the contextual help tab.</li> |
||
| 85 | * <li>**help_tab_sidebar_content** - (optional) the HTML string content of the sidebar of the contextual help tab.</li> |
||
| 86 | * </ul> |
||
| 87 | * @return void |
||
| 88 | */ |
||
| 89 | public function addHelpTab( $aHelpTab ) { |
||
| 92 | |||
| 93 | /* |
||
| 94 | * Head Tag Methods |
||
| 95 | */ |
||
| 96 | /** |
||
| 97 | * Enqueues styles by page slug and tab slug. |
||
| 98 | * |
||
| 99 | * Use this method to pass multiple files to the same page. |
||
| 100 | * |
||
| 101 | * <h4>Example</h4> |
||
| 102 | * <code>$this->enqueueStyle( |
||
| 103 | * array( |
||
| 104 | * dirname( APFDEMO_FILE ) . '/asset/css/code.css', |
||
| 105 | * dirname( APFDEMO_FILE ) . '/asset/css/code2.css', |
||
| 106 | * ), |
||
| 107 | * 'apf_manage_options' // page slug |
||
| 108 | * );</code> |
||
| 109 | * |
||
| 110 | * @since 3.0.0 |
||
| 111 | * @since 3.3.1 Moved from `AdminPageFramework`. |
||
| 112 | * @param array $aSRCs The sources of the stylesheet to enqueue: the url, the absolute file path, or the relative path to the root directory of WordPress. Example: `array( '/css/mystyle.css', '/css/mystyle2.css' )` |
||
| 113 | * @param string $sPageSlug (optional) The page slug that the stylesheet should be added to. If not set, it applies to all the pages created by the framework. |
||
| 114 | * @param string $sTabSlug (optional) The tab slug that the stylesheet should be added to. If not set, it applies to all the in-page tabs in the page. |
||
| 115 | * @param array $aCustomArgs (optional) The argument array for more advanced parameters. |
||
| 116 | * @return array The array holing the queued items. |
||
| 117 | */ |
||
| 118 | public function enqueueStyles( $aSRCs, $sPageSlug='', $sTabSlug='', $aCustomArgs=array() ) { |
||
| 121 | /** |
||
| 122 | * Enqueues a style by page slug and tab slug. |
||
| 123 | * |
||
| 124 | * <h4>Example</h4> |
||
| 125 | * <code> |
||
| 126 | * $this->enqueueStyle( |
||
| 127 | * dirname( APFDEMO_FILE ) . '/asset/css/code.css', |
||
| 128 | * 'apf_manage_options' // page slug |
||
| 129 | * ); |
||
| 130 | * $this->enqueueStyle( |
||
| 131 | * plugins_url( 'asset/css/readme.css' , APFDEMO_FILE ), |
||
| 132 | * 'apf_read_me' // page slug |
||
| 133 | * ); |
||
| 134 | * </code> |
||
| 135 | * |
||
| 136 | * @since 2.1.2 |
||
| 137 | * @since 3.3.1 Moved from `AdminPageFramework`. |
||
| 138 | * @see http://codex.wordpress.org/Function_Reference/wp_enqueue_style |
||
| 139 | * @param string The source of the stylesheet to enqueue: the url, the absolute file path, or the relative path to the root directory of WordPress. Example: '/css/mystyle.css'. |
||
| 140 | * @param string $sPageSlug (optional) The page slug that the stylesheet should be added to. If not set, it applies to all the pages created by the framework. |
||
| 141 | * @param string $sTabSlug (optional) The tab slug that the stylesheet should be added to. If not set, it applies to all the in-page tabs in the page. |
||
| 142 | * @param array $aCustomArgs (optional) The argument array for more advanced parameters. |
||
| 143 | * <h4>Argument Array</h4> |
||
| 144 | * <ul> |
||
| 145 | * <li>**handle_id** - (optional, string) The handle ID of the stylesheet.</li> |
||
| 146 | * <li>**dependencies** - (optional, array) The dependency array. For more information, see <a href="http://codex.wordpress.org/Function_Reference/wp_enqueue_style">codex</a>.</li> |
||
| 147 | * <li>**version** - (optional, string) The stylesheet version number.</li> |
||
| 148 | * <li>**media** - (optional, string) the description of the field which is inserted into the after the input field tag.</li> |
||
| 149 | * <li>**attributes** - (optional, array) [3.3.0+] attributes array. `array( 'data-id' => '...' )`</li> |
||
| 150 | * </ul> |
||
| 151 | * @return string The style handle ID. If the passed url is not a valid url string, an empty string will be returned. |
||
| 152 | */ |
||
| 153 | public function enqueueStyle( $sSRC, $sPageSlug='', $sTabSlug='', $aCustomArgs=array() ) { |
||
| 156 | /** |
||
| 157 | * Enqueues scripts by page slug and tab slug. |
||
| 158 | * |
||
| 159 | * <h4>Example</h4> |
||
| 160 | * <code> |
||
| 161 | * $this->enqueueScripts( |
||
| 162 | * array( |
||
| 163 | * plugins_url( 'asset/js/test.js' , __FILE__ ), // source url or path |
||
| 164 | * plugins_url( 'asset/js/test2.js' , __FILE__ ), |
||
| 165 | * ) |
||
| 166 | * 'apf_read_me', // page slug |
||
| 167 | * ); |
||
| 168 | * </code> |
||
| 169 | * |
||
| 170 | * @since 2.1.5 |
||
| 171 | * @since 3.3.1 Moved from `AdminPageFramework`. |
||
| 172 | * @param array The sources of the stylesheets to enqueue: the URL, the absolute file path, or the relative path to the root directory of WordPress. Example: '/js/myscript.js'. |
||
| 173 | * @param string (optional) The page slug that the script should be added to. If not set, it applies to all the pages created by the framework. |
||
| 174 | * @param string (optional) The tab slug that the script should be added to. If not set, it applies to all the in-page tabs in the page. |
||
| 175 | * @param array (optional) The argument array for more advanced parameters. |
||
| 176 | * @return array The array holding the queued items. |
||
| 177 | */ |
||
| 178 | public function enqueueScripts( $aSRCs, $sPageSlug='', $sTabSlug='', $aCustomArgs=array() ) { |
||
| 181 | /** |
||
| 182 | * Enqueues a script by page slug and tab slug. |
||
| 183 | * |
||
| 184 | * <h4>Example</h4> |
||
| 185 | * <code>$this->enqueueScript( |
||
| 186 | * plugins_url( 'asset/js/test.js' , __FILE__ ), // source url or path |
||
| 187 | * 'apf_read_me', // page slug |
||
| 188 | * '', // tab slug |
||
| 189 | * array( |
||
| 190 | * 'handle_id' => 'my_script', // this handle ID also is used as the object name for the translation array below. |
||
| 191 | * 'translation' => array( |
||
| 192 | * 'a' => 'hello world!', |
||
| 193 | * 'style_handle_id' => $sStyleHandle, // check the enqueued style handle ID here. |
||
| 194 | * ), |
||
| 195 | * ) |
||
| 196 | * );</code> |
||
| 197 | * |
||
| 198 | * @since 2.1.2 |
||
| 199 | * @since 3.0.0 Changed the scope to public |
||
| 200 | * @since 3.3.1 Moved from `AdminPageFramework`. |
||
| 201 | * @see http://codex.wordpress.org/Function_Reference/wp_enqueue_script |
||
| 202 | * @param string The URL of the stylesheet to enqueue, the absolute file path, or the relative path to the root directory of WordPress. Example: '/js/myscript.js'. |
||
| 203 | * @param string (optional) The page slug that the script should be added to. If not set, it applies to all the pages created by the framework. |
||
| 204 | * @param string (optional) The tab slug that the script should be added to. If not set, it applies to all the in-page tabs in the page. |
||
| 205 | * @param array (optional) The argument array for more advanced parameters. |
||
| 206 | * <h4>Argument Array</h4> |
||
| 207 | * <ul> |
||
| 208 | * <li>**handle_id** - (optional, string) The handle ID of the script.</li> |
||
| 209 | * <li>**dependencies** - (optional, array) The dependency array. For more information, see <a href="http://codex.wordpress.org/Function_Reference/wp_enqueue_script">codex</a>.</li> |
||
| 210 | * <li>**version** - (optional, string) The stylesheet version number.</li> |
||
| 211 | * <li>**translation** - (optional, array) The translation array. The handle ID will be used for the object name.</li> |
||
| 212 | * <li>**in_footer** - (optional, boolean) Whether to enqueue the script before `</head>` or before`</body>` Default: `false`.</li> |
||
| 213 | * <li>**attributes** - (optional, array) [3.3.0+] attributes array. `array( 'data-id' => '...' )`</li> |
||
| 214 | * </ul> |
||
| 215 | * @return string The script handle ID. If the passed url is not a valid url string, an empty string will be returned. |
||
| 216 | */ |
||
| 217 | public function enqueueScript( $sSRC, $sPageSlug='', $sTabSlug='', $aCustomArgs=array() ) { |
||
| 220 | |||
| 221 | /** |
||
| 222 | * Adds the given link(s) into the description cell of the plugin listing table. |
||
| 223 | * |
||
| 224 | * <h4>Example</h4> |
||
| 225 | * <code>$this->addLinkToPluginDescription( |
||
| 226 | * "<a href='http://www.google.com'>Google</a>", |
||
| 227 | * "<a href='http://www.yahoo.com'>Yahoo!</a>" |
||
| 228 | * );</code> |
||
| 229 | * |
||
| 230 | * @since 2.0.0 |
||
| 231 | * @since 3.0.0 Changed the scope to public from protected. |
||
| 232 | * @since 3.3.1 Moved from `AdminPageFramework`. |
||
| 233 | * @remark Accepts variadic parameters; the number of accepted parameters are not limited to three. |
||
| 234 | * @param string the tagged HTML link text. |
||
| 235 | * @param string (optional) another tagged HTML link text. |
||
| 236 | * @param string (optional) add more as many as want by adding items to the next parameters. |
||
| 237 | * @access public |
||
| 238 | * @return void |
||
| 239 | */ |
||
| 240 | public function addLinkToPluginDescription( $sTaggedLinkHTML1, $sTaggedLinkHTML2=null, $_and_more=null ) { |
||
| 246 | |||
| 247 | /** |
||
| 248 | * Adds the given link(s) into the title cell of the plugin listing table. |
||
| 249 | * |
||
| 250 | * <h4>Example</h4> |
||
| 251 | * <code>$this->addLinkToPluginTitle( |
||
| 252 | * "<a href='http://www.wordpress.org'>WordPress</a>" |
||
| 253 | * );</code> |
||
| 254 | * |
||
| 255 | * @since 2.0.0 |
||
| 256 | * @since 3.0.0 Changed the scope to public from protected. |
||
| 257 | * @since 3.3.1 Moved from `AdminPageFramework`. |
||
| 258 | * @remark Accepts variadic parameters; the number of accepted parameters are not limited to three. |
||
| 259 | * @param string the tagged HTML link text. |
||
| 260 | * @param string (optional) another tagged HTML link text. |
||
| 261 | * @param string (optional) add more as many as want by adding items to the next parameters. |
||
| 262 | * @access public |
||
| 263 | * @return void |
||
| 264 | */ |
||
| 265 | public function addLinkToPluginTitle( $sTaggedLinkHTML1, $sTaggedLinkHTML2=null, $_and_more=null ) { |
||
| 273 | |||
| 274 | /** |
||
| 275 | * Sets the label applied to the settings link which automatically embedded to the plugin listing table of the plugin title cell. |
||
| 276 | * |
||
| 277 | * To disable the embedded settings link, pass an empty value. |
||
| 278 | * |
||
| 279 | * @since 3.1.0 |
||
| 280 | * @since 3.3.1 Moved from `AdminPageFramework`. |
||
| 281 | */ |
||
| 282 | public function setPluginSettingsLinkLabel( $sLabel ) { |
||
| 285 | |||
| 286 | /** |
||
| 287 | * Sets the overall capability. |
||
| 288 | * |
||
| 289 | * <h4>Example</h4> |
||
| 290 | * <code>$this->setCpability( 'read' ); // let subscribers access the pages. |
||
| 291 | * </code> |
||
| 292 | * |
||
| 293 | * @since 2.0.0 |
||
| 294 | * @since 3.0.0 Changed the scope to public from protected. |
||
| 295 | * @since 3.3.1 Moved from `AdminPageFramework`. |
||
| 296 | * @see http://codex.wordpress.org/Roles_and_Capabilities |
||
| 297 | * @param string The <a href="http://codex.wordpress.org/Roles_and_Capabilities">access level</a> for the created pages. |
||
| 298 | * @return void |
||
| 299 | * @access public |
||
| 300 | */ |
||
| 301 | public function setCapability( $sCapability ) { |
||
| 307 | |||
| 308 | /** |
||
| 309 | * Sets an admin notice. |
||
| 310 | * |
||
| 311 | * <h4>Example</h4> |
||
| 312 | * <code>$this->setAdminNotice( sprintf( 'Please click <a href="%1$s">here</a> to upgrade the options.', admin_url( 'admin.php?page="my_page"' ) ), 'updated' ); |
||
| 313 | * </code> |
||
| 314 | * |
||
| 315 | * @access public |
||
| 316 | * @remark It should be used before the 'admin_notices' hook is triggered. |
||
| 317 | * @since 2.1.2 |
||
| 318 | * @since 3.0.0 Changed the scope to public from protected. |
||
| 319 | * @since 3.3.1 Moved from `AdminPageFramework`. |
||
| 320 | * @param string The message to display |
||
| 321 | * @param string (optional) The class selector used in the message HTML element. 'error' and 'updated' are prepared by WordPress but it's not limited to them and can pass a custom name. Default: 'error'. |
||
| 322 | * @param string (optional) The ID of the message. If not set, the hash of the message will be used. |
||
| 323 | */ |
||
| 324 | public function setAdminNotice( $sMessage, $sClassSelector='error', $sID='' ) { |
||
| 345 | |||
| 346 | /** |
||
| 347 | * Sets the disallowed query keys in the links that the framework generates. |
||
| 348 | * |
||
| 349 | * <h4>Example</h4> |
||
| 350 | * <code>$this->setDisallowedQueryKeys( 'my-custom-admin-notice' ); |
||
| 351 | * </code> |
||
| 352 | * |
||
| 353 | * @since 2.1.2 |
||
| 354 | * @since 3.0.0 It also accepts a string. Changed the scope to public. |
||
| 355 | * @since 3.3.1 Moved from `AdminPageFramework`. |
||
| 356 | * @access public |
||
| 357 | * @param array|string The query key(s) to disallow. |
||
| 358 | * @param boolean If true, the passed key(s) will be appended to the property; otherwise, it will override the property. |
||
| 359 | * @return void |
||
| 360 | */ |
||
| 361 | public function setDisallowedQueryKeys( $asQueryKeys, $bAppend=true ) { |
||
| 374 | |||
| 375 | /** |
||
| 376 | * Retrieves the saved option value from the given option key and the dimensional array key representation. |
||
| 377 | * |
||
| 378 | * <h4>Example</h4> |
||
| 379 | * <code> |
||
| 380 | * $aData = AdminPageFramework::getOption( 'APF' ); |
||
| 381 | * $aSection = AdminPageFramework::getOption( 'APF', 'my_section' ); |
||
| 382 | * $sText = AdminPageFramework::getOption( 'APF', array( 'my_section', 'my_text_field' ), 'foo' ); |
||
| 383 | * $sColor = AdminPageFramework::getOption( 'APF', 'my_color_field', '#FFF' ); |
||
| 384 | * </code> |
||
| 385 | * |
||
| 386 | * @since 3.0.1 |
||
| 387 | * @since 3.3.1 Moved from `AdminPageFramework`. |
||
| 388 | * @param string $sOptionKey the option key of the options table. |
||
| 389 | * @param string $asKey the representation of dimensional array keys. If the returning option structure is like the following, |
||
| 390 | * <code> |
||
| 391 | * array( |
||
| 392 | * 'a' => array( |
||
| 393 | * 'b' => array( |
||
| 394 | * 'c' => 'ccc', |
||
| 395 | * ), |
||
| 396 | * ), |
||
| 397 | * ) |
||
| 398 | * </code> |
||
| 399 | * then the value 'ccc' can be retrieved with the key representation array of |
||
| 400 | * <code> |
||
| 401 | * array( 'a', 'b', 'c' ) |
||
| 402 | * </code> |
||
| 403 | * @param mixed $vDefault the default value that will be returned if nothing is stored. |
||
| 404 | * @return mixed If the field ID is not specified |
||
| 405 | */ |
||
| 406 | static public function getOption( $sOptionKey, $asKey=null, $vDefault=null ) { |
||
| 409 | |||
| 410 | } |
||
| 411 |
Loading history...
You can fix this by adding a namespace to your class:
When choosing a vendor namespace, try to pick something that is not too generic to avoid conflicts with other libraries.