Drupal मॉड्यूल की मूल संरचना

भाग II: Drupal 8 के बेसिक मॉड्यूल बनाने के लिए व्यावहारिक गाइड
.info से लेकर टेस्ट तक, केवल बुनियादी बातें

मूल संरचना

loremipsum.info.yml

name: Lorem ipsum
type: module
description: 'Lorem ipsum generator for Drupal'
package: Development
core: 8.x
configure: loremipsum.form

अब info-फ़ाइलें YML फॉर्मेट में होती हैं, और मॉड्यूल और थीम्स के बीच अंतर type घोषणा से स्पष्ट किया जाता है। config घोषणा एक रूट की ओर इशारा करती है (इस पर बाद में विस्तार से), लेकिन इसके अलावा इसमें कुछ और नहीं है। वास्तव में, यह आपके मॉड्यूल के लिए आवश्यक एकमात्र फ़ाइल है। इसे सेव करने के बाद (root/modules फ़ोल्डर में) आप अपने मॉड्यूल को /admin/modules पर सक्षम कर सकते हैं, बिना अपनी साइट को तोड़े। लेकिन, जैसा कि आप आगे देखेंगे, यह पर्याप्त नहीं है।

loremipsum.module

<?php

use Drupal\Core\Routing\RouteMatchInterface;

/**
 * Implements hook_help().
 */
function loremipsum_help($route_name, RouteMatchInterface $route_match) {
  switch ($route_name) {
    case 'help.page.loremipsum':
      return t('
        <h2>Lorem ipsum generator for Drupal.</h2>
        <h3>Instructions</h3>
        <p>Lorem ipsum dolor sit amet... <strong>Just kidding!</strong></p>
        <p>Unpack in the <em>modules</em> folder (currently in the root of your Drupal 8 installation) and enable in <strong>/admin/modules</strong>.</p>
        <p>Then, visit <strong>/admin/config/development/loremipsum</strong> and enter your own set of phrases to build random-generated text (or go with the default Lorem ipsum).</p>
        <p>Last, visit <strong>www.example.com/loremipsum/generate/P/S</strong> where:</p>
        <ul>
          <li><em>P</em> is the number of <em>paragraphs</em></li>
          <li><em>S</em> is the maximum number of <em>sentences</em></li>
        </ul>
        <p>There is also a generator block in which you can choose how many paragraphs and
phrases and it\'ll do the rest.</p>
        <p>If you need, there\'s also a specific <em>generate lorem ipsum</em> permission.</p>
        <h3>Attention</h3>
        <p>Most bugs have been ironed out, holes covered, features added. But this module is a work in progress. Please report bugs and suggestions, ok?</p>
      ');
  }
}

यहाँ कम-से-कम hook_help() रखना अच्छा अभ्यास है। साथ ही ध्यान दें कि यहाँ use स्टेटमेंट क्लास RouteMatchInterface की ओर इशारा कर रहा है। ऐसा इसलिए है क्योंकि अब hook_menu() मौजूद नहीं है।

... और जैसे-जैसे आप आगे बढ़ेंगे, आप देखेंगे कि .module फ़ाइल का इस्तेमाल थीम-संबंधी जानकारी स्टोर करने के लिए भी किया जाता है। इसलिए इसे संभालकर रखें।

loremipsum.install

<?php

/**
 * @file
 * Installation functions for Lorem ipsum module.
 */

use Drupal\user\RoleInterface;

/**
 * Implements 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: 'Generate 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 settings'
  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 settings'
  description: 'Configure settings for the Lorem Ipsum module.'
  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 इंस्टॉलेशन की रूट में है) में अनपैक करें और /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 settings'
  mapping:
    loremipsum:
      type: mapping
      mapping:
        page_title:
          type: text
          label: 'Lorem ipsum generator page title:'
        source_text:
          type: text
          label: 'Source text for lorem ipsum generation:'
block.settings.loremipsum_block:
  type: block_settings
  label: 'Lorem ipsum block'
  mapping:
    loremipsum_block_settings:
      type: text
      label: 'Lorem ipsum block settings'

स्कीमा फ़ाइल का उपयोग तब भी होता है, जब आप अपने मॉड्यूल के लिए कस्टम टेबल परिभाषित नहीं कर रहे हों। यहाँ आप देख सकते हैं कि डिफ़ॉल्ट मान कैसे कॉन्फ़िगरेशन फ़ॉर्म फ़ील्ड्स को असाइन किए जाते हैं।

इस कोड को विकसित करते समय मुझे लगा कि "बॉक्स से बाहर" फ़ील्ड्स को पॉप्युलेट करना सबसे कठिन कार्यों में से एक था। लेकिन सौभाग्य से, इसके लिए एक मॉड्यूल है: Drupal 8 के लिए Config Inspector, जो आपको डिफ़ॉल्ट सेटिंग्स को डिबग करने में मदद करेगा।

इसके अलावा, YML स्कीमा फ़ाइल कई मायनों में बहुत उपयोगी है। अधिक पढ़ें।

/src/Controller/LoremIpsumController.php

<?php

namespace Drupal\loremipsum\Controller;

use Drupal\Component\Utility\Html;

/**
 * Controller routines for Lorem ipsum pages.
 */
class LoremIpsumController {

  /**
   * Constructs Lorem ipsum text with arguments.
   * This callback is mapped to the path
   * 'loremipsum/generate/{paragraphs}/{phrases}'.
   * 
   * @param string $paragraphs
   *   The amount of paragraphs that need to be generated.
   * @param string $phrases
   *   The maximum amount of phrases that can be generated inside a paragraph.
   */
  public function generate($paragraphs, $phrases) {

अब हम इस मॉड्यूल के मुख्य भाग पर पहुँचे हैं — एक क्लास जिसमें एक ही मेथड है, जो प्लेसहोल्डर टेक्स्ट जेनरेट करता है। जैसा कि आप देख सकते हैं, LoremIpsumController क्लास का मेथड YAML रूटिंग फ़ाइल में एंट्री से जुड़ा है:

सफेद बॉक्स में loremipsum.routing.yml फ़ाइल का कोड दिखाया गया है, और बैकग्राउंड में वह फ़ाइल है जिस पर हम काम कर रहे हैं।

अब आगे बढ़ते हैं, अगला कोड स्निपेट मॉड्यूल की सेटिंग्स प्राप्त करता है और उन्हें आगे उपयोग के लिए सेव करता है:

    // Default settings.
    $config = \Drupal::config('loremipsum.settings');
    // Page title and source text.
    $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();

    // Generate X paragraphs with up to Y phrases each.
    for ($i = 1; $i <= $paragraphs; $i++) {
      $this_paragraph = '';
      $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'][] = Html::escape($this_paragraph);
    }

ध्यान दें कि ['#source_text'] एक रेंडर ऐरे है जिसे टेम्पलेट में पास किया जाता है, और इस ऐरे के हर एलिमेंट को सुरक्षा के लिए Html::escape() से गुजारा जाता है।

अंत में, हम अपने रेंडर ऐरे को एक शीर्षक देते हैं, थीम फ़ंक्शन असाइन करते हैं और उसे रिटर्न करते हैं:

    $element['#title'] = Html::escape($page_title);
     
    // Theme function.
    $element['#theme'] = 'loremipsum';
    
    return $element;
  }

}

लेकिन इस वेरिएबल को टेम्पलेट में पास करने से पहले, हमें उसके लिए आवश्यक सेटअप करना होगा।

अगला कदम;

थीमिंग मॉड्यूल।

इसके बाद:

सेटिंग्स फ़ॉर्म जोड़ना

इस मॉड्यूल के लिए ब्लॉक परिभाषित करना

इस मॉड्यूल के लिए टेस्ट लिखना