Egy egyszerű tanács a WordPress Quicktags API-hoz

() translation by (you can also view the original English article)

Mint a 4.0-s verzióban, 18 beépített API van a WordPressben. Nagyon fontosak a WordPress különböző szempontjainak, és együtt segítik a WordPresst, hogy a legrugalmasabb tartalom menedzsment legyen a világon.

Az egyik ezek az API-k közül a Quicktags API, ami lehetővé teszi plugin és téma tervezőnek új gombok hozzáadását Szöveg módhoz (általában HTML módnak hívják) a WordPress szerkesztőben. Ebben a bemutatóban, meg fogjuk tanulni, mi a Quicktags API, és hogyan használjuk az API-t új gombok készítésére a HTML szerkesztőhöz.

Mi a Quicktags API?

Annak ellenére, hogy ez több annál, WordPress gyakran van használva "tartalom menedzsment rendszerként" és a WordPressnek engednie kell a felhasználókat menedzselni a tartalmat könnyen és hatékonyan. Ezért jár együtt a WordPress a TinyMCE-vel, a minden idők egyik legjobb WYSIWYG ("What You See Is What You Get") szerkesztőjével, és vitathatóan a legmegfelelőbb tartalom szereksztő a WordPresshez. A TinyMCE egyszerű tartalom szerkesztés tapasztalatot kínál a felhasználóknak, ami egyidejűleg megjeleníti a tartalmat majdnem egy pontos előnézeteként annak amit publikálni fogsz.

De néhány felhasználó nem szereti látni ezt. Valójában, néhány felhasználó jobban szereti látni a tartalom forráskódját, szóval a teljes irányítást birtokolják afölött, amit publikálni fognak. Vagy talán a felhasználó egy "Vizuális szerkesztőn" van és ellenőrizni és hitelesíteni akarja a forráskódot. Itt jön a képbe a "HTML szerkesztő". A WordPress HTML módja megjeleníti a tartalom forráskódját, és semmi többet.

A HTML szerkesztő tetején vannak gombok, ahol előhívjuk a "Quicktag gombokat", és lehetővé teszik a tartalom szerkesztését anélkül, hogy visszaváltanánk a Vizuális szerkesztőhöz. A Quicktags API használatával, új gombokat tudunk készíteni a már létezőkkel együtt.

A Quicktags API használata

A Quciktags API használata nagyon könnyű, mivel a mag quicktags.js fájl sokkal többel rendelkezik, mi az egyetlen funkciót fogjuk (és kell) használni: QTags.addButton().

Ha át akarod vinni a szkriptet egy külön fájlként (ami az ajánlott használat), a lentebbi kódtöredéket kell használnod:

<?php

function load_my_quicktags() {

    // Load the `my-quicktags.js` file with the `QTags.addButton()` functions.
    wp_enqueue_script( 'my-quicktags', 'http://the.url/to/my-quicktags.js', array( 'quicktags' ) );

}

add_action( 'admin_enqueue_scripts', 'load_my_quicktags' );

?>

De ha nincs választásod hanem ki akarod nyomtatni a szkriptet soronként, a következő kódtöredékkel tudod megoldani:

<?php

function load_my_quicktags_inline() {

    if ( wp_script_is( 'quicktags' ) ) { ?>
    
        <script>
        
            // The `QTags.addButton()` functions go here.
        
        </script>
    
    <?php }

}

add_action( 'admin_print_footer_scripts', 'load_my_quicktags_inline' );

?>

Nagyon könnyű, igaz? Észreveheted, hogy az admin_print_footer_scripts akciót használtuk ez alkalommal.

A `QTags.addButton()` paraméterei.

A QTags.addButton() funkciónak nyolc paramétere van:

QTags.addButton( 
    id, 
    display, 
    arg1, 
    arg2, 
    access_key, 
    title, 
    priority, 
    instance
);

id(string, required): Egy egyedi ID, ami a Quicktag gomb HTML ID értéke lesz. (Tartsd észben, hogy az ID érték minden gombnak automatikusan a húr 'qt_content_' mellett lesz.)
display (string, required): Írj szöveget megjeleníteni a gombon.
arg1 (string or function, required): Egy beillesztendő kezdőcímke, vagy egy visszahívó funkció neve.
arg2 (string, optional): A végső beillesztendő címke ha szükség van rá.
access_key (string, optional): Hozzáférési kulcs a gombhoz.
title (string, optional): A HTML title érték a gombhoz.
priority (integer, optional): A hely, ahova a gombod menni fog-1-től 9-is az első helyre, 11-től 19-ig a második helyre, 21-től 29-ig a harmadik helyre, és így tovább.
instance (string, optional): Egy különleges Quicktag példa, hogy megmutassam a gombot csak itt, ha van több mint egy Quicktag példa az oldalon. (Ha ez nincs beállítva, a gomb hozzá lesz adva az összes esethez.)

Alap használat: Egyszerű gombok készítése

A Quicktags API talán ijesztőnek és bonyolultnak tűnik elsőre, (különösen, ha a JavaScript tudásod gyenge, mint nekem), de ahogy most látni fogod, semmi nincs ami miatt aggódni kellene kód apró bitjeinek írásával kapcsolatban, hogy Quicktag gombokat készítsünk.

Kezdjük valami egyszerűvel: Tegyük fel, hogy két gyorskód gombok fogsz hozzáadni-egy zárt gyorskódot először, és egy önzáró gyorskódot utána. Itt van amit csinálsz:

QTags.addButton(
    'info-box', 
    'info box', 
    '[infobox]', 
    '[/infobox]'
);

Látod, milyen könnyű? Összesen annyit kell tenned, hogy beállítasz egy ID-t, egy gomb nevet, és a húrokat nyomtatni mikor a gomb kattintva van. Továbbá nem tudod elküldeni a második vitát (negyedik paraméter) és nyomtatni egy önzáró gyorskódot:

QTags.addButton(
    'signature', 
    'signature', 
    '[signature]'
);

Ez minden amit tudni kell a Quicktag gombok használatáról!

Haladó használat: Visszahívó funkciók kioldása

Természetesen, nem minden Quicktag gomb van ugyanígy csinálva. Tudsz készíteni egy egyszerű zárt és önzáró Quicktag gombot könnyen, de talán szükséged lesz készíteni egy gombot, amihez egy kicsit több munka szükségeltetik. Itt jönnek képbe a JavaScript funkciók.

Egyszerű példákat fogunk mutatni erre, de ez a képzelőerődre van bízva, hogy komplikált Quicktag gombokat készíts JavaScript funkciókkal.

Most, csináljunk két gyors példát. Az első a klasszikus alert gomb:

QTags.addButton(
    'alert', 
    'alert', 
    my_alert
);

function my_alert() {
    alert( 'Hello Quicktag!' );
}

Ahogy kitalálhatod, egy "Hello Quicktag!" üzenettel ugrik fel. Most csináljunk valamit egy súgással:

QTags.addButton( 
    'my_prompt', 
    'alert', 
    my_prompt
);

function my_prompt() {
    var my_class = prompt( 'Enter a class name:', '' );
    
    if ( my_class ) {
        QTags.insertContent('<div class="' + my_class +'"></div>');
    }
}

Ez már egy picit trükkösebb: Megkér, hogy írj be egy osztály nevet, és kinyomtat egy divet az osztállyal amit meghatároztál.

Következtetés

Ahogy korábban mondtam, az API egy kicsit félelmetesen néz ki. De ahogy láthatod, a használata meglehetősen egyértelmű-még ha visszahívás kioldó funkcióként is használod. A HTML módnak van néhány nagyon elkötelezett felhasználója, és nagyon hálásak lennének ha beleraknál egy vagy két gombot mikor egy témát vagy plugint fejlesztesz.

Mi a véleményed a Quicktags API-ról? Megfontolod a használatát, vagy van valami más, amit beleraknál ebbe a bemutatóba? Tudasd velünk lentebb kommenttel, mit gondolsz. És ha tetszett a cikk, ne felejtsd el megosztani a barátaiddal!