कस्टम टेंप्लेट बनाना

IDX में कई तरह के टेंप्लेट पहले से मौजूद होते हैं.इनमें सभी फ़ाइलें, सिस्टम पैकेज (जैसे, कंपाइलर) और एक्सटेंशन शामिल होते हैं. किसी भाषा या फ़्रेमवर्क का इस्तेमाल शुरू करने के लिए, किसी उपयोगकर्ता को इसकी ज़रूरत पड़ सकती है.

आप अपने खुद के ऐसे टेंप्लेट भी बना सकते हैं जिन्हें उपयोगकर्ता कॉन्फ़िगर कर सकते हैं. उदाहरण के लिए:

  • अगर आप अपना खुद का फ़्रेमवर्क, लाइब्रेरी या सेवा बना रहे हैं, तो आप अपने उपयोगकर्ताओं को ब्राउज़र को छोड़े बिना, क्लाउड-आधारित वर्चुअल मशीन की पूरी तरह से अपनी तकनीक का इस्तेमाल शुरू करने की अनुमति दे सकते हैं.

  • अगर आपके पास अपने प्रोजेक्ट के लिए पसंदीदा टेक्नोलॉजी स्टैक है, तो कस्टम टेंप्लेट की मदद से नए प्रोजेक्ट शुरू करने की प्रोसेस को आसान बनाया जा सकता है.

  • अगर कोडलैब की मदद से दूसरों को पढ़ा जा रहा है, तो कोडलैब के शुरुआती पॉइंट को कस्टम टेंप्लेट के तौर पर पहले से कॉन्फ़िगर करके, छात्र-छात्राओं के लिए कुछ शुरुआती चरणों को हटाया जा सकता है.

जब आपका कस्टम टेंप्लेट तैयार हो जाए, तो इसके लिए एक लिंक बनाएं, ताकि उसे अपनी वेबसाइट, Git रिपॉज़िटरी README फ़ाइल, पैकेज की जानकारी वाले पेज (जैसे कि NPM में) या ऐसी अन्य जगहों पर डाला जा सके जहां से उपयोगकर्ता आपकी टेक्नोलॉजी का इस्तेमाल शुरू करना चाहें.

ज़रूरी शर्तें

शुरू करने से पहले, पक्का करें कि आपको .idx/dev.nix फ़ाइलों की मदद से, अपने एनवायरमेंट को अपनी पसंद के मुताबिक बनाने के बारे में जानकारी हो.

टेंप्लेट में Nix लैंग्वेज का भी इस्तेमाल किया जाता है. इसलिए, हो सकता है कि आप कुछ बुनियादी चीज़ों को समझना चाहें या उन्हें रेफ़रंस के तौर पर आसान बनाना चाहें.

टेंप्लेट फ़ाइल का स्ट्रक्चर

टेंप्लेट, GitHub की सार्वजनिक रिपॉज़िटरी (या रिपॉज़िटरी में फ़ोल्डर या ब्रांच) होता है, जिसमें कम से कम दो फ़ाइलें होती हैं:

  • आपके टेंप्लेट से नया फ़ाइल फ़ोल्डर बनाने पर, उपयोगकर्ताओं को दिखने वाला डायलॉग
    कस्टम टेंप्लेट से नया फ़ाइल फ़ोल्डर बनाना

    idx-template.json में टेंप्लेट का मेटाडेटा शामिल होता है. इसमें उपयोगकर्ताओं को दिखने वाला नाम, ब्यौरा, और वे पैरामीटर शामिल होते हैं जो टेंप्लेट को कॉन्फ़िगर करने के लिए उपलब्ध होते हैं. उदाहरण के लिए, उपयोगकर्ताओं को कई प्रोग्रामिंग भाषाओं या इस्तेमाल के उदाहरणों में से चुनने की अनुमति दी जा सकती है. IDX इस जानकारी का इस्तेमाल, यूज़र इंटरफ़ेस (यूआई) को तैयार करने के लिए करता है. यह यूज़र इंटरफ़ेस (यूआई) तब दिखता है, जब वे आपके टेंप्लेट से कोई नया फ़ाइल फ़ोल्डर बनाने का विकल्प चुनते हैं.

  • idx-template.nix, Nix भाषा में लिखी गई फ़ाइल है. इसमें एक बैश शेल स्क्रिप्ट (निक्स फ़ंक्शन में रैप की गई) शामिल है, जो इन चीज़ों के लिए ज़िम्मेदार है:

    1. नए फ़ाइल फ़ोल्डर की काम करने वाली डायरेक्ट्री बनाना और
    2. .idx/dev.nix फ़ाइल बनाकर, इसका एनवायरमेंट सेट अप किया जा रहा है. ध्यान दें कि इस स्क्रिप्ट में, flutter create या npm init जैसे प्रोजेक्ट स्कैफ़ोल्डिंग टूल को भी चलाया जा सकता है या Go, Python, Node.js या किसी दूसरी भाषा में लिखी गई कस्टम स्क्रिप्ट को चलाया जा सकता है.

    टेंप्लेट को कॉन्फ़िगर करते समय, उपयोगकर्ता के तय किए गए पैरामीटर के हिसाब से इस फ़ाइल पर काम किया जाएगा.

टेंप्लेट को इंस्टैंशिएट करने के लिए, idx-template.nix में इस्तेमाल करने के लिए, इन दो फ़ाइलों के साथ अन्य फ़ाइलें भी शामिल की जा सकती हैं. उदाहरण के लिए, आखिरी .idx/dev.nix फ़ाइल को शामिल किया जा सकता है या डेटा स्टोर करने की जगह में मौजूद सभी मचान फ़ाइलों को भी शामिल किया जा सकता है.

बुनियादी उदाहरण: GitHub की सार्वजनिक रिपॉज़िटरी को टेंप्लेट में बदलना

अपने idx-template.json और idx-template.nix को तय करने के तरीके के बारे में ज़्यादा जानने से पहले, किसी सामान्य टेंप्लेट के उदाहरण को देख लें. इसमें:

  • इसमें उपयोगकर्ता द्वारा कॉन्फ़िगर किया जा सकने वाला कोई पैरामीटर नहीं है
  • बस, अपनी टेंप्लेट रिपॉज़िटरी (डेटा स्टोर करने की जगह) की सभी फ़ाइलों को उपयोगकर्ता के फ़ाइल फ़ोल्डर में कॉपी करें. इसमें, idx-template की दो फ़ाइलें शामिल नहीं हैं. इसमें पहले से एक .idx सब-फ़ोल्डर होना चाहिए, जिसमें एनवायरमेंट की जानकारी देने वाली dev.nix फ़ाइल मौजूद हो.

नीचे दी गई फ़ाइलों को किसी भी सार्वजनिक GitHub रिपॉज़िटरी (या सब-फ़ोल्डर या ब्रांच) में जोड़ने से, वह डेटा स्टोर करने की जगह असरदार तरीके से IDX टेंप्लेट में बदल जाती है.

idx-template.json

{
  "name": "Hello world",
  "description": "A template for a CLI program that prints 'hello world'",
  "icon": "https://www.gstatic.com/images/branding/productlogos/idx/v1/192px.svg",
  "params": []
}

idx-template.nix

# No user-configurable parameters
{ pkgs, ... }: {
  # Shell script that produces the final environment
  bootstrap = ''
    # Copy the folder containing the `idx-template` files to the final
    # project folder for the new workspace. ${./.} inserts the directory
    # of the checked-out Git folder containing this template.
    cp -rf ${./.} "$out"

    # Set some permissions
    chmod -R +w "$out"

    # Remove the template files themselves and any connection to the template's
    # Git repository
    rm -rf "$out/.git" "$out/idx-template".{nix,json}
  '';
}

अपनी bootstrap स्क्रिप्ट में अतिरिक्त सिस्टम पैकेज का इस्तेमाल करें

पिछले उदाहरण में, फ़ाइलों को सही जगह पर कॉपी करने के लिए, सिर्फ़ बुनियादी POSIX कमांड का इस्तेमाल किया गया है. आपके टेंप्लेट की bootstrap स्क्रिप्ट को इंस्टॉल करने के लिए, अतिरिक्त बाइनरी की ज़रूरत पड़ सकती है, जैसे कि git, node, python3 या कुछ अन्य.

अपनी idx-template.nix फ़ाइल में packages के बारे में बताकर, बूटस्ट्रैप स्क्रिप्ट के लिए अतिरिक्त सिस्टम पैकेज उपलब्ध कराए जा सकते हैं. यह ठीक वैसे ही होता है जैसे packages की dev.nix फ़ाइल में packages जोड़कर, किसी फ़ाइल फ़ोल्डर को अन्य सिस्टम पैकेज के साथ कस्टमाइज़ किया जाता है.

यहां pkgs.nodejs जोड़ने का एक उदाहरण दिया गया है, जिसमें node, npx, और npm जैसी बाइनरी शामिल हैं:

# idx-template.nix
{pkgs}: {
  packages = [
    # Enable "node", "npm" and "npx" in the bootstrap script below.
    # Note, this is NOT the list of packages available to the workspace once
    # it's created. Those go in .idx/dev.nix
    pkgs.nodejs
  ];

  bootstrap = ''
    mkdir "$out"
    # We can now use "npm"
    npm init --yes my-boot-strap@latest "$out"
  ''
}

उपयोगकर्ता को कॉन्फ़िगर किए जा सकने वाले पैरामीटर जोड़ें

उपयोगकर्ताओं को उनके नए प्रोजेक्ट के शुरुआती पॉइंट को पसंद के मुताबिक बनाने की अनुमति देने के लिए, कई टेंप्लेट बनाए जा सकते हैं या पैरामीटर वाला एक ही टेंप्लेट बनाया जा सकता है. अगर आपके अलग-अलग शुरुआती पॉइंट, सीएलआई टूल को अलग-अलग वैल्यू पास करते हैं (उदाहरण के लिए --language=js बनाम --language=ts), तो यह एक बेहतरीन विकल्प है.

पैरामीटर जोड़ने के लिए, आपको:

  1. अपनी idx-template.json मेटाडेटा फ़ाइल के params ऑब्जेक्ट में अपने पैरामीटर की जानकारी दें. IDX इस फ़ाइल में मौजूद जानकारी का इस्तेमाल करके, आपके टेंप्लेट का इस्तेमाल करने वाले उपयोगकर्ताओं को दिखने वाला यूज़र इंटरफ़ेस (यूआई) तैयार करता है. इस यूज़र इंटरफ़ेस (यूआई) में, चेकबॉक्स, ड्रॉप-डाउन, और टेक्स्ट फ़ील्ड शामिल होते हैं.
  2. टेंप्लेट को इंस्टैंशिएट करते समय, उपयोगकर्ता की चुनी गई वैल्यू का इस्तेमाल करने के लिए, अपने idx-template.nix बूटस्ट्रैप को अपडेट करें.

idx-template.json में अपने पैरामीटर की जानकारी दें

यहां enum पैरामीटर जोड़ने का एक उदाहरण दिया गया है. विकल्पों की संख्या के आधार पर, IDX, ड्रॉप-डाउन मेन्यू या रेडियो बटन ग्रुप के तौर पर दिखता है.:

{
  "name": "Hello world",
  "description": "A hello world app",
  "params": [
    {
      "id": "language",
      "name": "Programming Language",
      "type": "enum",
      "default": "ts",
      "options": {
        "js": "JavaScript",
        "ts": "TypeScript"
      },
      "required": true
    }
  ]
}

JavaScript और TypeScript की दो वैल्यू होने की वजह से, यूज़र इंटरफ़ेस (यूआई) इन दोनों विकल्पों के लिए एक रेडियो बटन ग्रुप रेंडर करेगा और idx-template.nix स्क्रिप्ट को ts या js वैल्यू पास करेगा.

हर पैरामीटर ऑब्जेक्ट में ये प्रॉपर्टी होती हैं:

प्रॉपर्टी वाई-फ़ाई के टाइप के बारे में जानकारी जानकारी
आईडी string पैरामीटर का यूनीक आईडी, वैरिएबल के नाम से मिलता-जुलता.
नाम string इस पैरामीटर का डिसप्ले नेम.
टाइप string

इस पैरामीटर के लिए इस्तेमाल किए जाने वाले यूज़र इंटरफ़ेस (यूआई) कॉम्पोनेंट के बारे में बताता है. साथ ही, बूटस्ट्रैप स्क्रिप्ट को पास करने के लिए डेटा टाइप के बारे में बताता है. मान्य मान हैं:

  • "enum" - यह एक ड्रॉप-डाउन या रेडियो बटन ग्रुप दिखाता है और बूटस्ट्रैप में string को पास करता है
  • "boolean" - चेकबॉक्स दिखाता है और true या false को पास करता है
  • "text" - टेक्स्ट फ़ील्ड दिखाता है और string पास करता है
विकल्प object enum पैरामीटर के लिए, यह उपयोगकर्ताओं को दिखाने के विकल्प दिखाता है. उदाहरण के लिए, अगर विकल्प {"js": "JavaScript", ...} है, तो "JavaScript" को विकल्प के तौर पर दिखाया जाएगा और चुने जाने पर, पैरामीटर की वैल्यू js होगी.
डिफ़ॉल्ट string या boolean यूज़र इंटरफ़ेस (यूआई) में शुरुआती वैल्यू सेट करता है. enum पैरामीटर के लिए, यह options की कुंजियों में से एक होनी चाहिए. boolean पैरामीटर के लिए, यह true या false होना चाहिए.
ज़रूरी है boolean इससे पता चलता है कि यह पैरामीटर ज़रूरी है.

idx-template.nix में पैरामीटर वैल्यू का इस्तेमाल करें

अपनी idx-template.json फ़ाइल में params ऑब्जेक्ट की जानकारी देने के बाद, उपयोगकर्ता की चुनी गई पैरामीटर वैल्यू के आधार पर बूटस्ट्रैप स्क्रिप्ट को पसंद के मुताबिक बनाया जा सकता है.

पिछले सेक्शन में दिए गए उदाहरण के मुताबिक, अगर आपके पास language आईडी वाला एक ही पैरामीटर है, जो संभावित वैल्यू ts या js वाली एक सूची है, तो इसका इस्तेमाल इस तरह किया जा सकता है:

# idx-template.nix
# Accept additional arguments to this template corresponding to template
# parameter IDs, including default values (language=ts by default in this example).
{ pkgs, language ? "ts", ... }: {
  packages = [
    pkgs.nodejs
  ];

  bootstrap = ''
    # We use Nix string interpolation to pass the user's chosen programming
    # language to our script.
    npm init --yes my-boot-strap@latest "$out" -- --lang=${language}
  ''
}

एक और आम पैटर्न, स्ट्रिंग की वैल्यू के हिसाब से कॉन्टेंट को शर्त के साथ शामिल करना है. पिछला उदाहरण लिखने का एक और तरीका यह है:

npm init --yes my-boot-strap@latest "$out" -- \
    ${if language == "ts" then "--lang=ts" else "--lang=js" }

चुनें कि डिफ़ॉल्ट रूप से कौनसी फ़ाइलें खुलनी चाहिए

यह कस्टमाइज़ करना एक अच्छा आइडिया है कि जब आपके टेंप्लेट की मदद से नए फ़ाइल फ़ोल्डर बनाए जाएं, तो किन फ़ाइलों में बदलाव करना चाहिए. उदाहरण के लिए, अगर आपका टेंप्लेट किसी बेसिक वेबसाइट के लिए है, तो हो सकता है कि आप मुख्य एचटीएमएल, JavaScript, और सीएसएस फ़ाइलें खोलना चाहें.

यह तय करने के लिए कि डिफ़ॉल्ट रूप से कौनसी फ़ाइलें खुलनी हैं, अपनी .idx/dev.nix फ़ाइल को अपडेट करें (अपनी idx-template.nix फ़ाइल नहीं!) इसमें openFiles एट्रिब्यूट के साथ onCreate फ़ाइल फ़ोल्डर हुक शामिल करें. जैसे:

# .idx/dev.nix
{pkgs}: {
  ...
  idx = {
    # Workspace lifecycle hooks
    workspace = {
      # Runs when a workspace is first created with this `dev.nix` file
      onCreate = {
        # Open editors for the following files by default, if they exist.
        # The last file in the list will be focused.
        default.openFiles = [
          "src/index.css"
          "src/index.js"
          "src/index.html"
        ];
        # Include other scripts here, as needed, for example:
        # installDependencies = "npm install";
      };
      # To run something each time the workspace is (re)started, use the `onStart` hook
    };
    # Enable previews and customize configuration
    previews = { ... };
  };
}

अपने टेंप्लेट से नया फ़ाइल फ़ोल्डर बनाएं

अपने टेंप्लेट को शुरू से आखिर तक टेस्ट करने का सबसे आसान तरीका है, इसके साथ एक नया फ़ाइल फ़ोल्डर बनाना. उदाहरण को अपने टेंप्लेट के GitHub रिपॉज़िटरी यूआरएल से बदलकर, नीचे दिए गए लिंक पर जाएं:

https://idx.google.com/new?template=https://github.com/my-org/my-repo

आपके पास ब्रांच और सब-फ़ोल्डर को शामिल करने का विकल्प भी होता है. नीचे बताई गई सभी चीज़ें मान्य हैं, बशर्ते वे सार्वजनिक तौर पर उपलब्ध हों:

  • https://github.com/my-org/my-repo/
  • https://github.com/my-org/my-repo/tree/main/path/to/myidxtemplate
  • https://github.com/my-org/my-repo/tree/branch
  • https://github.com/my-org/my-repo/tree/branch/path/to/myidxtemplate

इसी यूआरएल को आप दूसरे लोगों के साथ भी शेयर करेंगे, ताकि वे आपके नए टेंप्लेट का इस्तेमाल कर सकें. इसके अलावा, वे उस यूआरएल का भी इस्तेमाल कर सकें जिसे "IDX में खोलें" बटन से लिंक करना है.

अपना टेंप्लेट शेयर करें

यह पुष्टि करने के बाद कि आपका टेंप्लेट उम्मीद के मुताबिक काम करता है, उसे GitHub रिपॉज़िटरी में पब्लिश करें. साथ ही, वही लिंक शेयर करें जिसका इस्तेमाल आपने टेस्टिंग के लिए फ़ाइल फ़ोल्डर बनाते समय किया था.

साथ ही, उपयोगकर्ता आपके टेंप्लेट को आसानी से ढूंढ सकें, इसके लिए अपनी वेबसाइट या डेटा स्टोर करने की जगह README में "IDX में खोलें" बटन जोड़ें.