definition.json: שדות וערכי ברירת מחדל

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

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

{
  "contractVersion": 1,
  "presentationId": "studio",
  "version": 1,
  "name": "Studio website",
  "routes": ["/"],
  "fields": [
    {
      "id": "hero",
      "label": "Opening section",
      "type": "group",
      "required": true,
      "fields": [
        {
          "id": "title",
          "label": "Main headline",
          "type": "text",
          "required": true,
          "maxLength": 120
        },
        {
          "id": "summary",
          "label": "Short introduction",
          "type": "text",
          "maxLength": 600
        },
        {
          "id": "image",
          "label": "Cover image",
          "type": "asset"
        }
      ]
    },
    {
      "id": "showServices",
      "label": "Show services",
      "type": "boolean"
    },
    {
      "id": "services",
      "label": "Services",
      "type": "list",
      "required": true,
      "minItems": 1,
      "maxItems": 6,
      "fields": [
        {
          "id": "title",
          "label": "Service name",
          "type": "text",
          "required": true,
          "maxLength": 80
        },
        {
          "id": "summary",
          "label": "Description",
          "type": "text",
          "maxLength": 500
        },
        {
          "id": "image",
          "label": "Service image",
          "type": "asset"
        },
        {
          "id": "href",
          "label": "Read more link",
          "type": "link"
        }
      ]
    },
    {
      "id": "business",
      "label": "Business details",
      "type": "group",
      "required": true,
      "fields": [
        {
          "id": "name",
          "label": "Business name",
          "type": "text",
          "required": true,
          "maxLength": 120
        },
        {
          "id": "phone",
          "label": "Phone number",
          "type": "text",
          "maxLength": 40
        }
      ]
    }
  ],
  "defaults": {
    "hero": {
      "title": "Design that moves your business forward",
      "summary": "Meet the studio and explore our work."
    },
    "showServices": true,
    "services": [
      {
        "title": "Brand design",
        "summary": "A visual identity built around your business.",
        "href": "/contact-us"
      }
    ],
    "business": {
      "name": "Studio",
      "phone": "+972501234567"
    }
  }
}

זהות וגרסאות

presentationId מזהה את האתר הזה; שמרו עליו יציב בין גרסאותיו.
name הוא שם קריא לבני אדם.
version היא גרסת הגדרת התוכן שלכם. כשמשנים מבנה תוכן קיים, תכננו כיצד להעביר ערכים שמורים לגרסה הבאה באמצעות migrations.json.
contractVersion: 1 מזהה את מבנה הקובץ. אין קשר בינו לבין version, גרסת חבילת ה־SDK או גרסת ה־CLI.
routes הוא שדה חובה בחוזה וחייב לכלול את /. באתר שבדוגמה השתמשו ב־["/"]; אין צורך לרשום את הנתיבים המנוהלים של הפלטפורמה.

נתיבי הבלוג שייכים לפלטפורמה

ה־SDK יוצר אוטומטית את נתיבי רשימת הבלוג, העימוד והמאמרים מתוך הבלוגים והתוכן של הפלטפורמה. אין צורך לרשום בקובץ הזה את /blogs/:blogSlug או את /blogs/:blogSlug/:slug. הפלטפורמה מספקת גם נתיבים מנוהלים לדפי תוכן וליצירת קשר.

routes אינו מתג להפעלה או לביטול של הדפים האלה: השמטת הנתיבים שלהם אינה מסירה אותם. גם הוספת נתיב מותאם כאן אינה יוצרת דף Astro.

בנפרד, data.json יכול לבקש מאמרים להצגה ברכיבי דף הבית שלכם. הבקשה קוראת תוכן מהפלטפורמה; היא אינה רושמת נתיבי בלוג ואינה מחייבת אתכם לבנות בלוג.

השדות הופכים לערכים

מזהה id הוא מפתח לשימוש בקוד; label היא התווית שרואה בעל האתר. סוג group יוצר אובייקט מקונן, ו־list יוצר מערך של אובייקטים. בדוגמה:

הגדרה	ערך ברכיב
`hero` ← `title`	`content.hero.title`
`showServices`	`content.showServices`
`services` ← פריט ← `title`	`content.services[0].title`
`business` ← `phone`	`content.business.phone`

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

ברירות מחדל הן ערכי התחלה

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

שדות תמונה מכילים מזהי נכסים כמחרוזות, ולא כתובות של תמונות. הדוגמה משמיטה בכוונה מזהי תמונות: הקובץ assets.json מספק תמונה ארוזה ומקשר אותה ל־hero.image.

המאפיינים required ו־minItems נאכפים בעת פרסום. טיוטה יכולה להישאר לא גמורה. המגבלות maxLength ו־maxItems מגינות גם על עריכה רגילה. שינוי תווית או סידור העורך שונה משינוי מזהה: שינוי מזהה משנה את מבנה התוכן ועלול לדרוש מיגרציה.

לאחר עריכה צרו טיפוסים מחדש ואמתו את הפרויקט. מאפיינים לא מוכרים גורמים לשגיאה; אל תוסיפו מפתחות שאינם נתמכים כמו placeholder, ‏help או visibleWhen.