WordPress: Eigene Sammelaktionen (Bulk-Actions) definieren

Hinweis: Dieser Beitrag beschreibt ein Feature, das erst in Version 4.7 verfügbar ist (geplanter Veröffentlichungstermin: 6. Dezember 2016).

Bisher war es schwierig, eigene Sammelaktionen in WordPress hinzu zu fügen. Version 4.7 hat einen Hook erhalten, mit dem man einfach die Sammelaktionen erweitern kann.

add_action('bulk_actions-{screen_id}', 'my_bulk_action');

Die Screen-IDs

[table id=1 /]

Hook anlegen

Als Beispiel nehme ich die Beiträge-Seite, dementsprechend sind die Variablen benannt.

add_filter( 'bulk_actions-edit-post', 'register_my_bulk_actions' );

function register_my_bulk_actions($bulk_actions) {
$bulk_actions['my_bulk_action'] = __( 'My Bulk Action', 'domain');
$bulk_actions['my_other_bulk_action'] = __( 'My Other Bulk Action', 'domain');
return $bulk_actions;
}

Man kann mehr als eine Aktion in dieser Funktion definieren, denn hier passiert nichts anderes, als dass dem Feld $bulk_actions ein weiteres Element zugefügt wird. Man muss lediglich darauf achten, dass man unterschiedliche Elementschlüssel und, sinnvollerweise, unterschiedliche Anzeigetexte verwendet.

Callback-Funktion definieren

Zur Übersicht erst einmal die gesamte Funktion:

add_filter( 'handle_bulk_actions-edit-post', 'my_bulk_action_handler', 10, 3 );

function my_bulk_action_handler( $redirect_to, $action_name, $post_ids ) {

if ( 'my_bulk_action' === $action_name ) {
foreach ( $post_ids as $post_id ) {
$post = get_post($post_id);
// $post bearbeiten.
wp_update_post($post);
}
$redirect_to = add_query_arg( 'bulk_posts_processed', count( $post_ids ), $redirect_to );
return $redirect_to;
}

elseif ( 'my_other_bulk_action' === $action_name ) {
foreach ( $post_ids as $post_id ) {
$post_meta = get_post_meta($post_id);
// $post_meta bearbeiten
update_post_meta($post_meta);
}
$redirect_to = add_query_arg( 'other_bulk_posts_precessed', count( $post_ids ), $redirect_to );
return $redirect_to;
}
else
return $redirect_to;
}

Wie oben beschrieben, kann man mehr als eine eigene Sammelaktionen definieren, aber nur eine Aktions-Callback-Funktion. In dieser Funktion muss man deshalb zunächst abfragen, welche Sammelaktion ausgewählt wurde (Zeilen 3 und 12).
Als nächstes werden die Beiträge mit einer foreach -Schleife jeweils einzeln abgearbeitet. In dieser Schleife man z.B. mit get_post() oder get_post_meta() den jeweiligen Beitrag laden und bearbeiten.
Anschließend werden die die gänderten Daten mit wp_update_post($post) oder update_post_meta($post) zurück in die Datenbank geschrieben.
Die Variable $redirect_to gibt an, zu welcher URI der Browser wechselt, nachdem die Sammelaktion abgeschlossen ist, in unserem Fall …/wp-admin/edit.php?paged=1 . Mit der Funktion add_query_arg() fügen wir ein Argument zu der URL hinzu, der die Anzahl der bearbeiteten Beiträge angibt: …/wp-admin/edit.php?paged=1&bulk_posts_processed=1 .

Erfolgsmeldung ausgeben

Nach Abschluss der Sammelaktion kann eine Erfolgsmeldung (“admin notice”) mittels der Aktion admin_notices ausgeben werden. Der zweite Parameter muss den Textstring enthalten, den wir im Filter bulk_actions-{screen-id} definiert haben.

add_action( 'admin_notices', 'my_bulk_action_admin_notice' );

function my_bulk_action_admin_notice() {
if ( ! empty( $_REQUEST['bulk_posts_processed'] ) ) {
$posts_count = intval( $_REQUEST['bulk_posts_processed'] );
printf( '

' . _n( 'Processed %s post.', 'Processed %s posts.', $posts_count, 'add_asterix' ) . '

', $posts_count );
}
}

Die Anzahl der bearbeiteten Elemente können wir über den URL-Parameter ermitteln, den wir vorher mit $redirect_to = add_query_arg() hinzugefügt haben.

Trivia

Zum Schluss ein kleiner Fun Fact: Das entsprechende Ticket (#16031) wurde vor sechs Jahren eröffnet, also 2010, da waren wir bei WordPress v3.0.