יצירת כרטיסים אינטראקטיביים

בנוסף להצגת הנתונים, רוב התוספים מחייבים את המשתמש להזין מידע. כשיוצרים תוסף מבוסס-כרטיסים, אפשר להשתמש בווידג'טים אינטראקטיביים כמו לחצנים, אפשרויות בתפריט בסרגל הכלים או תיבות סימון כדי לבקש מהמשתמשים נתונים שהתוסף צריך, או פקדים אחרים לפעולות.

הוספת פעולות לווידג'טים

ברוב המקרים, ווידג'טים הופכים לאינטראקטיביים על ידי קישור שלהם לפעולות ספציפיות והטמעה של ההתנהגות הנדרשת בפונקציית קריאה חוזרת. פרטים נוספים זמינים בקטע פעולות שקשורות לתוספים.

ברוב המקרים, תוכלו לפעול לפי התהליך הכללי הבא כדי להגדיר ווידג'ט שיבצע פעולה ספציפית כשבוחרים או כשמעדכנים:

1. יוצרים אובייקט Action ומציינים את פונקציית הקריאה החוזרת (callback) שאמורה להתבצע יחד עם כל הפרמטרים הנדרשים.
2. כדי לקשר את הווידג'ט ל-Action, מפעילים את הפונקציה המתאימה של handler של ווידג'טים.
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!
  }

תכנון אינטראקציות אפקטיביות

במהלך עיצוב כרטיסים אינטראקטיביים, חשוב לזכור את הנקודות הבאות:

• בווידג'טים אינטראקטיביים צריך בדרך כלל לפחות שיטה אחת של handler כדי להגדיר את ההתנהגות שלהם.

• השתמשו בפונקציית handler של setOpenLink() בווידג'טים, אם יש לכם כתובת URL ואתם רוצים לפתוח אותה בכרטיסייה. כך לא צריך להגדיר אובייקט Action ופונקציית קריאה חוזרת. אם אתם צריכים ליצור קודם את כתובת ה-URL או לבצע פעולות נוספות לפני פתיחת כתובת ה-URL, עליכם להגדיר Action ולהשתמש במקום זאת ב-setOnClickOpenLinkAction().

• כשמשתמשים בפונקציות setOpenLink() או setOnClickOpenLinkAction() של handler של ווידג'טים, צריך לספק אובייקט OpenLink כדי להגדיר את כתובת ה-URL שצריך לפתוח. אפשר להשתמש באובייקט הזה גם כדי לציין פעולות פתיחה וסגירה באמצעות הטיפוסים OpenAs ו-OnClose.

• יכול להיות שיותר מווידג'ט אחד ישתמש באותו אובייקט Action. עם זאת, צריך להגדיר אובייקטים שונים של Action כדי לספק לפונקציית הקריאה החוזרת פרמטרים שונים.

• פונקציות הקריאה החוזרות (callback) צריכות להיות פשוטות. כדי שהתוספים יהיו רספונסיביים, שירות הכרטיסים מגביל את פונקציות הקריאה החוזרות (callback) ל-30 שניות לכל היותר. אם ההפעלה נמשכת יותר זמן, יכול להיות שממשק המשתמש של התוסף לא יתעדכן כמו שצריך.Action

• אם סטטוס הנתונים בקצה עורפי של צד שלישי משתנה כתוצאה מאינטראקציה של משתמש עם ממשק המשתמש של התוסף, מומלץ שהתוסף יגדיר ביט 'מצב השתנה' ל-true כדי למחוק את כל המטמון הקיים בצד הלקוח. לפרטים נוספים, קראו את תיאור השיטה ActionResponseBuilder.setStateChanged().