API pentru personalizare teme WordPress

API pentru personalizare teme WordPress, adăugat în WordPress 3.4, permite dezvoltatorilor să personalizeze și să adauge controale la ecranul de administrare „Aspect” → „Personalizare„. Ecranul de personalizare a temei (de exemplu, „Personalizare„) permite administratorilor site-ului să optimizeze setările unei teme, schema de culoare sau widget-uri, și să previzualizeze aceste schimbări în timp real.

Acest articol presupune că ați citit deja Dezvoltarea temelor și Dezvoltarea unui modul, care dau o imagine de ansamblu (și multe detalii) privind modul de dezvoltare de teme personalizate și plugin-uri pentru WordPress. Acest articol necesită, de asemenea o înțelegere funcțională a programării orientate-obiect. O familiarizare cu API-ul pentru setările WordPress este de asemenea foarte util.

Notă: Aceste informații se aplică doar la WordPress versiunea 3.4 și mai nouă.

Dezvoltarea personalizării

Fie ca sunteti un dezvoltator de temă sau plugin, puteți folosi acest API pentru a adăuga mai multe opțiuni puternice, o personalizare interactivă la temă sau plugin.

Pentru a adăuga propriile opțiuni de personalizare, aveți nevoie să utilizați minim de 2 cârlige:

customize_register – Acest cârlig permite definirea de noi panouri, secțiuni, setări, și controale de personalizare.
wp_head – Acest cârlig vă permite să obțineți CSS generat personalizat, astfel încât modificările apar în mod corect pe site-ul live.

Notă: Opțional, cârligul customize_preview_init poate fi de asemenea utilizat pentru a pune în coadă JavaScript personalizat pe ecranul de personalizare. JavaScript poate fi utilizat pentru a face personalizarea mai receptivă și mai puternică, dar acest pas nu este necesar.

Important: Nu încărcați condiționat codul de personalizare cu o verificare is_admin(). Dacă adăugați numai customize_register dacă is_admin(), atunci orice panouri, secțiuni, sau controale vor fi indisponibile atunci când se încarcă previzualizarea personalizării. Începând cu WordPress 4.1, există panouri contextuale, secțiuni, și controale, astfel încât acestea pot fi afișate numai pe anumite adrese URL pentru previzualizare. Dacă înregistrați doar panourile, secțiunile, și controalele dvs. if is_admin(), atunci vei putea spune efectiv că acestea nu sunt contextuale la orice URL pe site-ul dvs.

Partea 1: Definirea setărilor, controalelor, etc

Orice noi setări, secțiuni, sau controale pentru personalizarea temei trebuie să fie definite prin acțiunea customize_register. Această acțiune încarcă automat obiectul $wp_customize, care este o instanță a clasei WP_Customize_Manager.

În primul rând, definiți acțiunea astfel:

function mytheme_customize_register( $wp_customize ) {
//Toate secțiunile, setările, și controalele vor fi adăugate aici
}
add_action( ‘customize_register’, ‘mytheme_customize_register’ );

Rețineți că obiectul $wp_customize este trecut automat la funcție, și toate personalizări pe care le faceți la pagina de personalizare a temei sunt efectuate prin metode ale obiectului $wp_customize.

Apoi, trebuie să definiți setările, apoi secțiunile, apoi controalele (controalele au nevoie de o secțiune și o setare la funcție).

Adăugarea unei noi setări

Setările utilizează automat caracteristicile theme_mod WordPress pentru a obține/configura setările pentru temă.

Pentru a adăuga o nouă setare pentru personalizarea temei, aveți nevoie să apelați metoda $wp_customize-> add_setting(). Prin definirea setării în acest fel, nu aveți nevoie să faceți nicio muncă în plus pentru a crea, salva, sau prelua setări pentru temă.

Adăugarea unei setări la temă (în cadrul acțiunii „customize_register„) ar putea arăta astfel:

$wp_customize->add_setting( ‘header_textcolor’ , array(
‘default’ => ‘#000000’,
‘transport’ => ‘refresh’,
) );

Notă: Argumentul „transport” este opțional, și implicit pentru „refresh„. Dacă este lăsat implicit, atunci fereastra de previzualizare a personalizării temei se va actualiza prin reîncărcarea completă în sine, atunci când această setare este schimbată. Dacă preferați să evitați reîmprospătarea și să îmbunătățiți capacitatea de reacție, puteți seta acest lucru la „postMessage„, apoi manipula toate actualizările de stil manual cu puțin JavaScript.

Adăugarea unei noi secțiuni

Secțiunile sunt grupuri de opțiuni. Când definiți noi controale, acestea trebuie să fie adăugate la o secțiune. Deși puteți adăuga controale la secțiunile implicite existente, noi vom acoperi pe scurt adăugarea unei noi secțiuni.

Pentru a adăuga o nouă secțiune la personalizarea temei, trebuie să apelați la metoda $wp_customize-> add_section().

Adăugarea unei secțiuni a temei (în cadrul acțiunii „customize_register„) ar putea arata astfel:

$wp_customize->add_section( ‘mytheme_new_section_name’ , array(
‘title’ => __( ‘Numele secțiunii vizibile, ‘mytheme’ ),
‘priority’ => 30,
) );

WordPress include câteva secțiuni interne. Dacă doriți să utilizați oricare din cele interne existente, nu aveți nevoie să le declarați cu add_section(). În schimb, faceți referire la ele pe nume. Următoarele secțiuni sunt interne:

title_tagline – Titlu și tagline site (și icon site în WP 4.3+)
colors – Culori
header_image – Imagine antet
background_image – Imagine de fundal
nav – Navigare
static_front_page – Pagin de start statică

Adăugarea unui nou control

Un control este un element de formular HTML care redă pe pagina de personalizare a temei și permite administratorilor să schimbe o setare, și să previzualizeze aceste modificari in timp real. Controalele sunt legate de o singură setare, și o singură secțiune.

Pentru a adăuga un nou control la personalizarea temei, trebuie să apelați metoda $wp_customize-> add_control().

Adăugarea unui control la o secțiune a temei (în cadrul acțiunii „customize_register„) ar putea arata astfel:

$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, ‘link_color’, array(
‘label’        => __( ‘Header Color’, ‘mytheme’ ),
‘section’    => ‘your_section_id’,
‘settings’   => ‘your_setting_id’,
) ) );

Controalele au destul de puíne opțiuni, dintre care unele necesită trecerea ]n altă clasă (cum ar fi clasa WP_Customize_Color_Control() arătată în exemplul de mai sus).

Partea 2: Generarea live CSS

În cele din urmă, trebuie doar să vă asigurați că preluați setările și obțineți orice CSS necesar în antet. Dacă ați definit setările în cadrul unei acțiuni „customize_register„, așa cum este descris mai sus, atunci obtinerea valorilor de setare este la fel de simplu ca obținerea css cu acțiunea „wp_head” și preluarea valorilor cu get_theme_mod()

De exemplu, să presupunem că aveți o setare numită „header_color” si ea arată astfel:

$wp_customize->add_setting( ‘header_color’ , array(
‘default’ => ‘#000000’,
‘transport’ => ‘refresh’,
) );

Codul dvs. de ieșire CSS în antet ar putea arata ceva de genul acesta:

function mytheme_customize_css()
{
?>
<style type=”text/css”>
h1 { color:<?php echo get_theme_mod(‘header_color’, ‘#000000’); ?>; }
</style>
<?php
}
add_action( ‘wp_head’, ‘mytheme_customize_css’);

Când te uiți la sursa paginii ați vedea următoarele în antet:

Veți observa că valoarea implicită # 000000 este pentru culoare. Odată ce această valoare este schimbată prin personalizare, noua valoare va fi afișată. De exemplu, să spunem că ați vrut să schimbați culoarea în alb. În personalizare, introduceți valoarea hex pentru alb, #FFFFFF, faceți clic pe Salvare și Publicare.

Acum, în sursa paginii veți vedea:

În acest moment, opțiunile de personalizare live a temei ar trebui să fie pe deplin funcționale (dacă setările definite în partea 1 utilizează în mod explicit „transport”=>’postMessage”).

Traducere din wordpress.org