תוספות לאריחי בניין

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

דוגמאות לתוספים שאפשר להשתמש בהם כמשבצות בלוח הבקרה:

• התוסף להמחשת משבצות מראה איך ליצור המחשה בהתאמה אישית באמצעות מסגרת התוסף.
• התוסף Tile SDK מציג את שיטות ה-API הזמינות שספציפיות לתוספי משבצות.

שימו לב: אי אפשר להשתמש בתוכן מוטמע של Looker (כמו דוחות, לוחות בקרה, תצוגות, ניתוחים, לוחות בקרה של LookML וויזואליזציות של שאילתות) בתוספי משבצות.

שימוש ב-Looker Extension SDK עם תוספי משבצות

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

  mount_points: {
    dashboard_vis: yes
    dashboard_tile: yes
    standalone: yes
  }

• ‫dashboard_vis — כשההגדרה הזו מופעלת, התוסף יופיע באפשרויות התצוגה החזותית של Explore, שם אפשר לבחור את התוסף כסוג של תצוגה חזותית ולשמור אותו כמשבצת בלוח בקרה. כשמריצים את לוח הבקרה, הוא מריץ את השאילתה שמשויכת למשבצת ומעביר את הנתונים לתוסף. זה דומה לאופן הפעולה של הדמיות בהתאמה אישית. ההבדל העיקרי בין תצוגה חזותית מותאמת אישית לבין תוסף שפועל במשבצת בלוח בקרה שמופעל בה dashboard_vis הוא שהתוסף עשוי לבצע קריאות ל-Looker API.
• ‫dashboard_tile — כשהאפשרות הזו מופעלת, התוסף יופיע בחלונית Extensions שמוצגת כשמשתמש עורך לוח בקרה ובוחר באפשרות Extensions אחרי שהוא לוחץ על הלחצן Add. התוסף הזה אחראי לאחזור הנתונים שלו, במקום שהנתונים יסופקו לו באופן אוטומטי על ידי שאילתת המשבצת.

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

ממשקי API נוספים של תוסף Tile

תוספים של משבצות מקבלים נתונים וממשקי API נוספים בזמן הריצה. הערכים האלה מתקבלים מהקשר של התוסף:

const {
  tileSDK,
  tileHostData,
  visualizationData,
  visualizationSDK,
} = useContext(ExtensionContext40)

• ‫tileSDK – מספק פונקציות ספציפיות למשבצת כדי לאפשר לתוסף ליצור אינטראקציה עם המארח של מרכז הבקרה של Looker. לדוגמה, כדי לאפשר לתוסף להציג ולנקות הודעות שגיאה.
• ‫tileHostData — מספק נתוני משבצות לתוסף. הנתונים מתעדכנים אוטומטית על סמך האינטראקציות עם לוח הבקרה של האחסון. לדוגמה, האינדיקטור isDashboardEditing.
• ‫visualizationSDK – מספק פונקציות ספציפיות להמחשה כדי לאפשר לתוסף ליצור אינטראקציה עם המארח של לוח הבקרה ב-Looker. דוגמה לכך היא הפונקציה updateRowLimit.
• ‫visualizationData — מספק נתוני תצוגה חזותית לתוסף. הנתונים מתעדכנים אוטומטית על סמך האינטראקציות עם לוח הבקרה של האחסון. הנתונים דומים לנתונים שמוצגים בתצוגות חזותיות בהתאמה אישית.

פיתוח תוספים דינמיים

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

שיקולים לגבי עיבוד

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

  const { extensionSDK } = useContext(ExtensionContext40)

  useEffect(() => {
    extensionSDK.rendered()
  }, [])

גם האנימציות צריכות להיות מושבתות בזמן העיבוד. בדוגמה הבאה, הגדרות האנימציה מושבתות בזמן העיבוד:

  const { lookerHostData} = useContext(ExtensionContext40)
  const isRendering = lookerHostData?.isRendering

  const config = isRendering
    ? {
        ...visConfig,
        valueCountUp: false,
        waveAnimateTime: 0,
        waveRiseTime: 0,
        waveAnimate: false,
        waveRise: false,
      }
    : visConfig

  if (mountPoint === MountPoint.dashboardVisualization) {
    return <VisualizationTile config={config} />
  }

פונקציות ומאפיינים של Tile SDK

ה-SDK של כרטיסי המידע מספק פונקציות שמאפשרות לתוסף של כרטיס מידע ליצור אינטראקציה עם לוח הבקרה שבו הוא מתארח.

הפונקציות והמאפיינים הזמינים מוצגים בטבלה הבאה:

פונקציה או מאפיין	תיאור
tileHostData (נכס)	נתוני מארח שספציפיים לתוסף של המשבצת. פרטים נוספים זמינים בקטע נתוני Tile SDK.
addError	כשמפעילים את הפונקציה, מוצגת הודעת שגיאה מתחת להצגה החזותית בלוח הבקרה או בכלי הניתוחים.
clearError	כשמפעילים את הפונקציה הזו, מרכז הבקרה או התכונה 'ניתוח נתונים' מסתירים את כל הודעות השגיאה שמוצגות מתחת להדמיה.
openDrillMenu	בתוספי ויזואליזציה, הלחיצה הזו פותחת תפריט של פירוט. הקריאה הזו מתעלמת אם התוסף הוא לא תצוגה חזותית של תוסף משבצת.
runDashboard	הפעלת מרכז הבקרה הנוכחי. השיחה הזו מתעלמת מתוסף להצגת נתונים בצורה של משבצות שפועל בכלי הניתוח.
stopDashboard	הפסקת הפעולה של מרכז בקרה פעיל. השיחה הזו מתעלמת מתוסף להצגת נתונים בצורה של משבצות שפועל בכלי הניתוח.
updateFilters	עדכון המסננים בלוח הבקרה הנוכחי או ב'התנסות'.
openScheduleDialog	תיפתח תיבת הדו-שיח של לוח הזמנים. המערכת מתעלמת מהשיחה הזו כשמריצים אותה ב'ניתוח נתונים'.
toggleCrossFilter	החלפת מצב המסננים הצולבים. המערכת מתעלמת מהשיחה הזו כשמריצים אותה ב'ניתוח נתונים'.

נתונים של Tile SDK

המאפיינים הזמינים של נתוני ה-SDK של הרכיבים מוצגים בטבלה הבאה:

מאפיין (property)	תיאור
isExploring	אם הערך הוא True, המשמעות היא שהמשבצת מוגדרת כוויזואליזציה בתוך כלי הניתוח.
dashboardId	מזהה לוח הבקרה של המשבצת שמוצגת. אם מגדירים את המשבצת כניתוח, הנכס הזה לא יאוכלס.
elementId	מזהה הרכיב של המשבצת שמוצגת. אם מגדירים את המשבצת כניתוח, הנכס הזה לא יאוכלס.
queryId	מזהה השאילתה של המשבצת שמוצגת, אם היא משויכת להדמיה. אם מגדירים את המשבצת כניתוח, הנכס הזה לא יאוכלס. ‫queryId הוא מזהה השאילתה שנוצר כשיוצרים את ההמחשה בכלי 'ניתוח נתונים' ב-Looker. הוא לא מכיל מסננים או סינון צולב שאפשר להחיל על לוח הבקרה. כדי שהנתונים שמוצגים ב-QueryResponse ישקפו את הנתונים שמוצגים ב-QueryResponse, צריך להחיל מסננים ומסננים מצטלבים וליצור שאילתה חדשה. כתוצאה מכך, יכול להיות שיהיו יותר מאפיינים שימושיים מ-queryId. בדוגמה filteredQuery אפשר לראות אובייקט שאילתה עם מסננים.
querySlug	מחרוזת ה-slug של כרטיס התצוגה שמוצג, אם הוא משויך להמחשה. אם מגדירים את המשבצת כניתוח, הנכס הזה לא יאוכלס. ‫querySlug הוא slug של השאילתה שנוצרת כשיוצרים את ההמחשה ב-Looker Explore. הוא לא מכיל מסננים או סינון צולב שמוחל על לוח הבקרה. כדי שהנתונים שמוצגים ב-QueryResponse ישקפו את הנתונים שמוצגים ב-QueryResponse, צריך להחיל מסננים ומסננים מצטלבים וליצור שאילתה חדשה. כתוצאה מכך, יכול להיות שיהיו יותר מאפיינים שימושיים מ-querySlug. בדוגמה filteredQuery אפשר לראות אובייקט שאילתה עם מסננים.
dashboardFilters	המסננים שמופעלים בדשבורד. אם מגדירים את המשבצת כניתוח, הנכס הזה לא יאוכלס.
dashboardRunState	מציין אם לוח הבקרה פועל. אם מגדירים את המשבצת כניתוח, המצב יהיה UNKNOWN. מסיבות שקשורות לביצועים של מרכז הבקרה, יכול להיות שהסטטוס של ההרצה לא יוצג אף פעם כ'פועל'. זה קורה בדרך כלל אם אין משבצות אחרות שמשויכות לשאילתה, כולל המשבצת שהתוסף משויך אליה. אם התוסף צריך לדעת בוודאות שהופעל דאשבורד, הדרך המהימנה לעשות זאת היא לזהות הבדלים ב-lastRunStartTime.
isDashboardEditing	אם הערך הוא True, מרכז הבקרה נמצא במצב עריכה. אם מגדירים את המשבצת כניתוח, הנכס הזה לא יאוכלס.
isDashboardCrossFilteringEnabled	אם הערך הוא True, סינון צולב מופעל בלוח הבקרה. אם מגדירים את המשבצת כניתוח, הנכס הזה לא יאוכלס.
filteredQuery	אובייקט שאילתה שתואם למזהה השאילתה שמשויך לרכיב בלוח הבקרה הבסיסי שמחיל את כל המסננים של לוח הבקרה ושינויים באזור הזמן שבוצעו ברמת לוח הבקרה.
lastRunSourceElementId	המזהה של רכיב התוסף של המשבצת שהפעיל את ההרצה האחרונה של לוח הבקרה. המזהה יהיה לא מוגדר אם ההפעלה של לוח הבקרה הופעלה על ידי הלחצן הפעלה או רענון אוטומטי של לוח הבקרה, או אם ההפעלה הופעלה באמצעות ה-SDK להטמעה. אם מגדירים את המשבצת כניתוח, הנכס הזה לא יאוכלס. חשוב לשים לב שערך המאפיין lastRunSourceElementId יכול להיות זהה למזהה האלמנט של מופע התוסף הנוכחי. לדוגמה, אם התוסף מפעיל הרצה של לוח בקרה, הוא יקבל הודעה כשההרצה של לוח הבקרה תתחיל ותסתיים.
lastRunStartTime	מציין את זמן ההתחלה של ההרצה האחרונה של לוח הבקרה. אם מגדירים את המשבצת כניתוח, הנכס הזה לא יאוכלס. חשוב לדעת שלא כדאי להשתמש בשעות ההתחלה והסיום שמדווחות כדי לתעד מדדי ביצועים.
lastRunEndTime	מציין את שעת הסיום של ההרצה האחרונה של לוח הבקרה. אם מגדירים את המשבצת כניתוח, הנכס הזה לא יאוכלס. אם הריבוע פועל, המאפיין הזה לא יאוכלס. חשוב לדעת שלא כדאי להשתמש בשעות ההתחלה והסיום שמדווחות כדי לתעד מדדי ביצועים.
lastRunSuccess	מציין אם ההרצה האחרונה של לוח הבקרה הצליחה או לא. אם מגדירים את המשבצת כניתוח, הנכס הזה לא יאוכלס. אם הריבוע פועל, המאפיין הזה לא יאוכלס.

פונקציות ומאפיינים של Visualization SDK

בטבלה הבאה מוצגות הפונקציות והמאפיינים הזמינים של ה-SDK של הוויזואליזציה:

פונקציה או מאפיין	תיאור
visualizationData (נכס)	תרשים (שילוב של נתוני visConfig ונתוני queryResponse).
visConfig (נכס)	נתוני ההגדרה של התרשים: הגדרות מדידה הגדרות של מאפיינים חישובים בטבלה הגדרות של טבלאות צירים הגדרות של תרשימים להמחשה הם משמשים להתאמה אישית של המראה והתחושה של תרשים בכלי הניתוחים.
queryResponse (נכס)	נתוני התגובות מהשאילתה
configureVisualization	הגדרה של ברירת המחדל של התצוגה החזותית של תוסף. ההגדרה תוצג בעורך התצוגה החזותית של הניתוח. אפשר להפעיל אותה רק פעם אחת.
setVisConfig	עדכון ההגדרה של התצוגה החזותית.
updateRowLimit	עדכון מגבלת השורות של השאילתה.

נתוני Visualization SDK

ערכת ה-SDK של התצוגה החזותית מורכבת מהרכיבים הבאים:

• נתוני ההגדרה של התרשים
• נתוני תגובות לשאילתות

נתוני ההגדרה של התרשים

מאפיין (property)	תיאור
queryFieldMeasures	פרטי המדד
queryFieldDimensions	פרטי המאפיין
queryFieldTableCalculations	פרטים על חישובים בטבלה
queryFieldPivots	מידע על שינוי מהותי
visConfig	נתוני הגדרה חזותיים. התצורה הזו צריכה להתמזג עם הגדרות ברירת המחדל ולהיות מיושמת על הוויזואליזציה שמוצגת על ידי התוסף.

export interface VisualizationConfig {
  queryFieldMeasures: Measure[]
  queryFieldDimensions: Dimension[]
  queryFieldTableCalculations: TableCalculation[]
  queryFieldPivots: PivotConfig[]
  visConfig: RawVisConfig
}

נתוני תגובות לשאילתות

מאפיין (property)	תיאור
data	מערך של נתוני שורה
fieldMeasures	מידע על מדדי השדה.
fieldDimensions	פרטי מאפיין של שדה.
fieldTableCalculations	מידע על חישובים בטבלה של שדות.
fieldPivots	מידע על ציר השדה.
fieldMeasureLike	מערך משורשר של מידע על מדדי שדות וחישובים בטבלה שמתנהגים כמו מדדים.
fieldDimensionLike	מערך משורשר של מידע על מאפייני שדות וחישובים בטבלה שמתנהגים כמו מאפיינים.

שימוש ב-Embed SDK

לא מומלץ להשתמש ב-Embed SDK בתוסף של משבצת מהסיבות הבאות:

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