Drupal Twig-ի փոխարկման հրահանգներ (tpl.php-ից html.twig)

Այս փաստաթուղթը օգտագործվել է Drupal 8-ի Twig փոխարկման գործընթացի մեծ մասի ընթացքում և կարող է օգտակար լինել նաև ձեր սեփական թեմաները և մոդուլները թարմացնելու համար՝ օգտագործելով Twig տեմպլեյթ շարժիչը Drupal 8-ում։

Նշում․ Twig-ով բոլոր աշխատանքները հիմա կատարվում են Drupal արմատային խնդրների հերթում։ Օգտագործեք միայն Twig փոխարկման sandbox-ը նախօրոք փոխարկված տեմպլեյթներն ու ֆունկցիաները գտնելու համար։

Հիմնական մասնակցողների քայլերը՝

• Գտեք հիմնական խնդիրները՝ ուղղումներ հրապարակելու և դիտելու համար։
• Չկիրառել патчեր sandbox-ին
• Չստեղծել патчեր sandbox-ի համար։
• Օգտագործել sandbox-ը միայն թեստավորման և/կամ նախօրոք փոխարկված կոդ ստանալու համար։
• Դիտեք այս YouTube տեսանյութը՝ այս գործընթացի համառոտ ակնարկի համար։

Կարգավորում

Կլոնավորեք Drupal 8.0.x-ը՝

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

Ընթացիկ Drupal-ի աշխատող տարբերակը կտեղադրվի «d8» թղթապանակում (անվանեք ինչպես ցանկանաք)

1. Տեղադրեք Drupal սովորականի նման (օգտագործելով Սկզբնական տեղադրման պրոֆիլը):
2. services.yml-ում ավելացրեք Twig-ի բոլոր 3 պարամետրերը (debugging, cache, auto_reload)՝ True արժեքով։

Փոխարկում

Թեմայի ֆունկցիաներ

Փոխարկել թեմայի ֆունկցիան տեմպլեյթի ֆայլի և նախապատրաստման ֆունկցիայի

1. Վճռեք ֆայլը, որտեղից գալիս է ձեր թեման (theme.inc? Core/modules/color/?)
2. Ստեղծեք X.html.twig տեմպլեյթային ֆայլ ձեր թեմայի ֆունկցիայի համար՝
                     - Անվանեք նոր ֆայլը համապատասխանաբար
                     - Հեռացրեք theme_ նախածանցը ֆունկցիայի անունից և փոխարինեք ֆայլի վերջը .html.twig-ով
                     - Փոխարինեք ստորակետերը («_») գծիկներով («-»):
                     - Օրինակներ՝
                            * theme_link() դառնում է link.html.twig
                            * theme_user_signature() դառնում է user-signature.html.twig

3. Տեղադրեք նոր Twig տեմպլեյթը լիարժեք թեմայի տեմպլեյթների պանակում (sandbox-ում):
                     - Եթե ֆունկցիան գալիս է որոշակի մոդուլից, օրինակ՝ stark/templates/comment և այլն։
                     - Եթե ֆունկցիան գալիս է theme.inc-ից, տեղադրեք stark/templates/theme.inc
                     - Եթե ֆունկցիան form.inc-ից է, stark/templates/form.inc
4. Գնացեք Drupal 8 API-ի տեքստին և գտեք ձեր ֆունկցիան։
                     - (բոլոր ֆունկցիաների հղումները կան էլեկտրոնային աղյուսակում)
5. ավելացրեք PHP ոճի դոկբլոկ ֆայլի վերևում Twig մեկնաբանություններով {# #}
                     - Գտեք @file տողը ֆայլի վերևում։
                     - Կպցրեք ֆունկցիայի հայտարարությունը @file-ից ստորին հատվածում։ Փոխել «Վերադարձնում է HTML ...» որպես «Նախնական թեմայի իրականացում ...»՝ այնպես, որ տեղավորվի մեկ տողում։
                     - Ավելացրեք «Ստացվող փոփոխականներ:» տողը (փոխարինեք @param փոփոխականները)
                     - Փոխանցեք փոփոխականները, որոնք նշված են API-ի «Parameters» բաժնում։
                     - Հեռացրեք @see template_preprocess(), եթե կա։
                     - Ավելացրեք @see template_preprocess_THEME_HOOK() տողը։
                     - Ավելացրեք @ingroup թեմատիկ տողը (տես ստորև՝ դոկբլոկի օրինակ)

6. Կպցրեք ձեր ֆունկցիայի սկզբնական կոդը դոկբլոկից ներքև (տես օրինակ):
7. Փոխարկեք PHP կոդը հիմնականում HTML և տպագրական օպերատորների՝
                     - Հեռացրեք PHP կոդը HTML-ից, օրինակներ՝
                            * function whatever() {
                            * // …
                            * return $output; }
                    - Հեռացրեք PHP տպագրական օպերատորները և փոխարինեք {{}}-ով
                            * Փոխակերպեք $variables-ի անունները պարզ անունների՝ $variable['title'] դառնում է {{title}}
                            * Մասիվի սինտաքսը փոխարինեք կետային սինտաքսով՝ $variable['page']['tabs'] դառնում է {{page.tabs}}
                    - Հեռացրեք PHP տրամաբանությունը և փոխարինեք տեգերի {%%} սինտաքսով՝
                            * <?php foreach $items as $item?> դառնում է {% for item in items %}
                    - PHP մեկնաբանությունները փոխարինեք Twig մեկնաբանություններով՝ {# #}
                    - Փոխարինեք t() ֆունկցիան տեքստերի վրա Twig ֆիլտրով՝ {{ 'տեքստ'|t }}
                    - Բոլոր PHP տրամաբանությունը տեղափոխեք նախապատրաստման ֆունկցիա (տես ներքևի հրահանգները)

8. Եթե նկատեք, որ կարող եք բարելավել ինչ-որ բան, օրինակ՝ միավորել հավելյալ տեմպլեյթները մեկի մեջ, բարելավել նշումը կամ փոփոխականների անունները, նշեք դա այս էլեկտրոնային աղյուսակում կամ ստեղծեք խնդրի գրառում մեր sandbox-ում։ Օրինակ՝ http://drupal.org/node/180591

Փոխարկում կամ միավորում նախապատրաստման ֆունկցիաներում

ՆՇՈՒՄՆԵՐ․

• Նախապատրաստման ֆունկցիաները կփոխարինեն բոլոր թեմայի ֆունկցիաները։
• Եթե ձեր տեմպլեյթ ֆայլում կա PHP տրամաբանություն, որը ազդում է տպագրվող փոփոխականների վրա, այն պետք է տեղափոխել նախապատրաստման ֆունկցիա։
• Եթե ձեր տեմպլեյթը սկսվել է որպես թեմայի ֆունկցիա, այդ թեմայի ֆունկցիան պետք է փոխարկվի նախապատրաստման ֆունկցիայի։
• Եթե որոշ թեմայի ֆունկցիաներ արդեն ունեն նախապատրաստման ֆունկցիաներ, տեմպլեյթների փոփոխականների մշակման կոդը պետք է տեղափոխվի նախապատրաստման ֆունկցիաներ։
• Չավելացրեք ձեր hook_theme իրագործմանը տող, որը Drupal-ին կասի օգտագործել տեմպլեյթ ֆայլը թեմայի ֆունկցիայի փոխարեն։

ՀՐԱՄԱՆԱՎՈՐՈՒԹՅՈՒՆՆԵՐ․

• Փոխարինեք theme_YOURFUNCTION անունը template_preprocess_YOURFUNCTION-ով։
• Հղման միջոցով փոխանցեք $variables՝ ավելացնելով &- նշանը, օրինակ՝ theme_select($variable) դառնում է template_preprocess_select(&$variable)։
• Խմբագրեք ֆունկցիան՝ մշակելու միայն փոփոխականների տրամաբանությունը, հեռացրեք ցանկացած նշում (օրինակ՝ $output)։

Եթե ձեր տեմպլեյթներում բացակայում են տեգեր (branch functions)...

Եթե ձեզ հարկավոր է Twig տեմպլեյթում ֆիլտրի կամ ֆունկցիայի հասանելիություն, որը դեռ չի գործում, ավելացրեք այն այս բաց թողարկման։ Ուշադրություն դարձրեք, որ մեծամասնությունը PHP կամ Drupal ֆունկցիաներից պետք է տեղափոխվեն նախապատրաստման ֆունկցիաներ։ Միայն եթե կարծում եք, որ թեմայի մշակողը պետք է ունենա այս ֆունկցիային ուղղակի հասանելիություն, այն թողեք տեմպլեյթում։

Պարզ փոխարկման օրինակ (theme_link)

PHP կոդ

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

Twig տեմպլեյթ (ֆայլի անունը՝ link.html.twig)

{# /**
 * @file
 * Նախնական թեմայի իրականացում հղման ցուցադրման համար.
 *
 * Ստացվող փոփոխականներ:
 * - text: Հղման տեքստը.
 * - url: Լինկի ամբողջական URL-ը, օրինակ՝ "/node/34" կամ "http://example.com/foo".
 * - attributes: Տարրին առկայ HTML հատկությունները.
 *
 * @see template_preprocess_link()
 *
 * @ingroup themeable
 */ #}
<a href="{{ url }}" class="{{ attributes.class }}"{{ attributes }}>{{ text }}</a>

system.module-ում փոփոխություններ (նախապատրաստման ֆունկցիա)

/**
 * Նախապատրաստում է փոփոխականները հղման տեմպլեյթի համար։
 *
 * Նախնական տեմպլեյթ՝ link.html.twig։
 *
 * @param array $variables
 *  Համակարգված զանգված, որը պարունակում է՝
 *  - text: Թարգմանված հղման տեքստը։
 *  - path: Ներքին ուղի կամ արտաքին URL։
 *  - options: Ավելացված ընտրանքների զանգված։
 */
function template_preprocess_link(&$variables) {
  $variables['url'] = url($variables['path'], $variables['options']);
}

Մեկնաբանություններ

Անդրեյ Պոդանենկո՝ http://drupal.org/node/1783130 ինչպես փոփոխականների վերանվանումը
jen: Օգտագործեք Twig մեկնաբանությունների բացման և փակման նշանները {# և #}.
jen: Twig տեգերի մեկնաբանությունները համաժամեցրեք PHP-ի doxygen մեկնաբանությունների հետ:
jen: պատճենեք և կպցրեք այս հայտարարությունը api.drupal.org-ից:
Ջեյմս Ուիլսոն՝ Կիսվեք, որ երբ պատճենում եք ֆունկցիայի հայտարարությունը, փոխեք "Վերադարձնում է HTML ..." տողը որպես "Նախնական թեմայի իրականացում ...":
jen: պատճենեք «Պարամետրերը» api.drupal.org-ից:
Ջեյմս Ուիլսոն՝ Հեռացրեք $ նշանը փոփոխականների անուններից, եթե ցանկանում եք խոսել նրանց մասին դոկբլոկում, օգտագործեք պարզապես եզակի նշաններ։ [Տես http://drupal.org/node/1804710 քննարկումը]
jen: Twig-ում տպեք փոփոխականները {{}} սինտաքսով:
jen: «attributes» դաշտերը հնարավորություն են տալիս ուղղակի հասանելի լինել class-ներին:
jen: url() ֆունկցիաներ մեծ մասը պետք է հեռացվեն տեմպլեյթից և ավելացվեն նախապատրաստման ֆունկցիայում։