Wie man benutzerdefinierte WordPress-Schreib- / Meta-Boxen erstellt

German (Deutsch) translation by Alex Grigorovich (you can also view the original English article)

Das Erstellen von Meta-Boxen ist ein wesentlicher Bestandteil der Entwicklung von WordPress-Themes / Plugins. Auf diese Weise können Sie dem Post-Bildschirm einen ansprechenden Editor hinzufügen und Benutzer nicht dazu zwingen, sich auf benutzerdefinierte Felder zu verlassen. Wenn Sie jemals einen benutzerdefinierten Beitragstyp in WordPress erstellt haben, wollten Sie wahrscheinlich zusätzliche Daten hinzufügen. Sicher, Sie könnten benutzerdefinierte Felder verwenden, aber das ist hässlich. Der Einstieg in benutzerdefinierte Meta-Boxen ist einfach. Lassen Sie uns also eintauchen!

Was sind benutzerdefinierte Meta-Boxen?

Eine benutzerdefinierte Meta-Box (oder Schreibbox) ist theoretisch unglaublich einfach. Sie können einem Beitrag oder einer Seite in WordPress ein benutzerdefiniertes Datenelement hinzufügen.

Stellen Sie sich vor, Sie arbeiten an einem Thema für einen Kunden, der seine umfangreiche Sammlung von Konzertplakaten katalogisieren möchte. Sie sehen sich sofort die Kernfunktionalität von WordPress an, um zu sehen, wie Sie das Thema organisieren können: Jeder Beitrag stellt ein Poster dar, das sich perfekt zum Hinzufügen eines Bildes, eines Titels und einer Beschreibung eignet. Wir können auch das Kategorien- und Tag-System in WordPress verwenden, um die Poster zu organisieren. Aber was wäre, wenn wir für den "Künstler" jedes Posters eine neue Art von Metadaten hinzufügen wollten? Hmph. WordPress hat nicht sofort etwas dafür... was uns zu benutzerdefinierten Meta-Boxen bringt.

Eine benutzerdefinierte Meta-Box (oder Schreibbox) ist theoretisch unglaublich einfach. Sie können einem Beitrag oder einer Seite in WordPress ein benutzerdefiniertes Datenelement hinzufügen. Besser ist, dass es direkt in die meisten Standardseiten in WP passt, sodass Sie es einfach im Post-Editor platzieren können, um es einfach zu verwenden nichttechnische Typen. Wie ich im Intro sagte, können Sie Ihrem Beitrag dieselbe Art von "Metadaten" hinzufügen, indem Sie die integrierten benutzerdefinierten Felder für einen Beitrag oder eine Seite verwenden. Es ist nichts Falsches an diesem Persay, aber es ist nicht sehr anmutig oder benutzerfreundlich.

Stattdessen möchten Sie ein benutzerdefiniertes Meta-Feld erstellen, das Felder für alle Ihre Daten enthält und all diese Dinge direkt bei der Veröffentlichung des Beitrags speichert. Darum geht es hier. Dies ist in drei große Schritte unterteilt:

Hinzufügen der Meta-Box
Rendern der Meta-Box
Speichern der Daten (der richtige Weg - ja, es gibt einen falschen Weg)

Es ist erwähnenswert, dass viele dieser Informationen auch in der API für benutzerdefinierte Beitragstypen verwendet werden können (wir werden später darauf zurückkommen!). Um die Dinge heute fokussiert zu halten, werden wir sie jedoch direkt hinzufügen der Standard-Post-Editor.

Für die fortgeschrittenen Leser im Publikum: Ja, bei benutzerdefinierten Beitragstypen werden wir irgendwann damit anfangen, aber es ist wichtig, zuerst einige Grundlagen einzurichten. Da Sie die benutzerdefinierten Meta-Boxen an allen möglichen Orten verwenden können, ist es für jeden gut, dies zu wissen.

Alles in diesem Tutorial funktioniert in der Datei functions.php eines Themas. Das ist jedoch nicht der richtige Ort dafür. Wenn Sie einem Beitrag Daten hinzufügen, möchten Sie diese wahrscheinlich dort haben, unabhängig von Ihrem Front-End-Design. Daher sollten Sie diesen Code an einer Stelle platzieren, die nicht von Ihrem Design abhängt: einer Plugin-Datei.

Schritt 1 Hinzufügen der Meta Box

Praktischerweise bietet WordPress eine Funktion zum Hinzufügen von Meta-Boxen zu einem bestimmten Admin-Bildschirm: add_meta_box.

Der Codex-Eintrag ist für diese Funktion gut gemacht, aber hier ist eine kurze Übersicht. Sein Prototyp:

<?php add_meta_box( $id, $title, $callback, $page, $context, $priority, $callback_args ); ?>

$id ist das HTML-ID-Attribut der Box. Dies ist nützlich, wenn Sie benutzerdefiniertes CSS oder Javascript auf die Bearbeitungsseite laden, um die Optionen zu verarbeiten. Ansonsten ist es eigentlich gar nicht so wichtig.

$title wird oben im Meta-Feld angezeigt.

$callback ist die Funktion, die die Meta-Box tatsächlich rendert. Wir werden dies in Schritt 2 skizzieren.

Auf der Seite $page das Meta-Feld angezeigt werden. Dies sollte eine Zeichenfolge mit 'post' oder 'page' oder 'some_custom_post_type' sein.

In $context soll das Meta-Feld angezeigt werden. 'normal' setzt es unter den Post-Editor. 'side' verschiebt das Meta-Feld in die rechte Seitenleiste des Bearbeitungsbildschirms (nach Kategorien und Tags usw.). 'advanced' setzt das Feld ebenfalls in dieselbe Spalte wie der Post-Editor, jedoch weiter unten.

$priority teilt WordPress mit, wo die Meta-Box im Kontext platziert werden soll. 'high', 'default' oder 'low' bringt das Feld näher an der Oberseite, in seiner normalen Position bzw. nach unten. Da alle Meta-Boxen ziehbar sind, ist die Priorität von $priority große Sache.

Schließlich können Sie mit $callback_args Daten in Form eines Arrays an Ihre $callback-Funktion übergeben. Wir werden dies hier nicht verwenden, aber es könnte nützlich sein, um einige Daten an die Meta-Box zu übergeben. Angenommen, Ihr Plugin verfügt über mehrere Optionen, die Einfluss darauf haben, was in der Meta-Box angezeigt wird. Sie können diese Optionswerte über das Array $callback_args übergeben.

Unser Aufruf von add_meta_box sieht also folgendermaßen aus:

<?php add_meta_box( 'my-meta-box-id', 'My First Meta Box', 'cd_meta_box_cb', 'post', 'normal', 'high' ); ?>

Wir können dies nicht einfach alleine in unsere Plugin-Datei einfügen. Dies führt zum weißen Bildschirm des Todes und zu einem schwerwiegenden PHP-Fehler: Aufruf der undefinierten Funktion. Warum? Weil wir die Funktion add_meta_box aufgerufen haben, bevor WordPress geladen wurde. Wir müssen also einen WordPress-Hook verwenden, der Teil der Plugin-API ist. Grundsätzlich werden Funktionen in eine bestimmte WordPress-Aktion oder einen bestimmten Filter-Hook eingebunden. Diese Funktionen werden dann ausgelöst, wenn dieser Hook geladen wird. Indem wir unseren Aufruf add_meta_box in eine Funktion einschließen und diese Funktion dann in den Aktions-Hook add_meta_boxes einbinden, vermeiden wir den schwerwiegenden Fehler.

Unser Code zum Hinzufügen der Meta-Box zu unserem Post-Bildschirm würde folgendermaßen aussehen:

<?php
add_action( 'add_meta_boxes', 'cd_meta_box_add' );
function cd_meta_box_add()
{
	add_meta_box( 'my-meta-box-id', 'My First Meta Box', 'cd_meta_box_cb', 'post', 'normal', 'high' );
}
?>

Schritt 2 Rendern der Meta Box

Der obige Code reicht aus, um die Meta-Box hinzuzufügen, aber jetzt müssen wir das Ding rendern und tatsächlich Felder hinzufügen. Dies ist nur ein HTML-Formularcode, der mit etwas PHP gemischt wird, um die gespeicherten Daten anzuzeigen. Wir müssen die Formular-Tags nicht einfügen, da WordPress dies für uns erledigt.

Erinnern Sie sich an die Zeichenfolge, die wir als $callback in add_meta_box übergeben haben? Wir werden jetzt eine Funktion mit demselben Namen erstellen. Diese Funktion kümmert sich um die gesamte Anzeige innerhalb der Meta-Box.

<?php
function cd_meta_box_cb()
{
	echo 'What you put here, show\'s up in the meta box';	
}
?>

Wir werden unserem Meta-Feld mehrere Felder hinzufügen: eine Texteingabe, ein Dropdown-Menü und ein Kontrollkästchen. Beginnen wir mit der Texteingabe.

Hinzufügen der Texteingabe

<?php
function cd_meta_box_cb()
{
	?>
	<label for="my_meta_box_text">Text Label</label>
	<input type="text" name="my_meta_box_text" id="my_meta_box_text" />
	<?php	
}
?>

Aber wie sieht es mit der tatsächlichen Anzeige der Daten aus? Wie Sie in Schritt 3 sehen werden, speichern wir diese Daten mit der Funktion update_post_meta in der Tabelle wp_postmeta. Diese Funktion hat zwei Schwesterfunktionen namens get_post_meta und get_post_custom, die Daten von wp_postmeta abrufen. get_post_meta erfasst nur Daten von einem Schlüssel, während get_post_custom alle Daten erfasst. Da wir derzeit nur ein Feld verwenden, verwenden wir get_post_meta.

Beachten Sie auch, dass die Funktion add_meta_box eine Variable an unseren Rückruf übergibt: $post, ein Post-Objekt.

<?php
function cd_meta_box_cb( $post )
{
$values = get_post_custom( $post->ID );
$text = isset( $values['my_meta_box_text'] ) ? esc_attr( $values['my_meta_box_text'][0] ) : ”;
$selected = isset( $values['my_meta_box_select'] ) ? esc_attr( $values['my_meta_box_select'][0] ) : ”;
$check = isset( $values['my_meta_box_check'] ) ? esc_attr( $values['my_meta_box_check'][0] ) : ”;
	?>
<p>
	<label for="my_meta_box_text">Text Label</label>
	<input type="text" name="my_meta_box_text" id="my_meta_box_text" value="<?php echo $text; ?>" />
        </p>
	<?php		
}

?>

Hinzufügen des Dropdowns

<?php	
function cd_meta_box_cb( $post )
{
$values = get_post_custom( $post->ID );
$text = isset( $values['my_meta_box_text'] ) ? esc_attr( $values['my_meta_box_text'][0] ) : ”;
$selected = isset( $values['my_meta_box_select'] ) ? esc_attr( $values['my_meta_box_select'][0] ) : ”;
$check = isset( $values['my_meta_box_check'] ) ? esc_attr( $values['my_meta_box_check'][0] ) : ”;
	?>
	<p>
		<label for="my_meta_box_text">Text Label</label>
		<input type="text" name="my_meta_box_text" id="my_meta_box_text" value="<?php echo $text; ?>" />
	</p>
	
	<p>
		<label for="my_meta_box_select">Color</label>
		<select name="my_meta_box_select" id="my_meta_box_select">
			<option value="red" <?php selected( $selected, 'red' ); ?>>Red</option>
			<option value="blue" <?php selected( $selected, 'blue' ); ?>>Blue</option>
		</select>
	</p>
	<?php	
}
?>

Durch Hinzufügen eines zweiten Felds haben wir get_post_meta in get_post_custom geändert oder get_post_meta aufgerufen, wodurch ein assoziatives Array aller benutzerdefinierten Schlüssel und Werte des Posts zurückgegeben wird. Wir greifen dann einfach über deren Namen auf unsere Felder zu. Die ternären Anweisungen verhindern, dass unser Code PHP-Warnungen (undefinierte Indizes und dergleichen) auslöst. Wir werden die esc_attr-Funktion in Schritt drei behandeln.

In der Dropdown-Liste verwenden wir eine der praktischsten Funktionen von WordPress: Ausgewählt. Dies vergleicht den ersten Wert, die von uns gespeicherten Daten, mit dem zweiten, dem Wertattribut der <option>. Wenn sie gleich sind, gibt die Funktion das Echo selected="selected" aus, wodurch dieser Wert in der Dropdown-Liste angezeigt wird. Ziemlich süß, und es erspart uns, ein paar if- oder ternäre Aussagen zu schreiben. Sie können die Funktion selected() auch mit Optionsfeldern verwenden.

Hinzufügen des Kontrollkästchens

&lt?php
function cd_meta_box_cb()
{
	// $post is already set, and contains an object: the WordPress post
	global $post;
	$values = get_post_custom( $post->ID );
	$text = isset( $values['my_meta_box_text'] ) ? $values['my_meta_box_text'] : '';
	$selected = isset( $values['my_meta_box_select'] ) ? esc_attr( $values['my_meta_box_select'] ) : '';
	$check = isset( $values['my_meta_box_check'] ) ? esc_attr( $values['my_meta_box_check'] ) : '';
	
	// We'll use this nonce field later on when saving.
	wp_nonce_field( 'my_meta_box_nonce', 'meta_box_nonce' );
	?>
	<p>
		<label for="my_meta_box_text">Text Label</label>
		<input type="text" name="my_meta_box_text" id="my_meta_box_text" value="<?php echo $text; ?>" />
	</p>
	
	<p>
		<label for="my_meta_box_select">Color</label>
		<select name="my_meta_box_select" id="my_meta_box_select">
			<option value="red" <?php selected( $selected, 'red' ); ?>>Red</option>
			<option value="blue" <?php selected( $selected, 'blue' ); ?>>Blue</option>
		</select>
	</p>
	
	<p>
		<input type="checkbox" id="my_meta_box_check" name="my_meta_box_check" <?php checked( $check, 'on' ); ?> />
		<label for="my_meta_box_check">Do not check this</label>
	</p>
	<?php	
}
?>

Wieder bietet WordPress die praktische Funktion checked(). Es funktioniert genauso wie selected(), indem der erste Wert (unsere gespeicherten Daten) mit dem zweiten verglichen wird und checked="checked" ausgegeben wird, wenn sie gleich sind.

wp_nonce_field fügt unserer Meta-Box zwei versteckte Felder hinzu. Einer von ihnen ist eine Nonce. Hierbei handelt es sich um zufällige Zahlenfolgen, die pro Benutzer und Blog 24 Stunden lang gültig sind. Nonces sind eine Möglichkeit, die Absicht zu überprüfen, und sie stellen sicher, dass WordPress nichts tut, es sei denn, die Anfrage kam von einem ganz bestimmten Ort. Mit anderen Worten, wir möchten unsere Daten nicht versehentlich aktualisieren, indem wir unsere Speicherfunktion (siehe Schritt 3) an einem anderen Ort als dem save_post-Hook ausführen. Daher überprüfen wir, ob das Nonce gültig ist, bevor wir etwas unternehmen.

Schritt 3 Speichern der Daten

Die Regel Nummer eins beim Einfügen von Daten in Ihre Datenbank oder auf Ihrer Website lautet, dem Benutzer nicht zu vertrauen. Auch wenn dieser Benutzer Sie sind.

Um unsere Daten zu speichern, werden wir uns auf einen anderen WordPress-Hook verlassen: save_post. Dies funktioniert genau wie unser Action-Hook oben:

<?php add_action( 'save_post', 'cd_meta_box_save' ); ?>

Die Funktion cd_meta_box_save erhält ein Argument, die Post-ID, und kümmert sich um die Bereinigung und Speicherung aller unserer Daten. Der Haken save_post wird ausgelöst, nachdem die Schaltfläche zum Aktualisieren oder Speichern des Entwurfs gedrückt wurde. Wir haben also Zugriff auf alle $_POST-Daten, einschließlich unserer Meta-Box-Felder, innerhalb unserer Speicherfunktion. Bevor wir jedoch etwas tun können, müssen wir drei Dinge tun: Überprüfen Sie, ob der Beitrag automatisch gespeichert wird, überprüfen Sie den zuvor erstellten Nonce-Wert und stellen Sie sicher, dass der aktuelle Benutzer den Beitrag tatsächlich bearbeiten kann.

<?php
add_action( 'save_post', 'cd_meta_box_save' );
function cd_meta_box_save( $post_id )
{
	// Bail if we're doing an auto save
	if( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE ) return;
	
	// if our nonce isn't there, or we can't verify it, bail
	if( !isset( $_POST['meta_box_nonce'] ) || !wp_verify_nonce( $_POST['meta_box_nonce'], 'my_meta_box_nonce' ) ) return;
	
	// if our current user can't edit this post, bail
	if( !current_user_can( 'edit_post' ) ) return;
}
?>

Nun das lustige Zeug: tatsächlich unsere Daten speichern. Die Regel Nummer eins beim Einfügen von Daten in Ihre Datenbank oder auf Ihrer Website lautet, dem Benutzer nicht zu vertrauen. Auch wenn dieser Benutzer Sie sind. Zu diesem Zweck möchten wir vor dem Speichern von Daten sicherstellen, dass nichts Bösartiges darin enthalten ist. Glücklicherweise bietet WordPress eine Reihe von Funktionen zur Datenvalidierung.

Sie haben esc_attr() bereits oben gesehen (Schritt 2). Dieser codiert ' " und < > in HTML-Entitäten. Warum das benutzen? Daher konnten Benutzer kein <script> in Ihre Meta-Box eingeben. Wenn Sie bestimmte HTML-Tags zulassen möchten, andere jedoch entfernen möchten, kann wp_kses dies tun. Es werden zwei Argumente benötigt, von denen das erste die Zeichenfolge ist, die Sie überprüfen möchten, und das zweite ein assoziatives Array zulässiger Tags ist. WordPress bietet viele weitere Tools zur Datenvalidierung. Haben Sie keine Angst, diese zu verwenden.

Wir werden die Funktion update_post_meta verwenden, um die Daten zu speichern. Es werden drei Argumente benötigt: eine Post-ID, der Metaschlüssel und der Wert.

<?php
add_action( 'save_post', 'cd_meta_box_save' );
function cd_meta_box_save( $post_id )
{
	// Bail if we're doing an auto save
	if( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE ) return;
	
	// if our nonce isn't there, or we can't verify it, bail
	if( !isset( $_POST['meta_box_nonce'] ) || !wp_verify_nonce( $_POST['meta_box_nonce'], 'my_meta_box_nonce' ) ) return;
	
	// if our current user can't edit this post, bail
	if( !current_user_can( 'edit_post' ) ) return;
	
	// now we can actually save the data
	$allowed = array( 
		'a' => array( // on allow a tags
			'href' => array() // and those anchors can only have href attribute
		)
	);
	
	// Make sure your data is set before trying to save it
	if( isset( $_POST['my_meta_box_text'] ) )
		update_post_meta( $post_id, 'my_meta_box_text', wp_kses( $_POST['my_meta_box_text'], $allowed ) );
		
	if( isset( $_POST['my_meta_box_select'] ) )
		update_post_meta( $post_id, 'my_meta_box_select', esc_attr( $_POST['my_meta_box_select'] ) );
		
	// This is purely my personal preference for saving check-boxes
	$chk = isset( $_POST['my_meta_box_check'] ) && $_POST['my_meta_box_select'] ? 'on' : 'off';
	update_post_meta( $post_id, 'my_meta_box_check', $chk );
}
?>

Einpacken

Das ist es! Sie sollten eine voll funktionsfähige Meta-Box haben. Andere Beispiele finden Sie möglicherweise in der Webschleife durch eine Reihe von Feldern, ohne die Daten wirklich zu bereinigen. Dies ist der falsche Ansatz. Verwenden Sie immer die integrierten Datenüberprüfungsfunktionen. Unterschiedliche Felder / Werte erfordern möglicherweise eine unterschiedliche Datenvalidierung.

Verwenden Sie die Funktionen get_post_meta oder get_post_custom (siehe Schritt 2), um diese benutzerdefinierten Felder am Frontend Ihrer Site zu verwenden.