Hyvä CMS Component Fields and Validation

This page covers configuring a Hyvä CMS component's fields beyond the basics: HTML5 validation and input attributes, reusing common field groups, and offering style variants. To create a component from scratch, start with Creating Components.

Component Field Sections

The content property defines fields displayed in the component's Content section. You can similarly add fields to the design and advanced sections to organize different types of configuration options. Design fields typically control visual styling, while advanced fields handle technical settings like CSS classes and block IDs.

Adding HTML5 Validation and Field Attributes

Hyvä CMS components support HTML5 validation attributes to provide immediate feedback to content editors. The attributes property in your component field declaration adds validation rules and input constraints.

Example component with field validation:

{
  "my_component": {
    "content": {
      "text_field": {
        "type": "text",
        "label": "Text Field",
        "attributes": {
          "required": true,
          "minlength": "1",
          "maxlength": "100",
          "pattern": ".*(foo|bar|Foo|Bar).*",
          "comment": "This is a comment",
          "placeholder": "Enter text here"
        }
      }
    }
  }
}

The example above adds several validation constraints to a text field:

• required: Field must have a value before saving
• minlength / maxlength: Enforces character count limits
• pattern: Validates against a regular expression
• comment: Displays helper text below the field
• placeholder: Shows example text in empty fields

These validation rules run in the browser before content is saved, providing immediate feedback to content editors. For more information about available attributes, see the Component Declaration Schema attributes reference.

Adding Advanced Email Validation to Text Fields

HTML5 pattern attributes enable custom validation rules for Hyvä CMS component text fields. This example shows email validation with a custom error message.

Example email field with pattern validation:

{
  "email_field": {
    "type": "text",
    "label": "Email Address",
    "attributes": {
      "required": true,
      "pattern": "[a-z0-9._%+-]+@[a-z0-9.-]+\\.[a-z]{2,}$",
      "data-validation-message": "Please enter a valid email address"
    }
  }
}

The pattern attribute validates input against the regular expression. The data-validation-message attribute provides a custom error message when validation fails. Note that backslashes in the pattern must be escaped in JSON.

Reusing Common Fields with Includes

The includes property allows you to reuse common field definitions across multiple Hyvä CMS components. This is particularly useful for shared design settings and advanced options that should be consistent across many components.

Example: Including shared design fields:

{
  "my_component": {
    "label": "My Component",
    "content": {
      "title": {
        "type": "text",
        "label": "Title"
      }
    },
    "design": {
      "includes": "Hyva_CmsBase::etc/hyva_cms/default_design.json"
    }
  }
}

The example above includes all design fields from the default_design.json file in the Hyva_CmsBase module. The includes property accepts either a single path string or an array of paths to include multiple field definition files.

This approach ensures consistent design options across all components without duplicating JSON configuration.

Creating Component Style Variants

Component variants allow you to create multiple visual styles for a single Hyvä CMS component. Each variant can use a different template file to render the component with alternative HTML structure or styling.

Example component with variant selector:

{
  "my_component": {
    "label": "My Component",
    "content": {
      "variants": {
        "type": "variant",
        "label": "Style Variant",
        "options": [
          {
            "label": "Default",
            "value": "Vendor_Module::elements/my_component/default.phtml"
          },
          {
            "label": "Alternative",
            "value": "Vendor_Module::elements/my_component/alternative.phtml"
          }
        ]
      }
    }
  }
}

The variant field creates a dropdown selector in the Hyvä CMS editor. When a content editor selects a variant, the corresponding template renders the component. This allows a single component to have multiple visual presentations without creating separate component declarations.