Կարճ ներկայացում՝ հարմարեցված դաշտի տիպի ստեղծում

Այս ձեռնարկը սկզբնապես հրապարակվել է Web Wash-ում։ Սակայն Berdir-ը հարցրեց, թե արդյոք կարող եմ տեղադրել ձեռնարկը այստեղ, ուստի այն հիմա այստեղ է։

Drupal 7-ում մոդուլը թույլ է տալիս դաշտում պահել կոդի օրինակներ/հատվածներ։ Այն տրամադրում է հարմարեցված դաշտ, որը կոչվում է «Կոդի հատվածների դաշտ» և ցուցադրում է երեք ֆորմայի էլեմենտ՝ նկարագրություն, աղբյուրային կոդ և սինտաքսի ընդգծման ռեժիմ (программային լեզու)։

Հիմա ժամանակն է մոդուլը թարմացնել Drupal 8-ի համար։

Այս դասընթացում ես ցույց կտամ, թե ինչպես ստեղծել «հիմնական» հարմարեցված դաշտ Drupal 8-ում։ Ես չեմ խորանա PSR-4, անոտացիաներ կամ plugin-ներ թեմաներին, որպեսզի ձեռնարկը շատ մեծ չլինի։

Մյուս կողմից, կտեղադրեմ հղումներ այլ կայքերի, որոնք ավելի լավ բացատրում են այս հասկացությունները։

Եթե ցանկանում եք մանրամասն տեղեկություններ Drupal 8-ի Field API-ի մասին, ուսումնասիրեք հետևյալ շարքերը․

• Drupal 8 Field API, մաս 1՝ դաշտի ֆորմատորներ
• Drupal 8 Field API, մաս 2՝ դաշտի վիջեթներ

Drupal 8-ում դաշտերը չեն իրականացվում hook-երի միջոցով, ինչպես Drupal 7-ում։ Հաշվի առնելով նոր Drupal 8 plugin API-ն՝ դաշտերը ստեղծվում են տեսակների միջոցով՝ դասերի միջոցով։ Շատ Drupal 7-ի hook-եր, ինչպիսիք են hook_field_schema, hook_field_is_empty և այլոք, այժմ դասերի մեթոդներ են։

Քայլ 1․ Դաշտի էլեմենտի իրականացում

Առաջին քայլը ` սահմանել դաշտի էլեմենտի դասը՝ SnippetsItem, որը ժառանգում է FieldItemBase դասը։

1. Drupal 8-ում դասերը լիցքավորվում են PSR-4 ստանդարտով։

Ուստի, SnippetsItem դասը սահմանելու համար պետք է ստեղծել ֆայլ՝ SnippetsItem.php և տեղադրել այն մոդուլի /src/Plugin/Field/FieldType/ SnippetsItem.php հասցեում։

/**
 * @file
 * Contains \Drupal\snippets\Plugin\Field\FieldType\SnippetsItem.
 */

namespace Drupal\snippets\Plugin\Field\FieldType;

use Drupal\Core\Field\FieldItemBase;
use Drupal\Core\Field\FieldStorageDefinitionInterface;
use Drupal\Core\TypedData\DataDefinition;

Ֆայլում մենք ավելացնում ենք namespaces Drupal\snippets\Plugin\Field\FieldType և օգտագործում ենք երեք class-եր՝

• Drupal\Core\Field\FieldItemBase,
• Drupal\Core\Field\FieldStorageDefinitionInterface,
• Drupal\Core\TypedData\DataDefinition։

2. Հիմա պետք է սահմանենք դաշտի մանրամասները՝ ID, լեյբլ, լռելյայն վիջեթ, ֆորմատոր և այլն, ինչը համարժեք է Drupal 7-ի hook_field_info իրականացման։

Drupal 8-ում այդպիսի շատ hook-եր փոխարինվել են անոտացիաներով։

/**
 * Plugin implementation of the 'snippets' field type.
 *
 * @FieldType(
 *   id = "snippets_code",
 *   label = @Translation("Snippets field"),
 *   description = @Translation("This field stores code snippets in the database."),
 *   default_widget = "snippets_default",
 *   default_formatter = "snippets_default"
 * )
 */
class SnippetsItem extends FieldItemBase { }

Այստեղ դաշտը սահմանվում է անոտացիայի միջոցով դասի վերևում, այլ ոչ թե hook-ով։

Դուք պետք է ուշադիր լինեք, որ default_widget և default_formatter արժեքները համապատասխանեն վիջեթի և ֆորմատորի անոտացիաների ID-ներին, ոչ թե դասերին։

Մանրամասն տեղեկությունների համար դիտեք plugin-ների վրա հիմնված անոտացիաների փաստաթղթավորումը drupal.org-ում։

3. Քանի որ ունենք դաշտի էլեմենտի դաս, պետք է ավելացնել որոշ մեթոդներ։ Առաջին հերթին schema() մեթոդը։

Drupal 7-ում հարմարեցված դաշտի ստեղծման ժամանակ դուք օգտագործում էիք hook_field_schema։ Drupal 8-ում schema-ն սահմանվում է դասի մեջ՝ schema() մեթոդով։

Schema API-ի փաստաթղթավորում պարունակում է սքիմայի զանգվածի կառուցվածքի և արժեքների նկարագրությունը։

/**
 * {@inheritdoc}
 */
public static function schema(FieldStorageDefinitionInterface $field) {
  return [
    'columns' => [
      'source_description' => [
        'type' => 'varchar',
        'length' => 256,
        'not null' => FALSE,
      ],
      'source_code' => [
        'type' => 'text',
        'size' => 'big',
        'not null' => FALSE,
      ],
      'source_lang' => [
        'type' => 'varchar',
        'length' => 256,
        'not null' => FALSE,
      ],
    ],
  ];
}

4. Հավելենք isEmpty() մեթոդը, որը կասի, թե երբ դաշտը դատարկ է, նման hook_field_is_empty-ին Drupal 7-ում։

/**
 * {@inheritdoc}
 */
public function isEmpty() {
  $value = $this->get('source_code')->getValue();
  return $value === NULL || $value === '';
}

5. Վերջապես, ավելացնում ենք propertyDefinitions() մեթոդը՝ դաշտի արժեքների տիպերը հայտնելու համար։

/**
 * {@inheritdoc}
 */
static $propertyDefinitions;

/**
 * {@inheritdoc}
 */
public static function propertyDefinitions(FieldStorageDefinitionInterface $field_definition) {
    $properties['source_description'] = DataDefinition::create('string')
      ->setLabel(t('Snippet description'));

    $properties['source_code'] = DataDefinition::create('string')
      ->setLabel(t('Snippet code'));

    $properties['source_lang'] = DataDefinition::create('string')
      ->setLabel(t('Programming Language'))
      ->setDescription(t('Snippet code language'));

    return $properties;
  }

Այս մեթոդը սահմանում է դաշտի արժեքների տիպերը։ «Կոդի հատվածների դաշտը» ունի երեք արժեք՝ նկարագրություն, կոդ և լեզու։ Ես դրանք ավելացրել եմ որպես տողեր։

Լրացուցիչ տեղեկությունների համար կարդացեք Entity API-ն և Typed Data API-ի փաստաթղթավորումը drupal.org-ում։

Սեղմեք այստեղ ամբողջ ֆայլը տեսնելու համար։ Հիշեք, որ պետք է թարմացնել PSR-4 ստանդարտին՝ ավելի շատ մանրամասների համար տես այստեղ։

Քայլ 2․ Դաշտի վիջեթի իրականացում

Երբ դաշտի էլեմենտը սահմանված է, եկեք ստեղծենք դաշտի վիջեթը։ Պետք է ստեղծենք դաս՝ SnippetsDefaultWidget, որը ժառանգում է WidgetBase դասը։

1. Ստեղծեք SnippetsDefaultWidget.php ֆայլը և տեղադրեք մոդուլի /src/Plugin/Field/FieldWidget/SnippetsDefaultWidget.php հասցեում։

/**
 * @file
 * Contains \Drupal\snippets\Plugin\Field\FieldWidget\SnippetsDefaultWidget.
 */

namespace Drupal\snippets\Plugin\Field\FieldWidget;

use Drupal\Core\Field\FieldItemListInterface;
use Drupal\Core\Field\WidgetBase;
use Drupal\Core\Form\FormStateInterface;

Հաստատեք, որ ֆայլի namespace-ը Drupal\snippets\Plugin\Field\FieldWidget է և ավելացրեք հետևյալ «use» օպերատորները․

• Drupal\Core\Field\FieldItemListInterface
• Drupal\Core\Field\WidgetBase
• Drupal\Core\Form\FormStateInterface

2. Սահմանեք վիջեթը անոտացիայով, որը համարժեք է Drupal 7-ի hook_field_widget_info-ին։

/**
 * Plugin implementation of the 'snippets_default' widget.
 *
 * @FieldWidget(
 *   id = "snippets_default",
 *   label = @Translation("Snippets default"),
 *   field_types = {
 *     "snippets_code"
 *   }
 * )
 */
class SnippetsDefaultWidget extends WidgetBase { }

Ուշադրություն դարձրեք, որ field_types արժեքը պետք է համապատասխանեցվի դաշտի տիպի ID-ին, այս դեպքում snippets_code, քանի որ այն սահմանված է FieldType անոտացիայում։

3. Այժմ պետք է ավելացնել formElement() մեթոդը՝ վիջեթի ֆորմայի էլեմենտները սահմանելու համար, որը համարժեք է Drupal 7-ի hook_field_widget_form-ին։

/**
 * {@inheritdoc}
 */
public function formElement(FieldItemListInterface $items, $delta, array $element, array &$form, FormStateInterface $form_state) {

  $element['source_description'] = [
        '#title' => $this->t('Description'),
        '#type' => 'textfield',
        '#default_value' => isset($items[$delta]->source_description) ? $items[$delta]->source_description : NULL,
      ];
  $element['source_code'] = [
        '#title' => $this->t('Code'),
        '#type' => 'textarea',
        '#default_value' => isset($items[$delta]->source_code) ? $items[$delta]->source_code : NULL,
      ];
  $element['source_lang'] = [
        '#title' => $this->t('Source language'),
        '#type' => 'textfield',
        '#default_value' => isset($items[$delta]->source_lang) ? $items[$delta]->source_lang : NULL,
      ];
  return $element;
}

Սեղմեք այստեղ ամբողջ ֆայլը տեսնելու համար։ Նշում՝ պետք է թարմացնել PSR-4 ստանդարտին, ավելին՝ այստեղ։

Քայլ 3․ Դաշտի ֆորմատորի իրականացում

Վերջին տարրը դաշտի ֆորմատորն է։ Ստեղծում ենք SnippetsDefaultFormatter դասը, որը ժառանգում է FormatterBase դասը։

1. Ստեղծեք SnippetsDefaultFormatter.php ֆայլը և տեղադրեք մոդուլի /src/Plugin/Field/FieldFormatter/SnippetsDefaultFormatter.php հասցեում։

/**
 * @file
 * Contains \Drupal\snippets\Plugin\field\formatter\SnippetsDefaultFormatter.
 */

namespace Drupal\snippets\Plugin\Field\FieldFormatter;

use Drupal\Core\Field\FormatterBase;
use Drupal\Core\Field\FieldItemListInterface;

Հաստատեք, որ ֆայլի namespace-ը Drupal\snippets\Plugin\Field\FieldFormatter է և ավելացրեք հետևյալ «use» օպերատորները՝ Drupal\Core\Field\FieldItemListInterface և Drupal\Core\Field\FormatterBase։

2. Սահմանեք ֆորմատորը որպես անոտացիա, որը համարժեք է վիջեթի և դաշտի տիպի անոտացիաներին։

/**
 * Plugin implementation of the 'snippets_default' formatter.
 *
 * @FieldFormatter(
 *   id = "snippets_default",
 *   label = @Translation("Snippets default"),
 *   field_types = {
 *     "snippets_code"
 *   }
 * )
 */
class SnippetsDefaultFormatter extends FormatterBase { }

3. Ավելացրեք viewElements() մեթոդը, որը սահմանում է դաշտի ֆորմատավորման իրական տրամադրման լոգիկան, նման Drupal 7-ի hook_field_formatter_view-ին։

/**
 * {@inheritdoc}
 */
public function viewElements(FieldItemListInterface $items, $langcode) {
  $elements = [];
  foreach ($items as $delta => $item) {
    // Կատարում ենք արտածում՝ օգտագործելով snippets_default թեման։
    $source = [
      '#theme' => 'snippets_default',
      '#source_description' => $item->source_description,
      '#source_code' => $item->source_code,
    ];
    
    $elements[$delta] = ['#markup' => drupal_render($source)];
  }

  return $elements;
}

Ուշադրություն դարձրեք, որ ես օգտագործում եմ հարմարեցված snippets_default թեման՝ կոդի հատվածների ցուցադրման համար, որպեսզի viewElements() մեթոդը չլցվի ավելորդ տրամաբանությամբ կամ HTML-ով։

Սեղմեք այստեղ ամբողջ ֆայլը տեսնելու համար։ Հիշեք, որ պետք է թարմացնել PSR-4 ստանդարտին՝ ավելի շատ տեղեկությունների համար տես այստեղ։

Եզրակացություն

Ինչպես նշվեց, Drupal 8-ում ամենամեծ փոփոխությունը դաշտերի ստեղծման մեջ այն է, որ դրանք իրականանում են plugin API-ների միջոցով, այլ ոչ թե hook-երով։ Երբ դուք հասկանում եք սա, դաշտի ստեղծման գաղափարը շատ նման է Drupal 7-ի hook-երին։ Շատ մեթոդներ Drupal 8-ում համապատասխանում են hook-երին Drupal 7-ում։

Եթե ցանկանում եք փորձարկել կոդի հատվածները, ներբեռնեք 8.x-dev տարբերակը և փորձեք։