Customizer Uma melhor experiência na personalização de temas

˃ Co-Fundador da Haste ˃ Professor na ETEC Guaracy Silveira - Extensão Godofredo Furtado no curso de Programação de Jogos Digitais ˃ Graduado em Jogos Digitais pela FATEC São Caetano do Sul ˃ Membro da Comunidade WordPress São Paulo ˃ Contribuidor do WordPress allysonsouza.com.br

Customizer Uma melhor experiência na personalização de temas Objetivo: Apresentar como foi a evolução dos recursos de personalização do WordPress, implementação da API de Personalização e o seu estágio atual. Mostrar como o customizer promove uma melhor experiência na personalização de temas WordPress e como utilizá-lo.

WordPress Personalização no início da plataforma 01.

WordPress CMS (Content Management System), um software com o propósito de facilitar o gerenciamento de conteúdo. Mas nem sempre foi assim...

WordPress 1.2 mingus Interface do WordPress 1.2, mostrando a listagem de posts.

WordPress 1.2 mingus - painel administrativo Tela de edição de templates do WordPress 1.2. Aqui era possível modificar alguns templates básicos que modificavam a listagem de posts do WordPress.

Temas WordPress 1.5 (Strayhorn) 02.

Temas Na versão 1.5 do WordPress foram introduzidos os temas. Os temas controlam o modo como o conteúdo será exibido.

Personalização utilizando temas Desenvolvedor: pode desenvolver temas, utilizando PHP, HTML e CSS. Usuário: se limita a utilizar temas desenvolvidos, ou a contratar o serviço de desenvolvimento de um tema.

A personalização da personalização 03. Settings API

Introdução da Settings API No WordPress 2.7 Coltrane foi introduiza a Settings API, uma API que facilitou a criação de páginas de opções no painel administrativo, seja pra plugins ou temas.

Evolução com a Settings API Tema + Personalização de aspectos do tema.

Theme Customization API Também conhecido como Customizer 04.

Introdução da Theme Customization API Introduzida no WordPress 3.4 (Green). Agora é possível definir elementos gerais da instalação e itens do tema em uma interface única e amigável.

Customizer Visualização do site

Quais as vantagens da Theme Customization API em relação à Settings API? → Localização centralizada das configurações → Padronização → Pré-visualização em tempo real → Pré-visualização de responsividade (versão 4.5 - Coleman) → Obrigatório para temas do repositório oficial desde 22 de Abril de 2015 → Exibição contextual de opções de acordo com a página do site

Anatomia do Customizer Estrutura e componentes 05.

No content

Panels Panels são utilizados para agrupar e diferenciar o contexto de controles e seções. Resumindo, panels nada mais são do que agrupadores de sections.

Section Sections são os containers de controles do Customizer. Você pode definir as suas próprias seções em seu Tema ou Plugin, ou atribuir controles às seções padrão do WordPress.

Controls Os controls são os objetos primários de interface do customizer. Cada control deve estar relacionado a uma setting, que será responsável, por exemplo, em salvar as opções definidas no controle.

Controls: Tipos Tipos de controles padrão do WordPress. Tipos de controles checkbox | textarea | radio | select | dropdown-pages | text | hidden | number | range | url | tel | email | search | time | date | datetime | week *Obs: Os controles precisam ser atribuídos à uma seção para serem exibidos, seja ela uma seção padrão do WordPress, ou definida em tema ou plugin.

Settings As settings gerenciam a visualização em tempo real, o salvamento e a sanitização dos objetos do Customizer. Cada setting é gerenciada por um objeto control. //Settings com todos os seus parâmetros $wp_customize->add_setting( 'setting_id', array( 'type' => 'theme_mod', // or 'option' 'capability' => 'edit_theme_options', 'theme_supports' => '', // Rarely needed. 'default' => '', 'transport' => 'refresh', // or postMessage 'sanitize_callback' => '', 'sanitize_js_callback' => '', // Basically to_json. ) ); //Settings com todos os seus parâmetros $wp_customize->add_setting( 'setting_id', array( 'type' => 'theme_mod', // or 'option' 'capability' => 'edit_theme_options', 'theme_supports' => '', // Rarely needed. 'default' => '', 'transport' => 'refresh', // or postMessage 'sanitize_callback' => '', 'sanitize_js_callback' => '', // Basically to_json. ) );

Settings: Theme_mods x Options A princípio as settings podem ser armazenadas de duas formas: theme_mods ou options. Options Salvas na tabela wp_options. Se aplicam ao site independente de qual tema esteja ativo. Theme_mods Dizem respeito e se aplicam ao tema que estiver ativo. PLUGINS TEMAS

Criando settings, controls, sections e panels 06. Customizer na prática

Adicionando o hook Para trabalhar com os objetos do customizer, é preciso utilizar o hook customize_register. function themeslug_customize_register( $wp_customize ) { // Faça aqui coisas com o $wp_customize, o objeto da WP_Customize_Manager. } add_action( 'customize_register', 'themeslug_customize_register' );

Adicionando uma section Para trabalhar com os objetos do customizer, é preciso utilizar o hook customize_register. $wp_customize->add_section( 'custom_css', array( 'title' => __( 'Custom CSS' ), 'description' => __( 'Add custom CSS here' ), 'panel' => '', // Geralmente não necessário. 'priority' => 160, 'capability' => 'edit_theme_options', 'theme_supports' => '', // Raramente necessário. ) );

Adicionando uma setting Adicionar uma setting que irá controlar o armazenamento das informações de um control. $wp_customize->add_setting( 'setting_id', array( 'type' => 'theme_mod', // or 'option' 'capability' => 'edit_theme_options', 'theme_supports' => '', // Rarely needed. 'default' => '', 'transport' => 'refresh', // or postMessage 'sanitize_callback' => '', 'sanitize_js_callback' => '', // Basically to_json. ) ); //Código padrão para a criação de uma setting de campo de definição de cor hexadecimal $wp_customize->add_setting('setting_id', array( 'default' => '#f72525', 'sanitize_callback' => 'sanitize_hex_color', ) );

Adicionando um control $wp_customize->add_control( 'setting_id', array( 'type' => 'date', // Qual o tipo do controle 'priority' => 10, // Prioridade do controle dentro da seção 'section' => 'colors', // Em que seção será exibido 'label' => __( 'Date' ), 'description' => __( 'This is a date control with a red border.' ), 'input_attrs' => array( 'class' => 'my-custom-class-for-js', 'style' => 'border: 1px solid #900', 'placeholder' => __( 'mm/dd/yyyy' ), ), 'active_callback' => 'is_front_page', // Exibição contextual/condicional ) ); // Criação de um controle simples para input de texto $wp_customize->add_control( 'custom_theme_css', array( 'label' => __( 'Custom Theme CSS' ), 'type' => 'textarea', 'section' => 'custom_css', ) );

Utilizando as configurações no seu tema Para utilizar os valores das opções criadas no customizer em seu tema, é preciso utilizar uma das duas funções do WordPress: get_theme_mod() ou get_option()

Utilizando as configurações no seu tema: exibindo um custom css function my_custom_css_output() { echo '' . get_theme_mod( 'custom_theme_css', '' ) . ''; echo '' . get_option( 'custom_plugin_css', '' ) . ''; } add_action( 'wp_head', 'my_custom_css_output');

Default sections para adição de controles

Adicionando um panel Adicionando painéis para agrupar sections. Lembrando que um panel precisa ter ao menos uma section para ser exibido, e uma section precisa de ao menos um control atribuído para ser exibida. $wp_customize->add_setting( 'setting_id', array( 'type' => 'theme_mod', // or 'option' 'capability' => 'edit_theme_options', 'theme_supports' => '', // Rarely needed. 'default' => '', 'transport' => 'refresh', // or postMessage 'sanitize_callback' => '', 'sanitize_js_callback' => '', // Basically to_json. ) ); //Adiciona um panel $wp_customize->add_panel( 'menus', array( 'title' => __( 'Menus' ), 'description' => $description, 'priority' => 160, ) ); //Adiciona uma section ao panel personalizado (sem nenhuma section atribuída, um panel não é exibido) $wp_customize->add_section( $section_id , array( 'title' => $menu->name, 'panel' => 'menus', ) );

Conceitos e aplicações mais elaboradas do customizer 07. Customizer avançado

Controles contextuais Defina quando controls, panel e sections serão exibidos, de acordo com a página em que o usuário está. $wp_customize->add_section( 'featured_content', array( 'title' => __( 'Featured Content', 'twentyfourteen' ), 'description' => //... 'priority' => 130, 'active_callback' => 'is_front_page', //Pode ser uma função própria, definida por você ) );

PostMessage Padrão do customizer: recarregar, com AJAX, a página inteira quando uma mudança em um control é feita. Problemas: pode se tornar lento;

Atualização com refresh Atualização com postMessage

PostMessage //Passo 1: Definir o parâmetro transport como ‘postMessage’ $wp_customize->add_setting( 'setting_id', array( 'type' => 'theme_mod', 'capability' => 'edit_theme_options', 'default' => '', 'transport' => 'postMessage', // ou refresh ) );

PostMessage //Passo 2: Carregar o script JavaScript que será responsável por lidar com a atualização via postMessage function my_preview_js() { wp_enqueue_script( 'custom_css_preview', 'path/to/file.js', array( 'customize-preview', 'jquery' ) ); } add_action( 'customize_preview_init', 'my_preview_js' );

PostMessage //Passo 3: Tratar no JavaScript, a partir do objeto wp.customize, como serão atualizadas as informações da página ( function( $ ) { wp.customize( 'setting_id', function( value ) { value.bind( function( to ) { $( '#custom-theme-css' ).html( to ); } ); } ); } )( jQuery );

Demais recursos avançados do Customizer ➔ Selective Refresh ➔ Custom controls, sections, panels ➔ API JavaScript ➔ Templates Underscores https://developer.wordpress.org/themes/advanced-topics/customizer-api/

Kirki Toolkit Desenvolva mais rápido 08.

kirki.org Criada por Aristeides Stathopoulos Desenvolva mais rápido utilizando a Kirki. Uma camada de simplificação que já lida com os aspectos que seriam mais trabalhosos e repetitivos do customizer.

Benefícios da Kirki Capacidade de criar mais de 20 campos de controle diferentes. (Incluindo Google Fonts e Dashicons) Já lida com a geração de CSS personalizado a partir dos campos de controle. Já lida com postMessage para atualização em tempo real. Não conflitante com a API do WordPress. Apenas uma camada de abstração e simplificação. 1. 2. 3. 4.

Adicionando o um campo na Kirki //Kirki: Adicionando um campo Kirki::add_field( 'minha_config', array( 'settings' => 'minha_setting', 'label' => __( 'Meu Controle', 'text_domain' ), 'section' => 'minha_section', 'type' => 'color', 'priority' => 10, 'default' => 'algum-valor-padrao', 'output' => array( array( 'element' => '.seletor-css', 'property' => 'propriedade-css', 'units' => 'px', ), ) );

De personalização do tema a conteúdo 09. Aplicações do customizer

Estilização do tema. Se é possível de fazer com CSS, você pode criar opções no customizer para personalização.

Utilização dos valores do customizer para modificação de lógica no PHP

Many end users of WordPress are non-technically minded. [...] These are the users that we design the software for as they are ultimately the ones who are going to spend the most time using it for what it was built for. Design for the Majority, WordPress Philosophy

Referências https://codex.wordpress.org/History https://wordpress.org/download/release-archive/ https://codex.wordpress.org/Settings_API https://codex.wordpress.org/Theme_Customization_API https://developer.wordpress.org/themes/advanced-topics/customizer-api/ https://make.wordpress.org/themes/2015/04/22/details-on-the-new-theme-settings-custo mizer-guideline/ http://themefoundation.com/wordpress-theme-customizer/ https://wordpress.org/about/philosophy/ https://make.wordpress.org/core/2016/02/16/selective-refresh-in-the-customizer/

Obrigado! [email protected] Github /allysonsouza Facebook /allyson.a.de.souza Twitter /allyson_as