इंटरैक्टिव कार्ड बनाना

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

विजेट में कार्रवाइयां जोड़ना

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

ज़्यादातर मामलों में, किसी विजेट को कॉन्फ़िगर करने के लिए इस सामान्य तरीके का इस्तेमाल किया जा सकता है. इससे, विजेट को चुनने या अपडेट करने पर कोई खास कार्रवाई की जा सकती है:

1. Action ऑब्जेक्ट बनाएं. इसमें ज़रूरी पैरामीटर के साथ-साथ, उस कॉलबैक फ़ंक्शन के बारे में जानकारी दें जिसे लागू किया जाना है.
2. सही विजेट हैंडलर फ़ंक्शन को कॉल करके, विजेट को Action से लिंक करें.
3. ज़रूरी व्यवहार को लागू करने के लिए, कॉलबैक फ़ंक्शन लागू करें.

उदाहरण

यहां दिए गए उदाहरण में, एक ऐसा बटन सेट किया गया है जिस पर क्लिक करने के बाद, उपयोगकर्ता को सूचना दिखती है. क्लिक करने पर, notifyUser() कॉलबैक फ़ंक्शन ट्रिगर होता है. इसमें एक ऐसा आर्ग्युमेंट होता है जो सूचना के टेक्स्ट के बारे में बताता है. बनाया गया ActionResponse वापस करने पर, सूचना दिखती है.

  /**
   * Build a simple card with a button that sends a notification.
   * @return {Card}
   */
  function buildSimpleCard() {
    var buttonAction = CardService.newAction()
        .setFunctionName('notifyUser')
        .setParameters({'notifyText': 'Button clicked!'});
    var button = CardService.newTextButton()
        .setText('Notify')
        .setOnClickAction(buttonAction);

    // ...continue creating widgets, then create a Card object
    // to add them to. Return the built Card object.
  }

  /**
   * Callback function for a button action. Constructs a
   * notification action response and returns it.
   * @param {Object} e the action event object
   * @return {ActionResponse}
   */
  function notifyUser(e) {
    var parameters = e.parameters;
    var notificationText = parameters['notifyText'];
    return CardService.newActionResponseBuilder()
        .setNotification(CardService.newNotification()
            .setText(notificationText))
        .build();      // Don't forget to build the response!
  }

असरदार इंटरैक्शन डिज़ाइन करना

इंटरैक्टिव कार्ड डिज़ाइन करते समय, इन बातों का ध्यान रखें:

• आम तौर पर, इंटरैक्टिव विजेट को अपने व्यवहार को तय करने के लिए, कम से कम एक हैंडलर तरीके की ज़रूरत होती है.

• जब आपके पास कोई यूआरएल हो और आपको उसे सिर्फ़ किसी टैब में खोलना हो, तब setOpenLink() विजेट हैंडलर फ़ंक्शन का इस्तेमाल करें. इससे Action ऑब्जेक्ट और कॉलबैक फ़ंक्शन को तय करने की ज़रूरत नहीं पड़ती. अगर आपको यूआरएल खोलने से पहले उसे बनाना है या कोई अन्य कार्रवाई करनी है, तो Action को तय करें और setOnClickOpenLinkAction() का इस्तेमाल करें.

• setOpenLink() या setOnClickOpenLinkAction() विजेट हैंडलर फ़ंक्शन का इस्तेमाल करते समय, आपको OpenLink ऑब्जेक्ट देना होगा. इससे यह तय किया जा सकेगा कि कौनसा यूआरएल खोलना है. इस ऑब्जेक्ट का इस्तेमाल करके, OpenAs और OnClose enum का इस्तेमाल करके, खुलने और बंद होने के व्यवहार के बारे में भी बताया जा सकता है.

• ऐसा हो सकता है कि एक से ज़्यादा विजेट, एक ही Action ऑब्जेक्ट का इस्तेमाल करें. हालांकि, अगर आपको कॉलबैक फ़ंक्शन को अलग-अलग पैरामीटर देने हैं, तो आपको अलग-अलग Action ऑब्जेक्ट तय करने होंगे.

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

• अगर उपयोगकर्ता के ऐड-ऑन के यूज़र इंटरफ़ेस (यूआई) से इंटरैक्ट करने की वजह से, तीसरे पक्ष के बैकएंड पर डेटा की स्थिति में बदलाव होता है, तो हमारा सुझाव है कि ऐड-ऑन, true के लिए 'state changed' बिट सेट करे. इससे क्लाइंट-साइड की मौजूदा कैश मेमोरी मिट जाएगी. ज़्यादा जानकारी के लिए, ActionResponseBuilder.setStateChanged() तरीके का ब्यौरा देखें.