סקירה כללית של סכימת הטופס
בקטלוג השירותים, אחד מסוגי הפתרונות הנתמכים הוא הגדרות של Deployment Manager. כדי לעזור לכם ליצור ולפרוס הגדרות של Deployment Manager, אנחנו מציעים את Form Schema.
סכימת טופס משמשת לפריסת רכיבי ממשק משתמש (UI) בטופס HTML. באופן ספציפי, הוא מאפשר לאדמינים ולמפתחים בענן לספק ממשק משתמש להזנת פרמטרים כשיוצרים מכונה חדשה או פריסה בענן.
אדמינים ב-Cloud משתמשים בסכימת טופס כדי ליצור טפסים שמאפשרים למשתמשים להתאים אישית פתרונות שמבוססים על תבניות של Deployment Manager לפני שהם מפעילים את הפתרונות. לדוגמה, המשתמשים יכולים לבחור את סוג המכונה, גודל הדיסק, האזור ומספר יחידות ה-CPU שיהיו למכונה הווירטואלית. הטפסים האלה דומים לטפסים שמשמשים ב-Cloud Marketplace.
בצילום המסך הבא אפשר לראות איך נראה טופס פריסה:
חלופות לסכימת טופס
סכימת טופס היא חלופה לדרך קיימת ליצירת טפסים בממשק משתמש, שנקראת 'הצגת מטא-נתונים'.
בהשוואה למטא-נתונים של מודעות לרשת המדיה, סכימת הטופס גמישה יותר וקוד פתוח.
הקשר לסכימת JSON
סכימת הטופס מבוססת על טופס סכימת JSON, שהיא סכימה בקוד פתוח שנכתבה ב-JSON כדי לציין ולאמת קבוצה של פרמטרים.
סכימת הטופס מפנה לשדות בסכימת ה-JSON ומקבלת ממנה מאפיינים בירושה.
אפשר לכלול סכימת טופס בתוך סכימת ה-JSON על ידי הוספת מערך של אובייקטים form entry בתוך המאפיין form, כמו בדוגמה הבאה:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {...}
"form": [
...Form List goes here...
]
}
איך מציינים מופע של סכימת טופס
אפשר לציין מופעים של סכימת טופס בפורמט YAML.
יוצרים קובץ סכימה שמגדיר את הווידג'טים של ממשק המשתמש בסדר שבו הם צריכים להופיע בממשק המשתמש. לקובץ הסכימה הזה יש סיומת קובץ .py או .jinja, כמו שמתואר במסמכי Deployment Manager.
אחר כך מוסיפים את הקבצים לארכיון zip של תבנית Deployment Manager ומעלים את ארכיון ה-zip.
איך סכימת הטופס משתלבת בתהליך העבודה של קטלוג השירותים
אדמינים ב-Cloud משתמשים בסכימת טופס עם קטלוג השירותים באופן הבא:
- יוצרים תבנית Deployment Manager.
- מציינים סכימת JSON כדי להגדיר או לאמת אילו שדות קלט אפשר להשתמש בהם בממשק המשתמש להגדרת תבנית Deployment Manager.
- מגדירים בסכימת הטופס אילו שדות לכלול בפתרון מסוים ובאיזה סדר השדות האלה צריכים להופיע. בנוסף להזמנה, אפשר להשתמש בסכימת הטופס כדי לספק טקסט ידידותי למשתמש בשדות ממוספרים, כמו תפריטים נפתחים, ולקבץ שדות יחד עם כותרות של קטעים.
רשימת טפסים
מערך של אובייקטים מסוג form entry. כל אובייקט מייצג רכיב בממשק המשתמש בטופס. צריך לציין את השדות בסדר שבו רוצים שהם יופיעו בטופס, בלי קשר למיקום שלהם בסכימה.
הזנת נתונים בטופס
רכיב בטופס שמציין את המראה של רכיב בממשק המשתמש בטופס. הוא יכול להיות מחרוזת, שבה מצוין המפתח של שדה בסכימת JSON, או אובייקט. כשערך של רשומה בטופס הוא מחרוזת, ערכי ברירת המחדל של המראה עוברים בירושה מהרשומה בסכימת ה-JSON.
כשערך של טופס הוא אובייקט, המאפיין key מתייחס לערך של סכימת ה-JSON. כדי להפריד בין צמתים של ערך מקונן, משתמשים בנקודה .. לדוגמה, משתמשים ב-name.first כדי להפנות לשדה first בתוך אובייקט name. כל שאר השדות הם אופציונליים, ואם מציינים אותם, הם מקבלים ערך ברירת מחדל מ-JSON Schema.
| שדות | |
|---|---|
key* | Stringמציין את הגדרת השדה בסכימת ה-JSON. |
widget | Widgetמציינת את הווידג'ט של ממשק המשתמש שבו יש להשתמש בשדה הזה. ברירת מחדל: מבוסס על מיפוי סוג השדה. |
title | Stringהשם של השדה. המאפיין title עובר בירושה מהסכימה. |
notitle | Booleanהאם להסתיר את שם הספר. ברירת מחדל: false. |
description | Stringמשמש כרמז או כהסבר קצר לשדה. המאפיין description עובר בירושה מהסכימה. |
validationMessage | Stringההודעה שתוצג אם השדה לא תקין. |
placeholder | StringPlaceholder לשדה. הערה: ב-Material Design משתמשים ב- title כ-placeholder במקום. |
readonly | Booleanהאם השדה הוא לקריאה בלבד. המאפיין readonly עובר בירושה מהסכימה. |
condition | Stringביטוי לוגי שקובע אם השדה מוצג. |
titleMap | Title mapמספק תוויות טקסט לאפשרויות בווידג'טים checkboxes, radio ו-select. |
* חובה
טיפול מיוחד בסוגים
אובייקט
עבור הסוג object, השדה additionalProperties מגדיר אם יכולות להיות תכונות נוספות. הערך של השדה יכול להיות true (מאפשר הכול), false (לא מאפשר מאפיינים נוספים) או סכימת JSON שמגבילה את המאפיינים הנוספים שמותרים. אם הערך הוא false או לא מוגדר, הווידג'טים מוצגים בשדות שמפורטים במאפיין items. לערכים אחרים (true או סכימת JSON), מוצג אזור טקסט להזנת ערך JSON.
מיפוי של סוגים לווידג'טים
אם לא מציינים ווידג'ט בסכימת הטופס, המערכת משתמשת בערך ברירת מחדל על סמך סוג סכימת ה-JSON של השדה, באופן הבא:
| סוג הסכימה | ווידג'ט של טופס סכימה |
|---|---|
| מחרוזת | טקסט |
| מספר | number |
| מספר שלם | number |
| בוליאני | תיבת סימון |
| אובייקט | fieldset |
| מחרוזת + טיפוסים בני מנייה (enum) | radio (3 or less choices) |
| מחרוזת + טיפוסים בני מנייה (enum) | בחירה (4 אפשרויות או יותר) |
| array + enum | תיבות סימון |
| מערך | array |
ווידג'ט
הווידג'ט מצוין כמחרוזת שמתייחסת לאחת ממבני הנתונים הבאים.
מערך
רשימה שאפשר להוסיף, להסיר ולסדר בה מחדש שורות. ב-JSON Schema, הנכס items של סוג array יכול להיות סכימה או רשימה של סכימות. הרשימה לא נתמכת על ידי סכימת הטופס.
מערכים עם פריטים פרימיטיביים
סכימת הטופס מחייבת שלכל רשומה בטופס יהיה מפתח. למערכים שמכילים פריטים פרימיטיביים (לא אובייקטים) אין מפתח שאפשר להפנות אליו, ולכן הטופס צריך להפנות לרשומה במערך הפרימיטיבי באמצעות מילת מפתח שמורה: x-googleProperty.
לדוגמה, כך מגדירים מערך של סכימת JSON שמכיל מחרוזות:
{
'exampleArray': {
'type': 'array',
'items': {
'type': 'string'
}
}
}
אחר כך צריך להפנות אליו בסכימת הטופס באופן הבא:
[
{
'key': 'exampleArray',
'widget': 'array',
'items': [
{
'key': 'exampleArray.x-arrayPrimitive'
}
]
},
]
מערכים עם פריטים מסוג אובייקט
במערכים שמכילים אובייקטים צריך לציין כל מפתח בסוג הפריט שצריך להציג בטופס.
לדוגמה, נניח שיש מערך של סכימת JSON שמכיל אובייקט:
{
'exampleArray': {
'type': 'array',
'items': {
'type': 'object',
'properties': {
'someArrayItemAttribute': {
'type': 'string'
}
}
}
}
}
סכימת הטופס שנדרשת כדי ליצור מערך טפסים עם קלט למאפיין someArrayItemAttribute היא:
[
{
'key': 'exampleArray',
'widget': 'array',
'items': [
{
'key': 'exampleArray.someArrayItemAttribute'
}
]
},
]
תיבת סימון
שדה להזנת קלט מסוג checkbox.
תיבות סימון
רשימה של שדות קלט מסוג checkbox. השדה JSON Schema צריך להיות מסוג array ולכלול מאפיין enum. כדי לספק תוויות לאפשרויות, אפשר לציין titleMap.
אקספנדר
דומה מאוד לקטע, אבל השדות מוצבים בווידג'ט של חלונית הרחבה שהמשתמשים יכולים לפתוח ולסגור בלחיצה על הכותרת.
מספר
שדה להזנת קלט מסוג number. המאפיינים הבאים מסכימת ה-JSON הם מאמתים של השדה: minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf.
סיסמה
שדה להזנת קלט מסוג password.
רדיו
שדה להזנת קלט מסוג radio. משתמשים בזה לשדות שיש להם רשימה enum בסכימת JSON, או שהם מסוג בוליאני. כדי לספק תוויות לאפשרויות, אפשר לציין titleMap.
קטע
הווידג'ט הזה מקבץ יחד קבוצה של שדות. המערכת מתעלמת מהשדה key. לכל קטע יש מאפיין חובה items, שהוא מערך של אובייקטים מסוג form entry. לכל קטע יכולים להיות המאפיינים האופציונליים הבאים: title, description, condition.
בחירה
שדה להזנת קלט select. משתמשים בזה לשדות שיש להם רשימה enum בסכימת ה-JSON, או שהם מסוג בוליאני. כדי לספק תוויות לאפשרויות, אפשר לציין titleMap.
טקסט
ווידג'ט קלט עם הסוג text. אם סכימת ה-JSON מכילה מאפיין pattern, התבנית משמשת ככלי לתיקוף ביטוי רגולרי.
Textarea
ווידג'ט קלט של textarea. בווידג'ט הזה אפשר להזין JSON ישירות במקרים מסוימים. מידע נוסף זמין במאמר בנושא אובייקט.
מפת כותרות
אפשר לציין את המאפיין titleMap בווידג'טים מהסוגים checkboxes, radio ו-select. המערכת מתעלמת מהשדה הזה בווידג'טים אחרים.
המאפיין הוא מערך של אובייקטים שמכילים שני מאפיינים, value ו-name. המאפיין value הוא הפניה לערך enum אחד בשדה.
המאפיין name הוא טקסט שמשמש כתווית לאפשרות התואמת בווידג'ט של ממשק המשתמש. כשבוחרים באפשרות radio או checkboxes, נוסף שדה description אופציונלי כטקסט משני ללחצן הבחירה או לתיבת הסימון.
אם לא מציינים titleMap, המערכת משתמשת בערכי ה-enum.
תכונות שלא נתמכות
התכונות הבאות לא נתמכות כרגע בסכימת הטופס:
- אפשרויות כלליות
- הודעות אימות מורכבות (רק הודעה אחת נתמכת)
- אינטרפולציה של הודעות אימות
- פונקציות של הודעות אימות
- אימות מותאם אישית
- ווידג'טים שלא נתמכים:
actions,fieldset,radios-inline,radiobuttons,help,template,tab,tabarray - אפשרויות שלא נתמכות:
onChange,feedback,disabledSuccessState,disabledErrorState,ngModelOptions,htmlClass,fieldHtmlClass,labelHtmlClass,copyValueTo,destroyStrategy - פונקציית עיבוד תמונה (Post Processing)
- אירועים
- הוספה ידנית של שדות