Cum să creezi un plugin TinyMCE pentru WordPress

Dacă sunteți dezvoltator WordPress, atunci la un moment dat este posibil să întâlniți personalizarea sau extinderea Editorului Vizual WordPress. De exemplu, este posibil să doriți să adăugați un buton la bara de instrumente a Editorului Vizual pentru a permite clientului dvs. să insereze cu ușurință o casetă de text sau un buton de apel la acțiune fără a scrie cod HTML. În acest articol, vă vom arăta cum să creați un plugin TinyMCE în WordPress.

Cerințe

Acest tutorial este destinat utilizatorilor avansați. Dacă sunteți un utilizator începător care dorește doar să extindă editorul vizual, atunci vă rugăm să consultați plugin-ul TinyMCE Advanced sau să aruncați o privire la aceste sfaturi despre utilizarea editorului vizual WordPress.

Pentru acest tutorial, veți avea nevoie de abilități de bază de codare, acces la o instalare WordPress unde o puteți testa.

Este o practică proastă să dezvoltați plugin-uri pe un site web activ. O greșeală minoră în cod poate face site-ul dvs. inaccesibil. Dar dacă trebuie să o faceți pe un site activ, atunci cel puțin faceți backup la WordPress mai întâi.

Crearea primului tău plugin TinyMCE

Vom începe prin a crea un plugin WordPress pentru a înregistra butonul nostru personalizat din bara de instrumente TinyMCE. Când este apăsat, acest buton va permite utilizatorului să adauge un link cu o clasă CSS personalizată.

Codul sursă va fi furnizat integral la sfârșitul acestui articol, dar până atunci, să creăm pluginul pas cu pas.

Mai întâi, trebuie să creați un director în folderul wp-content/plugins al instalării dvs. WordPress. Numiți acest folder tinymce-custom-link-class.

De aici, vom începe să adăugăm codul plugin-ului nostru.

Antetul pluginului

Creați un fișier nou în directorul pluginului pe care tocmai l-am creat și numiți-l tinymce-custom-link-class.php. Adăugați acest cod în fișier și salvați-l.

/**
 * Plugin Name: TinyMCE Custom Link Class
 * Plugin URI: http://wpbeginner.com
 * Version: 1.0
 * Author: WPBeginner
 * Author URI: https://www.wpbeginner.com
 * Description: A simple TinyMCE Plugin to add a custom link class in the Visual Editor
 * License: GPL2
 */

Acesta este doar un comentariu PHP, care îi spune WordPress numele pluginului, precum și autorul și o descriere.

În zona de administrare WordPress, activați noul plugin accesând Plugins > Installed Plugins, apoi faceți clic pe Activate lângă pluginul TinyMCE Custom Link Class:

Configurarea clasei pluginului nostru

Dacă două pluginuri WordPress au funcții cu același nume, acest lucru ar cauza o eroare. Vom evita această problemă prin încapsularea funcțiilor noastre într-o clasă.

class TinyMCE_Custom_Link_Class {
	
	/**
	* Constructor. Called when the plugin is initialised.
	*/
	function __construct() {
		
	}

}

$tinymce_custom_link_class = new TinyMCE_Custom_Link_Class;

Aceasta creează clasa noastră PHP, împreună cu un constructor, care este apelat atunci când ajungem la linia $tinymce_custom_link_class = new TinyMCE_Custom_Link_Class;.

Orice funcții adăugăm în interiorul acestei clase nu ar trebui să intre în conflict cu alte plugin-uri WordPress.

Începe configurarea pluginului nostru TinyMCE

Apoi, trebuie să-i spunem lui TinyMCE că am putea dori să adăugăm butonul nostru personalizat la bara de instrumente a Editorului Vizual. Pentru a face acest lucru, putem folosi acțiunile WordPress – în mod specific, acțiunea init.

Adăugați următorul cod în interiorul funcției __construct() a plugin-ului dvs.:

if ( is_admin() ) {
	add_action( 'init', array(  $this, 'setup_tinymce_plugin' ) );
}

Aceasta verifică dacă ne aflăm în interfața de administrare WordPress. Dacă suntem, atunci îi cere WordPress să ruleze funcția setup_tinymce_plugin din clasa noastră atunci când WordPress și-a finalizat rutina inițială de încărcare.

Apoi, adăugați funcția setup_tinymce_plugin:

/**
* Check if the current user can edit Posts or Pages, and is using the Visual Editor
* If so, add some filters so we can register our plugin
*/
function setup_tinymce_plugin() {

// Check if the logged in WordPress User can edit Posts or Pages
// If not, don't register our TinyMCE plugin
	
if ( ! current_user_can( 'edit_posts' ) && ! current_user_can( 'edit_pages' ) ) {
	        return;
}

// Check if the logged in WordPress User has the Visual Editor enabled
// If not, don't register our TinyMCE plugin
if ( get_user_option( 'rich_editing' ) !== 'true' ) {
return;
}

// Setup some filters
add_filter( 'mce_external_plugins', array( &$this, 'add_tinymce_plugin' ) );
add_filter( 'mce_buttons', array( &$this, 'add_tinymce_toolbar_button' ) );
		
	}

Aceasta verifică dacă utilizatorul WordPress curent conectat poate edita Postări sau Pagini. Dacă nu pot, nu are rost să înregistrăm plugin-ul nostru TinyMCE pentru acel utilizator, deoarece acesta nu va vedea niciodată Editorul Vizual.

Apoi verificăm dacă utilizatorul folosește Editorul Vizual, deoarece unii utilizatori WordPress îl dezactivează prin Utilizatori > Profilul tău. Din nou, dacă utilizatorul nu folosește Editorul Vizual, returnăm (ieșim din) funcție, deoarece nu avem nevoie să facem altceva.

În final, adăugăm două filtre WordPress – mce_external_plugins și mce_buttons, pentru a apela funcțiile noastre care vor încărca fișierul Javascript necesar pentru TinyMCE și vor adăuga un buton la bara de instrumente TinyMCE.

Înregistrarea fișierului Javascript și a butonului în Editorul Vizual

Să continuăm și să adăugăm funcția add_tinymce_plugin:

/**
* Adds a TinyMCE plugin compatible JS file to the TinyMCE / Visual Editor instance
*
* @param array $plugin_array Array of registered TinyMCE Plugins
* @return array Modified array of registered TinyMCE Plugins
*/
function add_tinymce_plugin( $plugin_array ) {

$plugin_array['custom_link_class'] = plugin_dir_url( __FILE__ ) . 'tinymce-custom-link-class.js';
return $plugin_array;

}
    

Această funcție îi spune TinyMCE că trebuie să încarce fișierele Javascript stocate în array-ul $plugin_array. Aceste fișiere Javascript îi vor spune TinyMCE ce să facă.

De asemenea, trebuie să adăugăm niște cod la funcția add_tinymce_toolbar_button, pentru a informa TinyMCE despre butonul pe care am dori să-l adăugăm în bara de instrumente:

/**
* Adds a button to the TinyMCE / Visual Editor which the user can click
* to insert a link with a custom CSS class.
*
* @param array $buttons Array of registered TinyMCE Buttons
* @return array Modified array of registered TinyMCE Buttons
*/
function add_tinymce_toolbar_button( $buttons ) {

array_push( $buttons, '|', 'custom_link_class' );
return $buttons;
}

Aceasta adaugă două elemente în array-ul de butoane TinyMCE: un separator (|) și numele programatic al butonului nostru (custom_link_class).

Salvați pluginul, apoi editați o pagină sau o postare pentru a vizualiza editorul vizual. Probabil că bara de instrumente nu este afișată momentan:

Nu vă faceți griji – dacă folosim consola de inspecție a browserului nostru web, vom vedea că o eroare 404 și o notificare au fost generate de TinyMCE, spunându-ne că nu poate găsi fișierul nostru Javascript.

Acest lucru este bun – înseamnă că am înregistrat cu succes plugin-ul nostru personalizat TinyMCE și acum trebuie să creăm fișierul Javascript pentru a spune TinyMCE ce să facă.

Crearea plugin-ului Javascript

Creați un fișier nou în folderul wp-content/plugins/tinymce-custom-link-class și numiți-l tinymce-custom-link-class.js. Adăugați acest cod în fișierul dvs. js:

(function() {
	tinymce.PluginManager.add( 'custom_link_class', function( editor, url ) {
		
	});
})();

Aceasta apelează clasa TinyMCE Plugin Manager, pe care o putem folosi pentru a efectua o serie de acțiuni legate de plugin-urile TinyMCE. Specific, adăugăm plugin-ul nostru la TinyMCE folosind funcția add.

Acesta acceptă două elemente; numele pluginului (custom_link_class) și o funcție anonimă.

Dacă sunteți familiarizat cu conceptul de funcții în programare, o funcție anonimă este pur și simplu o funcție fără nume. De exemplu, function foobar() { ... } este o funcție pe care am putea-o apela în altă parte în codul nostru folosind foobar().

Cu o funcție anonimă, nu putem apela acea funcție în altă parte în codul nostru – ea este apelată doar în punctul în care este invocată funcția add().

Salvați fișierul Javascript și apoi editați o Pagină sau un Post pentru a vedea Editorul Vizual. Dacă totul a funcționat, veți vedea bara de instrumente:

În acest moment, butonul nostru nu a fost adăugat la acea bară de instrumente. Asta pentru că am spus doar TinyMCE că suntem un plugin personalizat. Acum trebuie să spunem TinyMCE ce să facă – adică, să adăugăm un buton la bara de instrumente.

Actualizați fișierul Javascript, înlocuind codul existent cu următorul:

(function() {
	tinymce.PluginManager.add( 'custom_link_class', function( editor, url ) {
		// Add Button to Visual Editor Toolbar
		editor.addButton('custom_link_class', {
			title: 'Insert Button Link',
			cmd: 'custom_link_class',
		});	
	});
})();

Observați că funcția noastră anonimă are două argumente. Primul este instanța editor – acesta este editorul vizual TinyMCE. În același mod în care putem apela diverse funcții pe PluginManager, putem apela și diverse funcții pe editor. În acest caz, apelăm funcția addButton, pentru a adăuga un buton la bara de instrumente.

Salvați fișierul Javascript și reveniți la Editorul vizual. La prima vedere, nimic nu pare să se fi schimbat. Cu toate acestea, dacă plasați cursorul mouse-ului în dreapta iconiței celei mai din dreapta din primul rând, ar trebui să vedeți să apară un tooltip:

Am adăugat cu succes un buton la bara de instrumente, dar acesta are nevoie de o imagine. Adăugați următorul parametru la funcția addButton, sub linia title::

image: url + '/icon.png',

url is the URL to our plugin. This is handy if we want to reference an image file within our plugin folder, as we can append the image file name to the URL. In this case, we’ll need an image called icon.png in our plugin’s folder. Use the below icon:

Reload our Visual Editor, and you’ll now see your button with the icon:

Definirea unei Comenzi de Executat

În acest moment, dacă faceți clic pe buton, nu se va întâmpla nimic. Să adăugăm o comandă la TinyMCE care să-i spună ce să facă atunci când butonul nostru este apăsat.

În fișierul nostru Javascript, adăugați următorul cod sub sfârșitul secțiunii editor.addButton:

// Add Command when Button Clicked
editor.addCommand('custom_link_class', function() {
	alert('Button clicked!');
});

Reîncărcați Editorul Vizual, faceți clic pe buton și va apărea o alertă confirmând că tocmai am făcut clic pe buton:

Să înlocuim alerta cu un prompt, cerând utilizatorului link-ul pe care dorește să-l înconjoare textul selectat în Editorul Vizual:

// Add Command when Button Clicked
editor.addCommand('custom_link_class', function() {
	// Check we have selected some text that we want to link
	var text = editor.selection.getContent({
		'format': 'html'
	});
	if ( text.length === 0 ) {
		alert( 'Please select some text to link.' );
		return;
	}

	// Ask the user to enter a URL
	var result = prompt('Enter the link');
	if ( !result ) {
		// User cancelled - exit
		return;
	}
	if (result.length === 0) {
		// User didn't enter a URL - exit
		return;
	}

	// Insert selected text back into editor, wrapping it in an anchor tag
	editor.execCommand('mceReplaceContent', false, '<a class="button" href="' + result + '">' + text + '</a>');
});

Acest bloc de cod efectuează câteva acțiuni.

Mai întâi, verificăm dacă utilizatorul a selectat text pentru a fi legat în Editorul Vizual. Dacă nu, va vedea o alertă care îi spune să selecteze text pentru a fi legat.

Apoi, le cerem să introducă un link, verificând din nou dacă au făcut-o. Dacă au anulat sau nu au introdus nimic, nu facem altceva.

În final, rulăm funcția execCommand pe editorul TinyMCE, rulând în mod specific acțiunea mceReplaceContent. Aceasta înlocuiește textul selectat cu codul nostru HTML, care constă dintr-un link de ancorare cu clasa „button”, folosind textul selectat de utilizator.

Dacă totul a funcționat, veți vedea că textul selectat este acum legat în vizualizările Editor Vizual și Text, cu clasa setată la button:

Rezumat

Am creat cu succes un plugin WordPress care adaugă un buton la editorul vizual TinyMCE în WordPress. Acest tutorial a acoperit, de asemenea, câteva dintre elementele de bază ale API-ului TinyMCE și filtrele WordPress disponibile pentru integrările TinyMCE.

Am adăugat cod astfel încât, atunci când un utilizator face clic pe butonul nostru personalizat, i se solicită să selecteze un text în editorul vizual, pe care îl poate apoi lega la un URL la alegerea sa. În final, pluginul nostru înlocuiește textul selectat cu o versiune legată care conține o clasă CSS personalizată numită button.

Sperăm că acest tutorial v-a ajutat să învățați cum să creați un plugin TinyMCE pentru WordPress. De asemenea, ați putea dori să consultați ghidul nostru despre cum să creezi un plugin WordPress specific site-ului.

Dacă v-a plăcut acest articol, atunci vă rugăm să vă abonați la canalul nostru de YouTube pentru tutoriale video WordPress. Ne puteți găsi, de asemenea, pe Twitter și Facebook.