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

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

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

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

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

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 पर सेट करें. इससे क्लाइंट साइड की मौजूदा कैश मेमोरी मिट जाएगी. ज़्यादा जानकारी के लिए, ActionResponseBuilder.setStateChanged() तरीके की जानकारी देखें.