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

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

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

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

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

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!
  }

עיצוב אינטראקציות יעילות

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

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

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

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

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

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

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