ब्लॉक API

अवलोकन

Drupal 8 में ब्लॉक्स वास्तव में दो अलग-अलग API संरचनाओं से मिलकर बने होते हैं, ताकि वही उपयोगकर्ता इंटरफ़ेस बनाया जा सके जिसे Drupal ने पिछली आवृत्तियों में समर्थन दिया था। ये दो API हैं Block Plugin API, जो एक स्वतंत्र पुन: प्रयोज्य API है, और Block Entity API, जो Drupal 8 में ब्लॉक्स रखने और उनकी दृश्यता को नियंत्रित करने के लिए एक विशिष्ट उपयोग का मामला है।

Block Plugin API ब्लॉक बनाना

आपके मॉड्यूल के कोड में परिभाषित ब्लॉक्स बनाने के लिए, प्लगइन API को सीखना और समझना आवश्यक है और विशेष रूप से एनोटेशन-आधारित प्लगइन्स की खोज, जो एक मैकेनिज्म है जिसका उपयोग Drupal 8 आपके ब्लॉक को परिभाषित करने वाले कोड को खोजने के लिए करता है।

आपके मॉड्यूल द्वारा परिभाषित एक कस्टम ब्लॉक बनाने में निम्नलिखित चरण शामिल होते हैं:

• एनोटेशन का उपयोग करके ब्लॉक प्लगइन बनाना
• Drupal\Core\Block\BlockBase क्लास को एक्सटेंड करना
• Drupal\Core\Block\BlockPluginInterface इंटरफ़ेस से आपके उपयोग के मामले के लिए आवश्यक विधियों को लागू करना

अपने ब्लॉक को Drupal और उपयोगकर्ताओं के लिए दृश्य बनाना

Drupal खोज के लिए PSR-4 मानक का उपयोग करता है। मान लेते हैं कि आपके मॉड्यूल का नाम fax है, तो आपके कस्टम ब्लॉक(स) का कोड fax/src/Plugin/Block/ में रखा जाना चाहिए। इस डायरेक्टरी में हर फ़ाइल का नाम उस क्लास के अनुसार होना चाहिए जिसे वह समाहित करती है। यदि हम FaxBlock क्लास परिभाषित करने जा रहे हैं, तो यह fax/src/Plugin/Block/FaxBlock.php नामक फ़ाइल में होना चाहिए और इसका कंटेंट निम्न उदाहरण के अनुसार होना चाहिए:

namespace Drupal\fax\Plugin\Block;

use Drupal\Core\Block\BlockBase;

/**
 * Provides a 'Fax' block.
 *
 * @Block(
 *   id = "fax_block",
 *   admin_label = @Translation("Fax block"),
 * )
 */
class FaxBlock extends BlockBase {
  // Override BlockPluginInterface methods here.
}

एनोटेशन में id प्रॉपर्टी आपके ब्लॉक के लिए एक यूनिक मशीन-पठनीय पहचानकर्ता और ब्लॉक का नाम निर्धारित करती है जो अन्य कोड से दिखाई देगा। 'admin_label' एनोटेशन एक मानव-पठनीय नाम निर्धारित करता है, जो आपके ब्लॉक को प्रशासनिक इंटरफ़ेस में प्रदर्शित करने के लिए उपयोग किया जाएगा। उपलब्ध एनोटेशन प्रॉपर्टीज़ को आप \Drupal\Core\Block\Annotation\Block (सार्वजनिक प्रॉपर्टीज़) में देख सकते हैं।

पुनः परिभाषित करने के लिए दो सबसे आम विधियाँ:

• BlockPluginInterface::build() – जिसे एक रेंडर ऐरे लौटाना चाहिए, जो उस कंटेंट को परिभाषित करता है जिसे आप अपने ब्लॉक में दिखाना चाहते हैं।
• BlockBase::access() – जो ब्लॉक की दृश्यता को नियंत्रित करता है। यह AccessResult ऑब्जेक्ट लौटाने की अपेक्षा करता है।

अपने ब्लॉक में कस्टम कॉन्फ़िगरेशन विकल्प जोड़ें

आप BlockPluginInterface::blockForm() और BlockPluginInterface::blockSubmit() मेथड्स को ओवरराइड करके ब्लॉक कॉन्फ़िगरेशन फ़ॉर्म में कस्टम कॉन्फ़िगरेशन विकल्प भी जोड़ सकते हैं, और फिर BlockBase::setConfigurationValue() और BlockBase::getConfiguration() का उपयोग कर सकते हैं।

निम्न उदाहरण में हम अपने blockForm() मेथड में एक नया टेक्स्ट फ़ील्ड जोड़ते हैं और फिर blockSubmit() मेथड में उपयोगकर्ता द्वारा दी गई जानकारी को सेव करते हैं। यह कोड दिखाता है कि कैसे वैल्यूज़ को प्राप्त, सत्यापित और अपडेट किया जा सकता है।

use Drupal\Core\Block\BlockBase;
use Drupal\Core\Block\BlockPluginInterface;
use Drupal\Core\Form\FormBuilderInterface;
use Drupal\Core\Form\FormStateInterface;
use Drupal\Core\Access\AccessResult;
use Drupal\Core\Cache\Cache;

/**
 * Provides a 'Fax' block.
 *
 * @Block(
 *   id = "fax_block",
 *   admin_label = @Translation("Fax block"),
 * )
 */
class FaxBlock extends BlockBase implements BlockPluginInterface {

  // Access method here ...

  /**
   * {@inheritdoc}
   */
  public function build() {
    $config = $this->getConfiguration();
    $fax_number = isset($config['fax_number']) ? $config['fax_number'] : '';
    return array(
      '#markup' => $this->t('The fax number is @number!', array('@number' => $fax_number)),
    );  
  }

  /**
   * {@inheritdoc}
   */
  public function blockForm($form, FormStateInterface $form_state) {
    $form = parent::blockForm($form, $form_state);

    // Retrieve existing configuration for this block.
    $config = $this->getConfiguration();

    // Add a form field to the existing block configuration form.
    $form['fax_number'] = array(
      '#type' => 'textfield',
      '#title' => t('Fax number'),
      '#default_value' => isset($config['fax_number']) ? $config['fax_number'] : '',
    );
    
    return $form;
  }

  /**
   * {@inheritdoc}
   */
  public function blockSubmit($form, FormStateInterface $form_state) {
    // Save our custom settings when the form is submitted.
    $this->setConfigurationValue('fax_number', $form_state->getValue('fax_number'));
  }

  /**
   * {@inheritdoc}
   */
  public function blockValidate($form, FormStateInterface $form_state) {
    $fax_number = $form_state->getValue('fax_number');

    if (!is_numeric($fax_number)) {
      $form_state->setErrorByName('fax_number', t('Needs to be an integer'));
    }
  }
}

आप build() मेथड में BlockBase::getConfiguration() मेथड का उपयोग करके कॉन्फ़िगरेशन डेटा प्राप्त कर सकते हैं और उन्हें अपने उपयोगकर्ताओं को दिखा सकते हैं। आपके ब्लॉक का access() मेथड भी अधिक जटिल लॉजिक शामिल कर सकता है, यह तय करने के लिए कि ब्लॉक प्रदर्शित होना चाहिए या नहीं।

Access कंडीशन मेथड का उदाहरण

/**
 * {@inheritdoc}
 */
public function access(AccountInterface $account, $return_as_object = FALSE) {
  return \Drupal\Core\Access\AccessResult::allowedIf($account->isAuthenticated());
}

आप अपनी खुद की कैशिंग कंडीशन भी बना सकते हैं।

कैश टैग्स का उपयोग करते हुए मेथड का उदाहरण। कैश टैग्स के बारे में और जानें।

/**
 * {@inheritdoc}
 */
public function getCacheTags() {
   return \Drupal\Core\Cache\Cache::mergeTags(parent::getCacheTags(), ['node_list']);
}

यदि आप ब्लॉक के कैश का अधिकतम समय 0 पर बदलना चाहते हैं। कैश max-age के बारे में और पढ़ें।

public function getCacheMaxAge() {
  // यदि आप इस ब्लॉक के लिए कैशिंग अक्षम करना चाहते हैं।
  return 0;
}