Block-API

Headways Block-API ermöglicht es Entwicklern, anderen Headway-Mitgliedern ihre eigenen Block-Typen in Headway Extend anzubieten. Mit dem API definieren Sie, welche Art von Inhalt der Block umfasst, welche Optionen im Optionsmenü für den Block verfügbar sind, und weitere Dinge.Jeder von Ihnen entwickelte Block wird ein WordPress-Plugin, wird also wie jedes andere Plugin installiert und aktiviert.Dieser Artikel bietet Beispielcodes für einen fiktiven Block, den wir „Quote of the Day“ (Zitat des Tages) oder kurz „QOTD“ nennen.

Wichtig: Die Beispiele hier sind sehr grundlegend und stellen keinen voll funktionsfähigen Block dar. Umfangreichere Beispielcode-Abschnitte finden Sie unter Block-API-Beispiele.

Dateien, die hinzugefügt werden müssen

Ihr Block-Plugin besteht mindestens aus einer zentralen php-Datei mit einem Namen, der vom Namen Ihres Blocks abgeleitet ist (z.B. qotd.php). Diese Datei enthält die Kopfzeilen-Informationen, die WordPress benötigt, um Ihr Plugin die erkennen, zu installieren und auszuführen. Den in dieser Datei benötigten Code finden Sie unter „Standard Plugin Information“ auf dieser Seite des WordPress Codex.
Diese Datei umfasst auch etwas PHP-Code.

Obwohl diese Datei auch den Rest des für Ihren Block nötigen PHP-Codes umfassen kann, empfiehlt es sich, mindestens zwei weitere php-Dateien anzulegen: block.php und block-options.php. Wenn sich bestimmte Funktionen in separaten Dateien finden, läuft das Ganze viel runder. Folgende Anleitung zeigt, was mit den drei php-Dateien anstatt einer einzigen anzufangen ist.

Sie sollten zwei kleine Bilddateien haben (icon.png und icon-white.png), die Ihren Block im Visual Editor darstellen.

Ihr Plugin kann auch andere Dateien enthalten, die zur Funktion Ihres Blocks nötig sind, wie etwa CSS- und Bilddateien.

Wenn Sie Ihre Dateien vorbereitet haben, fassen Sie sie alle in einer Zip-Datei zusammen.

Funktionen und Klassen

Fügen Sie diese Funktionen in den PHP-Code Ihres Blocks ein. Nicht vergessen: Wo immer „qotd“ steht, handelt es sich nur um ein Beispiel.

Die Version des Blocks festlegen (für Headway Extend)

Wenn Sie Ihren Block per Extend anderen Headway-Mitgliedern zugänglich machen, fügen Sie diese Zeile direkt nach den Kopfzeilen-Informationen in Ihre php-Datei ein.

	define('QOTD_BLOCK_VERSION', '1.0');

Vergessen Sie nicht, die hier stehende Versionszahl zu aktualisieren, wann immer Sie eine neue Version veröffentlichen.

Anmeldung Ihres Blocks in WordPress

Verwenden Sie folgende Codezeile nach der Kopfzeile der Hauptdatei, um dem Plugin zu befehlen, erst zu starten, wenn Headway bereits ausgeführt wird, sodass alle Klassen und Funktionen von Headway bereits geladen sind.

	add_action('after_setup_theme', 'qotd_register');

… wobei qotd_register Ihre Funktion ist, mit der Headway angewiesen wird, den Block einzufügen. Diese Funktion kommt als Nächstes:

Anmeldung Ihres Blocks in Headway

Fügen Sie diese Funktion ein, um Headway anzuweisen, Ihren Block im Visual Editor anzuzeigen. Diese Funktion stellt sicher, dass Headway zuerst aktiviert wird – andernfalls werden Sie Fehler erhalten.

	function qotd_register() {
		if ( !class_exists('Headway') )
		return;
		require_once 'block.php';
		require_once 'block-options.php';
		return headway_register_block('HeadwayQotdBlock', plugins_url(false, __FILE__));
	}

Details:

  • Die Zeilen require_once sind nur nötig, wenn sich ein Teil Ihres Codes in zusätzlichen php-Dateien befindet. Hier werden diese Dateien aufgeführt.
  • ‚HeadwayQotdBlock‘ ist der Name der Klasse in block.php.
  • plugins_url gibt den Verzeichnispfad an, der die Icons für den Block enthält. Für gewöhnlich muss hier nichts verändert werden.

Automatische Updates in Headway Extend aktivieren

Wenn Sie Ihren Block via Headway Extend anderen Headway-Mitgliedern anbieten, fügen Sie diese Funktion am Ende Ihrer php-Hauptdatei ein. Sie teilt dem Nutzer Ihres Plugins mit, dass es eine neue Version Ihres Plugins gibt und er es aktualisieren muss.

	add_action('init', 'qotd_extend_updater');
	function qotd_extend_updater() {
		if ( !class_exists('HeadwayUpdaterAPI') )
    		return;
      	$updater = new HeadwayUpdaterAPI(array(
			'slug' => 'qotd-block',
			'path' => plugin_basename(__FILE__),
			'name' => 'Quote of the Day Block',
			'type' => 'block',
			'current_version' => QOTD_BLOCK_VERSION
		));
	}

Wenn das Headway-Team Ihren Block in Headway Extend aufnimmt, nutzt es Ihren Slug, um Ihren Block der HeadwayUpdaterAPI hinzuzufügen.

Die Funktionen Ihres Blocks hinzufügen

Fügen Sie der block.php (bzw. Ihrem Gegenstück) die Hauptfunktion hinzu, die angibt, was Ihr Block tut, wenn die Webseite angezeigt wird.

	class HeadwayQotdBlock extends HeadwayBlockAPI {
		public $id = 'qotd-block';
		public $name = 'Quote of the Day';
		public $options_class = 'HeadwayQotdBlockOptions';
		public $description = 'Displays a famous quote each day, adding some fun quotational randomness to your website.'

Details:

Variable Possible Values Notes
$id Eindeutiger string
$name String Wird im Visual Editor als Block-Typ angezeigt.
$options_class String (Klassen Name) Nutzt den Klassennamen aus block-options.php (oder Ihrem Gegenstück).
$description String Der Wert ist der Kurzinfotext, der angezeigt wird, wenn bei der Auswahl des Block-Typs über den Block-Namen gefahren wird. Beschränken Sie die Beschreibung auf maximal 140 Zeichen.

Die folgenden Methoden für diese Klasse sind optional, mit Ausnahme der letzten unter „Den Inhalt des Blocks einfügen“, die definiert, was Ihr Block im Browser anzeigt. Falls Sie keine dieser Methoden verwenden möchten, fügen Sie sie bitte auch nichts ein, denn Headway wird trotzdem versuchen, sie auszuführen – selbst wenn die Methode nichts enthält.

Style und Scripte einbinden

Nutzen Sie in dieser Klasse die Methode enqueue_action, um Styles oder Scripte in Ihren Block einzubinden. Diese Methode wird für jedes Element Ihres Blocks auf einer Seite ausgeführt, wenn der Browser die Seite lädt. Diese Methode nutzt den „wp“-Hook von WordPress.

	function enqueue_action($block_id) {
		$block = HeadwayBlocksData::get_block($block_id);
		/* YOUR CODE HERE */
		return;
	}

Anmeldung von Sidebars und Menus

Diese Methode registriert Ihren Block als Sidebar (Seitenleiste), Menü oder ähnliches Objekt, sodass es über die Admin-Leiste von WordPress gesteuert werden kann. Es wird für jedes Element dieses Blocks ausgeführt, wenn die Seite geladen wird.

	function init_action($block_id) {
		/* YOUR CODE HERE */
		return;
	}

einfügen von JavaScript

Mit dieser Methode können Sie der Seite JavaScript hinzufügen, z.B. aktivieren von jQuery-Cycle oder jQuery-Tabs Elementen.

	function dynamic_js($block_id) {
		/* IHREN CODE HIER EINFÜGEN */
		return;
	}

einfügen von CSS

CSS, den Sie mit dieser Funktion einfügen, wird in CSS-Dateien eingefügt, anstatt als Inline-Style-Elemente oder Attribute.

	function dynamic_css($block_id) {
		/* IHREN CODE HIER EINFÜGEN */
		return;
	}

anmeldung von elementen für den Design Mode

Mit dieser Funktion können Sie jedes Element anmelden, dass im Design-Modus des Visual Editors zur Gestaltung verfügbar sein soll (Gestaltungsoptionen für Blöcke selbst sind vordefiniert). Wiederholen Sie die  $this->register_block_element Funktion für jedes Element, das Gestaltungsoptionen bekommen soll.

	function setup_elements() {	
		$this->register_block_element(array(
			'id' => 'example-id',
			'name' => 'Example Element',
			'selector' => '.example-element-selector',
			'properties' => array('property1', 'property2', 'property3'),
			'states' => array(
				'Selected' => '.example-element-selector.selected', 
				'Hover' => '.example-element-selector:hover',
				'Clicked' => '.example-element:active'
			)
		));
}

Details:

Parameter Index Type or Possible Values Notes
id Eindeutiger String Für jedes angemeldete Element erforderlich. Selektoren können später verändert werden, aber die ID ist unveränderlich.
name Eindeutiger String Wird als Child Ihres Blocks in der Optionsleiste angezeigt, wenn Ihr Block ausgewählt ist. Ist z.B. „Header“ in der Optionsleiste ausgewählt, werden „Site Title“ und „Site Tagline“ erscheinen.
selector Eindeutiger String beginnend mit einem Punkt Der Selektor teilt Headway mit, welche Klasse in der HTML zu verwenden ist. In der CSS Ihrer Seite wird den Selektor .block-type-type vorangestellt, wobei type ein Slug für den Block-Typ ist (siehe Headway CSS Map).
properties „fonts“
„borders“
„padding“
„rounded-corners“
„box-shadow“
„text-shadow“
Headway umfasst stets die Eigenschaftsgruppen „Nudging“ und „Margin“. Diese müssen Sie hier also nicht einfügen.
states Array (siehe nachfolgende Punkte) Legt Selektoren für Link-States fest. States sind optional. Wenn Sie keine States hinzufügen, entfernen Sie den gesamten 'states‘-Index und die 'states‘-Matrix aus dieser Funktion.
Selected Der 'selector‘ String plus die Klasse .selected Headway fügt den Selektor der CSS und die entsprechende Klasse der HTML hinzu, wenn der Block verwendet wird. Diese Klasse wird für Punkte im Navigationsmenü verwendet, die der aktuellen Seite entsprechen.
Hover Der 'selector‘ String plus die Pseudo-Klasse :hover Headway fügt den Selektor der CSS und die entsprechende Klasse der HTML hinzu, wenn der Block verwendet wird.
Clicked Der 'selector‘ String plus die Pseudo-Klasse :active Headway fügt den Selektor der CSS und die entsprechende Klasse der HTML hinzu, wenn der Block verwendet wird.

den inhalt des blocks hinzufügen (erforderlich)

Diese Funktions definiert den grundlegenden Funktionsumfang Ihres Blocks: Was im Block selbst dargestellt wird, wenn der Browser die Seite lädt.

	function content($block) {
		/* IHREN CODE HIER EINFÜGEN */
	}

Ihre Blockoptionen festlegen

Fügen Sie der block-options.php (oder Ihrem Gegenstück) diese Klasse hinzu, um Headway mitzuteilen, welche Optionen für diesen Block in der Optionsleiste des Visual Editors angezeigt werden sollen. Für jeden Unterreiter, der in der Optionsleiste erscheinen soll, benötigen Sie ein Paar aus Index und Wert unter $tabs und entsprechende Arrays unter $inputs. Beachten Sie, dass die Arrays für $inputs zwei Ebenen umfassen: Eine Ebene identifiziert die Art der Eingabe für den Unterreiter, eine zweite Ebene legt den Wert für jeden Eingabetyp fest.

Dieser Code zeigt ein Beispiel für einen einzelnen Unterreiter mit einem einzelnen Texteingabefeld.

	class HeadwayExampleBlockOptions extends HeadwayBlockOptionsAPI {
		public $tabs = array(
			'my-first-tab' => 'Example'
		);
		public $inputs = array(
			'my-first-tab' => array(
				'text-input' => array(
					'type' => 'text',
					'name' => 'my-text-input',
					'label' => 'Text',
					'default' => 'Type your text here.',
					'tooltip' => 'Put anything relevant about the input in this tooltip.',
					'callback' => "
						/* IHREN CODE HIER EINFÜGEN */
					"
				)
			)
		);
	}

Details:

Index Type or Possible Values Notes
type „checkbox“ (ein- und ausschalten)
„select“ (Klappmenü)
„colorpicker“ (Farbauswahlfenster inkl. Muster)
„image“ (Bild auswählen und hochladen)
„integer“ (Zahl)
„multi-select“ (Textfeld, in dem ein oder mehrere Punkte ausgewählt werden können)
„slider“ (Zahlenbereich mit Schieberegler)
„text“ (einzeiliges Textfeld)
„textarea“ (mehrzeiliges Textfeld)
„wysiwyg“ (Textfeld mit Möglichkeit zur Formatierung)
name Unique string Diese Einstellung wird aus der Datenbank geholt.
label String Dieser Text erscheint zu dieser Option in der Optionsleiste.
default String (für die Text und Textbereichs Typen)
Integer (für die Zahlen und Slider Typen)
Array (für die Mehrfachauswahl)
„true“ (für das Auswahlkästchen)
„false“ (für das Auswahlkästchen)
Akzeptable Voreinstellungen hängen vom Eingabetyp ab, und nicht alle Eingabetypen können Voreinstellungen haben.
options Array Nur anwendbar für die Typen „select“ und „multi-select“. Der Array enthält die Index- und Wertepaare für die Option, die erscheinen soll. Für eine Option „none“ (Null) nutzen Sie einen leeren Index mit dazugehörigem Anzeigetext, der auf keine Auswahl hinweist.
unit „px“
„%“
Nützlich als Zusatz zur Eingabe. Nur anwendbar für die Typen „integer“ und „slider“.
slider-min Integer (Zahl) Nur anwendbar für den Typ „slider“.
slider-max Integer (Zahl) Nur anwendbar für den Typ „slider“.
slider-interval Integer (Zahl) Der Betrag, um den der Schieberegler den Wert einer Position erhöht oder verringert. Nur anwendbar für den Typ „slider“.
tooltip String Optional. Wenn Sie eine Kurzinfo hinzufügen, wird ein Hilfe-Icon anzeigt. Nutzer sehen die Kurzinfo, wenn Sie mit der Maus über das Icon fahren.
callback JavaScript Befehle Optional. Zum Einsatz von JavaScript, wenn die Eingabe verändert wird. Verfügbare Variablen sind „block“ und „value“.

Dieser Artikel wurde zuletzt für Headway Version 3.6.3 aktualisert.

Letztes Update: 19. Mai 2014