Erstellen eines benutzerdefinierten CMB2-Link-Picker-Steuerelements für WordPress
In diesem Tutorial werde ich sehen, wie Sie ein benutzerdefiniertes Steuerelement erstellen können, um die Funktionalität von CMB2 (Custom Meta Boxes 2) von WebDevStudios zu erweitern .
Ich entwickle Websites (und Webanwendungen) mit dem WordPress CMS (Content Management System), und wenn ein neues Projekt landet, können Sie garantieren, dass ich „Custom Meta Boxes” entwickeln muss, um dem Benutzer eine genaue Kontrolle zu ermöglichen über den Inhalt und das Layout der Website.
Ich werde detailliert beschreiben, wie ich den CMB2-Steuerelement- Link-Picker für CMB2 erstellt habe (erhältlich in allen guten WordPress-Plugin-Repositories). Ein Screenshot davon ist unten zu sehen.
Das CMB2-Steuerelement „Link Picker” in Aktion
Die Link-Auswahl löst den in WordPress integrierten Dialog „Link einfügen/bearbeiten” aus, wenn Sie auf die Schaltfläche „Auswählen” klicken. Dies ist im folgenden Screenshot zu sehen:
Wenn Sie auf die Schaltfläche klicken, können Sie aus einem Link auswählen (oder Ihren eigenen hinzufügen)
Ich bin sicher, Sie werden zustimmen, dass ein solches Steuerelement unglaublich praktisch ist, wenn Sie Ihren Website-Editoren die Möglichkeit geben möchten, einen Link hinzuzufügen und auch WordPress nach seinen internen Links zu durchsuchen, anstatt die Links ausschneiden und in einen Link einfügen zu müssen aufstellen.
Einführung / Geschichte
Für diejenigen, die es nicht wissen, eine Meta-Box befindet sich auf dem Editor-Bildschirm eines WordPress-Beitrags und enthält wahrscheinlich verschiedene Formularsteuerelemente (Textfelder, Dropdown-Listen, Kontrollkästchen usw.). Mit diesen Steuerelementen können Ihre Website-Benutzer problemlos einen benutzerdefinierten Text oder eine benutzerdefinierte Funktionalität auf der Website ändern.
Ein Beispiel für eine Metabox mit verschiedenen Formularsteuerelementen
Mit WordPress können Sie Metaboxen mithilfe von Funktionen (z. B. [add_meta_box](https://developer.wordpress.org/reference/functions/add_meta_box/)) erstellen, aber das Erstellen von Metaboxen auf diese Weise kann ein langwieriger Prozess mit vielen Codewiederholungen sein (insbesondere, wenn Sie dieselben Formularsteuerelemente in mehreren Projekten verwenden möchten).
Warum CMB2?
Einige von Ihnen haben vielleicht schon von Advanced Custom Fields (ACF) gehört, das eine GUI (Graphical User Interface) bietet, mit der Sie Metaboxen direkt mit WordPress erstellen können.
ACF ist meiner Meinung nach kein großartiges Tool für skalierbare Weblösungen. Das Plugin ist zu sehr darauf angewiesen, dass Daten in der Datenbank gespeichert werden. Dies verursacht Probleme beim Bereitstellen von Änderungen an einer Website, da Sie Ihren Code nicht einfach hochschieben und die Änderungen sofort sehen können. Stattdessen müssen Sie die Arbeit an den verschiedenen Bereitstellungsumgebungen (Staging, Live usw.) erneut durchführen. Also brauchten wir eine Lösung, mit der wir Metaboxen programmatisch erstellen können. Geben Sie CMB2 ein.
Bevor wir CMB2 übernommen haben, haben wir zuvor HM Custom Meta Boxes von diesen netten Menschen bei Human Made verwendet (das als Fork von WebDevStudios Vorläufer von CMB2, ‘Custom Meta Boxes’, begann).
Wir liebten HM Custom Meta Boxes, und mit den einfachsten Codeschnipseln konnten wir schnell benutzerdefinierte Meta Boxen erstellen, um so ziemlich alles zu tun!
Markup-Beispiel für HM Custom Meta Boxes (dies ist das Markup für die Instagram Meta Box im ersten Screenshot)
Warum also der Wechsel zu CMB2? Nun, HM Custom Meta Boxes hat leider nicht viel Zuspruch bekommen (ich habe mit dem leitenden Entwickler gesprochen und er ist ein sehr, sehr beschäftigter Mann), während CMB2 mit neuen Funktionen und neuen Steuerelementen vorankam und an Zugkraft gewonnen hatte in der WordPress-Community mit vielen Leuten, die es übernehmen und Plugins veröffentlichen, um es zu erweitern (einschließlich mehrerer unserer Partneragenturen).
Wie Sie vielleicht schon bemerkt haben, ist die Arbeit mit CMB2 so unglaublich einfach, wie wir es gewohnt waren, da beide Plattformen einen gemeinsamen Vorfahren haben.
Lernprogramm
Bevor wir beginnen, jeder hat seine eigenen Ideale, wie man ein WordPress-Plugin erstellt, und ich habe einige ausprobiert, aber das Tutorial zu „ Root Composition in WordPress ” von Tom J Nowell hat meine Arbeitsweise komplett verändert. Ich finde seinen Ansatz sauber, einfach und er macht die zukünftige Wartung jedes Plugins zum Kinderspiel. Wenn Sie sich die Quelle des Link Picker for CMB2- Plugins holen, können Sie die Methoden sehen, die er in der Praxis lehrt.
Erstellen des Formulars
Um das Formular zu erstellen, das den Link Picker rendert, müssen wir uns zunächst in die cmb2_render_[control_name]Aktion einklinken. Da ich dieses Steuerelement ‚link_picker’ genannt habe, können wir den Hook wie folgt vervollständigen:
Für diejenigen unter Ihnen, die den Haken nicht wirklich verstehen add_action, es funktioniert wie folgt:
- Das erste Argument
cmb2_render_link_pickerist der Name des Hooks, in den wir uns einklinken möchten. - Das zweite Argument
array( $this, 'cmb2_render_link_picker' )ist die Funktion, die wir aufrufen möchten, wenn dieser Hook ausgeführt wird. Beachten Sie, dass ich dies in ein Array verpacke, mit$thisals erstem Parameter, da ich die Funktion innerhalb einer Klasse aufrufe. Wenn Sie nicht mit Klassen arbeiten, können Sie einfach den Funktionsnamen verwendencmb2_render_link_picker. - Das
10, ist die Reihenfolge, in der die Funktion ausgelöst werden soll (je niedriger die Zahl, desto früher wird sie ausgelöst, wenn die Aktion aufgerufen wird). - Das
5ist die Anzahl der Parameter, die an die Funktion übergeben werden, die ich aufrufe (dies wird in Kürze klar werden).
Als nächstes erstellen wir die Funktion, die das Formular rendert:
Ich habe den ‘DocBlock’ im obigen Code belassen, der beschreibt, was jeder der an die cmb2_render_link_picker()Funktion übergebenen Parameter bewirkt.
Beachten Sie, dass meine Funktion mit der publicDeklaration beginnt. Dies liegt wiederum daran, dass ich innerhalb einer Klasse arbeite. Wenn Sie nicht mit Klassen arbeiten, können Sie dies weglassen.
Der Wert dieses Feldes wird über den $valueParameter an die Funktion übergeben. Im Fall dieses Felds durchlaufen wir ein Array, da unser Steuerelement drei separate Elemente enthält:
- Der Text
- Die URL
- Wenn der Link in einem neuen Fenster geöffnet wird (oder nicht)
Da das $valuenicht immer gesetzt ist (z. B. wenn das Steuerelement zum ersten Mal gerendert wird), müssen wir es mit einigen Standardwerten initialisieren. Das machen wir mit folgendem Code:
Wir können uns dann an die Arbeit machen, das Formular zu rendern. Hier ist ein Beispiel für das erste Texteingabesteuerelement:
Puh! Das sieht ein bisschen chaotisch aus, oder? Lassen Sie es uns Zeile für Zeile aufschlüsseln:
- Das öffnende Absatz-Tag.
- Das öffnende Label-Tag für das Steuerelement, aber mit dem
forAttribut, das automatisch durch den$field_type_object_idParameter festgelegt wird. Dadurch wird automatisch eine ID für das Steuerelement generiert, wenn es gerendert wird. - Der Text unseres Etiketts, der mit Text aus dem Array der Steuerelementoptionen erstellt wurde (oder auf das Wort „Text” zurückgreift).
- Das schließende Label-Tag
- Das schließende Absatz-Tag.
- Starten Sie die PHP-Deklaration
- Verwenden Sie ein Eingabesteuerelement (Teil von
$field_type_object), um eine Formulareingabe zu erstellen (Standardtyp ist Text). - Starten Sie das Array von Parametern
- Legen Sie die Klasse der Eingabe fest.
- Legen Sie den Namen der Eingabe wieder mit dem
$field_type_objectHelfer fest. - Stellen Sie die ID des Eingangs auf dieselbe ID ein, die auf dem Label-Tag festgelegt wurde.
- Holen Sie sich den Wert aus dem
$value, da dies ein Array ist, wollen wir den ‘Text’-Schlüssel für dieses Steuerelement. - Schließen Sie das Array.
- Schließen Sie die Eingabefunktion.
- Schließen Sie die PHP-Deklaration.
Das URL-Formularfeld-Markup ist ziemlich gleich, nur um HTML5-Eingabetypen zu verwenden, können wir einen zusätzlichen Parameter von „type” auf „url” setzen:
Abschließend wollen wir noch ein Dropdown implementieren. Das Markup ist sehr vertraut:
Beachten Sie, dass die $field_type_objectFunktion, die wir verwenden, darin besteht select, ein Dropdown-Menü zu generieren. Beachten Sie auch, dass wir in Zeile 6 ein neues Attribut von haben options. Daran übergeben wir eine Reihe von ‘Optionen’. Dies wird vor diesem Steuerelement wie folgt generiert:
Dann müssen wir es nur noch in einige <div>‘s einpacken und wir haben unsere vollständig gerenderte Kontrolle:
Und das ist es! Wir haben unsere Kontrolle gemacht! CMB2 verarbeitet automatisch alle Daten, die wir speichern möchten, also ist dort nichts zu tun.
Stile
Auf den Screenshot des Steuerelements, das wir erstellen (oben in diesem Beitrag), sind einige benutzerdefinierte Stile angewendet, sodass es inline gerendert wird. Ich werde heute nicht darauf eingehen, wie das Formular gestaltet wird, aber wenn Sie neugierig sind, können Sie das Plugin herunterladen und die Quelle anzeigen.
Die Steuerung wiederholbar machen
Für diejenigen unter Ihnen, die etwas fortgeschrittener werden möchten, können Sie die Steuerung mit den wiederholbaren Regionen von CMB2 zum Laufen bringen. Dazu müssen Sie ein wenig Array-Mapping durchführen. Verwenden Sie dazu den folgenden Code:
Auswahl eines Links
Der eigentliche Sinn des Link-Pickers besteht natürlich darin, ihn in die WordPress-eigene Link-Auswahlfunktion zu integrieren, sodass der Dialog „Link einfügen/bearbeiten” erscheint, wenn auf die Schaltfläche „Auswählen” geklickt wird.
Um dies zu erreichen, verlassen wir uns stark auf JavaScript. Insbesondere verwende ich jQuery, um Dinge geschehen zu lassen.
Bevor ich Ihnen das JavaScript zeige, das den Dialog startet, müssen wir zunächst das eigene interne JavaScript von WordPress in die Warteschlange stellen, das die Modale und Bibliotheken vorab lädt, von denen unser Code abhängt. Das sieht ungefähr so aus:
Wie Sie sehen können, verlassen sich viele der internen WordPress-Bibliotheken auf jQuery, um das Popup zu laden, daher ist es sinnvoll, dass unser Popup-Trigger dasselbe tut. Dies geschieht über das /js/plugin.js, das in Zeile 10 des obigen Beispiels geladen wird.
jQuery(document).ready(function($) {
var url = $('body');
var text = $('body');
var blank = $('body');
$('body').on('click', '.js-insert-link', function(event) {
event.preventDefault? event.preventDefault(): event.returnValue = false;
event.stopPropagation();
url = $(this).closest('.link-picker').find('input.cmb_text_url ');
text = $(this).closest('.link-picker').find('input.cmb_text ');
blank = $(this).closest('.link-picker').find('input.cmb_checkbox ');
wpActiveEditor = true;
wpLink.open();
wpLink.textarea = url;
return false;
});
$('body').on('click', '#wp-link-cancel, #wp-link-backdrop, #wp-link-close', function(event) {
wpLink.textarea = url;
wpLink.close();
event.preventDefault? event.preventDefault(): event.returnValue = false;
event.stopPropagation();
return false;
});
$('body').on('click', '#wp-link-submit', function(event) {
console.log(text)
var linkAtts = wpLink.getAttrs();
linkAtts.text = $('#wp-link-text').val();
url.val(linkAtts.href);
if( linkAtts.text != '') {
text.val(linkAtts.text);
}
if (linkAtts.target == '_blank') {
blank.prop('checked', true);
} else {
blank.prop('checked', false);
}
wpLink.textarea = url;
wpLink.close();
event.preventDefault? event.preventDefault(): event.returnValue = false;
event.stopPropagation();
return false;
});
});
Mithilfe der Klassen, die wir um unsere Formularsteuerelemente gewickelt haben, zielt das JavaScript auf die Steuerelemente ab und überträgt das ausgewählte Ergebnis aus dem Linkauswahl-Popup in die relevanten Steuerfelder.
Verwenden der Steuerung
Nachdem Sie also das obige Tutorial durchgesehen und möglicherweise den Quellcode des Link Picker for CMB2- Plugins überprüft oder einfach meine Version heruntergeladen haben, fragen Sie sich jetzt vielleicht, wie Sie das Ding mit CMB2 verwenden können. Nun, es könnte nicht einfacher sein: