Styling

Variations

A variation is a pre-defined CSS class an author can switch on for a component, chosen from the component's Design option in the editor or from a variation-picker field in its Edit dialog. Registering a class as a variation turns it into a labelled toggle authors can pick, instead of asking them to remember and type raw class names.

How variations are structured

Variations belong to a component view and live in a variations folder under it. Each folder inside variations is a variation group (kes:ComponentVariationGroup), and each group holds one or more variations (kes:ComponentVariation):

JCR structure

{component}/                    # a component
  {library-or-framework-code}/  # the UI Library or UI Framework view it belongs to
    {version}/                  # component version, e.g. 1.0.0
      variations/
        {group}/                # kes:ComponentVariationGroup
          .content.xml          # the group and its kes:ComponentVariation nodes

A real example from the sample sites is navigation/top-navigation/acpl-framework/0.2.11/variations/style/: the top-navigation component, its acpl-framework view at version 0.2.11, and a style variation group that registers choices such as bg-primary and navbar-dark.

Defining a variation group

Add a .content.xml in the group folder. The root node is the kes:ComponentVariationGroup; each child node is a kes:ComponentVariation. In FileVault XML, boolean properties take the {Boolean} type hint, as the shipped sample content does:

style/.content.xml

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:jcr="http://www.jcp.org/jcr/1.0"
          xmlns:kes="http://kestros.io/kes/1.0"
          jcr:primaryType="kes:ComponentVariationGroup"
          jcr:title="Style"
          mutuallyExclusive="{Boolean}false">
    <navbar-dark jcr:primaryType="kes:ComponentVariation"
                 jcr:title="Dark"
                 inline="true"/>
    <bg-primary jcr:primaryType="kes:ComponentVariation"
                jcr:title="Primary Background"
                inline="true"/>
</jcr:root>

Group node (kes:ComponentVariationGroup):

Req: Y = required, Rec = recommended, blank = optional
Property	Type	Req	Description
`jcr:primaryType`		Y	Must be `kes:ComponentVariationGroup`
`jcr:title`	String		Group label shown in the authoring UI (Design option / Edit dialog)
`jcr:description`	String		Optional description of the group
`mutuallyExclusive`	Boolean		`true` allows only one variation in the group at a time; `false` (the default) lets an author apply several from the same group at once

Variation node (kes:ComponentVariation):

Property	Type	Req	Description
node name		Y	The CSS class token this variation applies, and the value content references. Name it as the class you want applied (for example `bg-primary`)
`jcr:primaryType`		Y	Must be `kes:ComponentVariation`
`jcr:title`	String		Display label in the authoring UI only; also the key groups sort their variations by
`inline`	Boolean		`false` (default): Kestros adds the class to the component's wrapper element automatically. `true`: the class is not added to the wrapper; the component's own HTL must emit it, typically via `${component.inlineVariations}`
`default`	Boolean		`true` assigns this variation to components that have no `variations` property set. Defaults to `false`

The inline flag decides where the class lands. A non-inline variation (the default) is added to the component's wrapper element by Kestros. An inline variation is not added to the wrapper: the component's HTL is responsible for emitting it, usually by printing ${component.inlineVariations} inside the element that should receive the class. Every variation in the sample sites sets inline="true" and prints inlineVariations in its layout markup.

The node name is the CSS class

The variation node name, not its jcr:title, is the CSS class token, and it is exactly what content references. A variation registered as <bg-primary jcr:title="Primary"> is applied on a component in content by node name (whether that class ends up on the wrapper or in the inline slot depends on the variation's inline flag):

component .content.xml (content)

<jcr:root xmlns:jcr="http://www.jcp.org/jcr/1.0"
          xmlns:sling="http://sling.apache.org/jcr/sling/1.0"
          jcr:primaryType="nt:unstructured"
          sling:resourceType="kestros/commons/components/navigation/top-navigation"
          variations="[bg-primary]"/>

Content matches by node name, not jcr:title. variations="[bg-primary]" resolves the variation whose node name is bg-primary; the jcr:title ("Primary") is display-only in the authoring UI. Any tooling that audits applied-versus-registered variations must compare node names, not titles.

Applying variations while authoring

Once a group is in place, its variations appear in the component's Design option in the editor, and also in a variation-picker field in the component's Edit dialog. An author toggles them on and off; Kestros writes the selected variations into the component's variations property.

Use mutuallyExclusive to control how many can be on at once. Set it to true when only one choice in the group makes sense (a single background color), and leave it false (the default) to let an author combine several variations from the same group.

Variations style a component in place, without new markup. For arranging components within a container instead, see Layouts. For the authoring fields that drive component configuration, see Dialogs.