Crie configurações do personalizador mais rapidamente usando o Kirki Framework em seu projeto

Publicados: 2019-08-10

Kirki é uma estrutura gratuita de código aberto (licenciada pelo MIT) criada para desenvolvedores que desejam adicionar controles do personalizador a seus temas ou plugins.

Aristeides Stathopoulos, desenvolvedor líder de Kirki, trabalha no framework desde 2014. Graças às atualizações e melhorias contínuas, Kirki construiu uma comunidade no Github que inclui mais de 1.000 estrelas e 300 bifurcações.

Antes de Kirki eu nunca toquei no customizador. Kirki me ajudou a entender o customizador e fazer muito em menos tempo!

LebCit – Desenvolvedor de Temas WordPress

Controles do personalizador do WordPress Core

O WordPress Core inclui um punhado de controles básicos do personalizador por padrão. Por exemplo: texto, área de texto, caixa de seleção, rádio, seleção, páginas suspensas, e-mail, URL, número, oculto e controles de data.

Kirki também suporta os Core Controls, além de cerca de vinte mais. De um modo geral, os controles Kirki cobrem os casos de uso mais avançados. Por exemplo:

  • Tipografia
  • Paletas de cores
  • Editor TinyMCE
  • Campos classificáveis

Kirki também oferece funcionalidades não disponíveis no Core WordPress, como a geração automática de sua saída CSS e scripts postMessage. Esses recursos, que veremos mais adiante neste artigo, podem facilmente reduzir pela metade o tempo de desenvolvimento.

Kirki é lento

Uma crítica comumente feita contra Kirki é que é lento. Na verdade, essa crítica é usada contra a maioria dos frameworks (incluindo o WordPress). Faz sentido, certo? Você está carregando muito código que talvez nunca use.

Neste caso, a realidade é que o oposto é verdadeiro. Na maioria das vezes, os painéis de controle construídos com Kirki serão realmente mais rápidos do que os mesmos painéis construídos com os Core Controls.

Isso ocorre porque Kirki adiciona uma camada de otimização que não está embutida no WordPress.

Quando o Personalizador é inicializado, o WordPress tenta instantaneamente carregar todos os controles, mesmo que estejam dentro de uma seção ou painel e o usuário ainda não possa interagir com eles. Em comparação, Kirki adia o carregamento até pouco antes de o usuário interagir com o controle.

Para ver o efeito disso na prática, vamos tentar adicionar 50 controles de cores usando cada método.

Método principal:

 for ($i = 0; $i < 50; $i++){
	$wp_customize->add_setting( 'color_setting_hex_' . $i , array(
		'padrão' => '#0088CC'
	));

	// adiciona o controle do seletor de cores
	$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'color_setting_hex_' . $i, array(
		'label' => 'Controle de cores',
		'section' => 'title_tagline',
		'configurações' => 'color_setting_hex_' . $i,
	) ) );
}

Com Kirki:

 for ($i = 0; $i < 50; $i++) {
     Kirki::add_field( 'config_id', array(
         'tipo' => 'cor',
         'configurações' => 'color_setting_hex_' . $i,
         'label' => __( 'Controle de cores', 'kirki' ),
         'section' => 'title_tagline',
         'default' => '#0088CC',
     ));
 }

Os resultados:

Como você pode ver, a velocidade de carregamento inicial é consideravelmente mais rápida ao usar Kirki. O código necessário para criar os controles também é mais conciso.

Integrando Kirki em seu projeto

Existem várias maneiras de integrar o Kirki Framework em seu projeto, a documentação oficial faz um bom trabalho explicando os diferentes métodos.

Eu recomendo que os desenvolvedores orientem o usuário a instalar a versão do plug-in do Kirki, em vez de incluir o framework diretamente no código do seu projeto. Isso pode ser feito usando o TGMPA ou o script fornecido.

O raciocínio por trás da rota do plug-in é que Kirki é atualizado e aprimorado com frequência. Ao instalar a versão do plugin, seus usuários terão acesso instantâneo a correções de bugs e atualizações de segurança.

Por outro lado, quando você inclui o framework como parte de seu projeto, os usuários só receberão atualizações quando você atualizar seu tema ou plugin, o que pode ocorrer com menos frequência do que o necessário.

Seja qual for o método usado, verifique se o Kirki foi inicializado antes de adicionar suas configurações:

 // Saída antecipada se Kirki não existir.
if (! class_exists( 'Kirki') ) {
    Retorna;
}

Campos

No exemplo do Core Method, primeiro criamos uma configuração e depois criamos um controle para ela. Na maioria dos casos, os dois estão diretamente ligados. Kirki simplifica o processo e nos permite criar um 'Campo'. Quando um campo é criado, ele cria a configuração e o controle em segundo plano para nós.

Os campos suportam todos os argumentos de controle que você esperaria (rótulo, descrição, seção, padrão), bem como alguns argumentos específicos de Kirki.

O argumento 'type' permite que você escolha um dos 30 tipos de controle de Kirki: https://kirki.org/docs/controls/

Seções

As seções do personalizador permitem agrupar os controles. O WordPress tem seis seções integradas que você também pode adicionar seus controles:

  • title_tagline – Identidade do site
  • cores – cores
  • header_image – Imagem de cabeçalho
  • background_image – Imagem de fundo
  • static_front_page – Configurações da página inicial
  • custom_css – CSS adicional


As seções no Kirki funcionam exatamente da mesma forma que no Core, o método Kirki::add_section() é simplesmente um wrapper para $wp_customize->add_section() e aceita os mesmos parâmetros e argumentos.

 Kirki::add_section( 'section_id', array(
     'title' => esc_html__( 'Minha seção', 'kirki' ),
     'description' => esc_html__( 'Descrição da minha seção.', 'kirki' ),
 ));

Painéis

Painéis permitem que você crie outro nível de hierarquia agrupando Seções. O WordPress Core tem um painel embutido, que é 'Menus'.

Novamente, a implementação Kirki é simplesmente um wrapper para a funcionalidade Core.

 Kirki::add_panel( 'painel_id', array(
     'prioridade' => 10,
     'title' => esc_html__( 'Meu Painel', 'kirki' ),
     'description' => esc_html__( 'Descrição do meu painel', 'kirki' ),
 ));

'transporte' => 'automático'

Tradicionalmente, ao criar controles do personalizador, você tem duas opções para o argumento de transporte:

  • Atualizar – Cada vez que o usuário faz uma alteração, o painel de visualização é atualizado para mostrar as alterações. Isso pode levar alguns segundos.
  • postMessage – Cada vez que o usuário faz uma alteração, o painel de visualização é atualizado usando Javascript, que não requer atualização e é quase instantâneo.

postMessage é, sem dúvida, o método superior para atualizar o visualizador e deve ser usado sempre que possível. No entanto, há uma desvantagem, usar postMessage significa que você precisa criar um código JS personalizado para cada um de seus controles. Uma implementação simples se parece com isso:

 // Atualiza o título do site em tempo real...
wp.customize( 'nome do blog', function( valor ) {
    valor.bind( function( newval ) {
        $( '#site-title a' ).html( newval );
    });
});

Quando você tem muitas configurações, isso pode se tornar rapidamente repetitivo.

É aqui que Kirki brilha, acrescenta uma terceira opção: 'transport' => 'auto'.

'transport' => 'auto' funciona junto com outro argumento que Kirki adiciona chamado 'output'. Quando ambos os valores são definidos, Kirki irá gerar automaticamente os scripts postMessage para você. O que significa que você obtém todos os benefícios de usar postMessage sem precisar escrever nenhum código Javascript.

Um campo usando transport => 'auto' se parece com isso:

 Kirki::add_field( 'config_id', array(
     'tipo' => 'cor',
     'configurações' => 'color_setting_hex',
     'label' => __( 'Controle de cores', 'kirki' ),
     'seção' => 'cores',
     'default' => '#0088CC',
     'transporte' => 'automático',
     'saída' => array(
         variedade(
             'elemento' => 'corpo',
             'propriedade' => 'cor de fundo',
         ),
     ),
 ));

Esse recurso de economia de tempo do Kirki significa que na maioria das vezes você não precisará mais escrever ou enfileirar seus próprios scripts postMessage.

Saída CSS de front-end

Outra parte da criação de configurações do Customizer é gerar a saída CSS no frontend. Um exemplo simples pode ser assim:

 /**
 * Saída do CSS do Customizador para wp_head
 */
function wptavern_customizer_css() {
	$bg_color = get_theme_mod('color_setting_hex');
	?>
	<estilo>
		corpo {
			cor de fundo: <?php echo higieniza_hex_color( $bg_color ); ?>;
		}
	</style>
	<?php
}
add_action( 'wp_head', wptavern_customizer_css );

Como no exemplo postMessage, escrever esse código pode se tornar rapidamente repetitivo se você tiver muitas configurações.

Felizmente, 'transport' => 'auto' cuida da saída do frontend para você também. Mesmo em nosso exemplo simplificado, 'transport' => 'auto' reduziu o código que precisamos escrever em ~50%.

Conclusão

Neste artigo, vimos apenas o básico do Kirki Framework e dois de seus argumentos, já podemos ver como ele nos permite criar Controles Personalizadores mais rapidamente e sem comprometer o desempenho.

Ao mergulhar no Kirki, você descobrirá rapidamente a riqueza de funcionalidades que ele adiciona à API de personalização. Não é surpresa que esteja em uso em mais de 300.000 sites e uma parte central de alguns dos maiores temas WordPress do mercado.