PHPPamokos.lt


11. Nustatymų langas (Settings API)

Namų darbai

Praėjusiame skyriuje kalbėjome apie nustatymų įrašymą ir nuskaitymą iš duomenų bazės, o namų darbams reikėjo pridėti vieną papildomą nustatymą (general_random) greta jau esančių trijų. Šis nustatymas turėjo reguliuoti, ar tinyRelated įskiepis turi užpildyti sąrašą atsitiktiniais įrašais, jei vartotojas nėra nurodęs susijusių įrašų.

Pakeitimai v0.8.1 versijoje - nedideli. 40-oje eilutėje pridėtas papildomas nustatymas (general_random) ir jo numatytoji reikšmė, o metode get_list() (147, 157-159 eilutės) - papildoma sąlyga, kuri patikrina general_random reikšmę.

Settings API

Atėjo metas sukurti mūsų įskiepio vartotojui sąsają, kurios pagalba jis galėtų keisti tinyRelated nustatymus. Tam mes naudosime WordPress Settings API - funkcijų rinkinį, kurio pagalba įskiepių ir išvaizdos temų kūrėjai gali kurti naujus langus WP Admin aplinkoje.

Pirmas žingsnis - nuorodos į nustatymų puslapį WP Admin meniu juostoje sukūrimas. Tam panaudosime funkciją add_options_page( $page_title, $menu_title, $capability, $menu_slug, $function ). Kaip matote, ji turi gan daug argumentų:

  • $page_title - (string) kokį pavadinimą rodyti nustatymų lango <title> elemente?
  • $menu_title - (string) kokį pavadinimą rodyti meniu punktui?
  • $capability - (string)kokias privilegijas turi turėti vartotojas, kad jam šis meniu punktas būtų rodomas?
  • $menu_slug - (string) unikalus meniu punkto kodas, naudojamas nuorodoje;
  • $function - (callable) funkcija, kuri išspausdins visą nustatymų lango turinį

Pavyzdys:

add_action('admin_menu', 'plugin_admin_add_page');
function plugin_admin_add_page() {
  add_options_page('Custom Plugin Page', 'Custom Plugin Menu', 'manage_options', 'plugin', 'plugin_options_page');
}

Antras žingsnis - reikia užregistruoti savo nustatymus į Settings API. Tam naudojamos tokios funcijos:

  • regsiter_setting( $option_group, $option_name, $sanitize ) - užregistruoja jūsų nustatymų lauką.
    • $option_gruop - (string) nustatymų grupės pavadinimas;
    • $option_name - (string) nustatymų lauko pavadinimas;
    • $sanitize - (callable) funkcija, kuri patikrina, ar vartotojo perduotos reikšmės yra tinkamos;
  • add_settings_section( $id, $title, $callback, $page ) - Sukuria nustatymų lango sekciją;
    • $id - (string) - unikalus sekcijos ID;
    • $title - (string) - sekcijos pavadinimas;
    • $callback - (callable) - funkcija, kuri išspausdina sekcijos turinį;
    • $page - (string) - meniu punkto, kuriam norite priskirti sekciją, kodas. Turi atitikti $menu_slugadd_options_page() funkcijos.
  • add_settings_field( $id, $title, $callback, $page, $section, $args ) - prideda nustatymą į atitinkamą nustatymų lango sekciją
    • $id - (string) nustatymo unikalus ID;
    • $title - (string) nustatymo pavadinimas;
    • $callback - (callable) funkcija, kuri išspaudina nustatymo turinį;
    • $page - (string) meniu punkto, kuriam norite priskirti nustatymą, kodas. Turi atitikti $menu_slugadd_options_page() funkcijos;
    • $section - (string) nustatymų sekcijos ID. Turi atitikti $idadd_settings_section() funkcijos;
    • $args - (array) argumentų, kuriuos reikia perduoti į $callback funkciją, masyvas.

Pavyzdys:

add_action('admin_init', 'plugin_admin_init');
function plugin_admin_init(){
  register_setting( 'plugin_options', 'plugin_options', 'plugin_options_validate' );
  add_settings_section('plugin_main', 'Main Settings', 'plugin_section_text', 'plugin');
  add_settings_field('plugin_text_string', 'Plugin Text Input', 'plugin_setting_string', 'plugin', 'plugin_main');
}

Trečias žingsnis - parengti funkciją, kuri sugeneruoja nustatymų jūsų įskiepio nustatymo lauką. Tam bus reikalingos dvi Settings API funkcijos:

  • settings_fields( $options_group ) - išspausdina nonce ir kitus pagalbinius laukus nustatymų lango formai:
    • $options_group - (string) nustatymų grupės pavadinimas. Turi atitikti $option_gruopregister_setting() funkcijos;
  • do_settings_sections( $page ) - išspausdina visas nustatymų sekcijas (ir joms priskirtus nustatymus), kuriuos atitinkamam $page priskyrėte naudodami add_settings_section() bei add_settings_field() funkcijas:
    • $page - (string) meniu punkto, kurio sekcijas norite spausdinti, kodas. Turi atitikti $pageadd_settings_section() funkcijos.

Pavyzdys:

function plugin_options_page() {
?>
<div>
<h2>My custom plugin</h2>
Options relating to the Custom Plugin.
<form action="options.php" method="post">
<?php settings_fields('plugin_options'); ?>
<?php do_settings_sections('plugin'); ?>
<input name="Submit" type="submit" value="<?php esc_attr_e('Save Changes'); ?>" />
</form></div>
<?php
}

tinyRelated_Options

Aš savo įskiepiams esu sukūręs klasę, kuriai užtenka perduoti masyvą su norimais nustatymų laukais, ir ši suformuoja reikiamą nustatymų langą. Jos naudojimas - labai paprastas. Tiesiog reikiamoje įskiepio vietoje reikia įtraukti options.php failą, ir tada įvykdyti funkciją tinyRelated_Options::init($args). $args šiuo atveju yra masyvas su informacija, kurios reikia įskiepio nustatymų langui suformuoti. Pavyzdinis $args turinys:

$args = array(
  // nustatymų lauko ID
  'id'          => 'tinyrelated_options',
  // nustatymų lango pavadinimas
  'title'       => 'tinyRelated Options',
  // nustatymų meniu punkto pavadinimas
  'menu_title'  => 'tinyRelated',
  // nustatymai, suskirstyti į sekcijas (masyvas masyve
  'fields'      => array(
    // sekcija 'general'
    "general" => array(
      // sekcijos pavadinimas
      'title' => '',
      // sekcijos callback'as
      'callback' => '',
      // sekcijai priskirti nustatymai
      'options' => array(
        // nustatymas
        'count' => array(
          // nustatymo pavadinimas
          'title'=> 'Number of related posts',
          // nustatymo lauko tipas - text/select/etc. 
          'callback' => 'text',
        ),
        // nustatymas
        'show' => array(
          // nustatymo pavadinimas
          'title'=> 'List location',
          // nustatymo lauko tipas
          'callback' => 'select',
          // papildomos nuostatos
          'args' => array(
            'values' => array(
              'false'  => '- do not show automatically -',
              'before' => 'Before post content',
              'after'  => 'After post content',
            )
          )
        ),
        'widget' => array(
          'title'=>__('Refresh session with JS','tinyip'),
          'callback' => 'checkbox',
        ),
      )
    )
  )
);
tinyRelated_Options::init( $settings );

Pastaba: Ši klasė yra specifiškai pritaikyta tinyRelated įskiepiui (jos viduje yra kreipiamasi į tinyRelated klasę), taigi, jei norėsite ją panaudoti kituose įskiepiuose, reikės atitinkamai pakoreguoti options.php failo kodą (Search & Replace bus jūsų draugas).

tinyRelated v0.9.0

tinyRelated v0.9.0 versijoje atsiranda trečia klasė, taigi, ir trečias failas - options.php.

Nustatymų lango kodas mums reikalingas tik tuomet, kai lankytojas yra WP Admin sąsajoje, todėl init() metode prieš įtraukiant options.php ir prisikabinant prie admin_menu kablio, dar yra atliekamas is_admin() patikrinimas (45-48 eilutės).

Pagrindinėje klasėje taip pat atsirado vienas naujas metodas - init_settings() (63-94 eilutės), kuriame suformuojamas nustatymų lango argumentų masyvas ir iškviečiamas tinyRelated_Options::init() metodas, t.y. suformuojamas nustatymų langas.

Namų darbai

  • Šiuo metu visi nustatymai atvaizduojami kaip tekstiniai laukai, tačiau tinyRelated_Options leidžia parinkti labiau konkretiems nustatymams tinkamus elementus - pasirinkimą iš sąrašo (<select>), varnelę (checkbox), skaičiaus pasirinkimą (number). Pataisykite init_settings() metodą, kad išnaudotų šias galimybes;
  • tinyRelated_Options klasės validate() metodas, kuris turėtų patikrinti, ar vartotojas įvedė tinkamas nustatymų reikšmes, šiuo metu - tuščias. Pataisykite jį.


(c) 2015-2018. Visais klausimais kreipkitės povilas@laraveldaily.com