Heute kann es ja eigentlich nur ein Thema geben. Richtig, Star Wars 😉 Da ich heute Nacht in der Mitternachtsvorstellung war und gestern keine Zeit zum Schreiben hatte, kommt der Artikel auch etwas später. Und keine Angst, ich werde hier nichts spoilern 🙂

Ich hatte schon länger vor, einen Artikel zum Thema Shortcodes zu schreiben und was bietet sich da besseres an, als ihn gleich mit Star Wars zu kombinieren 🙂 Nachdem Episode VII heute angelaufen ist, können wir schon mal anfangen, die Tage bis zu Episode VIII zu zählen. Das wollen wir in Form eines Countdown machen, den wir über einen Shortcode einbinden.

Einen einfachen Shortcode definieren

Einen Shortcode über die Shortcode API zu definieren ist im Grunde ganz einfach. Man muss lediglich mit der Funktion add_shortcode() einen Namen für den Shortcode definieren und eine Callback-Funktion hierfür. Ein einfacher Shortcode sieht wie folgt aus:

function foobar_func( $atts ){
	return "foo and bar";
}
add_shortcode( 'foobar', 'foobar_func' );

Wichtig ist bei der Callback-Funktion, dass sie den Text nicht per echo() ausgibt, sondern einen String zurückgibt. Hier passieren die häufigsten Fehler, beim Umgang mit Shortcodes.

Den Shortcode verwendet man dann wie gewohnt an einer beliebigen Stelle im Breitragstext:

[foobar]

Bei der Wahl für den Shortcodenamen solltet ihr auf eventuelle Konflikte mit bereits bestehenden Shortcodes achten. Ein eigenes Präfix kann auch hier nicht schaden.

Parameter an einen Shortcode übergeben

Viele Shortcodes können Parameter enthalten. Um diese zu verwenden müsst ihr eigentlich nichts weiter beachten. Alle Parameter, die ein Nutzer bei der Verwendung des Shortcodes angibt, stehen euch über das $atts Array automatisch zur Verfügung. Möchte man nur bestimmt Parameter verwenden und für diese auch Standardwerte definieren, falls ein Parameter nicht angegeben wurde, verwendet ihr einfach die Funktion shortcode_atts(). Diese führt die Standardwerte und die angegebenen zusammen. Sie wird wie folgt verwendet:

function bartag_func( $atts ) {
    $a = shortcode_atts( array(
        'foo' => 'something',
        'bar' => 'something else',
    ), $atts );

    return "foo = {$a['foo']}";
}
add_shortcode( 'bartag', 'bartag_func' );

Ein Countdown als Shortcode

Ich habe vor einigen Jahren mal einen Countdown geschrieben. Dieser basierte noch auf dem Prototype Framework, welches heutzutage größtenteils von jQuery verdrängt wurde. Es gibt aber viele fertige Lösungen und wir verwenden daher in diesem Beispiel einen solchen fertigen Countdown: The Final Countdown. Hierzu definieren wir erst einmal die entsprechende Callback-Funktion:

function countdown_shortcode_render( $atts ) {

	wp_enqueue_script( 'countdown-shortcode' );

	$a = shortcode_atts( array(
		'final_date' => '',
		'format' => __( '%w weeks %d days %H hours %M minutes %S seconds', 'countdown-shortcode' ),
	), $atts );

	$countdown_container_id = 'countdown-container-' . random_int( 0, 1000 );

	$content = '<div id="' . esc_attr( $countdown_container_id ) . '"></div>
				<script>
					jQuery(document).ready(function($){
						$("#' . esc_js( $countdown_container_id ) . '").countdown("' . esc_js( $a['final_date'] ) . '", function(event) {
							$(this).html(event.strftime("' . $a['format'] . '"));
						});
					});
				</script>';

	return $content;
}

Zu Beginn laden wir erst einmal das notwendige JavaScript. Wir tun dies innerhalb der Shortcode-Funktion, damit die Datei nur dann geladen wird, wenn sie auch wirklich benötigt wird. Anschließend definieren wir, welche Parameter zulässig sein sollen und welche Standardwerte diese bekommen. Für einen einfachen Countdown reichen ein Enddatum und das Ausgabeformat, welches wir selbstverständlich übersetzbar machen. Damit man mehr als einen solchen Shortcode verwenden kann, vergebe ich noch eine zufällige ID. Zuletzt wird das HTML-Element sowie der notwendige JavaScript-Code ausgegeben.

Die Verwendung des Countdown-Shortcodes

Die Verwendung des Countdown in einem Beitrag ist ganz einfach. An einer beliebigen Stelle fügt man einfach den Shortcode ein und gibt dabei das Zieldatum an. Für Star Wars Episode VIII ist es der 25. Mai 2017, Prämierenbeginn vermutlich wieder um 00:01 Uhr:

[countdown final_date="2017/05/25 00:01:00"]

Das Ergebnis

Hat alles funktioniert, solltet ihr im Beitrag nun den Countdown runterzählen sehen:

Selbstverständlich gibt es auch hierzu wieder ein GitHub-Repository, in dem ihr euch das Ganze in einer ZIP-Datei runterladen und als Plugin installieren könnt.

Fazit

Wie ihr gesehen habt, ist es wirklich ganz einfach, einen eigenen Shortcode zu erstellen. Ihr habt außerdem gelernt wie man Parameter an den Shortcode übergibt und wie man JavaScript dafür einbinden kann. Falls auch ihr einen netten Shortcode gebastelt habt, hinterlasst doch einfach einen Kommentar.