Conheça o Tainacan 1.0 – Parte 4: Para desenvolvedores

Este é o quarto de uma série de quatro artigos pré-lançamento tratando das novidades do Tainacan 1.0.0. Não deixe de ler os outros artigos que cobrem as novidades do lançamento da 1.0:

Neste artigo vamos focar em aspectos mais técnicos da nova versão. Mais do que um redesign para modernizar a interface, boa parte do esforço de refatoração do código do painel Admin do Tainacan foi para permitir a sua customização e expansão por códigos externos, em outras palavras, plugins e/ou temas que precisam adaptar o Tainacan para os mais diversos cenários.

Parte disso foi alcançado migrando uma porção do código do Admin do Tainacan de uma Single Page Application (SPA) em Vue para um sistema híbrido entre esta mesma SPA e classes em PHP que reaproveitam recursos que o WordPress já oferece há anos para se modificar via Hooks (Actions e Filters). Já tocamos em algumas das possibilidades no artigo sobre a nova interface, mas vamos repassar elas com aqui com mais detalhes, além de apresentar outras coisas bem legais como nossos componentes de seleção de dados em React.

Criando ou filtrando cartões no Dashboard

Os cartões existentes no Dashboard do Tainacan podem ser desabilitados por cada usuário pelas Opções de tela e podem ser ocultados por padrão por Administradores via formulário de edição de função de usuário, como explicamos no artigo sobre a nova interface.

Mas se você quiser ir adiante e forçadamente ocultar alguns dos nossos cartões ou mesmo acrescentar seus próprios cartões, basta filtrar o array $tainacan_dashboard_cards usando o filtro:

add_filter( 'tainacan-dashboard-cards',
   function($tainacan_dashboard_cards) { 
      $tainacan_dashboard_cards[] = array(
         'id' => 'my-plugin-card',
         'title' => 'Cartão do meu plugin',
         ...
      );
      return $tainacan_dashboard_cards;
   }
);

O objeto inserido no array deve conter os campos id , title, description, content (uma função callback com o miolo do cartão), icon (uma tag svg ou img), color (gray, blue ou turquoise) e position (normal, side, column3, column4). Se você já se aventurou com a API de Widgets de Dashboard o WordPress vai estar em casa, visto que este array basicamente alimenta a função de registro desta widget com algumas pequenas modificações nossas (como a existência do ícone).

Por padrão seu cartão estará visível para todos os usuários e eles poderão ocultá-lo via Opções de tela. Se deseja fazer com que ele esteja oculto por padrão, basta modificar a option tainacan_dashboard_disabled_cards usando a API de options do WordPress.

Criando páginas no Admin do Tainacan

Uma das grandes justificativas para a refatoração da navegação do Admin na versão 1.0.0 foi trazer uma API que permita aos desenvolvedores inserir novas páginas no Admin do Tainacan. Para isso estamos novamente expandindo a API de menus do WordPress (add_menu_page), mas adicionando algumas convenções nossas.

Você poderá criar páginas que fiquem na raiz do menu Tainacan ou páginas que fiquem no submenu “Outros”. Criamos uma classe base \Tainacan\Pages, que se herdada com seus métodos implementados corretamente, permitirá que seu código fique integrado ao nosso sistema de navegação e identidade visual.

Para facilitar o mergulho nas possibilidades dessa novidade, criamos um código demonstrativo, um plugin que pode ser usado como ponto de partida. Leia o artigo em nossa Wiki para desenvolvedores para explorar o assunto.

Criando opções na Página de Configurações

Talvez seu plugin ou tema não precise de uma página inteira no Admin do Tainacan – pode ser que uma ou outra configuração extra dê pro gasto. Neste caso, também é possível inserir campos no formulário de configurações do Tainacan. Novamente, estamos aproveitando a API add_settings_field() e add_settings_field() do WordPress, que são chamadas internamente em nossa função:

\Tainacan\Settings::get_instance()->create_tainacan_setting( ... );

Com alguns parâmetros esta função gerará o html dentro do formulário de configurações do plugin, além de registrar uma wp option que poderá ser consumida facilmente via get_option('tainacan_option_...). Desta forma os usuários podem ter em um só lugar as configurações relevantes ao Tainacan e suas funcionalidades complementares.

Para uma imersão completa em como usar esta funcionalidade, leia nossa página dedicada na Wiki de desenvolvedores.

Criando opções de aparência do Admin por Função do Usuário

A nova aba “Aparência do Admin” apresentada em outro artigo, trás a possibilidade de se definir opções booleanas por função de usuário, em geral voltadas para ocultar ou modificar certos comportamentos da interface administrativa. Este formulário é construído a partir de um array chamado $tainacan-available-admin-ui-options, e você pode modificá-lo com o filtro:

add_filter('tainacan-available-admin-ui-options',
   function($tainacan-available-admin-ui-options) {
      $tainacan-available-admin-ui-options['navigation']['items']['myAdminUIOption'] = __('My Admin UI Option', 'my-plugin-slug');
      return $tainacan-available-admin-ui-options;
   }
);

O array em si contém objetos nomeados para cada colapse de seção que você vê na interface, com campos como label, description, e items. Dentro de items, você pode adicionar uma opção chave-valor, onde chave será o ID da opção e valor será seu rótulo. Por padrão, qualquer opção neste array será false.

Feito isto, sua opção estará presente no formulário de opções de aparência do Admin por Função de Usuário. Para que sua opção esteja habilitada porém, ela precisa estar presente no array $tainacan-admin-ui-options. Se você quer seu valor padrão seja true, portanto, basta inseri-la no array:

add_filters('tainacan-admin-ui-options',
   function($tainacan-admin-ui-options) {
      $tainacan-admin-ui-options[] = 'myAdminUIOption';
      return $tainacan-admin-ui-options;
   }
);

Mais adiante no código se você quiser acessar o valor atual da opção, basta chamar:

$this->has_admin_ui_option('myAdminUIOption')

Dentro de qualquer classe \Tainacan\Pages.

Usando componentes React de Seleção do Tainacan

Se você está familiarizado com nossos blocos Gutenberg já notou que muitos deles tem uma “etapa de seleção” onde a sua configuração acontece. O mais comum é abrir um modal onde se escolhe a coleção e então um conjunto de itens (ou critérios de busca) para se definir o que vai ser exibido no bloco. Entendemos que este tipo de fluxo é algo que pode ser muito comum em diversos cenários. Imagine que você está construindo um plugin para permitir aos usuários definirem seus “itens favoritos”. Você precisa construir um fluxo onde as pessoas possam listar e marcar itens. Algo que nossa API REST permite facilmente, mas não é muito simples lidar com questões como paginação e filtragem.

Pensando nisso, estamos expondo alguns dos componentes React que criamos para nossos blocos Gutenberg. Se você tem planos para usá-los, fizemos um artigo detalhado em nossa Wiki para desenvolvedores explicando o processo. Não deixe de nos contatar pelo fórum para mais detalhes sobre como eles podem ser usados também.

Condicionais em Form Hooks de Entidade

Chamamos de Form Hooks as “brechas” existentes nos formulários de Coleção, Taxonomia, Item, Metadado, Seções de Metadado, Termos e Função de Usuário para permitir inserção de opções extras por plugins nestas entidades do plugin. Eles existem há muito tempo no Tainacan, e uma de suas possibilidades é a definição de condicionais para que as tais opções extras apareçam ou não.

Na versão 1.0.0, estamos evoluindo o esquema de condicionais para que não só uma, mas múltiplas condicionais existam. Desta forma, se você quer que sua opção extra apareça apenas em Metadados do Tipo Relacionamento que sejam da coleção de ID 1234, é possível restringir isso na definição do hook:

tainacan_register_admin_hook(
   'metadatum',          // Tipo de entidade
   array($this, 'form'), // Função callback que monta o formulário
   'end-right'           // Posição
   array(                // Conditionals
      'metadata_type' => 'Tainacan\Metadata_Types\Relationship',
      'collection_id' => 1234
   )
);

Saiba mais sobre Form Hooks em nosso artigo dedicado na Wiki.

Customizando o CSS do Admin

Como antecipamos no primeiro artigo desta série, está mais fácil de se customizar o CSS do Admin do Tainacan. Nós não consideramos que a customização ampla do Admin do Tainacan seja algo almejado por muita gente, mas entendemos que existem cenários, em acervos particulares, onde a mistura da identidade visual de outros sistemas da instituição com a interface do plugin pode ser desejada.

O melhor jeito de se entender o que é possível é inspecionando o navegador e dando uma olhada em nossas novas variáveis CSS. Veja a seguir o exemplo de algumas customizações feitas para se aproximar a interface do Admin da aparência do Editor de Sites do WordPress:

.tainacan-pages-container.tainacan-pages-container--admin-gutenberg-style {
    --tainacan-admin-background-color: #1e1e1e;
    --tainacan-admin-background-image: unset;
    --tainacan-admin-color: white;
    --tainacan-admin-link-color: #f0f0f1;
    --tainacan-admin-link-hover-color: white;
    --tainacan-admin-button-border-radius: 2px;
    --tainacan-admin-button-background-color: #1e1e1e;
    --tainacan-admin-button-color: #949494;
    --tainacan-admin-button-hover-color: white;
    --tainacan-admin-button-active-color: white;
    --tainacan-admin-button-hover-background-color: #2f2f2f;
    --tainacan-admin-button-active-background-color: #2271b1;
    --tainacan-admin-button-font-weight: 400;
    --tainacan-admin-navigation-sidebar-background-color: #1e1e1e;
    --tainacan-admin-navigation-sidebar-background-image: none;
    --tainacan-admin-navigation-sidebar-separator-color: #949494;
    --tainacan-admin-navigation-sidebar-floating-menu-background-color: #1e1e1e;
    --tainacan-page-container-border-radius: 8px;
    --tainacan-dashboard-card-border-radius: 4px;
    --tainacan-dashboard-card-border: 1px solid #e5e5e5;
    --tainacan-dashboard-card-box-shadow: none;
    --tainacan-input-border-radius: 2px;
    --tainacan-button-border-radius: 2px;
    --tainacan-dropdownmenu-border-radius: 4px;
    --tainacan-modal-border-radius: 4px;

    #tainacan-page-container {
        #tainacan-navigation-menu a,
        #tainacan-navigation-menu a .icon,
        #tainacan-navigation-menu button .icon {
            color: var(--tainacan-white) !important;
        }
        #tainacan-navigation-menu .menu-item-has-children button::after {
            filter: invert(1.0);
        }
    }
}
.tainacan-pages-container--fullscreen.tainacan-pages-container.tainacan-pages-container--admin-gutenberg-style {
    --tainacan-admin-navigation-sidebar-width: calc( 300px - var(--tainacan-page-container--inner-padding-x, 1rem) );
}

Quer usar uma versão branca da logo do Tainacan na barra lateral?

add_filter( 'tainacan-navigation-logo-use-white', function() { return true; });

E que tal alterar a logo e o texto de boas vindas do Dashboard?

add_filter( 'tainacan-dashboard-logo', function() { return '../logo.svg'; } );
add_filter( 'tainacan-dashboard-welcome-message', function() {
    return __( 'Este é a sua tela inicial de gestão do acervo...', 'my-plugin-slug' );
} );

Mais possibilidades de expansão

Interessado em alterar ou expandir o Tainacan de outras formas? Você sabia que pode registrar seus próprios tipos de metadado e modos de visualização? Este e outros tópicos estão explorados em mais detalhes em nossa documentação para desenvolvedores.

E tem mais!

Não deixe de ler os outros artigos que cobrem as novidades do lançamento da 1.0:

Deixe um comentário

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *

Posts relacionados