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

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.