Շրջանցում՝ հարմարեցված դաշտի ստեղծումը

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

Drupal 7-ում մոդուլը թույլ է տալիս պահպանել կոդի օրինակներ/հատվածներ դաշտում։ Այն գալիս է «Հատվածների դաշտ» անվամբ հարմարեցված դաշտով և ցուցադրում է ձևի երեք տարր՝ նկարագրություն, աղբյուրային կոդ և սինտաքսի հույստավորում (թե որ ծրագրավորման լեզու է)։

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

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

Փոխարենը կավելացնեմ հղումներ այլ կայքերի, որոնք այս գաղափարը ավելի մանրամասն բացատրում են։

Այդուհանդերձ, եթե փնտրում եք մանրամասն փաստաթղթեր Drupal 8-ի Field API-ի մասին, ծանոթացեք հետևյալ շարքին՝

• Drupal 8 Field API, 1-ին մաս՝ դաշտի ձևաչափավորիչներ
• Drupal 8 Field API շարքի 2-րդ մասը՝ դաշտի վիջեթներ

 

Drupal 8-ում դաշտերը չեն իրականացվում hook-երի միջոցով, ինչպես Drupal 7-ում։ Փոխարենը դրանք ստեղծվում են օգտագործելով նոր Drupal 8 API պլագինները։ Դա նշանակում է, որ hook-երի փոխարեն մենք սահմանում ենք դասեր վիջեթների, ձևաչափավորիչների և դաշտի տարրերի համար։ Շատ 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
 * Բարեհաճում է \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;

Հետո ֆայլին ավելացնում ենք անվան տարածություն Drupal\snippets\Plugin\Field\FieldType և երեք օգտագործման օպերատորներ՝ 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("Հատվածների դաշտ"),
 *   description = @Translation("Այս դաշտը պահպանում է կոդի հատվածները տվյալների բազայում։"),
 *   default_widget = "snippets_default",
 *   default_formatter = "snippets_default"
 * )
 */
class SnippetsItem extends FieldItemBase { }

Այսպիսով, hook_field_info-ի փոխարեն մենք դաշտը սահմանում ենք որպես անշանագրում (annotation)՝ դասի վերևում մեկնաբանության ներսում։

Անշանագրումների հատկությունները բացատրության չեն կարում։ Պարզապես համոզվեք, որ default_widget և default_formatter հղվում են վիջեթի և ձևաչափավորիչի անշանագրումների ID-ներին, այլ ոչ թե դասերին։

Եթե ցանկանում եք ավելի շատ իմանալ անշանագրումների մասին, այցելեք անշանագրումներով պլագինների փաստաթղթերի էջը drupal.org-ում։

3. Հիմա, երբ ունենք դաշտի տարրերի դասը, անհրաժեշտ է սահմանել մի քանի մեթոդներ։ Առաջին հերթին նայենք schema() մեթոդին։

Drupal 7-ում հարմարեցված դաշտ ստեղծելիս դուք սահմանում էիք schema-ը hook_field_schema-ով։ Drupal 8-ում schema-ն սահմանվում է ավելացնելով schema() մեթոդը SnippetsItem դասում։

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

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

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

/**
 * {@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('Հատվածի նկարագրություն'));

    $properties['source_code'] = DataDefinition::create('string')
      ->setLabel(t('Հատվածի կոդ'));

    $properties['source_lang'] = DataDefinition::create('string')
      ->setLabel(t('Ծրագրավորման լեզու'))
      ->setDescription(t('Հատվածի կոդի լեզու'));

    return $properties;
  }

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

Մանրամասներ իմանալու համար այցելեք Ինչպես Entity API-ն իրականացնում է Typed Data API փաստաթուղթը drupal.org-ում։

Սեղմեք այստեղ ամբողջ ֆայլը տեսնելու համար։ Հիշեցում՝ այն պետք է թարմացվի PSR-4 ստանդարտին համապատասխան, ավելի մանրամասն տեղեկությունների համար տեսեք Https://www.drupal.org/node/2128865.

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

Հիմա, երբ սահմանել ենք դաշտի տարրը, ստեղծենք դաշտի վիջեթը։ Պետք է ստեղծենք SnippetsDefaultWidget դասը, որը ընդլայնում է WidgetBase դասը։

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

/**
 * @file
 * Բարեհաճում է \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;

Հավաստիացեք, որ ֆայլի անվան տարածությունը Drupal\snippets\Plugin\Field\FieldWidget է և ավելացրեք հետևյալ երեք օգտագործման օպերատորները՝ 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("Դեֆոլտ հատվածներ"),
 *   field_types = {
 *     "snippets_code"
 *   }
 * )
 */
class SnippetsDefaultWidget extends WidgetBase { }

Պարզապես առաջ ծանուցեմ, որ համոզվեք, որ field_types հատկությունը անշանագրությունում հղվում է դաշտի տեսակների ID-ներին։ Այս մոդուլի համար դա snippets_code է, քանի որ մենք ավելացրել ենք id = "snippets_code" @FieldType անշանագրությունում։

3. Եվ վերջապես, մեզ պետք է սահմանենք վիջեթի իրական ձևը։ Դա անում ենք ավելացնելով formElement() մեթոդը SnippetsDefaultWidget դասում։ Այս մեթոդը համարժեք է Drupal 7-ում hook_field_widget_form-ի օգտագործմանը։

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

  $element['source_description'] = array(
        '#title' => $this->t('Նկարագրություն'),
        '#type' => 'textfield',
        '#default_value' => isset($items[$delta]->source_description) ? $items[$delta]->source_description : NULL,
      );
  $element['source_code'] = array(
        '#title' => $this->t('Կոդ'),
        '#type' => 'textarea',
        '#default_value' => isset($items[$delta]->source_code) ? $items[$delta]->source_code : NULL,
      );
  $element['source_lang'] = array(
        '#title' => $this->t('Աղբյուրի լեզու'),
        '#type' => 'textfield',
        '#default_value' => isset($items[$delta]->source_lang) ? $items[$delta]->source_lang : NULL,
      );
  return $element;
}

Սեղմեք այստեղ ամբողջ ֆայլը տեսնելու համար։ Հիշեցում՝ այն պետք է թարմացվի PSR-4 ստանդարտին համապատասխան, ավելի մանրամասն տեղեկությունների համար տեսեք Https://www.drupal.org/node/2128865.

Քայլ 3։ Դաշտի ձևաչափավորիչի իրականացում

Վերջին կտորը հանելուկի՝ դաշտի ձևաչափավորիչն է, որը ստեղծում ենք սահմանելով SnippetsDefaultFormatter դասը, որը ընդլայնում է FormatterBase դասը։

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

/**
 * @file
 * Բարեհաճում է \Drupal\snippets\Plugin\field\formatter\SnippetsDefaultFormatter։
 */

namespace Drupal\snippets\Plugin\Field\FieldFormatter;

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

Հավաստիացեք, որ ֆայլի անվան տարածությունը Drupal\snippets\Plugin\Field\FieldFormatter է և ավելացրեք հետևյալ օգտագործման օպերատորները՝ Drupal\Core\Field\FieldItemListInterface և Drupal\Core\Field\FormatterBase։

2. Հաջորդը պետք է սահմանենք ձևաչափավորիչը որպես անշանագրում։ Նույնպես ինչպես վիջեթի և դաշտի տեսակի դեպքում, սա համարժեք է Drupal 7-ում hook_field_formatter_info-ի օգտագործմանը։

/**
 * Plugin implementation of the 'snippets_default' formatter.
 *
 * @FieldFormatter(
 *   id = "snippets_default",
 *   label = @Translation("Դեֆոլտ հատվածներ"),
 *   field_types = {
 *     "snippets_code"
 *   }
 * )
 */
class SnippetsDefaultFormatter extends FormatterBase { }

3. Այժմ մնում է միայն ավելացնել viewElements() մեթոդը և սահմանել դաշտի իրական ձևաչափավորիչը։ Այս մեթոդը կրկին նման է Drupal 7-ի hook_field_formatter_view օգտագործմանը։

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

  return $elements;
}

Ուշադրության արժանի է, որ ես օգտագործում եմ կাস্টոմ ձևանմուշ snippets_default՝ հատվածների արտածման համար նախքան դրանք դաշտի ձևաչափավորիչով ցուցադրվելը։

Արդյունքը նրանում է, որ ես չէի ուզում շատ լոգիկա կամ HTML կոդ տեղադրել viewElements() մեթոդում։

Սեղմեք այստեղ ամբողջ ֆայլը տեսնելու համար։ Հիշեցում՝ այն պետք է թարմացվի PSR-4 ստանդարտին համապատասխան, ավելի մանրամասն տեղեկությունների համար տեսեք Https://www.drupal.org/node/2128865.

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

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

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