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

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

मूल रूप से 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 ट्रिगर फ़ंक्शन को फिर से चलाकर, आपका कार्ड रीफ़्रेश कर सकते हैं. उपयोगकर्ता इस रीफ़्रेश को ऐड-ऑन मेन्यू आइटम से ट्रिगर करते हैं:

यह कार्रवाई, 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();
  }