Adicionando campos adicionais ao seu tema

Ao estender o tema padrão do Mapas Culturais para personalizá-lo a sua realidade local ou setorial, além de poder modificar cores, textos e layouts, você também pode ter a necessidade de criar campos adicionais. Por exemplo, a plataforma Museus BR, do Instituto Brasileiro de Museus, cataloga muitos dados adicionais, específicos para os museus, além das informações básicas já presentes por padrão na plataforma.

Para fazer isso no seu tema, são necessário basicamente 3 passos simples:

1. Registrar os novos metadados
2. Criar um novo template para o campo
3. Carregar novo template

Registar novos metadados

Para isso, dentro do método register() no arquivo classe Theme do arquivo Theme.php do seu tema, chame o método correspondente: registerAgentMetadata(), registerSpaceMetadata(), registerEventMetadata(), registerProjectMetadata() ou registerSealMetadata().

Esses métodos recebem dois parâmetros: $key e $cfg.

$key (string) é um identificado único para este metadado. Utilize nomes sem acentos ou espaços e, para evitar conflitos, utilize um prefixo com o nome do seu tema. Ex: 'meutema_cor_preferida'.

$cfg (array) Array contendo as configurações do campo.

Exemplo:

<?php
namespace MeuTema;
use MapasCulturais\Themes\BaseV1;
use MapasCulturais\App;

class Theme extends BaseV1\Theme{

    function register() {
        $this->registerAgentMetadata('meutema_cor_preferida', array(
            'label' => 'Qual sua cor preferida?',
            'type' => 'select',
            'options' => ['Amarelo', 'Vermelho', 'Azul', 'Sou daltônico, não ligo muito pra isso']
        ));

    }

}

Exemplo adicionando um metadado em vários tipos de entidade:

    function register() {
        $teste = array(
            'label' => 'Justificativa',
            'type' => 'text',
        );
        $this->registerAgentMetadata('meutema_justificativa', $teste);
        $this->registerEventMetadata('meutema_justificativa', $teste);
        $this->registerSpaceMetadata('meutema_justificativa', $teste);

    }

Você também pode definir regras de validação para o campo, utilizando as opções da classe Validation, consulte sua documentação para todas as possibilidades.

    function register() {
        $this->registerAgentMetadata('meutema_lattes', array(
            'label' => 'Link do currículo Lattes',
            'type' => 'string',
            'validations' => [
                    'v::url()' => 'Url inválida'
                ]
        ));

        $this->registerSpaceMetadata('meutema_geladeiras', array(
            'label' => 'Número de geladeiras',
            'type' => 'string',
            'validations' => [
                    'v::intVal()' => 'O valor deve ser um número inteiro'
                ]
        ));
    }

Abaixo as opções e possibilidades de valores para a configuração do campo (em contrução):

label Nome de exibição do campo

type Tipo do campo. Por padrão, é exibido uma caixa de texto simples, mas alguns outros tipos já exibem campos diferentes no formlário. Valores possíveis: string (padrão), text, select, multiselect

validations Array com métodos de validação que devem ser acionados, sendo a chave o método e o valor a mensagem de erro. Veja exemplo acima.

options Array com as opções para os campos select e multiselect

private (bool) Padrao para false. Indica se o campo é ou não privado

allowOther (bool) Padrão para falso. Para campos select e multiselect, adiciona a opção 'outro' caso seja definido como true, que abre uma caixa de texto para inserção de um novo valor.

allowOtherText Caso allowOther seja true, define o texto do novo campo de texto. Por ex: "Especifique a cor"

Criar um novo template para o campo

Agora que já registramos o metadado, precisamos criar um template que vai exibí-lo. Para isso vamos criar um novo arquivo e salvá-lo na pasta layouts/parts do nosso tema. O conteúdo deste arquivo vai seguir o mesmo padrão dos outros campos, mas aqui você tem toda liberdade para exibir o campo da maneira que quiser.

Por exemplo, abaixo o conteúdo do arquivo layouts/parts/cor-preferida.php.

<?php if($this->isEditable() || $entity->meutema_cor_preferida): ?>
<p>
    <span class="label">Cor preferida:</span>
    <span class="js-editable" data-edit="meutema_cor_preferida" data-original-title="Cor preferida" data-emptytext="Selecione">
        <?php echo $entity->meutema_cor_preferida; ?>
    </span>
</p>
<?php endif; ?>

Carregar novo template

Agora basta carregarmos a parte no ponto em que desejarmos do tema. Para isso, utilizaremos os template hooks.

No tema BaseV1 existem hooks (ganchos) em várias partes do código onde vocẽ pode inserir ações sem precisar sobreescrever o arquivo. Essas ações devem ser colocadas no método init da classe Theme do seu Theme.php. Veja os exemplos abaixo.

Para inserir nosso campo como a primeira coisa da aba "sobre" dos agentes.

    $app->hook('template(agent.<<create|edit|single>>.tab-about):begin', function(){
        $this->part('cor-preferida', ['entity' => $this->data->entity]);
    });

Para inserir o novo campo como última coisa da aba sobre de vários tipos de entidade

    $app->hook('template(<<agent|event|space|project>>.<<create|edit|single>>.tab-about):end', function(){
        $this->part('cor-preferida', ['entity' => $this->data->entity]);
    });