Ein eigenes Dashboard für mein Plugin

Bei einem Projekt haben wir ein umfangreiches Plugin entwickelt. Schnell kam der Wunsch auf, für dieses Plugin eine eigene Dashboard Seite zu haben. Das Dashboard ist die zentrale Übersichtsseite auf die man (normalerweise) nach dem anmelden weitergeleitet wird. In einzelnen so genannten Widgets werden Informationen präsentiert. Die Widgets können auf- und zugeklappt werden, sie können verschoben werden mit der Maus und sie können ein- und ausgeschaltet werden.

So eine Übersichtsseite sollte nun innerhalb der Plugin-Hauptseite eingebaut werden. Bekannt (weil schon benutzt) war mir, das WordPress eine Dashboard Widget API hat, mit der man eigene Widgets für das System Dashboard erstellen kann. Wie ich dann festgestellt habe gibt es aber keine Dashboard API mit der man mal schnell ein neues Dashboard erzeugen kann.

Ich habe dann begonnen mir anzusehen wie WordPress sein Dashboard erstellt. Das Dashboard selbst habe ich am laufen, inkl HilfeTabs und verschiebbaren Widgets die über die übliche wp_add_dashboard_widget() Funktion hinzugefügt werden. Was noch fehlt, ist die Option die Widgets ein- und auszuschalten. Der aktuelle Stand des Pluginspezifischen Dashboards in dem Projekt sieht so aus.

Aber der Reihe nach. Als erstes erzeuge ich eine neue Seite auf der Hauptebene im Backend. Auf dieser Seite soll das Dashboard angezeigt werden und alle weiteren Seiten des Plugins (diverse Beitragstypen, Einstellungen usw) werden unterhalb dieser Seite registriert.

/**
 * Registrierung der Seite im Hauptmenü des WordPress Backends
 *
 * Unterhalb dieser Seite liegen später alle weiteren Seiten meines Plugins.
 */
function register_my_custom_menu_page() {
    $my_dashboard_page = add_menu_page(
        _x( 'My Dashboard page', 'Seitentitel' , 'textdomain'), // Page Titel
        _x( 'My Dashboard', 'Menütitel', 'textdomain' ),        // Menu Title
        'manage_options',                                       // Capability
        'mydashboard',                                          // menu slug
        'my_dashboard_html',                                    // Callback Function
        'dashicons-chart-pie',                                  // Menüicon
        6                                                       // Menü position
    );
    // Laden Hilfetext
    add_action( 'load-' . $my_dashboard_page, 'my_dashboard_help' );
}
add_action( 'admin_menu', 'register_my_custom_menu_page' );

Über den Hook admin_menu lasse ich meine Funktion register_my_custom_menu_page aufrufen, in der ich über add_menu_page WordPress eine neue Seite registrieren lasse. Der fünfte Parameter ist die Callback-Funktion, die wird aufgerufen um den Inhalt der Seite zu generieren, wenn der Benutzer die Seite im Backendmenü angeklickt hat.
Des weiteren füge ich über add_action noch eine Funktion hinzu die für meine Dashboard Seite die Hilfetext registriert.

Die my_dashboard_help Funktion nutzt dazu die add_help_tab Methode des Screen Objects.

function my_dashboard_help () {
    $screen = get_current_screen();

    /*
     * Hinzufügen eines Hilfe Tabs.
     */
    $screen->add_help_tab( array(
        'id'    => 'login_redirect_url_help',
        'title' => _x('Dashboard', 'Plugin Dashboard Hilfetab', 'textdomain' ),
        'content'   => '<p>' . _x( 'Hier steht dann ein Hilfetext zu dem Dashboard. ', 'Plugin Dashboard Hilfetext', 'textdomain' ) . '</p>',
    ) );
    /*
     * Hinzufügen eines Hilfesidebar Hinweises
     */
    $screen->set_help_sidebar(
        '<p>' . _x('Für weitere Informationen klicken sie bitte <a href="http://www.domain.tld">hier</a>.', 'Plugin Dashboard Hilfetab Sidebar', 'textdomain') . '<p>'
    );
}

Das erzeugt einen Hilfe-Tab oben rechts in der Seite

und aufgeklappt.

Nun folgt die my_dashboard_html Funktion, also jene Funktion die ich in der add_menu_page als Callback angegeben habe. Das bedeutet, das diese Funktion aufgerufen wird wenn ein Anwender die Seite aufruft.

function my_dashboard_html() {
    require_once(ABSPATH . 'wp-admin/includes/dashboard.php');
    wp_enqueue_script( 'dashboard' );

    do_action( 'register_my_dashboard_widgets' );

    ?>
    <div class="wrap">
        <div id="dashboard-widgets-wrap">
            <?php wp_dashboard(); ?>
        </div>
    </div>
    <?php
}

Der Code ist abgeleitet von der Seite des Haupt-Dashboards von WordPress ( /wp-admin/index.php ).
Ich lade die WordPress eigenen Dashboard Funktionen und das dazugehörige Javascript via wp_enqueue_script.
Anschliessend wird eine Aktion register_my_dashboard_widgets getriggert, über die nun die Widgets registriert werden können.
Danach wird dann das Dashboard dargestellt über wp_dashboard().
Das hinzufügen von zwei Testwidgets sieht dann so aus.

/*
 * Registrieren der Widgets meines Dashboards.
 */
function my_widgets() {
    wp_add_dashboard_widget( 'widget_1', __( 'Mein Widget 1' ), 'widget_1' );
    wp_add_dashboard_widget( 'widget_2', __( 'Mein Widget 2' ), 'widget_2' );
}
add_action( 'register_my_dashboard_widgets', 'my_widgets' );

/*
 * Ausgabe Widget 1
 */
function widget_1() {
    echo "Mein erstes Widget in meinem Dashboard";
}

/*
 * Ausgabe Widget 2
 */
function widget_2() {
    echo "Das ist der Inhalt von Widget #2";
}

Die Funktion my_widgets wird über add_action auf die Aktion register_my_dashboard_widgets registriert. Innerhalb der Funktion füge ich mit wp_add_dashboard_widget() zwei Widgets hinzu. Der dritte Parameter ist die Callback-Funktion, welche jeweils aufgerufen wird um den Inhalt des Widgets zu erzeugen.

Der vollständige Code sieht dann so aus.

/**
 * Registrierung der Seite im Hauptmenü des WordPress Backends
 *
 * Unterhalb dieser Seite liegen später alle weiteren Seiten meines Plugins.
 */
function register_my_custom_menu_page() {
    $my_dashboard_page = add_menu_page(
        _x( 'My Dashboard page', 'Seitentitel' , 'textdomain'), // Page Titel
        _x( 'My Dashboard', 'Menütitel', 'textdomain' ),        // Menu Title
        'manage_options',                                       // Capability
        'mydashboard',                                          // menu slug
        'my_dashboard_html',                                    // Callback Function
        'dashicons-chart-pie',                                  // Menüicon
        6                                                       // Menü position
    );
    // Laden Hilfetext
    add_action( 'load-' . $my_dashboard_page, 'my_dashboard_help' );
}
add_action( 'admin_menu', 'register_my_custom_menu_page' );





function my_dashboard_html() {
    require_once(ABSPATH . 'wp-admin/includes/dashboard.php');
    wp_enqueue_script( 'dashboard' );

    do_action( 'register_my_dashboard_widgets' );

    ?>
    <div class="wrap">
        <div id="dashboard-widgets-wrap">
            <?php wp_dashboard(); ?>
        </div>
    </div>
    <?php
}



function my_dashboard_help () {
    $screen = get_current_screen();

    /*
     * Hinzufügen eines Hilfe Tabs.
     */
    $screen->add_help_tab( array(
        'id'    => 'login_redirect_url_help',
        'title' => _x('Dashboard', 'Plugin Dashboard Hilfetab', 'textdomain' ),
        'content'   => '<p>' . _x( 'Hier steht dann ein Hilfetext zu dem Dashboard. ', 'Plugin Dashboard Hilfetext', 'textdomain' ) . '</p>',
    ) );
    /*
     * Hinzufügen eines Hilfesidebar Hinweises
     */
    $screen->set_help_sidebar(
        '<p>' . _x('Für weitere Informationen klicken sie bitte <a href="http://www.domain.tld">hier</a>.', 'Plugin Dashboard Hilfetab Sidebar', 'textdomain') . '<p>'
    );
}


/*
 * Registrieiren der Widgets meines Dashboards.
 */
function my_widgets() {
    wp_add_dashboard_widget( 'widget_1', __( 'Mein Widget 1' ), 'widget_1' );
    wp_add_dashboard_widget( 'widget_2', __( 'Mein Widget 2' ), 'widget_2' );
}
add_action( 'register_my_dashboard_widgets', 'my_widgets' );

/*
 * Ausgabe Widget 1
 */
function widget_1() {
    echo "Mein erstes Widget in meinem Dashboard";
}

/*
 * Ausgabe Widget 2
 */
function widget_2() {
    echo "Das ist der Inhalt von Widget #2";
}

Und erzeugt dieses Ergebnis.

Aktuell fehlt bei dieser Lösung noch der Tab “Ansicht anpassen” wie man ihn im original Dashboard hat. Auf diesem Tab kann man die Sichtbarkeit der Widgets einstellen. Aktuell habe ich noch keine Lösung, da der Code an einige Stellen explizit abfragt ob die Dashboard-Seite aktiv ist. Wenn ich das Problem gelöst habe wird es einen weiteren Artikel geben. Ich freue mich über Feedback und Anregungen wie man das anderweitig lösen kann.