API pentru setări în WordPress

API pentru setări, adăugat în WordPress 2.7, permite paginilor de administrare conținând formulare de setări să fie gestionate semi-automat. Aceasta vă permite să definiți pagini de setări, secțiuni în aceste pagini și câmpuri în cadrul secțiunilor.

Paginile de setări noi pot fi înregistrate împreună cu secțiunile și câmpurile din ele. Paginile de setări existente pot fi, de asemenea, adăugate prin înregistrarea secțiunilor sau câmăurilor noi de setări din ele.

Organizarea înregistrării și validării câmpurilor necesită încă unele efort din partea dezvoltatorilor folosind API pentru setări, dar evită o mulțime de depanări complexe a managementului opțiunilor de bază.

NOTĂ: Când utilizați API pentru setări, formularul se postează în wp-admin/options.php care oferă capabilități destul de stricte de control. Utilizatorii vor avea nevoie de capabilitatea „manage_options” (și în MultiSite vor trebui să fie Super Admin) pentru a transmite formularul.

Funcțiile se găsesc în wp-admin/include/plugin.php și wp-admin/include/template.php

de referință despre funcții

Referințe

Setarea înregistrării/deregistrării: register_setting(), unregister_setting()
Adaugă câmp/secțiune: add_settings_field(), add_settings_section()
Opțiuni de redarea formularului: settings_fields(), do_settings_sections(), do_settings_fields()
Erori: add_settings_error(), get_settings_errors(), settings_errors()

Adăugarea câmpurilor pentru setare

Puteți adăuga noi câmpuri pentru setări (de fapt, o opțiune în tabelul bazei de date wp_options dar total gestionată pentru tine) la paginile WordPress existente care folosesc această funcție. Funcția dumneavoastră de apel invers trebuie doar să obțină la ieșire intrarea HTML corespunzătoare și să o completeze cu valoarea veche, salvarea se va face în fundal. Puteți crea propriile secțiuni pe paginile existente folosind add_settings_section() așa cum este descris mai jos.

NOTĂ: TREBUIE să vă înregistrați orice opțiuni pe care le utilizați cu add_settings_field() altfel nu vor fi salvate și actualizate automat. Vezi mai jos pentru detalii și un exemplu.

add_settings_field( $id, $title, $callback, $page, $section = ‘default’, $args = array() )

$id – String pentru utilizare în atributul de etichete „id„.
$title – Titlul câmpului.
$callback – Funcție care completează câmpul cu intrările dorite, ca parte a formularului mai mare. Numele și ID-ul de intrare ar trebui să se potrivească cu $id dat pentru această funcție. Funcția trebuie să afișeze rezultatul său.
$page – Tipul de pagină de setări în care se arată câmpul (general, citire, scriere, …).
$section – Secțiunea a paginii de setări în care se arată caseta (implicită sau o secțiune pe care ai adăugat-o cu add_settings_section, vezi codul sursă a paginii pentru a vedea care sunt cele existente.)
$args – Argumente suplimentare trecute în funcția de apel invers

Adăugarea de secțiuni pentru setări

Secțiunile pentru setări sunt grupurile de setări pe care le vedeți pe paginile de setări WordPress cu antet partajat. În modulul tău poți adăuga noi secțiuni în paginile de setări existente, mai degrabă decât să creezi pagini cu totul noi. Acest lucru face plugin-ul mai simplu de întreținut și creează mai puține pagini noi pe care utilizatorii să le învețe. Trebuie doar să le spui să schimbe setarea de pe pagina relevantă existentă.

add_settings_section( $id, $title, $callback, $page )

$id – String pentru utilizare în atributul de etichete „id„.
$title – Titlul secțiunii.
$callback – Functie care completează secțiunea cu conținutul dorit. Funcția trebuie să afișeze rezultatul său.
$page – Tipul de pagină de setări pe care să se arate secțiunea (general, citire, scriere, media, etc.)

Înregistrarea setărilor

register_setting( $option_group, $option_name, $sanitize_callback )

unregister_setting( $option_group, $option_name, $sanitize_callback )

NOTĂ: Funcțiile register_setting(), precum și add_settings_*() menționate mai sus, ar trebui să fie toate apelate dintr-o funcție de apel invers cu cârlig de acțiune „admin_init„. Consultați exemplul de mai jos.

Redarea formularului de opțiuni

Atunci când se utilizează API pentru a adăuga setări la paginile de opțiuni existente, nu trebuie să vă preocupe formularul în sine, așa cum a fost deja definit pentru pagină. Când definiți o nouă pagină de la zero, aveți nevoie să obțineți o structură de formular minimală care conține câteva etichete care pe rând obțin la ieșire secțiunile actuale și setările pentru pagină.

Pentru a afișa câmpurile ascunse și a gestioneze securitatea formularului de opțiuni, API pentru setări oferă funcția settings_fields(). settings_fields( $option_group);

$option_group – (string) (obligatoriu) Un nume de grup pentru setări. Acesta trebuie să corespundă cu numele grupului utilizat în register_setting(), care este numele slug al paginii pe care formularul va apare.
- Implicit: Niciunul (None)

Pentru a afișa secțiunile atribuite paginii și setările conținute, API pentru setări oferă ffuncția do_settings_sections(). do_settings_sections( $page);

$page – (string) (obligatoriu) Numele slug al paginii ale cărei secțiuni pentru setări doriți să le obțineți la ieșire. Acest lucru ar trebui să se potrivească cu numele paginii folosit în add_settings_section().
- Implicit: Niciunul (None)

Funcția do_settings_fields() este prevăzută să obțină la ieșire câmpurile atribuite unei anumite pagini și secțiune. Nu trebuie să apelați această funcție în mod direct, mai degrabă utilizați do_settings_sections() pentru a transmite conținutul secțiunii, precum și câmpurile asociate.

Formularul de opțiuni are nevoie, de asemenea, de un buton pentru transmitere. Puteți folosi funcția submit_button() pentru aceasta.

În cele din urmă, trebuie să obțineți la ieșire eticheta HTML <form> care definește destinația acțiunii options.php și metoda de POST. Aici este un exemplu de opțiuni sub formă de cod pentru a genera toate secțiunile și câmpurile adăugate la o pagină al cărei nume de slug este ‘my-page‘:

Exemple

Adăugarea unui secțiuni pentru setări cu un nou câmp în ea

<?php
// ––––––––––––––––––––––
// Adaugă toate secțiunile, câmpurile și setările tale în timpul admin_init
// ––––––––––––––––––––––
//

function eg_settings_api_init() {
// Adaugă secțiunea pentru citirea setărilor astfel încât să le poți adăuga pe ale tale
// câmpuri către ea
add_settings_section(
‘eg_setting_section’,
‘Example settings section in reading’,
‘eg_setting_section_callback_function’,
‘reading’
);

// Adaugă câmp cu numele și funcție de folosit pentru cele noi ale tale
// setări, în noua ta secțiune
add_settings_field(
‘eg_setting_name’,
‘Example setting Name’,
‘eg_setting_callback_function’,
‘reading’,
‘eg_setting_section’
);

// Înregistreazî setările tale astfel încât gestionarea $_POST este făcută pentru tine și
// funcția ta de apel invers trebuie doar să afișeze la ieșire <input>
register_setting( ‘reading’, ‘eg_setting_name’ );
} // eg_settings_api_init()

add_action( ‘admin_init’, ‘eg_settings_api_init’ );

// ––––––––––––––––––––––
// Funcția de apel invers pentru secținea pentru setări
// ––––––––––––––––––––––
//
// Este nevoie de această funcție când adaugi o nouă secțiune. Această funcție
// va fi rulată la începutul secțiunii tale
//

function eg_setting_section_callback_function() {
echo ‘<p>Intro text for our settings section</p>’;
}

// ––––––––––––––––––––––
// Funcția de apel invers pentru setarea exemplului
// ––––––––––––––––––––––
//
// crează o casetă de bifare cu opțiunea adevărat/fals (true/false). Alte tipuri sunt posibile fără probleme
//

function eg_setting_callback_function() {
echo ‘<input name=”eg_setting_name” id=”eg_setting_name” type=”checkbox” value=”1″ class=”code” ‘ . checked( 1, get_option( ‘eg_setting_name’ ), false ) . ‘ /> Explanation text’;
}