Quick theme options

Kirki toolkit

@APredic
O meni
Aleksandar Predic

● Twitter: @Apredic
● Shindiri Studio
● PHP / WordPress developer
● Jedan od osnivača #WPNis zajednice
Izvinjavam se unapred

- Unapred se izvinjavam zbog

mešanja engleskih i srpskih reči.

- Jednostavno, tako mi je lakše!

Customizer - u kratkim crtama
● U WP verziji 3,4 uveden je "Theme Customizer screen". U WP verziji 4.1 iz naziva je izbačeno
"Theme" jer nije služilo samo za teme, već su u Appearance > Customize meniju opcije mogle
biti dodate i putem plugin-a za njihove potrebe.

● Customize API (Customizer) je framework za live preview promena opcija u WordPress-u. On

nam pruža unificiran interfejs koji korisnicima omogućava da promene mnoge aspekte WP teme.
Korisnici mogu menjati: boje, widget-e, menije… Za developere je preporučljivo da opcije koje
dodaju prikažu kroz Customizer.

● Customize API je objektno orijentisan

● Postoji 4 tipa Customizer objekata: Paneli, Sekcije, Podešavanja i kontrole (Panels, Sections,
Settings and Controls).
Tipovi Customizer objekata
1. Controls - Kontrole su UI koji koristimo za kreiranje opcija teme ili plugin-a:
Input, textarea, radio buttons…

2. Settings - Povezuju kontrole (controls) sa bazom, omogućuju live-preview,

obavljaju sanatizaciju zapamćenih vrednosti.

3. Sections - To su UI kontejneri za kontrole koji omogućavaju grupisanje više

podešavanja u opcijama teme (Header settings, Footer settings...).

4. Panels - To su kontejneri za sekcije, koji omogućavaju grupisanje više

sekcija.
Customizer object relationships and high-level API structure.
Customize API je komplikovan

- Da li sve ovo moram da naučim???

- Da, ali ne odmah. Najbolje je učiti kroz rad na

konkretnim primerima.

Too Much Information

Zašto Kirki?

● Future proof jer ne zamenjuje Customize API

● Možete i dalje koristiti Customize API
● Štedi mnooogo vremena
● Vrlo je lako dodati panele, sekcije i polja
● Automatic postMessage scripts creation
● Omogućava da dodate opcije teme ili plugin-a bez prethodnog znanja
Customize API-a (Poželjno je da pročitate)
Kako instalirati Kirki toolkit

Dva načina:

1. Instalacija putem plugin-a (kao i svaki drugi plugin)

2. Integracija u temu
Nije preporučljivo zbog budućih ažuriranja
Install Kirki Toolkit
Customizer Controls
1. <input> (text, hidden, number, range, url, tel, email, search, time, date)
2. checkbox
3. textarea
4. radio
5. select
6. Dropdown-pages

Core Custom Control

1. Color picker
2. Media control
Kirki kontrole (polja)
1. checkbox 13. Palette 25. Toggle
2. code 14. Radio-buttonset 26. Typography
3. color-palette 15. Radio-image 27. upload
4. color 16. Radio
5. custom 17. Repeater
6. dashicons 18. Select
7. dimension 19. Slider
8. dropdown-pages 20. Sortable
9. image 21. Spacing
10. multicheck 22. Switch
11. multicolor 23. Text
12. number 24. textarea
Customizer - partial refresh demo
Getting started
1. Kreirati child temu (nije uključeno u ovu prezentaciju)
2. Kreirati konfiguraciju
3. Dodati kontrole (polja)
4. Dodati Panel (nije obavezno)
5. Dodati Sekciju (nije obavezno)
Dodati konfiguraciju

capability: any valid WordPress Kirki::add_config( 'my_theme', array(

capability. See the WordPress Codex for 'capability' => 'edit_theme_options',
details. 'option_type' => 'theme_mod',
));
option_type: can be either option or
theme_mod.
Dodati sekciju
Customizer
Kirki

$wp_customize->add_section( 'custom_css', array(

Kirki::add_section( 'custom_css', array(
'title' => esc_html__( 'Custom CSS' ) ,
'title' => esc_html__( 'Custom CSS' ) ,
'description' => esc_html__( 'Add custom CSS here' ) ,
'description' => esc_html__( 'Add custom CSS
'panel' => '', // Not typically needed.
here' ) ,
'priority' => 160,
'panel' => '', // Not typically needed.
'capability' => 'edit_theme_options',
'priority' => 160,
'theme_supports' => '', // Rarely needed.
'capability' => 'edit_theme_options',
));
'theme_supports' => '', // Rarely needed.
));

theme_supports
The Kirki::add_section() method is Optional. This can be used to hide a
nothing more than a wrapper for the
setting if the theme lacks support for a
WordPress customizer API and
specific feature (using
therefore follows the exact same
add_theme_support).
syntax.
 Customizer
Dodati kontrole
function my_custom_text_settings( $wp_customize )
{
Kirki
// Register the settings

Kirki::add_field( 'my_config', array( $wp_customize->add_setting( 'my_setting', array(

'settings' => 'my_setting', 'default' => 'some-default-value',
'label' => esc_html__( 'My custom control', 'type' => 'theme_mod',
'translation_domain' ) , 'capability' => 'edit_theme_options',
'section' => 'my_section', ));
'type' => 'text',
'priority' => 10, // Add the controls
'default' => 'some-default-value',
)); $wp_customize->add_control( 'my_setting', array(
'label' => esc_html__(' My custom control',
'translation_domain' ) ,
Required arguments 'section' => 'my_section',
'settings' => 'my_setting',
'type' => 'text',
● type 'priority' => 10
● settings ));
● section }
● default
add_action( 'customize_register', 'my_custom_text_settings' );
Kreiranje funkcije za unos opcija teme
- Koristimo fajl: functions.php
- Za proveru da li je aktivan Kirki plugin
koristimo “Kirki Helpers”
https://github.com/aristath/kirki-hel
pers
- ovde koristimo drugi način provere,
kako bi prezentacija bila što
jednostavnija
if ( ! function_exists( 'twentyseventeen_child_kirki' ) ):
/**
* Add our Kirki fields
*
* For the sake of making this tutorial easier, we will use this function
* hooked on action hook "init"
*
* In development, you should use
* https://github.com/aristath/kirki-helpers
*/
function twentyseventeen_child_kirki() {
if ( ! class_exists( 'Kirki' ) ) {
Return;
}

// Our code goes here

}

endif;
add_action( 'init', 'twentyseventeen_child_kirki' );
Kreiranje Kirki konfiguracije

Arguments:

● Capability: any valid WordPress // Add configuration

capability Kirki::add_config( 'twentyseventeen_child_config', array(
● option_type: option or 'capability' => 'edit_theme_options',
theme_mod 'option_type' => 'theme_mod',
));
● option_name
● disable_output: disable any css
output
Dodavanje panela
// Add our panel for sections
Kirki::add_panel( 'twentyseventeen_child_panel_id', array(
'priority' => 10,
'title' => esc_html__( 'My Panel Title', 'twentyseventeen_child' ) ,
'description' => esc_html__( 'My Panel Description', 'twentyseventeen_child' )
));
Dodavanje sekcija
// Add our first section
Kirki::add_section( 'twentyseventeen_child_section_id', array(
'title' => esc_html__( 'My Section Title', 'twentyseventeen_child' ) ,
'description' => esc_html__( 'My Section Description', 'twentyseventeen_child' ) ,
'panel' => 'twentyseventeen_child_panel_id', // Not typically needed.
'priority' => 10,
'capability' => 'edit_theme_options'
));
Dodavanje kontrola (polja) - promena boje navigacije
// Add our field to change menu items color
Kirki::add_field( 'twentyseventeen_child_config', array(
'type' => 'color',
'settings' => 'twentyseventeen_child_color',
'label' => esc_attr__( 'This is the label for color control', 'twentyseventeen_child' ) ,
'section' => 'twentyseventeen_child_section_id',
'default' => '#0088CC',
'priority' => 10,
'choices' => array(
'alpha' => true,
),
'transport' => 'postMessage',
'js_vars' => array(
array(
'element' => '.main-navigation a',
'function' => 'css',
'property' => 'color',
),
),
'output' => array(
array(
'element' => '.main-navigation a',
'property' => 'color',
),
),
));
Rezultat
Customizer - partial_refresh
function my_register_blogname_partials( WP_Customize_Manager $wp_customize ) {

// Abort if selective refresh is not available.

if ( ! isset( $wp_customize->selective_refresh ) ) {
return;
}

$wp_customize->selective_refresh->add_partial( 'header_site_title', array(

'selector' => '.site-title a',
'settings' => array(
'blogname'
),
'render_callback' =>
function () {
return get_bloginfo( 'name', 'display' );
}

,
));
$wp_customize->selective_refresh->add_partial( 'document_title', array(
'selector' => 'head > title',
'settings' => array(
'blogname'
),
'render_callback' => 'wp_get_document_title',
));
}
add_action( 'customize_register', 'my_register_blogname_partials' );
Kirki - partial_refresh
Kirki::add_field( 'my_config', array(
'type' => 'text',
'settings' => 'my_setting',
'label' => esc_attr__( 'Text Control', 'my_textdomain' ) ,
'section' => 'my_section',
'default' => esc_attr__( 'This is a defualt value', 'my_textdomain' ) ,
'priority' => 10,
'partial_refresh' => array(
'header_site_title' => array(
'selector' => '.site-title a',
'render_callback' =>
function () {
return get_bloginfo( 'name', 'display' );
}

,
),
'document_title' => array(
'selector' => 'head > title',
'render_callback' => 'wp_get_document_title',
),
),
));
Twenty seventeen footer copyright via child theme
- footer.php

get_template_part('template-parts/footer/site', 'info');

- template-parts/footer/site-info.php

<div class="site-info">
<?php echo twentyseventeen_child_footer_copyright(); ?>
</div><!-- .site-info -->

- functions.php

if (!function_exists('twentyseventeen_child_footer_copyright')) :
/**
* Enable to control copyright text in footer
*/
function twentyseventeen_child_footer_copyright() {
return wp_kses_post(get_theme_mod('twentyseventeen_child_footer_text', __('This is a defualt copyright text',
'my_textdomain')));
}

endif;
Footer copyright kontrole
- functions.php
- Funkcija:
twentyseventeen_child_kirki
// Add our footer section
Kirki::add_section( 'twentyseventeen_child_footer_id', array(
'title' => esc_html__( 'My Footer Section', 'twentyseventeen_child' ) ,
'description' => esc_html__( 'My Footer Section Description',
'twentyseventeen_child' ) ,
'panel' => 'twentyseventeen_child_panel_id', // Not typically needed.
'priority' => 10,
'capability' => 'edit_theme_options'
));
Kirki::add_field( 'twentyseventeen_child_config', array(
'type' => 'textarea',
'settings' => 'twentyseventeen_child_footer_text',
'label' => esc_html__( 'Text Control', 'twentyseventeen_child' ) ,
'section' => 'twentyseventeen_child_footer_id',
'default' => esc_attr__( 'This is a defualt copyright text', 'my_textdomain' ) ,
'priority' => 10,
'partial_refresh' => array(
'twentyseventeen_footer_copyright' => array(
'selector' => '.site-info',
'render_callback' => 'twentyseventeen_child_footer_copyright',
),
),
'sanitize_callback' => 'wp_kses_post' // Optional
));
Rezultat
Preuzimanje vrednosti dodatin polja
- Theme Mods
$value = get_theme_mod( 'option_name', 'default_value' );

- Options
$value = get_option( 'option_name', 'default_value' );

- Serialized Options
function my_theme_get_option( $setting, $default ) {

$options = get_option( 'option_name', array() );

$value = $default;
if ( isset( $options[$setting] ) ) {
$value = $options[$setting];
}

return $value;
}
Bugs
- active_callback ne funkcioniše u kombinaciji sa:

● partial_refresh
● 'transport' => 'postMessage'

https://github.com/aristath/kirki/issues/1118

- Repeater field ne funkcioniše u kombinaciji sa:

● partial_refresh

https://aristath.github.io/kirki/docs/controls/repeater.html
Primer iz prezentacije
GitHub - https://github.com/AleksandarPredic/twentyseventeen_child

Resursi
Customize API - https://developer.wordpress.org/themes/customize-api

Tutorial - https://wpserbia.rs/blog/kirki-toolkit/

Dokumentacija - https://aristath.github.io/kirki/

Kirki helpers - https://github.com/aristath/kirki-helpers

Starter theme with Kirki included (_s fork) - https://github.com/aristath/_s

Hvala :)
Pitanja???