Instrukcije za transformaciju Drupal Twig (tpl.php u html.twig)

Ovaj dokument je korišćen tokom većeg dela procesa transformacije Twig za Drupal 8 i može vam biti koristan i za ažuriranje vaših sopstvenih tema i modula kako bi koristili Twig šablonski engine u Drupalu 8.

Napomena: sav rad sa Twig-om sada se obavlja u Drupal jezgru problematične liste. Koristite samo sandbox za transformaciju Twig-a da pronađete prethodno transformisane šablone i funkcije.

Koraci za glavne učesnike:

• Pronađite glavne probleme za objavljivanje i pregled ispravki.
• Ne primenjivati zakrpe na sandbox
• Ne pravite zakrpe za sandbox.
• Koristite sandbox samo za testiranje i/ili dobijanje prethodno transformisanog koda.
• Pogledajte ovaj YouTube video za pregled ovog procesa.

Podešavanje

Klonirajte Drupal 8.0.x:

git clone -b 8.0.x http://git.drupal.org/project/drupal.git d8

Trenutna radna verzija Drupala će biti instalirana u folder „d8“ (nazovite je kako želite)

1. Instalirajte Drupal kao i obično (koristeći Standardni instalacioni profil).
2. Podesite sva 3 Twig parametra (debugging, cache, auto_reload) na True u services.yml.

Transformacija

Tema funkcije

Transformišite temu funkciju u šablonsku datoteku i funkciju za prethodnu obradu:

1. Identifikujte datoteku iz koje potiče vaša tema (theme.inc? Core/modules/color/?)
2. Kreirajte šablonsku datoteku X.html.twig za vašu temu funkciju:
                     - Nazovite novu datoteku u skladu sa funkcijom
                     - Uklonite prefix theme_ sa početka imena funkcije i završite naziv datoteke sa .html.twig
                     - Pretvorite donje crte („_“) u crte („-“).
                     - Primeri:
                                * theme_link() postaje link.html.twig
                                * theme_user_signature() postaje user-signature.html.twig

3. Postavite vaš novi Twig šablon u folder sa šablonima u punoj temi (u sandbox-u):
                     - za funkcije koje potiču iz određenog modula, npr. stark/templates/comment itd.
                     - za funkcije koje potiču iz theme.inc, stark/templates/theme.inc
                     - za funkcije koje potiču iz form.inc, stark/templates/form.inc
4. Posetite dokumentaciju Drupal 8 API i pronađite vašu funkciju.
                     - (postoje linkovi ka svim funkcijama u elektronskoj tabeli)
5. Dodajte PHP stil dokblock na vrh datoteke i uokvirite ga Twig komentarima {# #}
                     - Dodajte liniju @file na samom vrhu.
                     - Kopirajte definiciju funkcije odmah ispod linije @file. Prepišite „Vraća HTML ...“ kao „Podrazumevana tema implementacija ...“. Prepišite da stane u jedan red.
                     - Dodajte liniju „Dostupne promenljive:“ (zamenite @param promenljive)
                     - Kopirajte promenljive navedene u sekciji „Parametri“ u dokumentaciji api.drupal.org
                     - Uklonite liniju @see template_preprocess(), ako postoji.
                     - Dodajte liniju @see template_preprocess_THEME_HOOK().
                     - Dodajte liniju @ingroup za temu (vidi primer dokblocka niže).

6. Kopirajte izvorni kod vaše funkcije ispod dokbloka (vidi primer dole)
7. Izmenite PHP kod uglavnom u HTML i print izraze
                   - Uklonite PHP kod iz HTML-a, primeri:
                               * function whatever() {
                               * // …
                               * return $output; }
                   - Uklonite PHP print izraze i zamenite ih sa {{}}
                               * Pretvorite $variables u jednostavna imena: $variable['title'] postaje {{title}}
                               * Zamenite sintaksu niza sa tačkom: $variable['page']['tabs'] postaje {{page.tabs}}
                   - Uklonite PHP logiku i zamenite je Twig grananjem {%%}.
                               * <?php foreach $items as $item?> postaje {% for item in items %}
                   - Zamenite PHP komentare Twig komentarima: {# #}
                   - Zamenite funkcije t() oko literalnih vrednosti sa Twig filtrom t: {{ 'tekst u navodnicima'|t }}
                   - Sav PHP kod za logiku promenljivih premestite u funkciju prethodne obrade. (instrukcije za prethodnu obradu slede niže.)
8. Ako primetite stvari koje biste želeli da unapredite, na primer, da spojite šablone koji izgledaju suvišno u jedan ili poboljšate markup ili imena promenljivih, zabeležite to u ovoj elektronskoj tabeli ili otvorite problem u našem sandboxu.

Transformacija ili spajanje u funkcije prethodne obrade

NAPOMENA:

• Funkcije prethodne obrade će zameniti sve teme funkcija.
• Ako u vašem šablonu postoji PHP logika koja utiče na promenljive za štampu, taj kod treba da se premesti u funkciju prethodne obrade.
• Ako je vaš šablon nekada bio tema funkcija, funkciju teme treba transformisati u funkciju prethodne obrade.
• Ako neke teme funkcija već imaju pripadajuće funkcije prethodne obrade, kod obrade promenljivih treba premestiti u prethodnu obradu.
• Nemojte dodavati liniju u vašu implementaciju hook_theme koja kaže Drupalu da koristi šablonsku datoteku umesto funkcije teme.

INSTRUKCIJE:

• Preimenujte theme_VASFUNKCIJA u template_preprocess_VASFUNKCIJA.
• Prosledite $variables po referenci dodavanjem ampersanda, npr. theme_select($variable) postaje template_preprocess_select(&$variable).
• Izmenite funkciju tako da obrađuje samo logiku promenljivih; uklonite bilo kakav markup (npr. $output).

Ako u vašim Twig šablonima nedostaju neke funkcije...

Ako vam je potreban pristup filteru ili funkciji u Twig šablonu koja još nije podržana, dodajte je u ovaj otvoreni zadatak. Imajte na umu da većinu PHP ili Drupal funkcija treba premestiti u funkcije prethodne obrade. Samo ako mislite da će temal developer morati pristupiti toj funkciji direktno u šablonu, ona treba ostati u šablonu.

JEDNOSTAVAN PRIMER TRANSFORMACIJE (theme_link)

PHP kod

function theme_link($variables) { return '<a href="' . ($variables['options']['html'] ? $variables['text'] : check_plain($variables['text'])) . '">' . $variables['text'] . '</a>'; }

Twig šablon (ime datoteke: link.html.twig)

{# /**
 * @file
 * Podrazumevana implementacija teme za prikaz linka.
 *
 * Dostupne promenljive:
 * - text: Tekst linka za  tag.
 * - url: Kompletan URL na koji se linkuje, npr.
 *   "/node/34" ili "http://example.com/foo".
 * - attributes: Preostali HTML atributi za element koji sadrži link.
 *
 * @see template_preprocess_link()
 *
 * @ingroup themeable
 */ #}
{{ text }}

Izmene u system.module (funkcija prethodne obrade)

/**
 * Priprema promenljive za link šablone.
 *
 * Podrazumevani šablon: link.html.twig.
 *
 * @param array $variables
 *   Asocijativni niz koji sadrži:
 *   - text: Prevedeni tekst linka za  tag.
 *   - path: Interni put ili eksterni URL na koji se linkuje.
 *   - options: Asocijativni niz dodatnih opcija.
 */
function template_preprocess_link(&$variables) {
  $variables['url'] = url($variables['path'], $variables['options']);
}

Komentari:

Andrej Podanenko: http://drupal.org/node/1783130 Kako preimenovati promenljive
jen: Dodajte sopstvene Twig komentare za početak i kraj {# i #}.
jen: pratite Twig komentare sa standardnim PHP doxygen markerima za doxygen.
jen: kopirajte i nalepite definiciju iz api.drupal.org
Džejms Vilson: Ako kopirate definiciju iz * funkcije *, prepišite „Vraća HTML ...“ kao „Podrazumevana tema implementacija“
jen: kopirajte i nalepite „Parametre“ iz api.drupal.org
Džejms Vilson: Uklonite znak dolara iz imena promenljivih, a ako treba da se pozovete na drugu promenljivu iz doc bloka, koristite jednostruke navodnike oko imena promenljive. [Pogledajte raspravu o politici ovde http://drupal.org/node/1804710]
jen: „štampate“ promenljive u Twig-u sa {{}}
jen: atributi su „bušeni“, tako da možete pristupiti klasama
jen: Većinu funkcija kao što je url() treba ukloniti iz šablona i dodati u preprocess funkciju.