אלמנטי דשבורד — מונים, גרפים, טקסט וטאבים

ארבעה כלים מציבים תוכן על דף: כותרת או פסקה, מונה KPI, גרף, ורצועת לשוניות. כולם עובדים באותה תבנית — מוסיפים כשמעבירים מיקום, עורכים כשמעבירים elemId.

קודם מקום, אחר כך אלמנט

כל ארבעת הכלים אומרים את אותו משפט בתיאור שלהם: “make sure there is a placeholder for the element on the page”. אלמנט לא יוצר לעצמו שורה. פותחים מקום עם Edit-Page בפעולה add-row, או יוצרים מיכל עם Add-Container-to-Page — ורק אז מציבים.

המיקום — שלוש דרכים, אותן שלוש בכל הכלים

הפרמטרים	מתי	ההערה
rowId + columnNumber	הוספה לשורה קיימת	columnNumber הוא 0‑based. ב‑RTL עמודה 0 היא הימנית
intoExistingElemId	הוספה לתוך אלמנט קיים — בדרך כלל מיכל	לא אלמנט עם המחלקה rDivider. למיכל: ה‑innerContainerId שחזר מ‑Add-Container-to-Page, לא ה‑newContainerId
elemId	עריכת אלמנט קיים	rowId שנשלח איתו מתעלמים ממנו — elemId גובר

התשובה של שלושת הכלים הראשונים: { "response": { "success": true, "msg": "counter element with id P289 added" } } — ה‑msg הוא המקום היחיד שבו חוזר מזהה האלמנט החדש. שמרו אותו. Add-Edit-Tabs-Element מחזיר success בלבד, ואת מזהה הלשוניות קוראים מהדף.

tableName נדרש גם בעריכה

הסכימה מסמנת את tableName כ‑“required when adding a new element”, אבל עריכה לפי elemId בלי tableName נכשלת ב‑Error: Table name not found in schema — במונה וגם בגרף. שלחו אותו תמיד.

elemId הוא ההבדל בין לערוך ובין לשכפל בטעות

העברת rowId + columnNumber על משבצת שכבר תפוסה מוסיפה אלמנט שני — היא לא מחליפה את הקיים. התוצאה הקלאסית: שני גרפים אחד על השני, שנראים כמו גרף אחד מקולקל. כשמעדכנים אלמנט קיים — elemId בלבד. את המזהה מוצאים ב‑Get-Page-Content(minimal: false); במצב minimal: true המונים והגרפים לא יופיעו בכלל. ומכיוון שאין כלי מחיקת אלמנט, אלמנט כפול מסתירים ב‑CSS או מוחקים את השורה כולה.

Add-Edit-Text-Element

כותרת או פסקה.

הפרמטר	טיפוס	חובה	המשמעות
pageId	String	✔	הדף. אין פרמטר pageName — המזהה בלבד
elemType	Enum	✔	H1 · H2 · H3 · H4 · P
html	String	✔	התוכן. HTML מוטבע מותר
rowId + columnNumber	String + Number	להוספה	מיקום
intoExistingElemId	String	להוספה	חלופה למיקום
elemId	String	לעריכה	האלמנט הקיים
siteId	String		האתר

JSON

{ "pageId": "<id>", "elemType": "H2",
  "html": "<font color=\"#3249b3\" style=\"font-size: 24px;\">פרטי התקשרות</font>",
  "rowId": "P280", "columnNumber": 0 }

בעריכה, elemType חייב להתאים לסוג הקיים. שינוי P ל‑H2 אינו פעולת עריכה — הוא דורש הסרה והוספה מחדש.

intoExistingElemId נתמך גם בכלי הטקסט

הפרמטר מוגדר בכלי הטקסט בדיוק כמו בשאר הכלים: תיאורו הוא “ID of the existing element to insert the text element into”, והוא נדרש בהוספת אלמנט חדש — אלא אם ממקמים דרך rowId + columnNumber.

מגבלה אחת שהתיאור מציין במפורש: אל תיתנו כאן אלמנט עם המחלקה rDivider (כלומר שורה). מיכל, עמודה או לשונית — כן; שורה — לא. הכלי לא מסרב — הוא מציב את הטקסט כאח של העמודות, מחוץ לגריד. למיקום ישירות בשורה יש rowId.

מוסכמות טיפוגרפיה של הדשבורדים המקוריים: כותרת סקשן H2 בכחול #3249b3 בגודל 24; כותרת גרף כ‑P עם border-bottom:1px solid #b5b5b5; כיתוב הסבר בגודל 12 בצבע #b5b5b5.

Add-Edit-Counter-Element

מונה KPI — מספר בודד גדול שמחושב משאילתה.

הפרמטר	טיפוס	חובה	המשמעות
pageId	String	✔	הדף
counterFunction	Enum	✔	sum-count · sum · avg · min · max
counterField	String	לכל פונקציה מלבד sum-count	השדה המספרי לחישוב. הכלי לא אוכף — avg בלי שדה מתקבל ומציג ריק
tableName	String	✔ (גם בעריכה)	הטבלה שעליה שואלים
criteria	Array<Object>		תנאי סינון — ראו למטה
format	String		פורמט מספר בתחביר Numeral.js, למשל 0,0 או 0,0.00
css	String		סגנון inline על אלמנט המונה
queryForm	String		שם טופס בדף שערכיו יסננו את התוצאה
rowId+columnNumber / intoExistingElemId / elemId			מיקום או עריכה
siteId	String		האתר

פונקציות החישוב

counterFunction	מה מחושב	counterField
sum-count	ספירת רשומות שעונות לתנאי	לא נדרש
sum	סכום ערכי שדה	נדרש
avg	ממוצע	נדרש
min / max	הערך הנמוך / הגבוה	נדרש

sum-count הוא ברירת המחדל המנטלית — “כמה פניות פתוחות”. השאר דורשים שדה Number; שדה מסוג אחר יחזיר 0 בלי שגיאה.

format — פורמט המספר

הפורמט הוא של ספריית Numeral.js, לא של Intl ולא של פורמט התאריכים של המערכת:

הפורמט	התוצאה
0,0	1,250 — פסיק לאלפים, בלי עשרוניות
0,0.00	1,250.00
0%	85%
0,0 a	קיצור לכמויות גדולות — 1890 מוצג 2 k

לסכומי כסף 0,0 הוא כמעט תמיד הנכון: מונה שמציג 1250000 נקרא שגוי בשבריר שנייה, ומונה שמציג 1,250,000 נקרא נכון.

JSON

{ "pageId": "<id>", "elemId": "P33", "tableName": "Sales",
  "counterFunction": "sum", "counterField": "Total",
  "format": "0,0", "criteria": [] }

Add-Edit-Chart-Element

גרף Chart.js — גרסה 2.9.4 (chart.min.2.9.4.js + chartjs-plugin-datalabels). זה קובע את התחביר של chartOptions ו‑chartDataset.

הפרמטר	טיפוס	חובה	המשמעות
pageId	String	✔	הדף
chartType	Enum	✔	Bar · Line · Pie · Doughnut
chartTheme	Enum	✔	ערכת צבעים — ראו הרשימה
tableName	String	✔ (גם בעריכה)	הטבלה
chartLabel	String		ציר ה‑X / הקיבוץ. מסלול Pointer: FieldId.TargetClass.FieldName
chartLabelFormat	Enum	כש‑chartLabel הוא תאריך	dow · q · q/yy · mm · mm/yy · yy · dd/mm/yy · mm/dd/yy
chartLabelSort	Enum		ascending · descending
chartCategory	String		ממד שני — פיצול לסדרות. רק ב‑Bar ו‑Line
chartCategoryFormat	Enum	כש‑chartCategory הוא תאריך	אותו enum
chartFunc	Enum		sum-count · sum · avg · min · max
chartValue	String	כש‑chartFunc אינו sum-count	השדה המספרי
chartDataset	String (JSON)		עקיפה גולמית בפורמט dataset של Chart.js 2 — כמחרוזת, ראו למטה
chartOptions	String (JSON)		עקיפה גולמית בפורמט options של Chart.js 2 — כמחרוזת, ראו למטה
criteria / queryForm			כמו במונה
rowId+columnNumber / intoExistingElemId / elemId			מיקום או עריכה
siteId	String		האתר

ערכות הנושא

ה‑enum מכיל ארבע‑עשרה:

icecream · rainyday · bluesky · grasshopper · partytime · simbla · romantic · heatwave · blooming · sunnysummer · underthesea · coldmountain · oldtown · daydream

chartTheme הוא פרמטר חובה — אין ברירת מחדל. בחרו אחת ודבקו בה בכל הגרפים באותו דף; דשבורד שכל גרף בו בערכה אחרת נראה שבור גם כשהנתונים מושלמים.

תווית מול קטגוריה

זה ההבדל שקובע איך הגרף ייראה:

• chartLabel — לפי מה מקבצים. זה ציר ה‑X בגרף עמודות, ואלה הפרוסות בעוגה.
• chartCategory — ממד שני, שמפצל כל עמודה לכמה סדרות. קיים רק ב‑Bar ו‑Line.

“מכירות לפי חודש” = chartLabel: "createdAt" עם chartLabelFormat: "mm/yy". “מכירות לפי חודש, מפוצל לפי אחראי” = אותו דבר, ועוד chartCategory: "OwnerId._User.name".

JSON

{ "pageId": "<id>", "elemId": "P52", "tableName": "Sales",
  "chartType": "Bar", "chartTheme": "bluesky",
  "chartLabel": "createdAt", "chartLabelFormat": "mm/yy", "chartLabelSort": "ascending",
  "chartCategory": "SaleStatusId.SaleStatuses.Name",
  "chartFunc": "sum", "chartValue": "Total",
  "criteria": [] }

עקיפות Chart.js גולמיות

chartDataset ו‑chartOptions נכתבים למאפייני data-chart-options / data-chart-dataset של האלמנט ומועברים לספרייה. זו הדרך היחידה לשלוט בכל מה שהערכות לא נותנות.

מגבלה ידועה — להעביר מחרוזת JSON, ובתחביר Chart.js 2

1. אובייקט JSON נשמר כ‑"[object Object]". הסכימה לא מגדירה טיפוס, והכלי משרשר את הערך כמו שהוא — התוצאה היא data-chart-options="[object Object]" ושגיאת קונסול chart data are not volid json. העבירו את האובייקט כמחרוזת (JSON.stringify) — אז הוא נשמר ומיושם.
2. התחביר הוא של Chart.js 2.9.4, לא 3/4: legend ו‑scales.yAxes[] ברמה העליונה, צבעים ב‑fontColor. מפתחות של גרסה 3 (plugins.legend, scales.y, ticks.color) מתקבלים ומתעלמים מהם. כך נראים ה‑options של הדשבורדים המקוריים.

JSON

{ "pageId": "<id>", "elemId": "P52", "tableName": "Sales",
  "chartType": "Bar", "chartTheme": "bluesky",
  "chartOptions": "{\"legend\":{\"position\":\"bottom\",\"labels\":{\"fontColor\":\"#252C57\",\"fontSize\":13}},\"scales\":{\"yAxes\":[{\"ticks\":{\"beginAtZero\":true,\"fontColor\":\"#252C57\"}}],\"xAxes\":[{\"barPercentage\":0.3}]}}" }

legend.position: "bottom" בתחביר הזה מופיע ברינדור.

טקסט של גרף אינו ניתן לצביעה ב‑CSS

הגרף מצויר על <canvas> — הוא תמונה רסטרית, לא DOM. כלל CSS שמכוון לצבעי הדף לא ישפיע על תוויות הצירים, המקרא או ה‑tooltips. כל שינוי טיפוגרפיה או צבע בתוך הגרף עובר דרך chartOptions. זו לא העדפה, זו המגבלה היחידה שיש.

Add-Edit-Tabs-Element

רצועת לשוניות.

הפרמטר	טיפוס	חובה	המשמעות
pageId	String	✔	הדף
newTabs	Array<{label}>	להוספה	הלשוניות. לפחות אחת ביצירת אלמנט חדש
elemId	String	לעריכה	אלמנט הלשוניות הקיים
updateTabs	Array<{id,label}>		שינוי כותרת ללשוניות קיימות
deleteTabs	Array<String>		מזהי לשוניות למחיקה
rowId + columnNumber / intoExistingElemId		להוספה	מיקום
siteId	String		האתר

JSON

// יצירה
{ "pageId": "<id>", "rowId": "P300", "columnNumber": 0,
  "newTabs": [ { "label": "פרטים" }, { "label": "מסמכים" }, { "label": "היסטוריה" } ] }

// עריכה — שינוי אחת, מחיקת אחרת, הוספת שלישית
{ "pageId": "<id>", "elemId": "P312",
  "updateTabs": [ { "id": "<tabId>", "label": "פרטי ההתקשרות" } ],
  "deleteTabs": [ "<tabId2>" ],
  "newTabs":    [ { "label": "חיובים" } ] }

לשונית היא מיכל — ומיכל הוא מלכודת מיקום

תוכן שמוצב “בתוך לשונית” יושב בתוך אלמנט simbla-nav. שני דברים נובעים מזה:

1. טבלת רשומות מקושרות שנוחתת בטעות בתוך רצועת לשוניות מאבדת את הסינון האוטומטי לרשומה הפתוחה, ולרוב גם לא נראית. אחרי כל הצבה — קראו את הדף וּודאו שאף אב של הווידג’ט אינו simbla-nav או simbla-table.
2. מזהי הלשוניות אינם מזהי האלמנטים שבתוכן. deleteTabs ו‑updateTabs מקבלים את מזהה הלשונית, בפורמט <elemId>tab<N> — למשל P307tab1, P307tab2 — שמופיע ב‑Get-Page-Content גם ב‑<a href="#P307tab1"> וגם כ‑id של ה‑tab-pane. מזהה אחר מחזיר Error: Tab with id … not found. המספור ממשיך אחרי מחיקה (לשונית חדשה אחרי מחיקת tab2 תהיה tab4/tab5, לא tab2). ה‑tab-pane הוא יעד תקין ל‑intoExistingElemId של אלמנט טקסט/מונה/גרף.

הסינון — criteria

שלושת הכלים המבוססים על שאילתה (מונה, גרף, ובעקיפין טבלת תצוגה) מקבלים את מבנה התנאי B — אותו מבנה של הטריגרים:

המפתח	חובה	המשמעות
F	✔	שם השדה. מסלול Pointer: OwnerId._User.name
C	✔	האופרטור
T	✔	טיפוס הערך — String · Number · Pointer · Boolean · Date
V	✔	הערך
P	ל‑Pointer	{ targetClass ✔, visibleVal, multiple }
FText		תווית לתצוגה

האופרטורים ב‑enum של שני הכלים האלה — עשרה: contains · startsWith · equalTo · greaterThan · lessThan · greaterThanOrEqualTo · lessThanOrEqualTo · notEqualTo · containedIn · notContainedIn

שני ערכי V מיוחדים

• "currentUser" — ב‑Pointer ל‑_User. כך בונים “המכירות שלי” בלי לקבע מזהה משתמש.
• "formName:fieldName" — קורא את הערך מתוך שדה בטופס שעל הדף, בזמן השאילתה. זה המנגנון שמאחורי מסנני התאריך של הדשבורדים: המשתמש בוחר טווח ולוחץ “הפעל”, והמונים והגרפים נשאלים מחדש.

JSON

"criteria": [
  { "F": "createdAt", "C": "greaterThanOrEqualTo", "T": "Date", "V": "genericform:FromDate" },
  { "F": "createdAt", "C": "lessThanOrEqualTo",     "T": "Date", "V": "genericform:ToDate" },
  { "F": "OwnerId",   "C": "equalTo", "T": "Pointer", "V": "currentUser",
    "P": { "targetClass": "_User" } }
]

תנאי שמפנה לשדה טופס שאינו קיים — לא נכשל, פשוט מאפס

אם השדה genericform:FromDate לא קיים בדף, התנאי לא מייצר שגיאה. הוא מתנהג כתנאי ריק, והתוצאה היא מונה שמראה 0 או גרף בלי עמודות — בלי שום רמז לסיבה. זו התקלה מספר 1 בשכפול דשבורדים: העותק נושא את התנאים של המקור, שמפנים לשדות שלא הועתקו. הכלל: בכל עריכה של אלמנט משוכפל, העבירו criteria: [] במפורש — ורק אז הוסיפו את התנאים שלכם.

שתי ההתנהגויות שמפתיעות

1. אלמנט בתוך דף כרטיס מסונן אוטומטית לרשומה הפתוחה

תיאור הכלי אומר את זה במפורש: אם המונה או הגרף יושבים בתוך טופס, והטבלה שהם שואלים עליה מחזיקה שדה Pointer למחלקה של הטופס — הנתונים מסוננים אוטומטית לרשומה הנוכחית, בלי שום criteria. הדוגמה מהתיאור: מונה על Sales בתוך הכרטיס של Accounts מסונן לבד לפי AccountId של הלקוח הפתוח. כך באמת עובדים המונים והטבלאות של הכרטיסים המובנים.

היסטוריה — הסינון האוטומטי לא פעל על מונה/גרף שנוצרו ב‑MCP

בגרסאות שרת ישנות, Add-Edit-Counter-Element ו‑Add-Edit-Chart-Element כתבו את מפת ה‑Pointers תחת שם שגוי — data-pointers-fields בקידוד כפול, במקום data-class-pointers שהריצה (simbla.js) קוראת — ולכן מונה בתוך כרטיס הציג את סך כל המערכת במקום נתוני הרשומה הפתוחה. המעקף היה לכתוב את האלמנט ידנית ב‑set-html-content עם data-class-pointers מקודד פעם אחת.

בשרת עדכני שני הכלים כותבים data-class-pointers בקידוד יחיד, והמונים והגרפים בתוך כרטיס מסוננים לרשומה הפתוחה. מול שרת ישן המעקף הידני עדיין תקף.

ושתי הסתייגויות: הסינון האוטומטי עובד רק כשקיים שדה Pointer מתאים בסכימה; וסינון ידני שתוסיפו ב‑criteria אמור להצטרף לסינון האוטומטי, לא להחליף אותו.

2. כל עריכת דף דורשת רענון בדפדפן

השינוי נשמר בשרת מיד, ולא מופיע במסך פתוח. כל ארבעת הכלים מסיימים באותה המלצה: “suggest the user to reload the page to see the changes”.

• שינוי אלמנט → רענון רגיל.
• שינוי jsFile / cssFile → רענון קשיח (Ctrl+F5), כי הקובץ נמצא במטמון.

זה נשמע טריוויאלי, והוא הגורם מספר 1 ל“הכלי אמר שהצליח אבל לא רואים כלום” — ולתיקון חוזר של משהו שכבר תוקן.

כשהאלמנט לא מציג מה שציפיתם

התסמין	הסיבה הסבירה
מונה מציג 0 כשיש נתונים	תנאי שמפנה לשדה טופס שאינו קיים בדף (מציג 0, לא שגיאה) · counterField שגוי או לא מספרי (max על String → 0) · תנאים מגבילים מדי
מונה ריק לגמרי	avg/sum בלי counterField
גרף עם צירים ובלי עמודות	חוסר התאמה בתנאים · chartValue ריק ברשומות
גרף ריק (canvas בלי ציור) ו‑HTTP 400 ברשת	chartLabel/chartCategory עוברים דרך טבלת lookup שאין עליה הרשאת find — טבלה מ‑newTableName נולדת כך (מגבלה ידועה) · chartOptions שנשלח כאובייקט ([object Object])
המונה בכרטיס מציג את כל המערכת	בגרסאות שרת ישנות הסינון האוטומטי לא פעל על אלמנטי MCP — ראו הערת ההיסטוריה; בשרת עדכני — בדקו שקיים שדה Pointer מתאים בסכימה
עמודה אחת ענקית	chartLabel הוא טקסט חופשי — החליפו לשדה קטגוריה
פרוסה בשם “Unknown” בעוגה	תוויות null — סננו אותן החוצה בתנאי
שני גרפים במשבצת אחת	הוספתם במקום לערוך — חסר elemId
הכול ריק אצל משתמש מסוים ותקין אצלכם	CLP — למשתמש אין find על הטבלה. בדקו ב‑הרשאות
השינוי לא נראה בכלל	הדף לא רוענן

המשך

• עריכת דפים ואלמנטים — לפתוח שורה ולייצר מיכל
• אתרים ודפים — קריאה — למצוא את rowId ואת elemId
• טבלאות תצוגה ודפי רשימה — האלמנט החמישי בדשבורד
• דוחות — כשהמספר צריך להיות טבלה ולא מונה
• תפריטים — להוסיף את הדשבורד לתפריט
• אינדקס הכלים המלא