14.10.2014

CKEditor plugin snadno a rychle

Jestli jste někdy přemýšleli o použití WYSIWYG „What you see is what you get“ editoru, pravděpodobně jste narazili i na CKEditor. Ten dnes patří mezi nejpoužívanější nástroje pro editaci textu na webových stránkách. Mezi jeho hlavní výhody patří snadné použití, velmi dobrá rozšiřitelnost a kvalitní dokumentace. I přes velmi širokou množinu funkcí a již existujících rozšíření se Vám může stát, že potřebujete v editaci textu využít specifickou funkcionalitu, která není součástí CKEditoru. Jednoduchým řešením je vytvoření vlastního pluginu. Jak na to si ukážeme v následujícím příkladu. Budeme přepokládat, že máme v databázi seznam citátů, který je přístupný přes vystavenou REST službu, a tyto citáty budeme chtít vkládat do stránky. K tomu bude třeba i nějaký dialog, ve kterém bude možné vybrat, který citát chceme vložit. Pojďme tedy společně na věc. Plugin nazveme myplugin a budeme ho vytvářet v CKEditoru v adresáři plugins. Jeho struktura bude následující:

  • ckeditor root/
    • plugins/
      • myplugin/
        • images/
          • myplugin.png
        • dialog/
          • mydialog.js
        • plugin.js

Začneme vytvořením souboru „plugin.js“. Ten obsahuje nastavení pluginu. Každý plugin se do CKeditoru přidává pomocí CKEDITOR.plugins.add funkce, která nastaví jméno pluginu a provede jeho inicializaci. Aby se po spuštění otevřel dialog, musíme vytvořit dialog command, který provede otevření našeho dialogu. Pod tím samým jménem musí být uvedeno přidání dialogu odkazující na soubor „myplugin.js“. Ten obsahuje nastavení dialogu.

Nakonec přidáme tlačítko do toolbaru CKEditoru, které vyvolá spuštění commandu a tím otevře definovaný dialog. Tlačítko umístíme do sekce toolbaru „insert“.

CKEDITOR.plugins.add( 'myplugin', {
  init: function( editor ) {
    editor.addCommand( 'mypluginDialog', new CKEDITOR.dialogCommand( 'mypluginDialog' ) );
    CKEDITOR.dialog.add( 'mypluginDialog', this.path + 'dialogs/mydialog.js' );
    editor.ui.addButton( 'Fragments', {
      label: 'Vloz citat',
      command: 'mypluginDialog',
      toolbar: 'insert',
      icon: this.path + 'icons/myplugin.png'
    });
  }
});

Nyní již máme vytvořené tlačítko v toolbaru CKEditoru. Dále musíme definovat vzhled a vlastnosti samotného dialogu.

V souboru „mydialog.js“ se vytvoří dialog pomocí funkce CKEDITOR.dialog.add se stejným jménem jako tím, které bylo použito v hlavním nastavení pluginu. Definici dialogu vytvoříme funkcí, která vrací data odpovídající API pro funkci add.

Ve funkci jakýmkoliv způsobem získáme seznam citátů. V příkladu je použit ajax pro načtení dat z lokální služby. V definici dialogu je možné nastavit titulek, velikost dialogu a hlavně prvky, které má dialog obsahovat. V našem  případě vytvoříme jeden tab myDialogId, který obsahuje element typu select s přednačtenými daty s citáty.

Poslední částí je reakce na tlačítko pro potvrzení výběru citátu. Tlačítka Ok i Close jsou automaticky součástí dialogu. Tlačítko Ok pouze vezme data z dialogu a vloží je do editoru na pozici kurzoru. Citát by bylo možné případně i obalit odstavcem, označit kurzívou apod.

CKEDITOR.dialog.add( 'myPluginDialog', function( editor ) {
  var json;
  $.ajax({
    url: 'http://localhost/example/myDialog/data' ,
    dataType: 'json',
    async: false,
    success: function(data){
      json = data;
    }
  });
  return {
    title: 'Insert MyDialog data',
    minWidth: 400,
    minHeight: 200,
    contents : [
      {
        id : 'myDialogId',
        label : '',
        title : '',
        elements :
          [
            {
             type : 'select',
             label: 'Vyber citat',
             labelLayout: 'horizontal',
             items : json
           }
         ]
      }
    ],

    onOk: function() {
      var dialog = this;
      editor.insertText( dialog.getValueOf( 'myDialogId' ) );
    }
  };
});

Funkční plugin máme vytvořen. Zbývá ho tedy pouze zaregistrovat v CKEditoru. To se provede v souboru „config.js“ uloženém v hlavním adresáři editoru. Do tohoto souboru přidáme do konfigurace editoru tento kód:

config.extraPlugins = 'myplugin';

Teď již stačí použít CKEditor ve Vaší stránce, podívat se, jak Váš plugin vypadá. Nebo se prostě jen můžete podívat na obrázek níže. Toto byl samozřejmě velice jednoduchý příklad, který měl pouze demonstrovat možnosti tvorby vlastních pluginů. Stejně tak jednoduše je možné vytvářet i komplexnější příklady.

Máte nějaké zkušenosti s psaním pluginů, ať už dobré či špatné? Podělte se o ně s námi…

screenshot
Výsledný plugin s výběrem citátů