Hur man skapar ett WordPress TinyMCE-plugin

Om du är WordPress-utvecklare kan du vid något tillfälle stöta på att anpassa eller utöka WordPress visuella redigerare. Du kanske till exempel vill lägga till en knapp i den visuella redigerarens verktygsfält för att låta din klient enkelt infoga en textruta eller en uppmaning till handling utan att skriva någon HTML-kod. I den här artikeln visar vi hur du skapar ett TinyMCE-plugin i WordPress.

Krav

Denna handledning är avsedd för avancerade användare. Om du är en nybörjare som bara vill utöka den visuella redigeraren, kolla in TinyMCE Advanced-pluginet eller ta en titt på dessa tips för att använda WordPress visuella redigerare.

För den här handledningen behöver du grundläggande kodningskunskaper, tillgång till en WordPress-installation där du kan testa den.

Det är dålig praxis att utveckla plugins på en live-webbplats. Ett litet misstag i koden kan göra din webbplats otillgänglig. Men om du måste göra det på en live-webbplats, så säkerhetskopiera WordPress först.

Skapa ditt första TinyMCE-plugin

Vi börjar med att skapa ett WordPress-plugin för att registrera vår anpassade TinyMCE-verktygsfältsknapp. När den klickas på kommer den här knappen att tillåta användaren att lägga till en länk med en anpassad CSS-klass.

Källkoden kommer att tillhandahållas i sin helhet i slutet av den här artikeln, men tills dess, låt oss skapa pluginet steg för steg.

Först måste du skapa en katalog i mappen wp-content/plugins i din WordPress-installation. Namnge denna mapp tinymce-custom-link-class.

Härifrån börjar vi lägga till vår plugin-kod.

Plugin-huvudet

Skapa en ny fil i plugin-katalogen vi just skapade och namnge filen tinymce-custom-link-class.php. Lägg till denna kod i filen och spara den.

/**
 * 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
 */

Detta är bara en PHP-kommentar, som talar om för WordPress pluginets namn, samt författaren och en beskrivning.

I WordPress adminpanelen, aktivera ditt nya plugin genom att gå till Plugins > Installera plugins och sedan klicka på Aktivera bredvid pluginet TinyMCE Custom Link Class:

Konfigurera vårt plugin-klass

Om två WordPress-plugins har funktioner med samma namn, skulle det orsaka ett fel. Vi undviker detta problem genom att våra funktioner är inneslutna i en klass.

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

}

$tinymce_custom_link_class = new TinyMCE_Custom_Link_Class;

Detta skapar vår PHP-klass, tillsammans med en konstruktor, som anropas när vi når raden $tinymce_custom_link_class = new TinyMCE_Custom_Link_Class;.

Eventuella funktioner vi lägger till inuti den här klassen bör inte krocka med andra WordPress-plugins.

Starta konfigurationen av vårt TinyMCE-plugin

Därefter måste vi tala om för TinyMCE att vi kanske vill lägga till vår anpassade knapp i verktygsfältet för den visuella redigeraren. För att göra detta kan vi använda WordPress åtgärder – specifikt init-åtgärden.

Lägg till följande kod inuti din plugins __construct()-funktion:

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

Detta kontrollerar om vi befinner oss i WordPress administrationsgränssnitt. Om vi gör det, ber det WordPress att köra funktionen setup_tinymce_plugin inuti vår klass när WordPress har slutfört sin initiala laddningsrutin.

Lägg sedan till funktionen 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' ) );
		
	}

Detta kontrollerar om den aktuella inloggade WordPress-användaren kan redigera inlägg eller sidor. Om de inte kan det, finns det ingen anledning att registrera vårt TinyMCE-plugin för den användaren, eftersom de aldrig kommer att se den visuella redigeraren.

Vi kontrollerar sedan om användaren använder den visuella redigeraren, eftersom vissa WordPress-användare stänger av den via Användare > Din profil. Återigen, om användaren inte använder den visuella redigeraren, returnerar vi (avslutar) funktionen, eftersom vi inte behöver göra något mer.

Slutligen lägger vi till två WordPress-filter – mce_external_plugins och mce_buttons – för att anropa våra funktioner som laddar den nödvändiga Javascript-filen för TinyMCE och lägger till en knapp i TinyMCE-verktygsfältet.

Registrera Javascript-filen och knappen till den visuella redigeraren

Låt oss nu lägga till funktionen 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;

}
    

Denna funktion talar om för TinyMCE att den behöver ladda Javascript-filerna som lagras i matrisen $plugin_array. Dessa Javascript-filer kommer att tala om för TinyMCE vad som ska göras.

Vi behöver också lägga till lite kod i funktionen add_tinymce_toolbar_button för att berätta för TinyMCE om knappen vi vill lägga till i verktygsfältet:

/**
* 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;
}

Detta lägger två objekt på arrayen av TinyMCE-knappar: en avdelare (|) och vårt knapps programmatiska namn (custom_link_class).

Spara ditt plugin och redigera sedan en sida eller ett inlägg för att se visuella redigeraren. Troligtvis visas inte verktygsfältet just nu:

Oroa dig inte – om vi använder vår webbläsares inspektionskonsol kommer vi att se att ett 404-fel och en notis har genererats av TinyMCE, vilket talar om för oss att den inte kan hitta vår Javascript-fil.

Det är bra – det betyder att vi har registrerat vårt anpassade TinyMCE-plugin framgångsrikt, och nu behöver vi skapa Javascript-filen för att tala om för TinyMCE vad den ska göra.

Skapa Javascript-pluginet

Skapa en ny fil i din mapp wp-content/plugins/tinymce-custom-link-class och namnge den tinymce-custom-link-class.js. Lägg till denna kod i din js-fil:

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

Detta anropar TinyMCE Plugin Manager-klassen, som vi kan använda för att utföra ett antal TinyMCE-plugin-relaterade åtgärder. Specifikt lägger vi till vårt plugin i TinyMCE med hjälp av funktionen add.

Detta accepterar två element; pluginets namn (custom_link_class) och en anonym funktion.

Om du är bekant med konceptet funktioner i kodning är en anonym funktion helt enkelt en funktion utan namn. Till exempel är function foobar() { ... } en funktion som vi kan anropa någon annanstans i vår kod genom att använda foobar().

Med en anonym funktion kan vi inte anropa den funktionen någon annanstans i vår kod – den anropas bara vid den tidpunkt då funktionen add() anropas.

Spara din Javascript-fil och redigera sedan en sida eller ett inlägg för att se den visuella redigeraren. Om allt fungerade ser du verktygsfältet:

Just nu har vår knapp inte lagts till i det verktygsfältet. Det beror på att vi bara har talat om för TinyMCE att vi är ett anpassat plugin. Vi måste nu tala om för TinyMCE vad som ska göras – det vill säga, lägga till en knapp i verktygsfältet.

Uppdatera din Javascript-fil och ersätt din befintliga kod med följande:

(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',
		});	
	});
})();

Lägg märke till att vår anonyma funktion har två argument. Det första är editor-instansen – detta är TinyMCE Visual Editor. På samma sätt som vi kan anropa olika funktioner på PluginManager, kan vi också anropa olika funktioner på editor. I det här fallet anropar vi funktionen addButton för att lägga till en knapp i verktygsfältet.

Spara din Javascript-fil och gå tillbaka till din visuella redigerare. Vid en första anblick verkar inget ha förändrats. Men om du för muspekaren till höger om den yttersta ikonen i den översta raden bör du se en verktygstips dyka upp:

Vi har framgångsrikt lagt till en knapp i verktygsfältet, men den behöver en bild. Lägg till följande parameter till addButton-funktionen, under raden 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:

Definiera ett kommando att köra

Just nu, om du klickar på knappen, kommer ingenting att hända. Låt oss lägga till ett kommando till TinyMCE som talar om vad som ska hända när vår knapp klickas.

I vår Javascript-fil, lägg till följande kod under slutet av sektionen editor.addButton:

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

Ladda om vår visuella redigerare, klicka på knappen och en varning kommer att visas som bekräftar att vi precis klickade på knappen:

Låt oss ersätta alerten med en prompt, som frågar användaren efter länken de vill slå in den markerade texten med i den visuella redigeraren:

// 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>');
});

Detta kodblock utför några åtgärder.

Först kontrollerar vi om användaren har valt någon text att länka i den visuella redigeraren. Om inte, kommer de att se en varning som talar om för dem att välja text att länka.

Därefter ber vi dem att ange en länk, och kontrollerar igen om de gjorde det. Om de avbröt, eller inte angav något, gör vi inget mer.

Slutligen kör vi funktionen execCommand på TinyMCE-redigeraren, specifikt kör vi åtgärden mceReplaceContent. Detta ersätter den markerade texten med vår HTML-kod, som består av en ankarlänk med klassen ”button”, med hjälp av den text som användaren valde.

Om allt fungerade ser du att din valda text nu är länkad i de visuella redigerings- och textvyerna, med klassen inställd på button:

Sammanfattning

Vi har framgångsrikt skapat ett WordPress-plugin som lägger till en knapp i TinyMCE:s visuella redigerare i WordPress. Denna handledning har också täckt några av grunderna i TinyMCE API och WordPress-filter som är tillgängliga för TinyMCE-integrationer.

Vi lade till kod så att när en användare klickar på vår anpassade knapp, uppmanas de att välja lite text i den visuella redigeraren, som de sedan kan länka till en URL som de väljer. Slutligen ersätter vårt plugin den valda texten med en länkad version som innehåller en anpassad CSS-klass som kallas button.

Vi hoppas att den här handledningen hjälpte dig att lära dig hur du skapar ett WordPress TinyMCE-plugin. Du kanske också vill kolla in vår guide om hur man skapar ett webbplatsspecifikt WordPress-plugin.

Om du gillade den här artikeln, vänligen prenumerera på vår YouTube-kanal för WordPress-videoguider. Du kan också hitta oss på Twitter och Facebook.