Admin Pages

1. # About Admin Pages
2. # Adding an Admin Page
3. # Function Arguments
4. # Set Icon
5. # Set Parent Pages
6. # Add Child Page
7. # Using Add Page
8. # Using Apply
9. # "Add New" Page Button
10. # Add To Admin Bar
11. # Use Controller
12. # Make Controller
13. # Map Actions (Core 3.0.12+)
14. # Remove Menu
15. # Arguments
16. # Position
17. # Capability
18. # Inherit Capability
19. # Menu
20. # View File
21. # Slug

#About Admin Pages

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.

#Adding an Admin Page

To register an "Admin Page" in WordPress you only need one line of code.

tr_page('Api', 'view', 'APIs Page');

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 normally take many many lines of code.

Note: By default, anyone who is logged in with the capability administrator can view a page. You can change this later.

#Function Arguments

The tr_page() function takes 4 arguments:

1. $resource - A string set to the resource or section the page belongs to.
2. $action - A string set to the action the page is responsible for.
3. $title - A string set to the title of the page and menu.
4. $settings - Array menu, capability, position, view, slug.

Take a look at creating an admin page.

$settings = ['capability' => 'administrator'];
$seat_index = tr_page('Seat', 'index', 'Plane Seats', $settings);

#Set Icon

To set an icon for the admin page use the setIcon() method.

$seat_index->setIcon('plane');

#Set Parent Pages

To set a parent page use the setParent() method.

$settings = ['capability' => 'editor'];
$add_seat = tr_page('Seat', 'add', 'Add Seat', $settings);
$add_seat->setParent($seat_index);

Note: By default, child pages will inherit the parent pages permission or capability settings unless the child has a capability set.

#Add Child Page

You can set child page with the addPage() and apply() methods.

#Using Add Page

$settings = ['capability' => 'administrator'];
$add_seat = tr_page('Seat', 'add', 'Add Seat', $settings);
$seat_index->addPage($add_seat);

#Using Apply

$settings = ['capability' => 'administrator'];
$add_seat = tr_page('Seat', 'add', 'Add Seat', $settings);
$seat_index->apply($add_seat);

#"Add New" Page Button

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.

$seat_index->addNewButton();

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.

#Add To Admin Bar

To add a page to the admin bar use the adminBar() method. By default, this will place items under the "New" dropdown.

$add_seat->adminBar('add_seat_page');

The adminBar() method takes 3 arguments:

1. $id - The ID to use in the admin bar for the menu.
2. $title - The title of the admin bar link.
3. $parent_id - The ID of the parent item in the admin bar.

#Use Controller

To have an admin page use the controller of its resource use the useController() method. For example, if the add seat page calls the useController() method it will use the SeatController and call the add method on it.

$add_seat->useController();

This works because when the page was created it was set to the "Seat" resource and assigned the "add" action. So, it calls add() on the SeatController.

#Make Controller

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.

php galaxy make:model -c base Seat

Note: Pages work best with controllers so reach for them.

#Map Actions (Core 3.0.12+)

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.

Note: This feature is available when a page has called useController.

$settings = ['capability' => 'administrator'];
$seat_ticket = tr_page('Seat', 'ticket', 'Tickets', $settings);
$seat_ticket->useController();
$seat_ticket->mapAction('GET', 'ticket');
$seat_ticket->mapAction('POST', 'create_ticket');

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.

#Remove Menu

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.

// create page
$settings = ['capability' => 'administrator'];
$view_seat = tr_page('Seat', 'view', 'View Seat', $settings);

// remove menu
$view_seat->removeMenu();

// add as child page
$seat->apply($view_seat);

#Arguments

There are 5 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.

These methods are: getArguments(), setArguments(), getArgument(), setArgument() and removeArgument().

1. getArguments() returns the full array of arguments.
2. setArguments() takes an array of arguments.
3. getArgument() return an argument by its key.
4. setArgument() sets an argument by a key.
5. removeArgument() removes an argument by its key.

Take a look at using all the methods without affecting the already set values.

$args = $book->getArguments();
$args = array_merge( $args, [ 'position' => 20 ] );
$book->setArguments( $args );
$public = $book->getArgument( 'position' );
$book->removeArgument( 'position' );
$book->setArgument( 'position', 20 );

#Position

A parent page is placed in the menu based on its position argument. By default, the position is 99. You see a list of menu positions in the WordPress developer reference guide.

• 2 for Dashboard
• 4 for Separator
• 5 for Posts
• 10 for Media
• 15 for Links
• 20 for Pages
• 25 for Comments
• 59 for Separator
• 60 for Appearance
• 65 for Plugins
• 70 for Users
• 75 for Tools
• 80 for Settings
• 99 for Separator

#Capability

Set the capability setting to a value from the WordPress capability levels. This will restrict access to the page based on the permissions level.

You can also set the values to a role level. This is many times the simplest and most effective method. The role levels are:

• administrator
• editor
• author
• contributor
• subscriber

#Inherit Capability

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.

#Menu

The menu setting controls the menu title. This is not the page title.

#View File

The view_file setting controls what file will be used as the page's template.

#Slug

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.