Como criar um módulo (parte 3) - Drupal 7

Como criar um módulo", conforme falei na parte 2, vou abordar agora como adicionar configurações específicas no módulo. Essas configurações são formulários em duas páginas diferentes. Em uma página, é pra escolher o comportamento padrão de cada vez que rodar o meu custom_deploy. A segunda, será onde vou rodar o custom_deploy, que irá se comportar de acordo o que defini na primeira página." data-share-imageurl="">

Olá pessoas! Dando sequência a essa série "Como criar um módulo", conforme falei na parte 2, vou abordar agora como adicionar configurações específicas no módulo. Essas configurações são formulários em duas páginas diferentes. Em uma página, é pra escolher o comportamento padrão de cada vez que rodar o meu custom_deploy. A segunda, será onde vou rodar o custom_deploy, que irá se comportar de acordo o que defini na primeira página.

Adição de configurações específicas no módulo

A primeira coisa a fazer aqui é definir quais são as configurações que desejo inserir no módulo. Para isso, vou criar um novo arquivo custom_deploy.admin.inc no mesmo diretório onde está o custom_deploy.info, ou seja, /sites/all/modules/custom/custom_deploy e adicionar nele as configurações. Não vou usar o custom_deploy.module para adicionar essas configurações pois o Drupal carrega os arquivos *.module de todos os módulos habilitados a cada requisição de página e como não preciso que essas configurações sejam carregadas dessa forma, coloco meu código em novo arquivo.

<?php

/**
 * @file
 * Administration page callbacks for the custom_deploy module.
 */

/**
 * Form builder. Set custom_deploy preferences.
 *
 * @ingroup forms
 * @see system_settings_form().
 */

function custom_deploy_admin_settings($form, &$form_state) {
  // Define what functions will run at each
  // time in the custom_deploy

  $values = db_select('custom_deploy', 'c')
    ->fields('c')
    ->orderBy('cdid', 'DESC')
    ->execute()
    ->fetchAssoc();

  $custom_deploy_options = array(
    '1' => t('Put site on maintenence mode during deploy'),
    '2' => t('GIT pull to get developers update code'),
    '3' => t('Revert all features'),
    '4' => t('Clear all caches after deploy'),
    '5' => t('Run cron after deploy'),
  );

  $form['custom_deploy_set_preferences'] = array(
    '#type' => 'checkboxes',
    '#title' => t('Choice the functions to run for each Custom Deploy submit'),
    '#options' => $custom_deploy_options,
    '#default_value' => $values['actions'] ? unserialize($values['actions']) : array(),
    '#description' => t('This options run all time when the Custom Deploy option is submited.'),
    '#required' => TRUE,
  );

  $form['custom_deploy_user_information'] = array(
    '#type' => 'fieldset',
    '#title' => t('User information'),
    '#collapsible' => TRUE,
    '#collapsed' => FALSE,
    '#description' => t('We use a server connection to run <strong>GIT</strong> and <strong>drush</strong> commands. So let me know about username and pass to connect in this server.'),
  );

  $form['custom_deploy_user_information']['username'] = array(
    '#type' => 'textfield',
    '#title' => t('Username'),
    '#default_value' => $values['username'],
    '#required' => TRUE,
  );

  $form['custom_deploy_user_information']['password'] = array(
    '#type' => 'password',
    '#title' => t('Password'),
    '#default_value' => $values['password'],
    '#required' => TRUE,
  );

  $form['custom_deploy_send_email'] = array(
    '#type' => 'fieldset',
    '#title' => t('Send email confirmation message'),
    '#collapsible' => TRUE,
    '#collapsed' => FALSE,
  );

  $form['custom_deploy_send_email']['email'] = array(
    '#type' => 'textfield',
    '#title' => t('Send email'),
    '#default_value' => $values['email_address'],
    '#description' => t('Input a email address to send a custom message after deploy. Leave blank to no send message'),
  );

  $form['custom_deploy_send_email']['message'] = array(
    '#type' => 'textarea',
    '#title' => t('Message'),
    '#default_value' => $values['email_message'],
    '#description' => t('Input a message to send after deploy.'),
  );

  $form['submit'] = array(
    '#type' => 'submit',
    '#value' => t('Save configuration'),
  );

  $form['#submit'][] = 'custom_deploy_admin_settings_submit';
  return $form;
}

Os formulários no Drupal são representados por uma estrutura de árvore aninhada, ou seja, um array de arrays. Essa estrutura descreve como os formulários devem ser apresentados ao sistema de renderização de formulários do Drupal. Cada propriedade é definida por uma cerquilha (#) e atua como uma chave array. Defini alguns formulários.

Antes de definir os formulários, defini duas variáveis. A primeira usa a função db_select() para fazer uma consulta no banco de dados. A segunda variável define alguns valores. O resultado dessas duas variáveis serão usadas nos formulários.

No primeiro formulário, onde comecei declarando a propriedade #type com o elemento checkboxes, que vai usar os valores múltiplos da variável. Depois defini o título declarando um valor na propriedade #title. As opções de cada checkbox são das chaves de array definas antes, na variável chamada $custom_deploy_options. Em seguida declarei valores padrões através do elemento #default_value, que são definidas pelas chaves de array das opções. Nesses formulários, toda vez que for declarado o elemento #default_value, será um valor vindo da tabela custom_deploy, que a variável $values consulta. Logo depois defini uma descrição para o formulário com o elemento #description. Por último, user o elemento #required para dizer que esse campo é obrigatório, ou seja, é preciso que tenha algum valor para que o submit seja aceito. A maior diferença entre esse e os outros formulários é o tipo. O primeiro formulário é um grupo de checkboxes, seguido por um agrupador de campos que contém dois campos de texto simples, que por sua vez é seguido de outro agrupador de campos, contendo um campo de texto simples e uma área de texto. Por último, o botão de submit e a definição da ação para quando o formulário for submetido.

O que fiz até agora foi dar a possibilidade do administrador do site para escolher quais as ações irão rodar junto, definir usuário e senha para conexão no servidor e criar uma mensagem para ser enviada por email toda vez que o custom_deploy rodar. Através do menu é possível configurar o custom_deploy para:

  • Colocar o site em modo de manutenção enquanto o deploy roda. Ao final, volta para o modo online.
  • Rodar o comando git pull no servidor, que atualiza o código da instalação com a última versão de commits de um repositório GIT.
  • Reverter todas as features, aplicando o que está em código para o banco de dados.
  • Limpar todos os caches do Drupal após o deploy.
  • Rodar o cron para atualizar informações que dependem do agendador de tarefas ao final do deploy.
  • Guardar o usuário e senha para conexão no servidor, obrigatório para atualizar o código com GIT e reverter as features com drush.
  • Guardar um endereço de email que será usado para enviar uma mensagem de notificação.
  • Definir qual é a mensagem de notificação que será enviada ao endereço de email guardado.

 

A próxima coisa que farei é definir a rotina de submissão dos formulários que será chamada quando o administrador do site salvar as informações. Minha rotina será bem simples: Ao escolher e definir as opções do formulário, as informações serão gravadas no banco de dados após o submit, para que eu possa recuperá-las depois, quando chamar o processo que roda o custom_deploy.

/**
 * Process custom_deploy preferences form
 */

function custom_deploy_admin_settings_submit($form, &$form_state) {
  // Get values from current choices and insert on database
  $actions = array_filter($form_state['values']['custom_deploy_set_preferences']);
  $record = array(
    'actions' => serialize($actions),
    'username' => $form_state['values']['username'],
    'password' => $form_state['values']['password'],
    'email_address' => $form_state['values']['email'],
    'email_message' => $form_state['values']['message'],
  );

  drupal_write_record('custom_deploy', $record);
}

 

 

 

O código define quais valores estou inserindo em cada coluna de uma tabela no banco de dados. As colunas são referenciadas nas chaves de array, cujo valores vêem do formulário atual. Nesse caso, quais ações irão rodar junto ao custom_deploy, o nome de usuário com senha para conexão no servidor e se irá enviar uma notificação para algum endereço de email que eu escolher. A função drupal_write_record() cuida de inserir os registros na tabela custom_deploy, que vou criar logo a seguir.

Para criar a tabela com suas devidas colunas da forma correta, vou usar um outro hook. Esse hook é o hook_schema(), que é um array representante de uma ou mais tabelas e suas relativas chaves e índices. Esse hook é chamado toda vez que o módulo é instalado ou desinstalado. Ele cria automaticamente as tabelas que preciso quando instalo o módulo e apaga as tabelas quando desinstalo o módulo. Como é um hook para instalação e desinstalação, vou criar um novo arquivo, no mesmo diretório onde está o .info do meu módulo, o custom_deploy.install:

<?php

/**
 * Implements hook_schema().
 */

function custom_deploy_schema() {
  $schema['custom_deploy'] = array(
    // define especifications for custom_deploy table
    'description' => 'The Custom Deploy table.', 
    'fields' => array(
      'cdid' => array(
        'description' => 'The primary key identifier for custom deploy.',
        'type' => 'serial',
        'unsigned' => TRUE,
        'not null' => TRUE,
      ),
      'actions' => array(
        'description' => 'The options set for custom_deploy submit.', 
        'type' => 'text', 
        'size' => 'normal',
        'not null' => TRUE,
      ), 
      'username' => array(
        'description' => 'The username to connect on server.', 
        'type' => 'varchar', 
        'length' => 32,
        'not null' => TRUE,
      ), 
      'password' => array(
        'description' => 'The username pass to connect on server.', 
        'type' => 'varchar', 
        'length' => 32,
        'not null' => TRUE, 
      ), 
      'email_address' => array(
        'description' => 'The email address to send confirmation message.', 
        'type' => 'varchar', 
        'length' => 255, 
      ),
      'email_message' => array(
        'description' => 'The email message to send confirmation message.', 
        'type' => 'varchar', 
        'length' => 255, 
      ),
    ),
    'primary key' => array('cdid'),
  );
  return $schema;
}

Assim, na minha tabela custom_deploy, defini as seguintes colunas:

  • cdid: Em referência a "Custom Deploy ID". Esse valor é um número incremental, aumentado a cada vez que as preferências do custom_deploy é atualizada e também quando roda o custom_deploy. Será usado como chave primária para identificar um registro na tabela.
  • actions: Para guardar as ações escolhidas pelo administrador do site, definindo quais irão rodar junto ao custom_deploy.
  • username: Guarda o nome de usuário para fazer a conexão SSH necessária para rodar comandos GIT e drush, que usamos para atualizar o código e reverter features.
  • password: Guarda a senha que acompanha o nome de usuário para fazer a conexão SSH.
  • email_address: Para guardar o endereço de email que será notificado toda vez que o custom_deploy rodar.
  • email_message: Guarda a mensagem de notificação que é enviada por email quando o custom_deploy roda.

 

Nesse momento já consigo instalar meu módulo com algumas configurações específicas, que até agora cria uma tabela no banco de dados no momento da instalação e me dá um formulário na interface administrativa para que eu possa guardar as informações preenchidas nesse formulário na tabela criada pelo módulo. Na página de administração dos módulos, com o custom_deploy instalado, deve exibir como a imagem a seguir (clique para ampliar):

 



Figura 1

Clicando no link "Configurar" ou seguindo o caminho no menu "Configurações > Sistema > Custom Deploy > Custom Deploy Settings" (/admin/config/system/custom_deploy/settings), abrirá o formulário, que deve ser exibido assim (clique para ampliar):



Figura 2

O formulário é exibido em branco, pois ainda não foi definida nenhuma configuração. A partir do momento em que eu preencho e salvo a primeira vez, o formulário guarda essas informações no banco de dados e é exibido com as informações salvas da última alteração. Note que os campos Usuário e Senha, do grupo User Information, são obrigatórios e foram definidos assim intencionalmente, pois a senha não é retornada no formulário junto às outras informações que estão salvas no banco de dados, forçando o administrador a informar uma senha a cada vez que definir essas configurações.

Observação: a mistura de idiomas nas imagens que ilustram os formulários é devida á tradução da minha instalação, que está em português. Assim, expressões que existem traduzidas no sistema serão mostradas em português.

O próximo passo agora é adicionar mais configurações específicas no módulo. Ainda falta o formulário para rodar o custom_deploy, onde vou poder escolher rodar os updates do meu módulo e quaisquer outros com pendência de update, escolher quais são os nodes que serão criados durante o deploy, definir uma mensagem de log para registrar o que o deploy atual está aplicando e ainda ter uma lista com o registro de todos os deploys realizados, para conferência.

Muito importante: Antes de continuar com a criação do módulo, adicionando novas configurações específicas, vou desinstalá-lo, para que ele apague a tabela no banco de dados, pois vou inserir mais colunas na tabela para gravar essas outras configurações e essas colunas devem ser inseridas na criação da tabela, ou seja, no momento de instalação. Em outro momento vou abordar um tanto sobre updates, mas agora não é necessário.

No próximo post sobre esse assunto, a parte 4, falarei sobre as outras configurações específicas no módulo. Se você gostou ou teve proveito deste post, pode retribuir com comentários, curtindo e compartilhando. Quando sair a continuação, aqui terá um link. Até breve!

Como criar um módulo", conforme falei na parte 2, vou abordar agora como adicionar configurações específicas no módulo. Essas configurações são formulários em duas páginas diferentes. Em uma página, é pra escolher o comportamento padrão de cada vez que rodar o meu custom_deploy. A segunda, será onde vou rodar o custom_deploy, que irá se comportar de acordo o que defini na primeira página." data-share-imageurl="">