Pesquisa de site

Como criar seu próprio plug-in para documentos do ONLYOFFICE

Resumo: neste artigo, você aprenderá como criar seu próprio plugin para o ONLYOFFICE Docs e como publicá-lo no mercado oficial de plugins que está disponível a partir da versão 7.2.

ONLYOFFICE Docs não é um pacote de escritório comum no sentido tradicional. Claro, ele permite que você faça o que você pode fazer usando outros pacotes de escritório – criar e editar documentos, planilhas e apresentações, compartilhá-los e coeditá-los on-line, criar formulários preenchíveis, navegar e converter arquivos PDF e assim por diante.

No entanto, existe uma maneira de tornar o ONLYOFFICE ainda mais poderoso. O que se entende aqui são plug-ins de terceiros, ou seja, ferramentas de software adicionais que aprimoram os recursos funcionais padrão do pacote. Por exemplo, os plug-ins permitem conectar serviços de terceiros ou adicionar novos elementos de interface do usuário.

Como criar um plug-in para documentos do ONLYOFFICE

Antes de começar a criar seu próprio plugin para ONLYOFFICE Docs, você precisa ter uma conta GitHub e conhecer os fundamentos de como trabalhar com esta plataforma. Isto é muito importante. Se você é novo no GitHub, pode dar uma olhada na documentação oficial do GitHub.

O processo de criação do plugin pode ser dividido em sete etapas que você precisa seguir com atenção:

  • Atividades preliminares.
  • Codificação.
  • Ajuste do estilo do plugin.
  • Localização (opcional).
  • Preparação.
  • Testando.
  • Publicação no mercado de plugins.

Vamos nos aprofundar no desenvolvimento do plugin.

Etapa 1. Bifurque o repositório do Plugin Marketplace

Primeiro de tudo, você precisa fazer login em sua conta GitHub ou criar uma, caso ainda não tenha uma. Depois disso, você precisa criar um fork do repositório do mercado de plug-ins ONLYOFFICE que está disponível no seguinte endereço URL:

https://github.com/ONLYOFFICE/onlyoffice.github.io.

Como resultado, você terá outro repositório e seu endereço URL será mais ou menos assim:

https://github.com/YOUR-USERNAME/ONLYOFFICE/onlyoffice.github.io

Depois de bifurcar com sucesso o repositório do plugin marketplace, é necessário criar um site de Páginas GitHub a partir deste repositório para fins de teste. Se você não sabe como fazer isso, consulte o guia oficial do GitHub.

Agora que você tem seu próprio site GitHub Pages, é hora de clonar o fork para o seu computador.

Finalmente, você precisa criar uma pasta para seu futuro plugin em:

onlyoffice.github.io/sdkjs-plugins/content/.

É isso. Você acabou de concluir todas as atividades preliminares necessárias e pode prosseguir para a próxima etapa.

Etapa 2. Escreva o código do seu plugin

Você não precisa ser extremamente bom em codificação, mas definitivamente precisa de algum conhecimento básico de codificação para criar seu próprio plugin para o ONLYOFFICE Docs.

Resumindo, um plugin ONLYOFFICE é uma pasta com vários arquivos. Você deve criar três arquivos para que seu plugin funcione corretamente:

  • config.json – Este é um arquivo de configuração do plugin que contém informações sobre todos os dados importantes. Neste arquivo existem alguns parâmetros que são necessários para cadastrar o plugin nos editores do ONLYOFFICE. Consulte esta página na documentação oficial da API para ler a descrição completa de cada parâmetro.
  • código do plugin (arquivo .js) – Este é o próprio arquivo do plugin que contém o código JavaScript do seu plugin. Este arquivo descreve as operações que o plugin realiza e como elas são executadas. Leia este guia da API para saber como funciona.
  • index.html – Este é o ponto de entrada do seu plugin que conecta os arquivos config.json e plugin.js. Dê uma olhada neste exemplo para entender como deve ser.

Além desses arquivos obrigatórios, a pasta do plugin pode conter outros arquivos. Por exemplo, ícones, estilos de plug-ins, arquivos leia-me, serviços de terceiros, etc. Você encontrará mais informações sobre esses arquivos abaixo.

Para escrever um bom código funcional para o seu plugin, você precisa conhecer os métodos e eventos necessários.

Etapa 3. Ajuste o estilo do seu plugin

Escrever código para o seu plugin não é suficiente. Você também precisa ajustar seu estilo para que pareça parte integrante dos editores do ONLYOFFICE. Para fazer isso, basta adicionar a folha de estilo do ONLYOFFICE ao arquivo index.html descrito acima:

<link rel="stylesheet" href="https://onlyoffice.github.io/sdkjs-plugins/v1/plugins.css">

Você pode adicionar botões, controles de entrada, controles de rótulos, carregadores e outros elementos.

Por exemplo, para adicionar uma caixa de combinação ao seu plugin, você pode usar a função select2:

<select id="select_example" class="" ></select> 
$('#select_example').select2({     
data : [{id:0, text:'Item 1'}, {id:1, text:'Item 2'}, {id:2, text:'Item 3'}],     
minimumResultsForSearch: Infinity,     
width : '120px' 
});

A caixa de combinação inserida ficará assim:

Mais informações sobre os elementos de estilo ONLYOFFICE podem ser encontradas aqui.

Etapa 4. Localize seu plug-in (opcional)

Você pode pular esta etapa se quiser criar um plugin apenas para usuários que falam inglês. Porém, se quiser que seu plugin esteja disponível em outros idiomas, você pode criar a pasta de traduções no diretório do plugin e colocar os arquivos .json para todos os idiomas que deseja usar.

Leia a documentação oficial da API para saber como localizar seu plugin corretamente.

Etapa 5. Preparar o plug-in para publicação no ONLYOFFICE Marketplace

Para aprimorar a aparência do seu plug-in antes que ele fique disponível no mercado ONLYOFFICE, você precisa adicionar uma janela Sobre com uma breve descrição do seu plug-in, sua versão, o nome do desenvolvedor, etc.

Por exemplo, esta é a janela Sobre do plugin Photo Editor:

Para poder criar essa janela para o seu plugin, siga estas instruções.

Além disso, você precisa criar ícones para o seu plugin e colocá-los na pasta de recursos. Em geral, você precisa de 8 ícones para que seu plug-in seja exibido corretamente no mercado de plug-ins do ONLYOFFICE: 4 ícones (125%, 150%, 175% e 200% de escala) para os temas de interface Claro e Escuro.

Além disso, você pode criar um arquivo leia-me e colocá-lo na pasta principal do plugin. Este arquivo pode incluir qualquer informação que você deseja que outros usuários saibam – uma descrição dos principais recursos do seu plugin, instruções de instalação, problemas conhecidos e bugs, etc.

Agora seu plugin está pronto e você pode testá-lo adequadamente antes de publicá-lo no mercado.

Etapa 6. Teste seu plug-in do ONLYOFFICE Docs

Agora é hora de colocar todos os arquivos que você já criou conforme as instruções acima na pasta do plugin. Em seguida, envie a pasta do plugin para o repositório remoto e teste o plugin no ONLYOFFICE Desktop Editors. Para isso, você pode executar o aplicativo de desktop no modo de depuração.

No Linux, você pode abrir o terminal com CTRL+ALT+T. Depois disso, insira o caminho para ONLYOFFICE Desktop Editors, adicione um espaço e especifique --ascdesktop-support-debug-info:

"/opt/onlyoffice/desktopeditors/DesktopEditors" --ascdesktop-support-debug-info

Teste seu plugin e seus recursos.

Se tudo estiver bem, você também pode testar seu plugin na versão web do pacote ONLYOFFICE, ONLYOFFICE Docs. Em outras palavras, seu plugin pode ser adicionado como uma nova extensão.

Para criar a extensão correspondente, você precisa abrir o arquivo onlyoffice.github.io/store/plugin-dev/extension/inject.js e especificar o caminho para o seu plugin no site GitHub Pages no campo Variável URL_TO_PLUGIN:

var URL_TO_PLUGIN = "https://YOUR-USERNAME.github.io/onlyoffice.github.io/sdkjs-plugins/content/your-plugin/"

A pasta onlyoffice.github.io/store/plugin-dev/extension é a extensão que você precisa. Basta carregá-lo em seu navegador, executar seu ONLYOFFICE Docs e encontrar seu plug-in no Gerenciador de plug-ins na guia Plug-ins na barra de ferramentas superior. Aqui está um guia detalhado sobre como adicionar um plugin a um navegador da web.

Se o seu plugin funcionar conforme esperado, você pode prosseguir para a etapa final.

Etapa 7. Envie o plug-in para o ONLYOFFICE Marketplace

Parabéns! Você passou pelo processo de criação do plugin e agora pode disponibilizá-lo para outros usuários. Para isso, você pode criar uma solicitação pull do seu fork para este repositório do ONLYOFFICE em:

https://github.com/ONLYOFFICE/onlyoffice.github.io

Se o seu plug-in funcionar bem, os desenvolvedores do ONLYOFFICE aprovarão sua solicitação pull e seu plug-in aparecerá no mercado de plug-ins do ONLYOFFICE. Nesse caso, outras pessoas poderão instalá-lo no marketplace com apenas alguns cliques.

Esperamos que este artigo seja útil. Não se esqueça de compartilhar o que você pensa nos comentários abaixo.