Adventskalender Tag 17: Einen eigenen Shortcode erstellen am Beispiel eines Countdown

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:

countdown-shortcode

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.

Veröffentlicht von

Bernhard ist fest angestellter Webentwickler, entwickelt in seiner Freizeit Plugins, schreibt in seinem Blog ĂŒber WordPress und andere Themen, treibt sich gerne bei den WP Meetups in Berlin und Potsdam herum und lĂ€uft nach Feierabend den ein oder anderen Halbmarathon.

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert