Schema Components: Settings, Blocks, and Presets

This guide covers the three key components of section schemas: Settings, Blocks, and Presets. Understanding these components is essential for creating flexible, user-friendly sections.

Settings

Settings are individual form fields that control specific aspects of a section's appearance or behavior. Each setting has a type, default value, and user-facing label.

Example Settings Schema

{
  "name": "Product Gallery",
  "settings": [
    {
      "type": "header",
      "id": "content_header",
      "label": "Content Settings"
    },
    {
      "type": "text",
      "id": "heading_text",
      "label": "Section heading",
      "default": "Product Images"
    },
    {
      "type": "textarea",
      "id": "description",
      "label": "Gallery Description",
      "default": "Browse our product images"
    },
    {
      "type": "select",
      "id": "gallery_layout",
      "label": "Gallery Layout",
      "options": [
        { "value": "grid", "label": "Grid" },
        { "value": "carousel", "label": "Carousel" },
        { "value": "stacked", "label": "Stacked" }
      ],
      "default": "grid"
    },
    {
      "type": "range",
      "id": "columns_count",
      "label": "Columns per row",
      "min": 2,
      "max": 6,
      "step": 1,
      "default": 4
    },
    {
      "type": "checkbox",
      "id": "show_thumbnails",
      "label": "Show thumbnail navigation",
      "default": true
    },
    {
      "type": "color_background",
      "id": "background_color",
      "label": "Background color",
      "default": "#ffffff"
    }
  ]
}

Available Setting Types

Text & Content

Type	Description	Example Value
`text`	Single-line text input	`"Welcome"`
`textarea`	Rich text editor with formatting	`"<p>Hello</p>"`
`html`	Raw HTML code editor	`"<div>Custom</div>"`

Layout & Style

Type	Description	Example Value
`select`	Dropdown menu	`"center"`
`radio`	Radio button tabs	`"grid"`
`checkbox`	Toggle switch (yes/no)	`true` or `false`
`range`	Slider with min/max	`24`
`text_alignment`	Alignment picker	`"left"`, `"center"`, `"right"`
`color_background`	Color picker (solid + gradients)	`"#ff0000"` or `"linear-gradient(...)"`

Media & Assets

Type	Description	Example Value
`image_picker`	Image from media library	`"https://cdn.example.com/image.jpg"`
`video_picker`	Video from media library	`"https://cdn.example.com/video.mp4"`
`font_picker`	Font selector	`"Arial"`

Type	Description	Example Value
`url`	URL input with validation	`"https://example.com"`
`link_list`	List of navigation links	`["/home", "/products"]`

Single Resource Selectors

Type	Description	Example Value
`product`	Select one product	`123`
`collection`	Select one collection	`456`
`posts`	Select one blog post	`789`
`category`	Select one category	`101`
`enrollment_pack`	Select one enrollment pack	`202`

Multiple Resource Selectors

Type	Description	Example Value
`product_list`	Select multiple products	`[123, 456, 789]`
`collections_list`	Select multiple collections	`[123, 456]`
`posts_list`	Select multiple blog posts	`[123, 456]`
`categories`	Select multiple categories	`[123, 456]`
`enrollment_list`	Select multiple enrollments	`[123, 456]`

Organization

Type	Description
`header`	Creates collapsible sections (doesn't store data)

Important Notes

Using Color Gradients

The color_background setting can hold both solid colors and gradients. When using gradients in your template, use background instead of background-color:

<!-- ✅ Works with both solid colors and gradients -->
<div style="background: {{ section.settings.background_color }}">

<!-- ❌ Only works with solid colors, gradients won't show -->
<div style="background-color: {{ section.settings.background_color }}">

Always Provide Default Values

Every setting needs a default value that matches what type of data it stores:

Text settings: Use "" or sample text
Number settings: Use 0 or a reasonable number
Toggle switches: Use true or false
Single resource selectors: Use null or a resource ID
Multiple resource selectors: Use [] or an array of IDs
Link lists: Use [] or an array of URLs

Blocks

Blocks are dynamic content items that can be added, removed, and reordered within a section. Each block has its own settings and can represent different content types.

Example Block Schema

{
  "name": "Testimonials Section",
  "settings": [
    {
      "type": "text",
      "id": "section_title",
      "label": "Section Title",
      "default": "What Our Customers Say"
    }
  ],
  "blocks": [
    {
      "type": "testimonial",
      "name": "Customer Testimonial",
      "limit": 10,
      "settings": [
        {
          "type": "text",
          "id": "customer_name",
          "label": "Customer Name",
          "default": ""
        },
        {
          "type": "textarea",
          "id": "testimonial_text",
          "label": "Testimonial",
          "default": ""
        },
        {
          "type": "image_picker",
          "id": "customer_photo",
          "label": "Customer Photo",
          "default": ""
        },
        {
          "type": "range",
          "id": "star_rating",
          "label": "Star Rating",
          "min": 1,
          "max": 5,
          "step": 1,
          "default": 5
        }
      ]
    },
    {
      "type": "video_testimonial",
      "name": "Video Testimonial",
      "limit": 3,
      "settings": [
        {
          "type": "video_picker",
          "id": "testimonial_video",
          "label": "Testimonial Video",
          "default": ""
        }
      ]
    }
  ]
}

Block Characteristics

Dynamic Quantity: Users can add/remove blocks as needed
Reorderable: Blocks can be dragged to change their sequence
Type-Specific: Different block types have different settings
Limited: Optional limit property restricts maximum blocks

Presets

Presets provide ready-to-use configurations that combine section settings with a predefined set of blocks, giving users a starting point for common use cases.

Example Preset Schema

{
  "name": "Feature Showcase",
  "settings": [
    {
      "type": "text",
      "id": "section_heading",
      "label": "Section Heading",
      "default": "Key Features"
    }
  ],
  "blocks": [
    {
      "type": "feature_item",
      "name": "Feature",
      "settings": [
        {
          "type": "text",
          "id": "feature_title",
          "label": "Feature Title",
          "default": ""
        },
        {
          "type": "textarea",
          "id": "feature_description",
          "label": "Feature Description",
          "default": ""
        }
      ]
    }
  ],
  "presets": [
    {
      "name": "Basic Features (3 items)",
      "settings": {
        "section_heading": "Why Choose Us"
      },
      "blocks": [
        {
          "type": "feature_item",
          "settings": {
            "feature_title": "Fast Delivery",
            "feature_description": "Get your order in 24 hours"
          }
        },
        {
          "type": "feature_item",
          "settings": {
            "feature_title": "Quality Guarantee",
            "feature_description": "100% satisfaction guaranteed"
          }
        },
        {
          "type": "feature_item",
          "settings": {
            "feature_title": "Expert Support",
            "feature_description": "24/7 customer service"
          }
        }
      ]
    }
  ]
}

Preset Benefits

Quick Setup: Users start with pre-configured content
Best Practices: Presets demonstrate optimal configurations
Inspiration: Show users what's possible with the section
Consistency: Common use cases follow established patterns

How They Work Together

User Selects Preset: When adding a section, user chooses a preset
System Applies Configuration: Section gets the preset's settings and blocks
User Customizes Settings: User modifies section through settings panel
User Manages Blocks: User can edit, reorder, add, or remove blocks
Final Rendering: Section template renders with customized data

Reserved Section IDs

When creating sections, certain IDs are reserved by the system:

⚠️ Reserved IDs (Cannot Use):

main_navbar - Reserved for main navigation
main_footer - Reserved for main footer

What You Can Do:

✅ Edit their settings (colors, fonts, content)
✅ Customize appearance through the editor
✅ Configure their content

What You Cannot Do:

❌ Delete reserved sections
❌ Create sections with reserved IDs
❌ Clone sections with reserved IDs

Best Practices

1. Organize Settings into Groups

Use header settings to create collapsible groups:

{
  "settings": [
    { "type": "header", "id": "content_group", "label": "Content Settings" },
    // ... content settings ...
    { "type": "header", "id": "style_group", "label": "Style Settings" }
    // ... style settings ...
  ]
}

2. Pick the Right Setting Type

Use text_alignment for alignment (gives visual picker)
Use color_background for colors that might be gradients
Use textarea when users need formatting options
Use range for bounded numeric values

3. Set Limits on Collections

{
  "type": "product_list",
  "id": "featured_products",
  "label": "Featured Products",
  "default": [],
  "limit": 10
}

4. Write Clear Labels

Use simple, descriptive labels that tell users exactly what each setting does.