Vlastní tlačítka v TinyMCE editoru pro Wordpress

Kdo se setkal s administrací Wordpressu, je určitě obeznámen s jeho WYSIWYG editorem. TinyMCE je snadno rozšířitelný a open-source. Rozšíříme jej vytvořením vlastního jednoduchého TinyMCE pluginu, který do něj přidá tlačítko pro vložení shortcode. Shortcode se budeme věnovat v budoucím článku. Ve zkratce jde o kód, který po vložení do editoru vykoná nějakou funkci. Nejčastěji se používá pro vykreslení části HTML, které by jinak nebylo do výstupu editoru snadné dostat. Běžnému uživateli ale zadávání nějakého kódu nemusí být přijemné. Proto je dobré tuto úlohu omezit na klik tlačítka.

Náš shortcode bude vykreslovat vlastní kus HTML obsahující libovolný text. Protože shortcode může být i párový, textový obsah bude uvozený mezi jeho tagy. Po vybrání textu v editoru a kliknutí na naše tlačítko se vybraný text obalí shortcode tagy.

Pro začátek si stanovíme adresářovou strukturu. V adresáři šablony vytvoříme adresář js/tiny-mce pro náš plugin. Ten bude obsahovat složku img pro obrázky a hlavní skript tiny-mce.js. Ve finále bude struktura vypadat nějak takto:

js
../tiny-mce 
../../img 
../../tiny-mce.js

Následně vytvoříme ikonu, která bude zobrazená na tlačítku. Cílem je PNG obrázek velký 48x48 px. Dobrý výběr hotových ikon je např. na Flaticon nebo v tomto repozitáři, který obsahuje sbírku FontAwesome ikon převedených do SVG a PNG. Ikona příjde do adresáře img. V mém případě to bude icon.png.

Hlavní část rozšíření pro přidání tlačítka bude v souboru tiny-mce.js. V něm pomocí metody create() na objektu tinymce vytvoříme náš plugin.

(function () {

  // Vytvoří TinyMCE plugin
  tinymce.create('tinymce.plugins.MyPluginName', {

    init: function (editor, url) {
      // Inicializace pluginu
    },

    getInfo: function () {
      // Informace o pluginu a autorovi
      return {
        longname: 'Můj plugin s tlačítkem',
        author: 'Michael Tichopád',
        authorurl: 'https://www.kutac.cz/',
        version: "1.0"
      };

    }

  });

  // Přidá plugin do TinyMCE editoru
  tinymce
    .PluginManager
    .add('mytinymceplugin', tinymce.plugins.MyPluginName);

})();

Nyní máme vytvořený plugin s prázdnými funkcemi init() a getInfo(). Funkce init je hlavní funkce pluginu, která by měla obsahovat veškerou jeho logiku. Přijímá dva parametry - první parametr je objekt editoru a druhý je URL cesty ke složce ve které se tento JS soubor nachází. Informace o autorovi a jiná metadata vrací funkce getInfo.

Uvnitř funkce init budeme na objektu editoru volat dvě metody - addButton a addCommand. Metoda addButton vytvoří v editoru tlačítko a addCommand tomuto tlačítku přidá funkčnost.

addButton přijímá jako první parametr nějaký unikátní název tlačítka a druhým parametrem je objekt definující title, který se zobrazí po najetí kurzorem na tlačítko, jeho ikonu a nějaký název jeho "příkazu" definovaného v addCommand.

// Přidá tlačítko do editoru
editor.addButton('myshortcodebtn', {
  title: 'Přidat shortcode',
  cmd: 'myShortcodeBtnCmd',
  image: url + '/img/icon.png'
});

// Přidá tlačítku funkčnost
editor.addCommand('myShortcodeBtnCmd', function () {
  // Funkce, která bude vykonaná kliknutím na tlačítko
});

V metodě addCommand nyní potřebujeme vytáhnout z editoru vybraný text, upravit ho a vložit zpátky do editoru. Výběr lze z editoru získat metodou getContent objektu editor.selection. Jako parametr přijímá objekt s nastavením, to bude v mém případě pro zachování HTML formátu vybraného textu. Vybraný text upravíme a pak je vložen zpět do editoru pomocí metody execCommand.

editor.addCommand('myShortcodeBtnCmd', function () {

  // Výběr textu z editoru a jeho obalení shortcode tagy
  var selected = editor.selection.getContent({ format: 'html' });
  var returnText = '[myshortcode]' + selected + '[/myshortcode]';

  // Vloží upravený text zpátky do editoru
  editor.execCommand('mceInsertContent', 0, returnText);

});

Teď když máme JS část za sebou, je třeba ještě plugin zaregistrovat do Wordpressu. To provedeme v souboru functions.php pomocí filter hooků.

// Přidá plugin do editoru
function tiny_mce_add_buttons($plugins) {
  $path = get_template_directory_uri() . '/js/tiny-mce';
  // Stejný název, jaký je použitý v souboru tiny-mce.js
  $plugins['mytinymceplugin'] = "$path/tiny-mce.js";
  
  return $plugins;
}

// Přidá vlastní tlačítko do editoru
function tiny_mce_register_buttons($buttons) {
  // Stejný název, jaký je použitý pro tlačítko v tiny-mce.js
  $newBtns = array(
    'myshortcodebtn'
  );
  $buttons = array_merge($buttons, $newBtns);
  
  return $buttons;
}

// Přidá filter hooky při inicializaci stránky
function tiny_mce_new_buttons() {
  add_filter('mce_external_plugins', 'tiny_mce_add_buttons');
  add_filter('mce_buttons', 'tiny_mce_register_buttons');
}

add_action('init', 'tiny_mce_new_buttons');

To je vše. Editor v administraci Wordpressu by měl nyní mít přidáno nové tlačítko, které po kliknutí obalí vybraný text vlastním shortcodem.

Pro další možnosti, jak rozšířit TinyMCE editor, ať už hotovými nebo vlastními pluginy, doporučuji dokumentaci TinyMCE a Wordpressu.

---

Používáte TinyMCE i mimo Wordpress? Napadá vás, jak jinak by jej šlo rozšířit? Podělte se s ostatními v komentářích.