Override generated content

Add a generator rule file (name matches the pattern in therulesFileMask option) next to an HTML or JavaScript source file to modify the generated content.

<inputRootDir>
├── generator.config.json
├── src/
   └── modules/
      ├── my-component/
         └── my-component.html
         └── my-component.rules.json

Generation parameters from the component-level rules override the rules defined at the project level. In addition to Runner parameters and HTML interpretation parameters, you can customize generated content by adding elements of UTAM page object grammar directly to the configuration file. In our example, the configuration file is my-component.rules.json.

NOTE: The supported parameters were updated in version 2.1.0. Please do not use earlier versions.

Root selector

By default, the generator adds a root selector if the object is recognized as a root. Otherwise, you can add a selector to a rules file following the selector UTAM grammar.

Example of configuring root selector in my-component.rules.json:

{
    "selector": {
        "css": "my-root"
    }
}

If a root selector was generated and you want to remove it, set "root": false in my-component.rules.json.

Description and metadata

By default, the generator adds a root description in this format:

{
    "description": {
        "author": "UTAM generator",
        "text": ["Page Object: <name of file>", "<root if present>"]
    }
}

You can add both the description and the metadata to a rules file. For the syntax, see the description and metadata UTAM grammar.

Example of configuring description and metadata in my-component.rules.json:

{
    "description": "very useful page object",
    "metadata": {
        "some": "value"
    }
}

Root properties

You can add more root properties to the generation rules by using UTAM JSON grammar.

• exposeRootElement
• type
• beforeLoad
• platform
• implements

Example of configuring root properties in my-component.rules.json:

{
    "beforeLoad": [ ... ],
    "implements": "some/other/type",
    "type": "actionable",
    "exposeRootElement": true,
    "platform": "Web"
}

shadowRoot

The generator determines if the source HTML has a shadowRoot based on the following rules.

A <template> HTML element or custom HTML element (with a dash in the tag name) is considered a shadow boundary if they are not marked as lwc:render-mode="light". For example for following HTML snippets:

<template>
    <div class="wrapper">
        <!-- content -->
    </div>
</template>

<div>
    <my-generated-component>
        <button id="number"></button>
    </my-generated-component>
</div>

The generator produces a shadow boundary:

"shadow": {
     "elements": [
        { }
    ]
}

Let's use the following HTML as a source for generation:

<template>
    <button>button</button>
</template>

By default, the generated code is:

{
    "shadow": {
        "elements": [
            {
                "public": true,
                "name": "button",
                "type": ["actionable", "clickable"],
                "selector": { "css": "button" }
            }
        ]
    }
}

To move all generated elements outside shadowRoot, set "shadowRoot": false in the configuration file. The generated code is:

{
    "elements": [
        {
            "public": true,
            "name": "button",
            ...
        }
    ]
}

To move elements inside shadowRoot, set "shadowRoot": true.

Add generated elements

If the generator didn't pick up some of the elements, it's possible to add them using "elements": [] or "shadow: { "elements" : []} syntax from UTAM grammar.

For example, if the originally generated my-component.utam.json is:

{
    "elements" : [
        {
            "name" : "generated",
            "public": true,
            "selector" : { ... }
        }
    ]
}

Add a configured element in the my-component.rules.json rules file.

{
    "shadow": {
        "elements": [
            {
                "name": "configured",
                "selector": {...}
            }
        ]
    }
}

The generated my-component.utam.json is now:

{
    "elements" : [
        {
            "name" : "generated",
            "public": true,
            "selector" : { ... }
        }
    ],
    "shadow": {
        "elements": [
            {
                "name": "configured",
                "selector": {...}
            }
        ]
    }
}

Note that configured elements are added to existing ones, they don’t replace them. To replace the generated version, check out remove generated element.

Change generated elements

Generated elements are based on generation rules that aren’t always optimal or aware of the business function. Sometimes, it makes sense to change generated element properties using the replaceElements configuration parameter. The format of replaceElements is an array where each element points to the generated name of the generated element and defines a subset of properties to change consistent with the element grammar format:

• name is a generated element whose properties should be changed
• 'element' compose changes to be applied to the element with the give name
  • selector changes the auto-generated selector
  • type changes the type of the generated element
  • nullable defines whether the element is nullable
  • description adds documentation to the element getter
  • public defines if the element should have a public getter
  • filter sets an element's filter
  • shadow nested shadow elements
  • elements nested elements

For example, if the originally generated my-component.utam.json is:

{
    "elements": [
        {
            "name": "div",
            "selector": { "css": ".generatedCss" }
        }
    ]
}

Use replaceElements in a my-component.rules.json rules file.

{
    "replaceElements": {
        [
            "name" : "div",
            "element": {
                "name": "updatedName",
                "selector" : { "css": ".configuredCss" },
                "public" : true,
                "nullable": true,
                "description": "element description",
                "filter": { ... },
                "shadow": { ... },
                "elements": [
                    //nested elements
                ]
            }
        ]
    }
}

The generated my-component.utam.json is now:

{
    "elements" : [
        {
            "name": "updatedName",
            "selector" : { "css": ".configuredCss" },
            "public" : true,
            "nullable": true,
            "description": "element description",
            "filter": { ... },
            "shadow": { ... },
            "elements": [
                    //nested elements
            ]
        }
    ]
}

Remove generated elements

Redundant elements can be removed using replaceElements parameter from the previous section. To remove a generated element, set a rule that sets value for the generated element with the given name as undefined.

For example, if the originally generated my-component.utam.json is:

{
    "elements": [
        {
            "name": "div",
            "selector": { "css": ".generatedCss" }
        }
    ]
}

Given generation rules my-component.rules.json:

{
    "replaceElements": [
        {
            "name": "div"
            // do not set "element"
        }
    ]
}

The generated my-component.utam.json is now empty because the rules defined that an element with the name div should be removed:

{}

Add compose methods

To add compose methods to the generated JSON file, add methods to the generation rules. These methods follow the same syntax as a regular compose method in UTAM grammar.

methods

• Type: compose method
• Default: undefined

Here's an example of rules:

{
    "methods": [
        {
            "name": "getRootText",
            "compose": [
                {
                    "element": "root",
                    "apply": "getText"
                }
            ],
            "description": {
                "text": ["get record label text"]
            }
        }
    ]
}

This exact method is added to the generated JSON.