PHPPamokos.lt


7. Redaktoriaus žymos (shortcodes)

Namų darbai

Kaip visada, pradedame nuo namų darbų - tinyRelated v0.4.1:

  1. Pirmoji užduotis nesunkiai įvykdoma prie visų meta laukų pavadinimų pradžioje pridėjus _ - iš tinyrelated_count į _tinyrelated_count ir t.t.
  2. Antrąjai užduočiai reikėjo modifikuoti print_metabox (148-154 eilutės) ir metabox_field() (201-212 eilutės) metodus. Užuot generavę 10 lentelės eilučių (po vieną kiekvienam <select>, juos visus sudedame į vieną eilutę ir atskiriame <br/>. Dabar skydelis atrodo štai taip:

Pataisytas tinyEditor redaktoriaus dėžutės skydelis

Redaktoriaus žymos

Kaip minėjau anksčiau, yra 4 pagrindiniai būdai, kuriais WordPress įskiepis gali įtakokti WordPress sistemos veikimą, išvesti savo rezultatus ir pridėti naują funkcionalumą:

  1. Veiksmų ir filtrų kabliai (hooks)
  2. Redaktoriaus žymos (shortcodes)
  3. Skydeliai (widgets)
  4. Šablono žymos (template tags)

Veiksmų ir filtrų kablius jau aptarėme (žr. 4 skyrių), o dabar metas pakalbėti apie kitą dažnai naudojamą būdą - redaktoriaus žymas. Tai - specialiu formatu rašomi raktiniai žodžiai įrašo/puslapio tekste, kuriuos atpažinusi WordPress sistem automatiškai paverčia į įskiepio nurodytą HTML kodą.

Tokios žymos labai praverčia įskiepiams, kurių rezultatus vartotojai nori panaudoti savo tekste. Pavyzdžiui, parašius [poll id="2"] įskiepis WP Polls gali straipsnio tekste automatiškai pavaizduoti apklausos skydelį, o parašius [contact-form-7 id="5" title="Kontaktai"], įskiepis Contact Form 7 gali vietoj jo įterpti kontaktų formą, ir t.t.

Kaip turbūt jau supratote iš pavyzdžių, redaktoriaus žymos savo struktūra primena HTML žymas, tik vietoj <> simbolių naudojami laužtiniai skliaustai []. Pats paprasčiausias žymos formatas yra [raktažodis], tačiau neretai žymos turi atributų, o kartais savo viduje - turinio. Keletas pavyzdžių:

// paprasta žyma
[ad]
// žyma su atributu
[ad id="5"]
// žyma su atributu ir užbaigimo simboliu
[ad id="5"/]
// žyma su turiniu viduje
[column]turinys[/column]
// viena žyma kitos žymos viduje
[column] [ad] [/column]

Visi aukščiau pateikti pavyzdžiai gali būti naudojami. Su redaktoriaus žymomis susijusi API yra labai paprasta - vos keletas pagrindinių funkcijų:

  • add_shortcode()/remove_shortcode()
  • shortcode_atts()
  • do_shortcode()

Žymos sukūrimas

Naujos žymos sukūrimui naudojama funkcija add_shortcode( $tag, $func ). Abu argumentai yra privalomi.

  • $tag - žymos pavadinimas. Jeigu norite turėti [petras] žymą, šio argumento reikšmė bus 'petras';
  • $func - callable tipo kintamasis - nuoroda į funkciją, kurios rezultatą turėtų pavaizduoti žyma. Ši funkcija turėtų priimti vieną arba du argumentus.

Pavyzdys:

add_shortcode( 'labas', 'mano_labas' );
function mano_labas( $atts, $content = '' ) {
  return 'Labas, pasauli';
}

$atts argumentas - į masyvą sudėtos visų žymos argumentų reikšmės. Pavyzdžiui, jei tekste parašyta [labas vardas="Petras" pavarde="Petraitis"], tuomet $atts reikšmė bus array('vardas'=>'Petras','pavarde'=>'Petraitis').

Į $content argumentą perduodamas visas tekstas, esantis tarp žymos pradžios ir pabaigos ženklo. Pavyzdžiui, jei tekste turime [labas]Mano mano mano![/labas], tai $content reikšmė bus Mano mano mano!.

Gražinti funkcija turi visą tekstą/HTML kodą, kurį norite atvaizduoti vietoj žymos.

Kaip sako pavadinimas remove_shortcode() funkcija leidžia panaikinti anksčiau pridėtą redaktoriaus žymą. Dažniausiai naudojama, kai įskiepio autorius nori perdaryti vieną iš WordPress standartinių žymų. Tokios yra 7:

  • [audio]
  • [wp_caption]
  • [caption]
  • [embed]
  • [gallery]
  • [video]
  • [playlist]

Žymos atributų apdorojimas

Jeigu jūsų žyma naudos atributus, tikriausiai norėsite nurodyti jiems standartines reikšmes, naudojamas pagal nutylėjimą. Tam naudojama shortcode_atts( $defaults, $atts ) funkcija. Ji paima perduotų atributų masyvą ir papildo jį reikšmėmis iš numatytųjų reikšmių masyvo.

Žemiau pateikiamame pavyzdyje, jei vartotojas nenurodys atributo vardas, vietoj jo bus naudojamas vardas 'Anonimas'

add_shortcode( 'labas', 'mano_labas' );
function mano_labas( $atts, $content = '' ) {
  $defaults = array( 'vardas' => 'Anonimas' );
  $atts = shortcode_atts( $defaults, $atts );
  return 'Labas, '.$atts['vardas']; 
}

Darbas su žymos turiniu

Jeigu jūsų įskiepis gali turėti vidinio turinio, svarbu nepamiršti, kad šiame turinyje gali būti kitų redaktoriaus žymų, pavyzdžiui mūsų ankstesnis pavyzdys [column] [ad] [/column]. Jeigu savo funkcijoje mes tiesiog naudosime $content kintąmąjį, [ad] žyma liks neįvykdyta. Kad to išvengtume, $content kintamajam reikia panaudoti funkciją do_shortcodes( $string ). Ši funkcija yra skirta žymoms tekste atpažinti ir įvykdyti ir pagal nutylėjimą yra taikoma įrašo tekstui kaip filtras. Bet visiems vidiniams žymų teksto gabaliukams ją reikia pritaikyti rekursiškai.

add_shortcode( 'labas', 'mano_labas' );
function mano_labas( $atts, $content = '' ) {
  $defaults = array( 'vardas' => 'Anonimas' );
  $content = do_shortcode($content);
  $atts = shortcode_atts( $defaults, $atts );
  return 'Labas, '.$atts['vardas']. $content; 
}

PASTABA - jei WordPress tekste norite įterpti žymos pavyzdį, kad ji nebūtų įvykdtyta, reikia naudoti dvigubus skliaustus - [[testas]] tekste bus atvaizduota kaip [testas] ir neįvykdyta.

tinyRelated v0.5.0

Grįžkime prie mūsų įskiepio. Suteikime galimybę vartotoju pačiam nuspręsti, kurioje teksto vietoje įterpti susijusius įrašus, sukurdami tam redaktoriaus žymą [tinyrelated].

Jeigu praėjusiame skyriuje įskiepio kodas padidėjo daugiau nei du kartus, tai tinyRelated v0.5.0 versija turi labai mažai pasikeitimų.

Mes pasinaudojame jau turimu build_list() metodu sąrašo HTML generavimui, todėl telieka pridėti žymos deklaravimo eilutę (36 eilutė) ir atitinkamą shortcode() metodą klasėje (242-245 eilutės)

Namų darbas

Deja, mūsų build_list() metodas yra nelabai lankstus, tad per žymą įterpiamas sąrašas laikysis visų redaktoriaus skydelyje padarytų nustatymų - kiek įrašų rodyti, kokie tai turi būti įrašai ir pan.

Taigi, užduotis namams - pataisyti build_list() ir shortcode() metodus taip, kad redaktoriaus žymos argumentais būtų galima koreguoti sąrašo nustatytymus:

  • kiek įrašų rodyti;
  • sąrašo pavadinimą;
  • kokius susijusius įrašus rodyti;


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