|
| 1 | +Title: Admin Pages |
| 2 | +Description: Making and adding admin pages to the WordPress admin. |
| 3 | + |
| 4 | +--- |
| 5 | + |
| 6 | +## Admin Pages |
| 7 | + |
| 8 | +Admin pages are located in the WordPress admin in the main sidebar navigation. Admin pages can be used for any purpose. Commonly they are for building custom functionality that requires it's own administrative section. |
| 9 | + |
| 10 | +## Adding an Admin Page |
| 11 | + |
| 12 | +To register an "Admin Page" in WordPress, you only need one line of code. |
| 13 | + |
| 14 | +```php |
| 15 | +tr_page('Api', 'view', 'APIs Page'); |
| 16 | +``` |
| 17 | + |
| 18 | +Or, the same using OOP. |
| 19 | + |
| 20 | +```php |
| 21 | +\TypeRocket\Register\Page::add('Api', 'view', 'APIs Page'); |
| 22 | +``` |
| 23 | + |
| 24 | +This one line of code adds the "Admin Page" to the WordPress admin, sets all the correct labels in the navigation and applicable places, and implements the required WordPress hooks. This would typically take many lines of code. |
| 25 | + |
| 26 | +! **Note**: By default, anyone who is logged-in with the capability `administrator` can view a page. You can change this later. |
| 27 | + |
| 28 | +### Function Arguments |
| 29 | + |
| 30 | +The `tr_page()` function takes 4 arguments: |
| 31 | + |
| 32 | +1. `$resource` - A string set to the resource or section the page belongs to. |
| 33 | +2. `$action` - A string set to the action the page is responsible for. |
| 34 | +3. `$title` - A string set to the title of the page and menu. |
| 35 | +4. `$settings` - (optional) Array with keys `menu`, `capability`, `position`, `view`, `slug`. |
| 36 | +5. `$handler` - (optional) A controller class name as a string or callable to handle the request. |
| 37 | + |
| 38 | +Take a look at creating an admin page. |
| 39 | + |
| 40 | +```php |
| 41 | +$settings = ['capability' => 'administrator']; |
| 42 | +$seat_index = tr_page('Seat', 'index', 'Plane Seats', $settings); |
| 43 | +``` |
| 44 | + |
| 45 | +Or, a page with a custom function handler. |
| 46 | + |
| 47 | +```php |
| 48 | +$settings = ['capability' => 'read']; |
| 49 | +$fn = function() { |
| 50 | + return 'hi'; |
| 51 | +}; |
| 52 | + |
| 53 | +tr_page('Api', 'view', 'APIs Page', $settings, $fn); |
| 54 | +``` |
| 55 | + |
| 56 | +Or, with a controller. |
| 57 | + |
| 58 | +```php |
| 59 | +$settings = ['capability' => 'read']; |
| 60 | +$controller = '\MyPlugin\Controllers\ApiController'; |
| 61 | +tr_page('Api', 'view', 'APIs Page', $settings, $controller); |
| 62 | +// Calls the `view` method on the controller |
| 63 | +``` |
| 64 | + |
| 65 | +## Set Icon |
| 66 | + |
| 67 | +To set an icon for the admin page use the `setIcon()` method. Use a [WordPress dashicon](https://developer.wordpress.org/resource/dashicons/#heart). |
| 68 | + |
| 69 | +```php |
| 70 | +$seat_index->setIcon('dashicons-heart'); |
| 71 | +``` |
| 72 | + |
| 73 | +## Set Parent Pages |
| 74 | + |
| 75 | +To set a parent page use the `setParent()` method. |
| 76 | + |
| 77 | +```php |
| 78 | +$settings = ['capability' => 'editor']; |
| 79 | +$add_seat = tr_page('Seat', 'add', 'Add Seat', $settings); |
| 80 | +$add_seat->setParent($seat_index); |
| 81 | +``` |
| 82 | + |
| 83 | +! **Note**: By default, child pages will inherit the parent pages permission or capability settings unless the child has a capability set. |
| 84 | + |
| 85 | +## Add Child Page |
| 86 | + |
| 87 | +You can set child page with the `addPage()` and `apply()` methods. |
| 88 | + |
| 89 | +### Using Add Page |
| 90 | + |
| 91 | +```php |
| 92 | +$settings = ['capability' => 'administrator']; |
| 93 | +$add_seat = tr_page('Seat', 'add', 'Add Seat', $settings); |
| 94 | +$seat_index->addPage($add_seat); |
| 95 | +``` |
| 96 | + |
| 97 | +### Using Apply |
| 98 | + |
| 99 | +```php |
| 100 | +$settings = ['capability' => 'administrator']; |
| 101 | +$add_seat = tr_page('Seat', 'add', 'Add Seat', $settings); |
| 102 | +$seat_index->apply($add_seat); |
| 103 | +``` |
| 104 | + |
| 105 | +## "Add New" Page Button |
| 106 | + |
| 107 | +If you have a page with the action "add" you can use the `addNewButton()` to have an add button appear at the top of related admin pages. |
| 108 | + |
| 109 | +```php |
| 110 | +$seat_index->addNewButton(); |
| 111 | +``` |
| 112 | + |
| 113 | +This will add an "Add New" button to the top of the seat index page and automatically find the page with the "add" action and link the button to it. |
| 114 | + |
| 115 | +## Add To Admin Bar |
| 116 | + |
| 117 | +To add a page to the admin bar use the `adminBar()` method. By default, this will place items under the "New" dropdown. |
| 118 | + |
| 119 | +```php |
| 120 | +$add_seat->adminBar('add_seat_page'); |
| 121 | +``` |
| 122 | + |
| 123 | +The `adminBar()` method takes 3 arguments: |
| 124 | + |
| 125 | +1. `$id` - The ID to use in the admin bar for the menu. |
| 126 | +2. `$title` - The title of the admin bar link. |
| 127 | +3. `$parent_id` - The ID of the parent item in the admin bar. |
| 128 | + |
| 129 | +## Set Controller |
| 130 | + |
| 131 | +To have an admin page use a controller pass to the `setHandler()` method the class name as a string. For example, if the add seat page calls the `setHandler()` method it will use the `SeatController`. |
| 132 | + |
| 133 | +```php |
| 134 | +$add_seat->setHandler(\App\Controllers\SeatController::class); |
| 135 | +``` |
| 136 | + |
| 137 | +By default, the mapped action is used based on the response type. We will get into mapping actions soon. For now, know the action is the method the controller will call. |
| 138 | + |
| 139 | +### Make Controller |
| 140 | + |
| 141 | +If you're are using a controller for your pages you need to create a controller. To make a seat controller and model for the "Seat" resource use the TypeRocket Galaxy CLI. |
| 142 | + |
| 143 | +```bash |
| 144 | +php galaxy make:model -c base Seat |
| 145 | +``` |
| 146 | + |
| 147 | +! **Note**: Pages work best with controllers so reach for them. |
| 148 | + |
| 149 | +### Map Actions |
| 150 | + |
| 151 | +To take full advantage of the controller, you can map HTTP request methods to specific class functions on the controller. You will need to map actions that are not `add`, `index`, `delete`, `edit`, `create`, `update`, or `show` since only these are mapped automatically. |
| 152 | + |
| 153 | +```php |
| 154 | +$settings = ['capability' => 'administrator']; |
| 155 | +$seat_ticket = tr_page('Seat', 'ticket', 'Tickets', $settings); |
| 156 | +$seat_ticket->setHandler(\App\Controllers\SeatController::class); |
| 157 | +$seat_ticket->mapAction('GET', 'ticket'); |
| 158 | +$seat_ticket->mapAction('POST', 'create_ticket'); |
| 159 | +``` |
| 160 | + |
| 161 | +When using admin pages your options for controllers are somewhat limited, due to the pattern WordPress uses for making routes within the `wp-admin`. The `mapAction` method allows you to take more control over how the admin routes HTTP requests to your controller class. |
| 162 | + |
| 163 | +## Remove Menu |
| 164 | + |
| 165 | +There are times when you want to add a page as a child page but not have it appear in the admin menu. To accomplish this use the `removeMenu()` method. |
| 166 | + |
| 167 | +```php |
| 168 | +// create page |
| 169 | +$settings = ['capability' => 'administrator']; |
| 170 | +$view_seat = tr_page('Seat', 'view', 'View Seat', $settings); |
| 171 | + |
| 172 | +// remove menu |
| 173 | +$view_seat->removeMenu(); |
| 174 | + |
| 175 | +// add as child page |
| 176 | +$seat->apply($view_seat); |
| 177 | +``` |
| 178 | + |
| 179 | +## Arguments |
| 180 | + |
| 181 | +There are five methods for dealing with arguments. Arguments are used when the page is being registered. The available arguments are: `menu`, `capability`, `inherit_capability`, `position`, `view_file`, and `slug`. |
| 182 | + |
| 183 | +These methods are: `getArguments()`, `setArguments()`, `getArgument()`, `setArgument()` and `removeArgument()`. |
| 184 | + |
| 185 | +1. `getArguments()` returns the full array of arguments. |
| 186 | +2. `setArguments()` takes an array of arguments. |
| 187 | +3. `getArgument()` return an argument by its key. |
| 188 | +4. `setArgument()` sets an argument by a key. |
| 189 | +5. `removeArgument()` removes an argument by its key. |
| 190 | + |
| 191 | +Take a look at using all the methods without affecting the already set values. |
| 192 | + |
| 193 | +```php |
| 194 | +$args = $book->getArguments(); |
| 195 | +$args = array_merge( $args, [ 'position' => 20 ] ); |
| 196 | +$book->setArguments( $args ); |
| 197 | +$public = $book->getArgument( 'position' ); |
| 198 | +$book->removeArgument( 'position' ); |
| 199 | +$book->setArgument( 'position', 20 ); |
| 200 | +``` |
| 201 | + |
| 202 | +## Position |
| 203 | + |
| 204 | +A parent page is placed in the menu based on its `position` argument. By default, the position is '25`. You see a list of [menu positions in the WordPress developer reference guide](https://developer.wordpress.org/reference/functions/add_menu_page/#menu-structure). |
| 205 | + |
| 206 | +- `2` for Dashboard |
| 207 | +- `4` for Separator |
| 208 | +- `5` for Posts |
| 209 | +- `10` for Media |
| 210 | +- `15` for Links |
| 211 | +- `20` for Pages |
| 212 | +- `25` for Comments |
| 213 | +- `59` for Separator |
| 214 | +- `60` for Appearance |
| 215 | +- `65` for Plugins |
| 216 | +- `70` for Users |
| 217 | +- `75` for Tools |
| 218 | +- `80` for Settings |
| 219 | +- `99` for Separator |
| 220 | + |
| 221 | +```php |
| 222 | +$page->setPosition(25); |
| 223 | +``` |
| 224 | + |
| 225 | +## Capability |
| 226 | + |
| 227 | +Set the `capability` setting to a value from the [WordPress capability levels](https://codex.wordpress.org/Roles_and_Capabilities). This will restrict access to the page based on the permissions level. |
| 228 | + |
| 229 | +You can also set the values to a role level. This is many times the simplest and most effective method. The role levels are: |
| 230 | + |
| 231 | +- `administrator` |
| 232 | +- `editor` |
| 233 | +- `author` |
| 234 | +- `contributor` |
| 235 | +- `subscriber` |
| 236 | + |
| 237 | +```php |
| 238 | +$page->setCapability('administrator'); |
| 239 | +``` |
| 240 | + |
| 241 | +### Inherit Capability |
| 242 | + |
| 243 | +By default, the `inherit_capability` setting is set to true. If a page is a child page, and it has this setting, it will inherit the parent pages `capability` setting if the child page has no capability set. |
| 244 | + |
| 245 | +## Titles |
| 246 | + |
| 247 | +The `menu` argument setting controls the menu title. This is not the page title. |
| 248 | + |
| 249 | +You can also use these methods to control the titles used by an admin page. |
| 250 | + |
| 251 | +```php |
| 252 | +$page->setTitle('Page Title'); |
| 253 | +$page->setMenuTitle('Main Menu'); |
| 254 | +$page->setSubMenuTitle('Sub Menu'); // If is sub page |
| 255 | +``` |
| 256 | + |
| 257 | +## Views |
| 258 | + |
| 259 | +The `view` setting controls what file will be used as the page's template. You can use the `View` using `tr_view()`. Also, you can pass callable, file path, or text block. |
| 260 | + |
| 261 | +```php |
| 262 | +$view = tr_view('my.view', ['name' => 'Kevin']); |
| 263 | +$page->setView($view); |
| 264 | +``` |
| 265 | + |
| 266 | +```php |
| 267 | +$fn = function() { |
| 268 | + return 'Hi!'; |
| 269 | +}; |
| 270 | +$page->setView($fn); |
| 271 | +``` |
| 272 | + |
| 273 | +```php |
| 274 | +$view = __DIR__ . '/my-file.php'; |
| 275 | +$page->setView($view); |
| 276 | +``` |
| 277 | + |
| 278 | +```php |
| 279 | +$page->setView('Hi there'); |
| 280 | +``` |
| 281 | + |
| 282 | +## Set Slug |
| 283 | + |
| 284 | +The `slug` setting controller the admin pages URL "page" parameter. For example, a slug with the value of "my_page" will appear in the URL as `http://example.com/wp-admin/admin.php?page=my_page`. |
| 285 | + |
| 286 | +```php |
| 287 | +$page->setSlug('my_page'); |
| 288 | +``` |
0 commit comments