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

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

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

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

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

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() तरीके की जानकारी देखें.