Desenvolvendo um plug-in personalizado para o CMS de outubro

No ano passado, fiz algumas pesquisas sobre novos sistemas CMS em PHP para encontrar uma boa alternativa ao WordPress. Idealmente, deveria ser uma solução de código aberto com uma base de código limpa e moderna.

Um deles me chamou a atenção: Outubro CMS. Experimentei e quase instantaneamente gostei. A estrutura do código foi muito boa e foi fácil escrever plugins personalizados.

Este artigo tem como objetivo fornecer uma visão geral do que esperar da plataforma e dar uma amostra dela antes de decidir se comprometer a usá-la.

Por que escolher outubro como sua plataforma CMS?

Existem algumas razões principais pelas quais eu pessoalmente decidi usá-lo para meus projetos.

Desenvolvido por Laravel

O October é construído sobre o framework PHP mais poderoso para criar aplicativos web modernos: Laravel. Posso dizer com muita confiança que é o melhor. É muito fácil de usar e entender, e possui todos os recursos que um framework moderno precisa, desde roteamento, mapeamento objeto-relacional (ORM), autorização, cache e muitos outros que fornecem uma estrutura MVC agradável e clara. Como é desenvolvido pelo Laravel, o October herdou todos esses recursos de seu irmão mais velho.

Código limpo e documentação

Ao contrário de muitas outras soluções de CMS, October tem uma base de código muito limpa e bem documentada. Está escrito usando um paradigma orientado a objetos. Em vez do velho PHP simples, October usa Twig como seu mecanismo de modelagem, o que simplifica as coisas para os desenvolvedores. A documentação técnica também está bem escrita e ajuda você a encontrar rapidamente respostas para a maioria de suas perguntas.

Grande Comunidade

Embora a comunidade de outubro ainda não seja tão grande, é muito útil e responsiva. Você pode participar de um canal público do Slack, onde encontrará desenvolvedores felizes em ajudá-lo a corrigir seu problema.

Grande mercado

Assim como o WordPress e outros CMSs, outubro tem um mercado para temas e plugins. Mesmo que não haja muitos bons temas para escolher, existem mais de 700 plugins no momento, então é muito provável que você possa adicionar funcionalidades simplesmente procurando e instalando um deles. Um ótimo recurso dos plugins é que eles podem ser facilmente sincronizados entre todos os seus projetos se você apenas adicionar o ID do projeto no painel de administração.

Plugins e componentes

Os plug-ins são a base para adicionar novas funcionalidades a outubro. Um plug-in pode consistir em vários arquivos e diretórios responsáveis ​​por registrar componentes personalizados, modelos, atualizar a estrutura do banco de dados ou adicionar traduções.

Um plugin geralmente é criado no diretório plugins/ do projeto. Como muitos plug-ins são enviados ao mercado para uso de outros, cada plug-in deve ter um namespace personalizado, que geralmente começa com o nome da empresa ou desenvolvedor que criou o plug-in. Assim, por exemplo, se seu nome é Acme e você criou um plugin incrível chamado Blog, seu plugin ficará sob o namespace Acme\Blog .

Deixe-me mostrar como uma estrutura de diretórios de plugins pode se parecer:

Como você pode ver, existe também um arquivo chamado plugin.php que é responsável por registrar um plugin e todos os seus componentes no CMS de outubro.

Outra coisa importante a mencionar é que nem todos os diretórios listados acima são necessários para que um plugin seja executado. Seu plugin pode ter a seguinte estrutura e ainda funcionar perfeitamente:

Na maioria das vezes, um plugin é construído para adicionar apenas uma funcionalidade. Por exemplo, o plug-in 'Traduzir' foi projetado para ajudá-lo a traduzir o conteúdo do seu site para diferentes idiomas e fornecer suporte multilíngue para os usuários.

Outubro CMS tem um ótimo mercado onde você pode encontrar para suas necessidades.

Ao contrário do WordPress e de outros CMSs populares, os plugins de outubro também podem ter componentes. De acordo com a documentação de outubro, os componentes são “elementos de construção configuráveis ​​que podem ser anexados a qualquer página, parcial ou layout”. Os exemplos podem incluir: um formulário de contato, navegação, uma lista de perguntas frequentes e suas respostas; basicamente qualquer coisa que faça sentido agrupar como um bloco de construção que pode ser reutilizado em várias páginas.

Os componentes são criados como parte de um plugin e existem no subdiretório components/ :

Cada componente tem um arquivo PHP como componentName.php que define o componente, bem como um subdiretório opcional para parciais de componentes. Uma pasta de parciais de componentes deve ter o mesmo nome em letras minúsculas que o próprio componente.

Para demonstrar como um componente funciona, vamos supor que nosso componente seja responsável por mostrar as postagens do blog.

 namespace Acme\Blog\Components; class BlogPosts extends \Cms\Classes\ComponentBase { public function componentDetails() { return [ 'name' => 'Blog Posts', 'description' => 'Displays a collection of blog posts.' ]; } // This array becomes available on the page as {{ component.posts }} public function posts() { return ['First Post', 'Second Post', 'Third Post']; } }

Como podemos ver, o componente tem duas funções principais. O primeiro, componentDetails() , fornece informações sobre o componente ao administrador que irá adicionar e usar componentes em suas páginas da web.

A segunda função, posts() , retorna postagens fictícias que podem ser usadas dentro de um componente parcial (arquivo blogposts/default.htm ) como este:

 url = "/blog" [blogPosts] == {% for post in blogPosts.posts %} {{ post }} {% endfor %}

Para que o CMS de outubro saiba que nosso componente existe, devemos registrá-lo usando nosso arquivo de plug-in principal dentro de uma função chamada registerComponents() :

 public function registerComponents() { return [ 'October\Demo\Components\Todo' => 'demoTodo' ]; }

Criando um plug-in de formulário de contato personalizado

Vamos criar um plug-in de formulário de contato personalizado. Aqui estão as suposições sobre como o plugin deve funcionar:

• O formulário terá os seguintes campos: Nome, Sobrenome, Email, Mensagem.
• Os dados serão enviados ao servidor usando Ajax.
• Após o envio dos dados, o administrador receberá um e-mail com a mensagem enviada pelo usuário.

Para os propósitos deste tutorial, usaremos uma nova instalação do October CMS:

Vamos começar a criar nosso plugin executando um comando em um terminal que irá gerar a estrutura do plugin: php artisan create:plugin progmatiq.contactform

O argumento progmatiq.contactform contém o nome do autor (progmatiq) e o nome do plugin (contactform).

Agora precisamos abrir nosso arquivo plugin.php e modificar os detalhes do plugin no seguinte método:

 public function pluginDetails() { return [ 'name' => 'Contact Form', 'description' => 'A simple contact form plug-in', 'author' => 'progmatiq', 'icon' => 'icon-leaf' ]; }

Aqui estão alguns outros métodos que você deve dar uma olhada:

• registerComponents()
  Aqui você pode definir uma matriz de componentes que seu plugin fornece.
• registerPermissions()
  Você pode registrar permissões personalizadas que podem ser usadas posteriormente em outras áreas do aplicativo.
• registerNavigation()
  Você pode adicionar um item de menu personalizado com um URL ao menu do painel de administração.

Agora vamos criar nosso componente ContactForm :

1. Crie uma nova pasta chamada components/ dentro do diretório raiz do seu plug-in.
2. Crie um arquivo chamado contactForm.php dentro da pasta components/ .



3. Cole o código a seguir que informará a October o que nosso componente faz. Podemos fazer isso criando um método dentro do nosso componente chamado componentDetails() .

 <?php namespace Progmatiq\Contactform\Components; use Cms\Classes\ComponentBase; class ContactForm extends ComponentBase { public function componentDetails() { return [ 'name' => 'Contact Form', 'description' => 'A simple contact form' ]; } }

Agora precisamos registrar nosso componente dentro do plug-in. Para fazer isso, modificamos o método registerComponents() :

 public function registerComponents() { return [ 'Progmatiq\Contactform\Components\ContactForm' => 'contactForm', ]; }

Esta função retorna um array de componentes que nosso plugin fornece. O nome completo da classe do componente é uma chave neste método, e um valor é um alias que usaremos para referenciar nosso componente dentro de nossos templates Twig.

Depois de registrar o componente, podemos criar uma nova página de contato e adicionar nosso componente (os números nas etapas referem-se à captura de tela):

1. No seu painel de administração, vá para CMS (1) > Páginas (2) e clique em + Adicionar (3).
2. Dê um nome e um URL à sua página (4).
3. Nomeie seu arquivo (5) e selecione o layout padrão (6).

Vamos adicionar nosso novo componente à página:

1. Clique em Componentes no menu esquerdo (1) e selecione nosso componente “Formulário de contato”. Depois de clicar nele (2), ele deve ser adicionado à página.
2. Precisamos colocar um pedaço de código que daria à nossa página um título, bem como renderizar o componente usando a diretiva Twig {% component 'contactForm' %} :

 <div class="container"> <h1> Contact </h1> {% component 'contactForm' %} </div>

Se você abrir sua página de contato agora, verá o título dizendo “Contato” e nada mais.

Isso porque nosso formulário de contato não tem HTML para renderizar.

Precisamos criar um arquivo contactform/default.htm dentro de nossa pasta components/ .

E adicione o seguinte código HTML ao arquivo:

 <form method="POST" data-request="onSend" data-request-validate data-request-success="this.reset(); alert('Thank you for submitting your inquiry')" > <div> <label for="first_name">First Name</label> <input type="text" name="first_name" class="form-control"> <p data-validate-for="first_name" class="text-danger"></p> </div> <div> <label for="last_name">Last Name</label> <input type="text" name="last_name" class="form-control"> <p data-validate-for="last_name" class="text-danger"></p> </div> <div> <label for="email">Email</label> <input type="text" name="email" class="form-control"> <p data-validate-for="email" class="text-danger"></p> </div> <div> <label for="content">Content</label> <textarea rows="6" cols="20" name="content" class="form-control"></textarea> <p data-validate-for="content" class="text-danger"></p> </div> <div> <button type="submit" class="btn btn-primary" data-attach-loading>Send</button> </div> </form>

A maior parte deste código é bastante simples. No entanto, é aromatizado com atributos data-* especiais que outubro nos permite usar:

1. A tag <form> tem três atributos especiais:
   • data-request="onSend" . Este atributo informa a October que a função onSend do nosso componente (que vamos criar a seguir) deve ser chamada quando o formulário for enviado usando Ajax.
   • data-request-validate habilitará a validação do formulário Ajax usando erros que serão enviados do servidor se o formulário for inválido.
   • data-request-success="this.reset(); alert('Thank you for submitting your inquiry')" limpa o formulário e aciona a mensagem de alerta se a solicitação for bem-sucedida e não houver erros de validação ou do lado do servidor.
2. Cada entrada possui um bloco a seguir que é responsável por exibir os erros de validação retornados pelo servidor para aquela determinada entrada:

 <p data-validate-for="content" class="text-danger"></p>

3. O botão de envio possui o atributo data-attach-loading , que adicionará um spinner e desabilitará o botão enquanto a solicitação estiver sendo processada pelo servidor. Isso é feito para evitar que o usuário envie um formulário novamente até que a solicitação anterior seja concluída.

E aqui está como nossa página está agora:

Vamos voltar ao nosso componente contactForm.php e criar o método auxiliar onSend() e validate() que será responsável por tratar o envio do formulário:

 public function onSend() { // Get request data $data = \Input::only([ 'first_name', 'last_name', 'email', 'content' ]); // Validate request $this->validate($data); // Send email $receiver = '[email protected]'; \Mail::send('progmatiq.contact::contact', $data, function ($message) use ($receiver) { $message->to($receiver); }); } protected function validate(array $data) { // Validate request $rules = [ 'first_name' => 'required|min:3|max:255', 'last_name' => 'required|min:3|max:255', 'email' => 'required|email', 'content' => 'required', ]; $validator = \Validator::make($data, $rules); if ($validator->fails()) { throw new ValidationException($validator); } }

A primeira coisa que estamos fazendo é obter dados da solicitação e validá-los usando o método auxiliar validate() . (Todas as regras de validação disponíveis que você pode usar podem ser encontradas na documentação.) Se a validação falhar, o método validate() lançará uma exceção ValidationException e a execução do código será interrompida, e o servidor responderá com o código de status 406 e com validação mensagens.

Se a validação for bem-sucedida, enviaremos um e-mail ao nosso administrador.

Observação : para simplificar, presumi que o e-mail para o qual desejamos enviar o envio é [email protected]. Certifique-se de usar seu próprio e-mail!

Aqui está o código completo do seu plug-in contactForm.php :

 <?php namespace Progmatiq\Contactform\Components; use Cms\Classes\ComponentBase; use October\Rain\Exception\ValidationException; class ContactForm extends ComponentBase { public function componentDetails() { return [ 'name' => 'Contact Form', 'description' => 'A simple contact form' ]; } public function onSend() { // Get request data $data = \Input::only([ 'first_name', 'last_name', 'email', 'content' ]); // Validate request $this->validate($data); // Send email $receiver = '[email protected]'; \Mail::send('progmatiq.contact::contact', $data, function ($message) use ($receiver) { $message->to($receiver); }); } protected function validate(array $data) { // Validate request $rules = [ 'first_name' => 'required|min:3|max:255', 'last_name' => 'required|min:3|max:255', 'email' => 'required|email', 'content' => 'required', ]; $validator = \Validator::make($data, $rules); if ($validator->fails()) { throw new ValidationException($validator); } } }

Como você pode ver, o primeiro argumento que a função Mail::send() aceita é o nome do modelo de email que será renderizado para o corpo do email. Precisamos criá-lo no painel de administração. Vá para Configurações > Modelos de e-mail e clique no botão Novo modelo . Em seguida, preencha o formulário conforme mostrado na tela abaixo:

Aqui está o corpo do e-mail que vamos usar:

 You have received a new contact inquiry **First Name**: {{ first_name }} *** **Last Name**: {{ last_name }} *** **Email**: {{ email }} *** **Message**: {{ content }} ***

Agora salve o modelo de e-mail. A próxima coisa que precisamos fazer é configurar o servidor SMTP que enviará e-mails.

Vá para Configurações > Configuração de e-mail e preencha todas as configurações.

Obviamente, não compartilharei minha configuração pessoal. Use suas próprias configurações.

Nesta fase, temos tudo pronto para começar a testar nosso componente de formulário de contato.

Primeiro, vamos verificar se a validação funciona quando deixamos o campo “Conteúdo” vazio e inserimos um email inválido:

A validação funciona como esperado. Vamos agora inserir os dados corretos e ver se o email será enviado com sucesso para o nosso administrador.

Aqui está o e-mail que [email protected] receberá:

Após o envio do formulário com sucesso, o usuário verá uma mensagem de alerta informando que a operação foi bem-sucedida:

Conclusão

Neste tutorial, abordamos o que são um plug-in e um componente e como usá-los com o October CMS.

Não tenha medo de criar um plugin personalizado para o seu projeto se você não encontrar um existente que atenda às suas necessidades. Não é tão difícil e você tem total controle sobre ele, podendo atualizá-lo ou estendê-lo a qualquer momento. Até mesmo criar um plug-in de formulário de contato simples, como fizemos hoje, pode ser útil se você quiser integrá-lo a outros serviços, como Mailchimp ou HubSpot.

Espero que este tutorial tenha sido útil para você. Se você tiver alguma dúvida, não hesite em perguntar na seção de comentários abaixo.