Jak využít myšlenku zkratek (shortcode) z WordPressu v Drupalu

Hned na začátku článku se omlouvám, ale jelikož neznám přesně českou terminologii pro shortcodes ve WordPressu a zřejmě všichni víte, o co jde spíše při použití anglického termínu, nebudu se tu snažit vnucovat slovo zkratka nebo něco podobného.

Na WordPressu se mi líbí řada věcí (a řada věcí zase nelíbí), mimo jiné taky jeho shortcodes. Do hranatých závorek napíšete nějakou značku, například [gallery] a na dané místo v textu se vloží vygenerovaná galerie. Samozřejmě až při vykreslování obsahu, ne v editoru. Více viz Shortcode API.

Drupal sice ve svém základu nic takového nemá, na druhou stranu jak je jeho zvykem, řadu věcí lze doplnit pomocí přídavných modulů.

Shortcode coby implementace nového filtru pro Drupal

Na několika projektech, kde jsem měl potřebu něco jako shortcode vytvořit, jsem postupoval tak, že jsem prostě vytvořil jednoduchý vlastní modul, do kterého jsem implementoval nový filtr. Stačí vám na to trojice funkcí:

• hook_filter_info(), kde specifikujete nový filtr a jeho callback spolu s funkcí generující popisek k filtru,
• samotný callback
• a ona funkce pro vygenerování popisku.

Funkce vracející popisek prostě vytvoří řetězec, který se vypíše pod formulářovým polem pro zadávání obsahu, kde bude textový formát mající povolený váš nový filtr. Zajímavější je callback zpracovávající dodaný text a provádějící s ním nějaké kejkle. Například přetvoření nějakého shortcode na HTML.

Ve specifikaci hook_filter_info() uvedete jako process_callback název nějaké funkce, dejme tomu _muj_filter_process. V modulu si pak vytvoříte novou funkci v tomto tvaru:

function _muj_filter_process($text, $filter, $format, $langcode, $cache, $cache_id){ ...; return $text; }

Význam parametrů funkce by měl být jasný. Zajímat vás bude především proměnná $text obsahující data z políčka, která chcete svým filtrem zpracovat. V těle funkce pak můžete například pomocí regulárního výrazu text zpracovat a najít v něm nějaké své definované shortcode či jiné vzorky textu, nějak je upravit a celý pozměněný text zase z funkce vrátit ven k dalšímu zpracování v Drupalu.

Má to jednu nevýhodu, kterou zatím netuším, jak obejít a ani jsem se o to moc nenažil. Uvnitř callbacku pro zpracování filtru totiž nemáte přístup k NID nebo UID, obecně k ID entity, kterou zpracováváte. Pokud byste to potřebovali, pak je možná jednodušší použít funkci hook_node_view_alter(), nebo případně hook_entity_view_alter() a vykašlat se na implementaci filtru.

Shortcode v Drupalu jednoduše pomocí existujícího modulu

Je mi jasné, že pokud nebudete muset nic programovat, budete raději. Pro Drupal existuje modul nazvaný Shortcode, který vychází z implementace shortcodes pro WordPress. Umí toho o něco méně, ale i tak si zaslouží vaši pozornost.

Po nakopírování modulu Shortcode do Drupalu najdete v přehledu modulů několik nových „součástek“. Používáte-li vizuální editor, zapněte je všechny, a to včetně té s označením Experimental. Doplňuje totiž právě nové tlačítko pro editor umožňující snazší vložení shortcode do textu.

Tlačítko pro editor aktivujete v administrační části Nastavení > Vytváření obsahu > Wysiwyg Profiles > Upravit. Vyhledejte a zapněte zde tlačítko Shortcode a nastavení uložte.

Nyní přejděte do administrační části Nastavení > Vytváření obsahu > Formáty textu. Rozklepněte úpravu vybraného vstupního formátu, například Full HTML. Povolte zde nový filtr Shortcodes. Pokud používáte editor, tak ještě i filtr Shortcodes – html corrector. Dole v nastavení pak zapněte shortcodes, které chcete používat. Momentálně je jich k dispozici 11, tipuju, že nejpoužívanější bude zkratka pro vkládání videa. Řeší to totiž problém s iframy v editoru.

Pokud by vám tato základní sada shortcodes nestačila, koukněte ještě na modul Basic Shortcodes Library nabízející řadu dalších zkratkových kódů.

Jak vytvořit vlastní shortcode pomocí Shortcode API

Modul Shortcode nabízí i API, pomocí kterého můžete implementovat nové zkratky ze strany svého modulu. Toto API je poměrně jednoduché – obsahuje totiž jenom dvě hákovací funkce. Pomocí hook_shortcode_info_alter(&$shortcodes) lze změnit chování stávajících shortcodů a třeba přesměrovat volání funkcí, které slouží pro jejich zpracování. Vše potřebné najdete v atributu $shortcodes.

Pro vytvoření úplně nového shortcodu nás ale bude zajímat funkce hook_shortcode_info(). Ta vrací pole s definicí shortcode podobně, jak to děláte, když definujete novou cestu v Drupalu pomocí hook_menu() nebo formulář pomocí hook_form(). Kompletní popis funkce najdete v souboru shortcode.api.php. Na ukázku si zkusíme vytvořit nový shortcode pro vložení nějaké mapy do článku.

Vytvořte si tedy základní kostru modulu – soubor něco.module a soubor něco.info, přičemž soubor info naplňte základními hodnotami. Detailní informace o tvorbě modulu je mimo rozsah tohoto článku.

Do souboru module nyní vložte následující implementaci funkce hook_shortcode_info():

function něco_shortcode_info() {

  $shortcodes['mapa'] = array(

    'title' => 'Mapa',

    'description' => 'Zkratka pro vygenerování mapy s adresou',

    'process callback' => 'něco_shortcode_mapa',

    'tips callback' => 'něco_shortcode_mapa_quote_tip',

    'attributes callback' => '_shortcode_settings_form',

    'default settings' => array(),

  );

  return $shortcodes;

}

Názvem klíče v poli $shortcodes informujete Drupal o podobě nového shortcodu, který implementujete. V tomto případě se tedy bude zpracovávat [mapa], respektive zápis v textu mající podobu [mapa]Jakuba Obrovského 21, Brno[/mapa].

Titulek a popisek se objeví v definici Shortcodů na místě, kde je zapínáte u Textového formátu, viz výše. Pozornost věnujte části process callback, kde je uveden názve funkce zpracovávající shotcode.

Tu v našem příkladu tvoří následující kód:

function něco_shortcode_mapa($attrs, $text){

  $adresa = urlencode($text);

  $sirka = 500;

  $vyska = 400;

  if (isset($attrs['sirka']) && is_numeric($attrs['sirka'])){

    $sirka = $attrs['sirka'];

  }

  if (isset($attrs['vyska']) && is_numeric($attrs['vyska'])){

    $vyska = $attrs['vyska'];

  } 

  return '<iframe src="http://maps.google.com/maps?f=q&;source=s_q&hl=cs&geocode=&q='.$adresa.'&output=embed" marginwidth="0" marginheight="0" frameborder="0" height="'.$vyska.'" scrolling="no" width="'.$sirka.'"></iframe>';

}

Všimněte si, že funkce přebírá dva parametry. Prvním je pole obsahující atributy nastavené v shortcode. Druhým je řetězec obsahující text mezi značkami shortcode, v našem případě to tedy bude adresa.

Nyní prakticky jen stačí adresu zapracovat do řetězce tvořícího iframe pro Mapy Google a tento iframe z funkce navrátit. Mezi tím máme ještě logiku ověřující, zda je nastaven atribut pro výšku a šířku vkládané mapy a pokud ano, pak se tyto údaje použijí místo výchozí hodnoty.

Uživatel tedy může do textu vložit jednu z těchto dvou variant shortcode:

• [mapa]Jakuba Obrovského 21, Brno[/mapa]
• [mapa vyska=500 sirka=800]Jakuba Obrovského 21, Brno[/mapa]

Pro pořádek ještě doplníme funkci specifikovanou callbackem pro zobrazení nápovědného tipu:

function něco_shortcode_mapa_quote_tip(){

  return '[mapa]adresa[/mapa] vygeneruje adresu s mapou v textu';

}

Nyní vše můžete vyzkoušet. Zapněte modul, případně vyprázdněte cache, pokud jste kód dali do nějakého svého stávajícího modulu. U povolených shortcodů v textovém formátu zapněte mapu a vyzkoušejte.

Upozornění: Nemusím nad zdůrazňovat, že řetězce něco z výše uvedených příkladů je nutné přepsat podle názvu vašeho modulu.

Nový filtr nebo Shortcode API?

Abych tedy výše uvedené informace nějak shrnul. Je několik možností jak v Drupalu funkcionalitu shortcode implementovat a navrhnout vaše vlastní značky. Přestože jsem dříve používal postup s definicí nového filtru, práce se Shortcode API je mnohem snazší. To především díky tomu, že odpadá práce s regulárním výrazem, kterým byste parsovali text a hledali v něm shortcode značku a její parametry. Proto Shortcode API vřele doporučuji.

Tipy: chcete-li si zrychlit práci s vkládáním obsahu v Drupalu a nemáte rádi vizuální editor, koukněte na tip, jak implementovat snadno použitelný markdown do Drupalu. Pokud naopak editor rádi máte a chtěli byste pro něj vytvořit tlačítko vkládající nejenom mapu, mrkněte na článek Jak na to: Drupal, Wysiwyg a tvorba tlačítka pro editor TinyMCE.