Admin Helpers

Conifer comes with some helpful goodies to make working with the WP admin easier.

Admin Notices

The Conifer\Admin\Notice provides a simple, intuitive API for adding notices to the top of the WP Admin screen. Just tell it what message should be displayed (and optionally a class to put on the message <div>) and Notice will display it for you:

use Conifer\Admin\Notice;

$notice = new Notice('all your base are belong to us');
$notice->error();

This will display an error message in the admin:

<div class="notice notice-error"><p>all your base are belong to us</p></div>

Notice styles

You can call any of the following methods to get a different style notice:

• $notice->success() renders a success message (green bar)
• $notice->info() renders an info message (blue bar)
• $notice->warning() renders a warning message (yellowish orange bar)
• $notice->error() renders an error message (red bar)

Dismissable Notices

WordPress supports dismissable notices: when a notice <div> has a special class, WordPress renders a close button that the user can click to make it go away. You can add this to any notice by calling dismissable():

use Conifer\Admin\Notice;

$notice = new Notice('all your base are belong to us');
$notice->dismissable()
  ->error();

The dismissable() method returns the Notice object itself, for a "fluent" interface.

Adding classes

For customizing notice front-end behavior/styles, you can specify optional extra classes to put on the <div> by with add_class():

$notice = new Notice('fancy custom notice!');
$notice->add_class('fancy custom') 
  ->info();

You can also specify a second argument to the constructor:

$notice = new Notice('fancy custom notice!', 'fancy custom');
$notice->info();

Either of these will render:

<div class="notice notice-info fancy custom"><p>fancy custom notice!</p></div>

Displaying Flash Notices

Many web frameworks and libraries, such as Ruby on Rails, provide "flash" notices: messages that appear once and then disappear on the next page load. We thought: what makes those frameworks so special? Nothing, that's what.

NOTE: To use Flash Notices, you must have sessions enabled. Some web hosts, notably Pantheon, disable sessions by default. Check with your web host and/or server configuration before assuming sessions are enabled.

First, enable flash notices:

use Conifer\Admin\Notice;

Notice::enable_flash_notices();

Then, display a flash message to appear on the next page load:

if (isset($_POST['do_a_thing'])) {
    do_a_thing();
    $notice = new Notice('You got redirected!!!1');
    $notice->flash_success();
    wp_redirect('/wp-admin/page=some-admin-page');
    exit;
}

As you can see, we can redirect after calling Notice::flash() and the message will display after the redirect. This is useful if you want to redirect after a non-idempotent change, such as deleting or updating a resource, so that folks can't accidentally replay the action by simply refreshing.

Flash notices have an almost identical API as regular notices:

• $notice->flash_success() renders a success message (green bar)
• $notice->flash_info() renders an info message (blue bar)
• $notice->flash_warning() renders a warning message (yellowish orange bar)
• $notice->flash_error() renders an error message (red bar)

Admin Pages

The AdminPage class is a simple abstraction around the add_menu_page() function. Simply implement the abstract render method...

use Conifer\Admin\Page;

class HelloPage extends Page {
  public function render() : string {
    return 'HELLO';
  }
}

...and add the page:

$page = new HelloPage('Hello');
$page->add();

Or, you can specify individual parameters using a fluent interface:

$page = new HelloPage('Hello');
$page
  ->set_title('WHY HELLO THERE')
  ->set_menu_title('O HAI')
  ->set_slug('hai')
  ->set_capability
  ->add();

Conifer provides sane defaults for individual parameters. Just make sure to check existing menu slugs to avoid overriding them.

Sub-Pages

Adding sub-pages is just as easy. Again, just implement render...

use Conifer\Admin\SubPage;

class HelloAgainPage extends SubPage {
  public function render() : string {
    return 'HELLO AGAIN';
  }
}

...and add the sub-page to its parent:

$parent = new HelloPage('Hello');
$parent->add();

// instantiate the sub-page and add it...
$child = new HelloAgainPage('Hello Again', $parent);
$child->add();

You can also add a sub-page using Admin\Page's fluent interface. This is equivalent to the example above:

$parent = new HelloPage('Hello');
$parent->add()
  ->add_sub_page(HelloAgainPage::class, 'Hello Again');

Of course, this means you can also add a whole slew of sub-pages in one fell swoop:

$parent = new HelloPage('Hello');
$parent->add()
  ->add_sub_page(HelloAgainPage::class, 'Hello Again')
  ->add_sub_page(GoodbyePage::class, 'Goodbye')
  ->add_sub_page(GoodbyeForRealzPage::class, 'Goodbye for Realz');

SubPage is a subclass of AdminPage and therefore inherits the same fluent interface. Instances of SubPage inherit their required capability from their parent page.

Hotkeys

Admin hotkeys are a special feature of Conifer and one of the few things it does out of the box. These hotkeys allow you type, for example, gd to go to the Dashboard from any page in the WP Admin.

You can add your own custom hotkeys from your config callback:

$this->set_custom_admin_hotkeys([
  // typing "ga" redirects us to the home page
  '97' => '/a-page'
]);

Note that we're passing a character code here, not a letter. JavaScript uses character codes to recognize the letter that the user typed. 97 is the code for a lower-case "a", so this is telling the JavaScript that when the user types ga it should redirect to /a-page.

Here are the default hotkeys and their corresponding character codes. Note that g is the universal prefix for all hotkeys (its character code is 103, by the way):

Disabling hotkeys

You can disable admin hotkeys from your config callback by calling:

$this->disable_admin_hotkeys();

The Conifer help widget

By default, Conifer displays a small widget on the admin dashboard containing links you may find helpful. To remove it, put this in your config callback:

$this->remove_conifer_widget();