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

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

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

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

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

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 एन्सम का इस्तेमाल करके, खोलने और बंद करने के व्यवहार की जानकारी देने के लिए भी किया जा सकता है.

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

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

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