Components Definition

This guide explains how to create XML component definition files for the ExpressiveWeb framework. These files allow you to define reusable components in the visual editor by specifying their structure, behavior, and features.

General Component Structure

Each XML component file follows this basic structure:

<?xml version="1.0" encoding="utf-8" ?>
<Component xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/sebbouez/ExpressiveWeb/refs/heads/main/Schemas/schema_components.xsd">
    <!-- Component definition -->
</Component>

Required Elements

1. UID - Unique Identifier

<UID>bootstrap.Card</UID>

• Description: Unique identifier for the component within the kit
• Recommended format: [kit_name].[component_name]
• Usage: Reference the component in other components or actions

2. Name - Display Name

<Name>Card</Name>

• Description: Name displayed in the editor's user interface
• Usage: User-friendly name in the component palette

3. Template - HTML Template

<Template>
    <![CDATA[
    <div class="card">
        <slot/>
    </div>
    ]]>
</Template>

• Description: HTML code generated by the component
• <slot/>: Indicates where child elements will be inserted
• CDATA: Encapsulates HTML to avoid XML conflicts

4. Allows - Allowed Child Components

<Allows>*</Allows>
<!-- or -->
<Allows>bootstrap.Button;bootstrap.Text</Allows>
<!-- or -->
<Allows>text</Allows>

• *: Allows all types of children
• UID List: Separate with ; to allow only these components
• Predefined values:
  • text: Text content only
  • paragraphs: Paragraph elements
  • headings: Heading elements

Optional Elements

Denies - Forbidden Child Components

<Denies>bootstrap.Card</Denies>

• Description: Forbids certain components even if Allows is set to *
• Usage: Prevent problematic nesting (e.g., card within card)

Family - Component Family

<Family>Layout</Family>

• Description: Logical group to which the component belongs
• Usage: Organization in the editor's palette

Slots - CSS Selectors for Insertion

<Slots>.card-body</Slots>

• Description: Defines precisely where child elements will be inserted
• Format: Valid CSS selectors
• Usage: Complex templates with specific insertion zones

Variants - Style Variants

<Variants>
    <Variant name="Card model 1" className="card1"/>
    <Variant name="Card model 2" className="card2"/>
</Variants>

• Description: Offers different visual variations of the component
• Attributes:
  • name: Name displayed in the interface
  • className: CSS class applied

Features - Advanced Features

Use the correct Xml Schema Description to get the list of supported features.

InlineEdit

<Features>
    <InlineEdit/>
</Features>

• Description: Enables inline editing of text content
• Usage: Text components, headings, paragraphs

Actions - Contextual Actions

Use the correct Xml Schema Description to get the list of supported actions.

<Actions>
    <Action Header="Add card" Command="AppendChild" Params="bootstrap.Card"/>
    <Action Header="Add button" Command="AppendChild" Params="bootstrap.Button"/>
</Actions>

• Description: Defines actions available in the context menu
• Attributes:
  • Header: Text displayed in the context menu
  • Command: Command to execute
  • Params: Command parameters

Best Practices

Naming Conventions

• Consistent UIDs: Use a prefix for your kit (e.g., bootstrap., mykit.)
• Explicit names: Choose clear and descriptive names
• Convention: Use PascalCase for component names

Structure and Hierarchy

• Logical relationships: Clearly define parent-child relationships with Allows/Denies
• Modularity: Create reusable and composable components
• Granularity: Balance between overly generic and overly specific components

HTML Templates

• Valid HTML: Ensure generated HTML is valid
• CSS Classes: Use classes consistent with your CSS framework
• Accessibility: Include appropriate ARIA attributes

Documentation and Maintenance

• XML Comments: Document complex components
• Testing: Validate your components in the editor
• Versioning: Manage versions of your component kits

Validation

• XSD Schema: Always use schema reference for validation
• Tools: Use an XML editor with real-time validation

Complete Example - Bootstrap Card Component

<?xml version="1.0" encoding="utf-8" ?>
<Component xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/sebbouez/ExpressiveWeb/refs/heads/main/Schemas/schema_components.xsd">

    <UID>bootstrap.Card</UID>
    <Name>Card</Name>
    <Family>Layout</Family>

    <Slots>.card-body</Slots>
    
    <Variants>
        <Variant name="Standard card" className="card"/>
        <Variant name="Card with border" className="card border"/>
    </Variants>
    
    <Features>
        <ContextualBoxStyle EnableBorderSettings="true" EnableBackgroundSettings="true" />
    </Features>
    
    <Actions>
        <Action Header="Add title" Command="AppendChild" Params="bootstrap.CardTitle"/>
        <Action Header="Add text" Command="AppendChild" Params="bootstrap.CardText"/>
    </Actions>
    
    <Allows>bootstrap.CardTitle;bootstrap.CardText;bootstrap.Button</Allows>
    <Denies>bootstrap.Card</Denies>

    <Template>
        <![CDATA[
        <div class="card">
            <div class="card-body">
                <slot/>
            </div>
        </div>
        ]]>
    </Template>
    
</Component>

This structure enables the creation of rich and interactive component kits for the ExpressiveWeb visual editor, providing an intuitive and powerful development experience.