Limpar Busca

Criando um plugin customizado para o CKEditor no LumisXP

Introdução

O CKEditor utilizado pelo LumisXP pode ser estendido para atender a necessidades específicas de um projeto. Além dos recursos disponibilizados pela plataforma, é possível criar plugins customizados para adicionar novos comandos, botões e funcionalidades ao editor.

Neste artigo, será apresentado um exemplo de criação de um plugin customizado chamado helloWorld. Ao clicar no botão correspondente na barra de ferramentas do CKEditor, o plugin irá inserir o conteúdo <p>Hello World!</p> na posição atual do cursor.

Embora o exemplo seja simples, o mesmo conceito pode ser utilizado como base para a implementação de funcionalidades mais específicas em projetos que utilizam o LumisXP.

Integração do CKEditor no LumisXP

No LumisXP, o CKEditor é integrado por meio do controle DOUI lum_inputHtmlEditor. A customização do editor com um plugin envolve principalmente dois pontos: os arquivos que implementam o plugin e as configurações que informam ao CKEditor quais plugins devem ser carregados e quais botões devem aparecer na barra de ferramentas.

Os arquivos do plugin devem ser disponibilizados dentro da pasta www do tema. Já as configurações são realizadas por meio das Property Bags:

  • lumis.doui.ckeditor.extraPlugins
  • lumis.doui.ckeditor.toolbarButtons

Estrutura de arquivos

Para criar o plugin do exemplo, considere a seguinte estrutura de arquivos:

src/br/com/example/
├── component-collection/default/
│   └── lum-component-collection.xml
├── structure/example/
│   ├── componentdefinition.xml
│   └── componentfiles/structure/example/
│       └── ch_example.xml
└── theme/example/
    ├── themedefinition.xml
    └── www/
        └── ckeditor/
            └── customplugins/
                └── helloWorld/
                    ├── plugin.js
                    ├── icons/
                    │   └── helloworld.png
                    └── lang/
                        ├── en.js
                        └── pt-br.js

Os arquivos do plugin devem ficar dentro do diretório www/ckeditor/customplugins/ do tema.

Na configuração do plugin, o caminho deve ser informado a partir do tema, seguindo o formato:

lumis-theme/<pacote-do-tema>/ckeditor/customplugins/<nomeDoPlugin>

Criando o plugin

Dentro do diretório www/ckeditor/customplugins/helloWorld/, crie o arquivo plugin.js com o seguinte conteúdo:

(function(){
    var commandName = 'helloWorld';

    CKEDITOR.plugins.add(commandName, {
        lang: ['en', 'pt-br'],

        init: function(editor) {

            editor.addCommand(commandName, {
                exec: function(editor) {
                    editor.insertHtml('<p>Hello World!</p>');
                }
            });

            editor.ui.addButton(commandName, {
                label: editor.lang.helloWorld.buttonTitle,
                icon: this.path + 'icons/helloworld.png',
                command: commandName
            });
        }
    });
})();

O commandName, definido como helloWorld, é o identificador do plugin. Esse mesmo nome será utilizado posteriormente nas configurações do CKEditor.

O método editor.addCommand() registra o comando executado pelo plugin. Neste exemplo, o comando utiliza editor.insertHtml() para inserir o HTML na posição atual do cursor.

O método editor.ui.addButton() cria o botão que será disponibilizado na barra de ferramentas. Nesse caso, são definidas três informações principais:

  • label: texto utilizado para identificar o botão, obtido a partir do arquivo de tradução.
  • icon: caminho para o ícone do botão.
  • command: comando executado quando o botão é acionado.

Adicionando as traduções

O plugin pode disponibilizar textos em diferentes idiomas. Para isso, crie o diretório lang dentro da pasta do plugin:

helloWorld/
└── lang/
    ├── en.js
    └── pt-br.js

No arquivo lang/en.js, adicione:

CKEDITOR.plugins.setLang('helloWorld', 'en', {
    buttonTitle: 'Insert Hello World'
});

No arquivo lang/pt-br.js, adicione:

CKEDITOR.plugins.setLang('helloWorld', 'pt-br', {
    buttonTitle: 'Inserir Hello World'
});

Essas traduções são utilizadas pelo plugin por meio da propriedade editor.lang.helloWorld.buttonTitle, definida no momento da criação do botão.

Adicionando o ícone

O botão do plugin também utiliza um ícone. Crie o diretório icons dentro da pasta do plugin e adicione o arquivo:

icons/helloworld.png

Para este exemplo, o ícone deve ser um arquivo PNG com dimensões de 16x16 pixels.

Ao final dessa etapa, a estrutura do plugin será:

helloWorld/
├── plugin.js
├── icons/
│   └── helloworld.png
└── lang/
    ├── en.js
    └── pt-br.js

Configurando as Property Bags

Depois de criar os arquivos do plugin, é necessário configurá-lo no LumisXP. As Property Bags permitem informar ao CKEditor quais plugins adicionais devem ser carregados e quais botões devem ser apresentados na barra de ferramentas.

As propriedades podem ser configuradas diretamente pelo Portal Studio, nas configurações avançadas do canal.

Em projetos LumisXP, também é comum que os canais sejam distribuídos por meio de módulos que contêm sua estrutura e suas configurações. Nesse caso, as Property Bags podem ser declaradas no arquivo de definição do canal, como no exemplo:

structure/example/componentfiles/structure/example/ch_example.xml

Adicione a seguinte configuração:

<property-bag>
    <property name="lumis.doui.ckeditor.extraPlugins">
        <default-values>
            <value>lum_default,helloWorld:lumis-theme/br/com/example/theme/example/ckeditor/customplugins/helloWorld</value>
        </default-values>
    </property>

    <property name="lumis.doui.ckeditor.toolbarButtons">
        <default-values>
            <value>lum_default,{ name: 'custom', items : [ 'helloWorld' ] }</value>
        </default-values>
    </property>
</property-bag>

Property Bag lumis.doui.ckeditor.extraPlugins

A Property Bag lumis.doui.ckeditor.extraPlugins é responsável por registrar os plugins adicionais que serão carregados pelo CKEditor.

No exemplo, foi utilizado:

lum_default,helloWorld:lumis-theme/br/com/example/theme/example/ckeditor/customplugins/helloWorld

O valor lum_default representa os plugins padrão do LumisXP. Dessa forma, os plugins já disponibilizados pela plataforma são mantidos.

O plugin customizado é informado no formato:

<nomeDoPlugin>:<caminho>[:<nomeDoArquivo>]

Neste exemplo:

  • helloWorld é o nome do plugin e deve corresponder ao identificador utilizado no arquivo plugin.js.
  • lumis-theme/br/com/example/theme/example/ckeditor/customplugins/helloWorld é o caminho da pasta do plugin dentro do tema.

O nome do arquivo JavaScript é opcional. Quando não é informado, o CKEditor utiliza plugin.js como nome padrão.

Property Bag lumis.doui.ckeditor.toolbarButtons

A Property Bag lumis.doui.ckeditor.toolbarButtons define os botões que serão apresentados na barra de ferramentas do CKEditor.

No exemplo, foi utilizada a seguinte configuração:

lum_default,{ name: 'custom', items : [ 'helloWorld' ] }

Assim como na configuração dos plugins, o valor lum_default mantém a toolbar padrão do LumisXP.

O trecho:

{ name: 'custom', items : [ 'helloWorld' ] }

adiciona um grupo chamado custom contendo o botão helloWorld.

O nome informado em items deve ser o mesmo utilizado no método editor.ui.addButton() do plugin.

Também é possível organizar os botões em diferentes grupos. Para criar uma quebra de linha na toolbar, utilize /.

Utilizando uma toolbar customizada

O uso de lum_default não é obrigatório. Quando ele está presente, os plugins e botões padrão do LumisXP são mantidos e os elementos customizados são adicionados à configuração.

Caso seja necessário criar uma toolbar completamente customizada, basta omitir o lum_default e definir manualmente os grupos e botões que deverão ser apresentados.

Configurando pelo Portal Studio

As mesmas propriedades podem ser configuradas diretamente pelo Portal Studio, nas configurações avançadas do canal.

Para o exemplo deste artigo, utilize:

lumis.doui.ckeditor.extraPlugins

lum_default,helloWorld:lumis-theme/br/com/example/theme/example/ckeditor/customplugins/helloWorld

lumis.doui.ckeditor.toolbarButtons

lum_default,{ name: 'custom', items : [ 'helloWorld' ] }

Testando o plugin

Depois de criar os arquivos e realizar as configurações, faça o deploy do projeto em um ambiente de desenvolvimento.

Após o deploy, acesse um componente que utilize o editor HTML do LumisXP e verifique se o botão Hello World está disponível na barra de ferramentas.

Posicione o cursor no conteúdo do editor e clique no botão. O plugin deverá inserir:

<p>Hello World!</p>

O conteúdo será inserido na posição atual do cursor.

Conclusão

A criação de plugins customizados permite estender os recursos do CKEditor utilizado pelo LumisXP sem modificar o funcionamento padrão da plataforma.

Neste exemplo, foram apresentados os principais elementos necessários para criar um plugin: o arquivo JavaScript responsável pela implementação, os arquivos de tradução, o ícone e as configurações das Property Bags.

A partir dessa estrutura, é possível desenvolver plugins com funcionalidades específicas para cada projeto, adicionando novos comandos e recursos ao editor de conteúdo.

Referências

Property Bags

Definição de componentes

Autor: Luiz Valença