Drupal մոդուլի հիմնական կառուցվածքը

Բաժին II՝ գործնական ուղեցույց Drupal 8-ի հիմնական մոդուլներ ստեղծելու համար
.info-ից մինչև թեստեր, միայն հիմունքներ

Հիմնական կառուցվածք

loremipsum.info.yml

name: Lorem ipsum
type: module
description: 'Lorem ipsum գեներատոր Drupal-ի համար'
package: Development
core: 8.x
configure: loremipsum.form

Info ֆայլերը այժմ ձևաչափված են YML ձևաչափով, և կա տարբերություն մոդուլների և թեմաների միջև, որը պետք է հասկանալի լինի type-ի հայտարարության միջոցով։ configure-ը ցույց է տալիս երթուղին (այս մասին ավելի ուշ), բայց դրանից բացի ուրիշ ոչինչ չկա։ Իրականում սա միակ ֆայլն է, որ ձեզ անհրաժեշտ կլինի ձեր մոդուլի համար։ Պահպանելուց հետո (root/modules թղթապանակում) կարող եք միացնել ձեր մոդուլը /admin/modules-ում առանց ձեր կայքը վնասելու։ Բայց ինչպես կտեսնեք առաջ, սա բավարար չէ։

loremipsum.module

<?php

use Drupal\Core\Routing\RouteMatchInterface;

/**
 * Իրականացնում է hook_help().
 */
function loremipsum_help($route_name, RouteMatchInterface $route_match) {
  switch ($route_name) {
    case 'help.page.loremipsum':
      return t('
        <h2>Lorem ipsum գեներատոր Drupal-ի համար։</h2>
        <h3>Ներդրման հրահանգներ</h3>
        <p>Lorem ipsum dolor sit amet... <strong>Ո՛չ, պարզապես կատակ է։</strong></p>
        <p>Փաթեթավորեք <em>modules</em> թղթապանակում (այժմ Drupal 8-ի root-ում) և միացրեք <strong>/admin/modules</strong>-ում։</p>
        <p>Այնուհետև այցելեք <strong>/admin/config/development/loremipsum</strong> և մուտքագրեք ձեր նախընտրած արտահայտությունները պատահական տեքստ ստեղծելու համար (կամ օգտագործեք ստանդարտ Lorem ipsum-ը):</p>
        <p>Վերջապես այցելեք <strong>www.example.com/loremipsum/generate/P/S</strong>, որտեղ՝</p>
        <ul>
          <li><em>P</em>՝ պարբերությունների քանակը</li>
          <li><em>S</em>՝ առավելագույն նախադասությունների քանակը պարբերության մեջ</li>
        </ul>
        <p>Գեներատորի բլոկ կա, որտեղ կարող եք ընտրել պարբերությունների և արտահայտությունների քանակը, և այն կկատարի մնացածը։</p>
        <p>Եթե անհրաժեշտ է, կա նաև հատուկ թույլտվություն՝ <em>generate lorem ipsum</em>։</p>
        <h3>Ուշադրություն</h3>
        <p>Բազմաթիվ սխալներ շտկված են, թերությունները փակված են, ավելացվել են նոր ֆունկցիաներ։ Սակայն այս մոդուլը դեռ աշխատանք է կատարվում։ Խնդրում ենք հաղորդել սխալների և առաջարկությունների մասին։</p>
      ');
  }
}

Լավ պրակտիկա է այստեղ գոնե ունենալ hook_help()-ի ի հայտ գալը։ Նշենք նաև օգտագործման օպերատորը, որը ցույց է տալիս RouteMatchInterface դասը։ Դա հիմնականում այն պատճառով է, որ hook_menu() այլևս չկա։

... Եվ ինչպես կշարունակենք, դուք կտեսնեք, որ .module ֆայլը օգտագործվում է նաև թեմատիկ տեղեկություններ պահելու համար։ Դրա մասին հիշեք։

loremipsum.install

<?php

/**
 * @file
 * Lorem ipsum մոդուլի տեղադրման ֆունկցիաներ։
 */

use Drupal\user\RoleInterface;

/**
 * Իրականացնում է hook_install().
 */
function loremipsum_install() {
  user_role_change_permissions(RoleInterface::ANONYMOUS_ID, array(
    'generate lorem ipsum' => TRUE,
  ));
}

Այստեղ օգտագործվում է RoleInterface դասը։ Իրականում այս ֆայլը Drupal-ին ասում է՝ «երբ այս մոդուլը միացված է, գտիր 'generate lorem ipsum' թույլտվությունը և միացրու այն»։

Բայց որտեղ է սահմանված այդ թույլտվությունը?

loremipsum.permissions.yml

generate lorem ipsum:
  title: 'Ստեղծել Lorem ipsum'

Ինչպես տեսնում եք, սա շատ ավելի պարզ է, քան hook_permission()-ը։ Լրիվ սինտաքսը գտնվում է PermissionHandler փաստաթղթում։

loremipsum.routing.yml

loremipsum.generate:
  path: '/loremipsum/generate/{paragraphs}/{phrases}'
  defaults:
    _controller: '\Drupal\loremipsum\Controller\LoremIpsumController::generate'
  requirements:
    _permission: 'generate lorem ipsum'

loremipsum.form:
  path: '/admin/config/development/loremipsum'
  defaults:
    _form: '\Drupal\loremipsum\Form\LoremIpsumForm'
    _title: 'Lorem ipsum կարգավորումներ'
  requirements:
    _permission: 'administer site configuration'

Երթուղավորման ֆայլը փոխարինում է hook_menu()-ի կանչը։ Ամեն գրառում (առանց ներդրման) ցույց է տալիս երթուղի, իսկ հաջորդ տողերը՝ դրա կոնկրետ կարգավորումները։

loremipsum.generate երթուղին ցույց է տալիս էջ, որը ստանում է երկու արգումենտ՝ {}-երի մեջ․ այն կապվում է կոնտրոլերի հետ (այս մասին ավելի ուշ), մինչդեռ loremipsum.form-ը ցույց է տալիս (կարգավորումների) ֆորմա վերնագրով։

Որոշում են պահանջվող թույլտվությունները, բայց դրանք կարող եք փոխարինել _access: 'TRUE'-ով անվերջ մուտքի համար։

loremipsum.services.yml

Թույլ է տալիս հայտարարել հարմարեցված ծառայություն։

loremipsum.links.menu.yml

loremipsum.form:
  title: 'Lorem Ipsum կարգավորումներ'
  description: 'Կարգավորեք Lorem Ipsum մոդուլի պարամետրերը։'
  route_name: loremipsum.form
  parent: 'system.admin_config_development'

Երթուղավորման ֆայլը ստեղծում է էջ /admin/config/development/loremipsum հասցեում, իսկ այս սահմանումները անհրաժեշտ են հավելվածը մուտքագրելու համար վարչական մենյուում։

loremipsum.links.task.yml

Սահմանումներ լրացուցիչ տեղական առաջադրանքների (բացառիկ ներդիրների) ստեղծման համար տվյալ երթուղու համար։

loremipsum.links.action.yml

Սահմանումներ լրացուցիչ տեղական գործողությունների (կոճակների) ստեղծման համար տվյալ երթուղու համար։

loremipsum.links.contextual.yml

Սահմանումներ լրացուցիչ համատեքստային գործողությունների ստեղծման համար UI որոշ տարրի համար։

loremipsum.libraries.yml

Օգտագործվում է CSS և Javascript գրադարանների կախվածությունների գրանցման համար։ Մանրամասները՝ համապատասխան բաժնում։

README.md

Փաթեթավորեք *modules* թղթապանակում (այժմ գտնվում է Drupal 8-ի root-ում) և միացրեք /admin/modules-ում։

Այնուհետև մուտք գործեք /admin/config/development/loremipsum և մուտքագրեք ձեր նախընտրած արտահայտությունները պատահական տեքստի համար (կամ օգտագործեք կանխորոշված Lorem ipsum-ը)։

Վերջապես այցելեք www.example.com/loremipsum/generate/P/S, որտեղ՝
- *P* - պարբերությունների քանակը
- *S* - առավելագույն նախադասությունների քանակը

Գործարկիչ բլոկ կա, որտեղ կարող եք ընտրել պարբերությունների և արտահայտությունների քանակը, և այն կկատարի մնացածը։

Եթե անհրաժեշտ է, կա նաև հատուկ թույլտվություն՝ *generate lorem ipsum*։

Ուշադրություն
---------

Շատ սխալներ ուղղվել են, թերությունները փակվել են, ավելացվել են նոր ֆունկցիաներ։ Բայց այս մոդուլը դեռ աշխատանք է։ Խնդրում ենք հաղորդել սխալների և առաջարկությունների մասին։

Այո, README ֆայլերը այժմ գրանցվում են markdown ձևաչափով։ Հիանալի է, եթե ինձ հարցնեք։

Հիմա եկեք անցնենք թղթապանակներին՝ մանրամասն ուսումնասիրելու համար կոնկրետ մանրամասները։

LICENSE.TXT

Մի ներառեք LICENSE.txt (կամ նման ֆայլ)։ Պարկավորող սցրիպտը կավելացնի այն։

/config/install/loremipsum.settings.yml

loremipsum:
   page_title: 'Lorem ipsum'
   source_text: "Lorem ipsum dolor sit amet, consitteur adipisci elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua". ...

Այս ֆայլում պահվում են կանխադրված կարգավորումները, որոնք նշանակվում են համապատասխան դաշտերին հաջորդ ֆայլի միջոցով՝

loremipsum:
  page_title: 'Lorem ipsum'
  source_text: "Lorem ipsum dolor sit amet, consectetur adipisci elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. \nUt enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. \nDuis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. \nExcepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. "

Այս ֆայլում պահվում են կանխադրված կարգավորումները, որոնք նշանակվում են համապատասխան դաշտերին հաջորդ ֆայլի միջոցով՝

/config/schema/loremipsum.schema.yml

loremipsum.settings:
  type: config_object
  label: 'Lorem Ipsum կարգավորումներ'
  mapping:
    loremipsum:
      type: mapping
      mapping:
        page_title:
          type: text
          label: 'Lorem ipsum գեներատորի էջի վերնագիր՝'
        source_text:
          type: text
          label: 'Լորեմ իպսում գեներացման աղբյուրային տեքստ՝'
block.settings.loremipsum_block:
  type: block_settings
  label: 'Lorem ipsum բլոկ'
  mapping:
    loremipsum_block_settings:
      type: text
      label: 'Lorem ipsum բլոկի կարգավորումներ'

Սխեմայի ֆայլը օգտագործվում է նույնիսկ եթե դուք չեք սահմանում ձեր մոդուլի համար անհատական աղյուսակ - այստեղ տեսնում եք կանխադրված արժեքները, որոնք նշանակվում են կոնֆիգուրացիայի ֆորմայի դաշտերին։

Այս կոդի մշակման ընթացքում պարզեցի, որ դաշտերը «արկղից դուրս» լրացնելը ամենաբարդ խնդիրներից մեկն է։ Բայց բախտավորաբար կա մոդուլ՝ Drupal 8-ի կոնֆիգուրացիայի ինսպեկտոր, որը կօգնի ստուգել կանխադրված կարգավորումները։

Բացի այդ, YML սխեմայի ֆայլը շատ օգտակար է երկրաբանական տեսանկյունից։

/src/Controller/LoremIpsumController.php

<?php

namespace Drupal\loremipsum\Controller;

// Ընթացիկ փոփոխությունները https://www.drupal.org/node/2457593
// Տեղեկություններ մեթոդների հնացումների մասին՝ https://www.drupal.org/node/2549395
// use Drupal\Component\Utility\SafeMarkup;
use Drupal\Component\Utility\Html;
// օգտագործել Html փոխարեն SafeMarkup

/**
 * Lorem ipsum էջերի կոնտրոլեր։
 */
class LoremIpsumController {

  /**
   * Ստեղծում է Lorem ipsum տեքստ՝ արգումենտներով։
   * Այս կոլբեքը կապված է 'loremipsum/generate/{paragraphs}/{phrases}' երթուղու հետ։
   * 
   * @param string $paragraphs
   *   Պահանջվող պարբերությունների քանակը։
   * @param string $phrases
   *   Պարբերությունում առավելագույն արտահայտությունների քանակը։
   */
  public function generate($paragraphs, $phrases) {

Մենք հասել ենք մոդուլի սրտին՝ դասին մեկ մեթոդով, որը ստեղծում է տեքստ՝ որպես լրացում։ Ինչպես տեսնում եք, LoremIpsumController դասի ներսում գրված մեթոդը կապված է YML երթուղավորման ֆայլի գրառման հետ։

Սպիտակ շրջանակում ցուցադրված է loremipsum.routing.yml ֆայլի կոդը և ֆայլի ֆոնը, որի հետ աշխատում ենք։

Հետո շարունակենք՝ հաջորդ կոդի կտորն ստանում է մոդուլի կարգավորումները և պահում դրանք հետագա օգտագործման համար՝

    // Նախնական կարգավորումներ։
    $config = \Drupal::config('loremipsum.settings');
    // Էջի վերնագիր և աղբյուրային տեքստ։
    $page_title = $config->get('loremipsum.page_title');
    $source_text = $config->get('loremipsum.source_text');

Վերևում նշված պարամետրերը (loremipsum.page_title և loremipsum.source_text) վերցված են YAML կարգավորումների ֆայլից՝

Հետո $source_text-ից բաժանում ենք արտահայտությունները մեկ զանգվածի՝

$repertory = explode(PHP_EOL, $source_text);

Եվ օգտագործում ենք այդ զանգվածը տեքստային պարբերություններ կառուցելու համար՝

    $element['#source_text'] = array();

    // Ստեղծում է X պարբերություններ՝ ամեն մեկում մինչև Y արտահայտությամբ։
    for ($i = 1; $i = $paragraphs; $i++) {
      $this_paragraph = '';
      // Երբ ասում ենք «մինչև Y արտահայտություն», չենք նկատի «1-ից մինչև Y»։
      // Ուստի գնում ենք կեսից։
      $random_phrases = mt_rand(round($phrases / 2), $phrases);
      // Բացի այդ, չկրկնել վերջին արտահայտությունը։
      $last_number = 0;
      $next_number = 0;
      for ($j = 1; $j = $random_phrases; $j++) {
        do {
          $next_number = floor(mt_rand(0, count($repertory) - 1));
        } while ($next_number === $last_number && count($repertory) > 1);
        $this_paragraph .= $repertory[$next_number] . ' ';
        $last_number = $next_number;
      }
      //$element['#source_text'][] = SafeMarkup::checkPlain($this_paragraph);
        $element['#source_text'][] = Html::escape($this_paragraph);

    }

Նկատեք, որ ['#source_text'] հանդիսանում է ցուցադրման զանգված, որը փոխանցվում է կաղապարին, և որ զանգվածի յուրաքանչյուր տարր անցնում է Html::escape() անվտանգության համար։

Վերջապես, մենք մեր ցուցադրման զանգվածին տալիս ենք վերնագիր, նշանակում թեմայի ֆունկցիան և վերադարձնում այն՝

    //$element['#title'] = SafeMarkup::checkPlain($page_title);
    $element['#title'] = Html::escape($page_title);
     
    // Թեմայի ֆունկցիա։
    $element['#theme'] = 'loremipsum';
    
    return $element;
  }

}

Բայց մինչ այդ, նախ պետք է հոգ տանել դրանց մասին։

Հաջորդ քայլը՝

Մոդուլի թեմատիկացում։

Հետևյալը՝

Կարգավորման ձև ավելացնելը։

Մոդուլի բլոկի սահմանում։

Մոդուլի թեստեր գրել։