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

החל מ-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 של רכיבי ה-UI מוצגים בטבלה הבאה:

מאפיין (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 של תוכן מוטמע בתוך תוסף של משבצת לא עובד.