कार्ड नेविगेशन

ज़्यादातर कार्ड-आधारित ऐड-ऑन कई कार्ड का इस्तेमाल करके बनाए जाते हैं जो ऐड-ऑन इंटरफ़ेस के अलग-अलग 'पेज' दिखाते हैं. बेहतर उपयोगकर्ता अनुभव पाने के लिए, आपको अपने ऐड-ऑन में कार्ड के बीच आसान और नैचुरल नेविगेशन का इस्तेमाल करना चाहिए.

मूल रूप से Gmail ऐड-ऑन में, यूज़र इंटरफ़ेस (यूआई) के अलग-अलग कार्ड के बीच ट्रांज़िशन को एक कार्ड स्टैक पर पुश और पॉप करके मैनेज किया जाता है. इसमें Gmail में स्टैक का टॉप कार्ड दिखता है.

होम पेज कार्ड नेविगेशन

Google Workspace ऐड-ऑन में आपको होम पेज और ऐसे कार्ड जोड़ने की सुविधा मिलती है जो ज़रूरी नहीं हैं. कॉन्टेक्स्ट के हिसाब से और बिना संदर्भ वाले कार्ड को शामिल करने के लिए, Google Workspace ऐड-ऑन में हर कार्ड के लिए एक इंटरनल कार्ड स्टैक होता है. जब किसी होस्ट में ऐड-ऑन को खोला जाता है, तो उससे जुड़ा homepageTrigger, स्टैक पर पहला होम पेज कार्ड बनाने के लिए चालू हो जाता है. (नीचे दिए गए डायग्राम में, गहरे नीले रंग का "होम पेज" कार्ड). अगर homepageTrigger तय नहीं किया गया है, तो एक डिफ़ॉल्ट कार्ड बनाया जाता है, दिखाया जाता है, और गैर-संदर्भ वाले स्टैक पर पुश किया जाता है. यह पहला कार्ड एक रूट कार्ड है.

जब उपयोगकर्ता आपके ऐड-ऑन के ज़रिए नेविगेट करता है, तो आपका ऐड-ऑन, बिना संदर्भ के अन्य कार्ड बना सकता है और उन्हें स्टैक (इमेज में मौजूद नीले रंग के "पुश किए गए कार्ड") पर पुश कर सकता है. ऐड-ऑन यूज़र इंटरफ़ेस (यूआई), स्टैक में टॉप कार्ड दिखाता है, इसलिए नए कार्ड को स्टैक में पुश करने से डिसप्ले बदल जाता है और स्टैक से कार्ड पॉप-अप करने पर डिसप्ले पिछले कार्ड की स्थिति में आ जाता है.

अगर आपके ऐड-ऑन में संदर्भ के हिसाब से ट्रिगर तय है, तो उपयोगकर्ता के उस कॉन्टेक्स्ट में जाने पर ट्रिगर ट्रिगर हो जाता है. ट्रिगर फ़ंक्शन, कॉन्टेक्स्चुअल कार्ड बनाता है, लेकिन यूज़र इंटरफ़ेस (यूआई) डिसप्ले, नए कार्ड के DisplayStyle के आधार पर अपडेट किया जाता है:

  • अगर DisplayStyle REPLACE (डिफ़ॉल्ट) है, तो कॉन्टेक्स्चुअल कार्ड (इमेज में गहरे नारंगी रंग का "संदर्भ के मुताबिक" कार्ड) मौजूदा समय में दिखाए गए कार्ड की जगह ले लेता है. इससे बिना संदर्भ वाले कार्ड स्टैक के सबसे ऊपर, नए कॉन्टेक्स्ट के हिसाब से कार्ड स्टैक को शुरू किया जाता है. साथ ही, यह कॉन्टेक्स्ट के हिसाब से कार्ड, संदर्भ के हिसाब से स्टैक का रूट कार्ड होता है.
  • अगर DisplayStyle PEEK है, तो यूज़र इंटरफ़ेस (यूआई) इसके बजाय दिखने वाला हेडर बनाता है. यह ऐड-ऑन साइडबार में सबसे नीचे दिखता है और मौजूदा कार्ड को ओवरले करता है. झलक हेडर, नए कार्ड का टाइटल दिखाता है. साथ ही, उपयोगकर्ता बटन के कंट्रोल उपलब्ध कराता है. इनकी मदद से, वे यह तय कर सकते हैं कि नए कार्ड को देखना है या नहीं. अगर उपयोगकर्ता देखें बटन पर क्लिक करता है, तो कार्ड मौजूदा कार्ड की जगह ले लेता है (जैसा कि ऊपर REPLACE से बताया गया है).

काम के अन्य कार्ड बनाए जा सकते हैं और उन्हें स्टैक (इमेज में पीले रंग के "पुश किए गए कार्ड") पर पुश किया जा सकता है. कार्ड स्टैक को अपडेट करने से, ऐड-ऑन यूज़र इंटरफ़ेस (यूआई) बदल जाता है, ताकि सबसे ऊपर मौजूद कार्ड दिखाया जा सके. अगर उपयोगकर्ता कोई कॉन्टेक्स्ट छोड़ता है, तो स्टैक से कॉन्टेक्स्ट के हिसाब से बने कार्ड हटा दिए जाते हैं. साथ ही, डिसप्ले, बिना कॉन्टेक्स्ट के सबसे ऊपर वाले कार्ड या होम पेज पर अपडेट हो जाता है.

अगर उपयोगकर्ता ऐसा संदर्भ डालता है जिसके लिए आपका ऐड-ऑन, संदर्भ के हिसाब से ट्रिगर तय नहीं करता है, तो कोई नया कार्ड नहीं बनाया जाता है और मौजूदा कार्ड दिखता है.

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

वहीं दूसरी ओर, उपयोगकर्ता के लिए बटन हमेशा उपलब्ध रहता है, ताकि वह संदर्भ के हिसाब से बने कार्ड से ऐसे कार्ड पर जा सके जो कॉन्टेंट से मेल नहीं खाते.

कार्ड स्टैक में से कार्ड जोड़कर या हटाकर, उनके बीच ट्रांज़िशन बनाए जा सकते हैं. Navigation क्लास, स्टैक से कार्ड पुश और पॉप करने के लिए फ़ंक्शन देती है. कार्ड नेविगेशन को बेहतर बनाने के लिए, विजेट को कॉन्फ़िगर करना ज़रूरी है, ताकि आप नेविगेशन कार्रवाइयों का इस्तेमाल कर सकें. एक साथ कई कार्ड पुश या पॉप किए जा सकते हैं. हालांकि, होम पेज के उस शुरुआती कार्ड को नहीं हटाया जा सकता जिसे ऐड-ऑन शुरू होने पर, स्टैक पर सबसे पहले पुश किया जाता है.

विजेट के साथ हुए उपयोगकर्ता इंटरैक्शन के जवाब में नए कार्ड पर जाने के लिए, यह तरीका अपनाएं:

  1. एक Action ऑब्जेक्ट बनाएं और उसे अपने तय किए गए कॉलबैक फ़ंक्शन से जोड़ें.
  2. विजेट पर Action सेट करने के लिए, विजेट के सही विजेट हैंडलर फ़ंक्शन को कॉल करें.
  3. नेविगेशन को मैनेज करने वाले कॉलबैक फ़ंक्शन को लागू करें. इस फ़ंक्शन को आर्ग्युमेंट के तौर पर, ऐक्शन इवेंट ऑब्जेक्ट दिया जाता है. इसलिए, आपको ये काम करने होंगे:
    1. कार्ड में किए गए बदलाव के बारे में बताने के लिए, Navigation ऑब्जेक्ट बनाएं. एक Navigation ऑब्जेक्ट में, नेविगेशन के कई चरण हो सकते हैं. ये चरण उसी क्रम में होते हैं जिस क्रम में उन्हें ऑब्जेक्ट में जोड़ा जाता है.
    2. ActionResponseBuilder क्लास और Navigation ऑब्जेक्ट का इस्तेमाल करके, ActionResponse ऑब्जेक्ट बनाएं.
    3. बनाई गई फ़ाइल ActionResponse लौटाना.

नेविगेशन कंट्रोल बनाते समय, इन Navigation ऑब्जेक्ट फ़ंक्शन का इस्तेमाल किया जाता है:

फ़ंक्शन ब्यौरा
Navigation.pushCard(Card) मौजूदा स्टैक पर, कार्ड पुश करता है. इसके लिए, पहले कार्ड बनाना ज़रूरी है.
Navigation.popCard() स्टैक के सबसे ऊपर से एक कार्ड हटाता है. इसका मतलब है कि ऐड-ऑन हेडर लाइन में बैक ऐरो पर क्लिक करना. ऐसा करने से, रूट कार्ड नहीं हटते.
Navigation.popToRoot() रूट कार्ड को छोड़कर, स्टैक से सभी कार्ड हटा देता है. उस कार्ड स्टैक को आवश्यक रूप से रीसेट करता है.
Navigation.popToNamedCard(String) स्टैक से कार्ड तब तक पॉप-अप करते हैं, जब तक वे दिए गए नाम या स्टैक के रूट कार्ड वाले कार्ड तक नहीं पहुंचते. CardBuilder.setName(String) फ़ंक्शन का इस्तेमाल करके, कार्ड के नाम असाइन किए जा सकते हैं.
Navigation.updateCard(Card) मौजूदा कार्ड को अपनी जगह पर ही बदला जा सकता है, ताकि यूज़र इंटरफ़ेस (यूआई) में इसके डिसप्ले को रीफ़्रेश किया जा सके.

अगर किसी उपयोगकर्ता इंटरैक्शन या इवेंट की वजह से, एक ही कॉन्टेक्स्ट में कार्ड को फिर से रेंडर किया जाता है, तो मौजूदा कार्ड को बदलने के लिए Navigation.pushCard(), Navigation.popCard(), और Navigation.updateCard() तरीकों का इस्तेमाल करें. अगर किसी उपयोगकर्ता इंटरैक्शन या इवेंट की वजह से, कार्ड को किसी दूसरे कॉन्टेक्स्ट में फिर से रेंडर करना पड़ता है, तो उन मामलों में अपने ऐड-ऑन को फिर से लागू करने के लिए ActionResponseBuilder.setStateChanged() का इस्तेमाल करें.

नेविगेशन के उदाहरण यहां दिए गए हैं:

  • अगर किसी इंटरैक्शन या इवेंट से मौजूदा कार्ड की स्थिति बदलती है (जैसे, टास्क की सूची में टास्क जोड़ना), तो updateCard() का इस्तेमाल करें.
  • अगर कोई इंटरैक्शन या इवेंट ज़्यादा जानकारी देता है या उपयोगकर्ता को ज़्यादा जानकारी देने के लिए कहता है (उदाहरण के लिए, ज़्यादा जानकारी देखने के लिए किसी आइटम के टाइटल पर क्लिक करना या नया कैलेंडर इवेंट बनाने के लिए बटन दबाना), तो pushCard() का इस्तेमाल करके नया पेज दिखाएं. साथ ही, उपयोगकर्ता को 'वापस जाएं' बटन का इस्तेमाल करके नए पेज से बाहर निकलने की अनुमति दें.
  • अगर पिछले कार्ड और मौजूदा कार्ड में किसी इंटरैक्शन या इवेंट की स्थिति अपडेट हुई है, तो पिछले कार्ड और मौजूदा कार्ड को अपडेट करने के लिए, popCard(), popCard(), pushCard(previous), और pushCard(current) जैसा कुछ इस्तेमाल करें.

कार्ड रीफ़्रेश करना

Google Workspace ऐड-ऑन की मदद से लोग आपके कार्ड को रीफ़्रेश कर सकते हैं. इसके लिए, आपकी मेनिफ़ेस्ट फ़ाइल में रजिस्टर किए गए Apps Script ट्रिगर फ़ंक्शन को फिर से चलाकर देखना होगा. उपयोगकर्ता इस रीफ़्रेश को किसी ऐड-ऑन मेन्यू आइटम के ज़रिए ट्रिगर करते हैं:

Google Workspace ऐड-ऑन का साइडबार

यह कार्रवाई, homepageTrigger या contextualTrigger ट्रिगर फ़ंक्शन से जनरेट किए गए कार्ड में अपने-आप जुड़ जाती है, जैसा कि आपके ऐड-ऑन की मेनिफ़ेस्ट फ़ाइल में बताया गया है (संदर्भ के मुताबिक और काम न करने वाले कार्ड स्टैक के 'रूट').

एक से ज़्यादा कार्ड वापस किए जा रहे हैं

ऐड-ऑन कार्ड का उदाहरण

होम पेज या कॉन्टेक्स्चुअल ट्रिगर फ़ंक्शन का इस्तेमाल किसी एक Card ऑब्जेक्ट या Card ऑब्जेक्ट की कलेक्शन बनाने और उसे लौटाने के लिए किया जाता है. जिसे ऐप्लिकेशन के यूज़र इंटरफ़ेस (यूआई) में दिखाया जाता है.

अगर सिर्फ़ एक कार्ड है, तो उसे रूट कार्ड के तौर पर गैर-संदर्भ या कॉन्टेक्स्ट के हिसाब से स्टैक में जोड़ दिया जाता है और होस्ट ऐप्लिकेशन यूज़र इंटरफ़ेस (यूआई) उसे दिखाता है.

अगर दिखाए गए कलेक्शन में एक से ज़्यादा बिल्ट-Card ऑब्जेक्ट शामिल हैं, तो होस्ट ऐप्लिकेशन इसके बजाय एक नया कार्ड दिखाता है, जिसमें हर कार्ड के हेडर की सूची होती है. जब उपयोगकर्ता इनमें से किसी हेडर पर क्लिक करता है, तो यूज़र इंटरफ़ेस (यूआई) उस कार्ड से जुड़ा कार्ड दिखाता है.

जब उपयोगकर्ता सूची से कोई कार्ड चुनता है, तो वह कार्ड मौजूदा स्टैक में पुश कर दिया जाता है और होस्ट ऐप्लिकेशन उसे दिखाता है. बटन, उपयोगकर्ता को कार्ड हेडर सूची पर वापस ले जाता है.

अगर आपके ऐड-ऑन को बनाए जाने वाले कार्ड के बीच किसी तरह के ट्रांज़िशन की ज़रूरत नहीं है, तो यह 'फ़्लैट' कार्ड अरेंजमेंट अच्छी तरह से काम कर सकता है. हालांकि, ज़्यादातर मामलों में कार्ड ट्रांज़िशन को सीधे तौर पर परिभाषित करना और आपके होम पेज और संदर्भ के हिसाब से ट्रिगर करने वाले फ़ंक्शन को एक ही कार्ड ऑब्जेक्ट दिखाना बेहतर होता है.

उदाहरण

यहां एक उदाहरण दिया गया है, जिसमें नेविगेशन बटन की मदद से कई कार्ड बनाने का तरीका बताया गया है. createNavigationCard() से दिखाए गए कार्ड को किसी खास कॉन्टेक्स्ट में या उससे बाहर पुश करके, इन कार्ड को कॉन्टेक्स्ट के हिसाब से या बिना संदर्भ वाले स्टैक में जोड़ा जा सकता है.

  /**
   *  Create the top-level card, with buttons leading to each of three
   *  'children' cards, as well as buttons to backtrack and return to the
   *  root card of the stack.
   *  @return {Card}
   */
  function createNavigationCard() {
    // Create a button set with actions to navigate to 3 different
    // 'children' cards.
    var buttonSet = CardService.newButtonSet();
    for(var i = 1; i <= 3; i++) {
      buttonSet.addButton(createToCardButton(i));
    }

    // Build the card with all the buttons (two rows)
    var card = CardService.newCardBuilder()
        .setHeader(CardService.newCardHeader().setTitle('Navigation'))
        .addSection(CardService.newCardSection()
            .addWidget(buttonSet)
            .addWidget(buildPreviousAndRootButtonSet()));
    return card.build();
  }

  /**
   *  Create a button that navigates to the specified child card.
   *  @return {TextButton}
   */
  function createToCardButton(id) {
    var action = CardService.newAction()
        .setFunctionName('gotoChildCard')
        .setParameters({'id': id.toString()});
    var button = CardService.newTextButton()
        .setText('Card ' + id)
        .setOnClickAction(action);
    return button;
  }

  /**
   *  Create a ButtonSet with two buttons: one that backtracks to the
   *  last card and another that returns to the original (root) card.
   *  @return {ButtonSet}
   */
  function buildPreviousAndRootButtonSet() {
    var previousButton = CardService.newTextButton()
        .setText('Back')
        .setOnClickAction(CardService.newAction()
            .setFunctionName('gotoPreviousCard'));
    var toRootButton = CardService.newTextButton()
        .setText('To Root')
        .setOnClickAction(CardService.newAction()
            .setFunctionName('gotoRootCard'));

    // Return a new ButtonSet containing these two buttons.
    return CardService.newButtonSet()
        .addButton(previousButton)
        .addButton(toRootButton);
  }

  /**
   *  Create a child card, with buttons leading to each of the other
   *  child cards, and then navigate to it.
   *  @param {Object} e object containing the id of the card to build.
   *  @return {ActionResponse}
   */
  function gotoChildCard(e) {
    var id = parseInt(e.parameters.id);  // Current card ID
    var id2 = (id==3) ? 1 : id + 1;      // 2nd card ID
    var id3 = (id==1) ? 3 : id - 1;      // 3rd card ID
    var title = 'CARD ' + id;

    // Create buttons that go to the other two child cards.
    var buttonSet = CardService.newButtonSet()
      .addButton(createToCardButton(id2))
      .addButton(createToCardButton(id3));

    // Build the child card.
    var card = CardService.newCardBuilder()
        .setHeader(CardService.newCardHeader().setTitle(title))
        .addSection(CardService.newCardSection()
            .addWidget(buttonSet)
            .addWidget(buildPreviousAndRootButtonSet()))
        .build();

    // Create a Navigation object to push the card onto the stack.
    // Return a built ActionResponse that uses the navigation object.
    var nav = CardService.newNavigation().pushCard(card);
    return CardService.newActionResponseBuilder()
        .setNavigation(nav)
        .build();
  }

  /**
   *  Pop a card from the stack.
   *  @return {ActionResponse}
   */
  function gotoPreviousCard() {
    var nav = CardService.newNavigation().popCard();
    return CardService.newActionResponseBuilder()
        .setNavigation(nav)
        .build();
  }

  /**
   *  Return to the initial add-on card.
   *  @return {ActionResponse}
   */
  function gotoRootCard() {
    var nav = CardService.newNavigation().popToRoot();
    return CardService.newActionResponseBuilder()
        .setNavigation(nav)
        .build();
  }