Create a Custom Entity App Form Element

If the entity app doesn't provide a suitable form element for your requirements, you have the option to build your own custom form element. Custom form elements are web components that can be registered in the entity app form.

Create A Custom Form Element

Just create a web component with or without any library you like. As an interface between the entity app form and your component, we work with web component properties (not attributes) and events.

Properties

The following properties on your component will be set by Confinity. We don't use attributes, so you have to use it like properties.

Property Name	Data Type	Description
`value`	`any`	The current value for the given property.
`readonly`	`boolean`	Whether or not the form element is in read-only state.
`entity`	`object`	The current state of the entity in the form.
`configuration`	`any`	The configuration data you have provided via the form configuration.

You don't have to declare or use all of these properties. In most cases you only need the value property.

Property Example

You can declare and access the properties like this:

class MyCustomComponent extends HTMLElement {
    // ...
    value = null;
    readonly = null;
    entity = null;
    configuration = null;
    // ...
}

Or you can use getters and setters which allows you to react to changes on the properties:

class MyCustomComponent extends HTMLElement {
    // ...
    set value(newValue) {
        // do something with the new value
    }

    // ...
}

Events

Confinity listens to the following events which you can trigger accordingly.

Event Name	Payload	Description
`cfy-input`	`{value: any}`	With the `cfy-input` event you will transmit the current value to the form. You have to trigger this event anytime the internal value changes. E.g. like the native `input` event on an input field.
`cfy-change`	`none`	With the `cfy-change` event you will trigger the form to run validations and reevaluate conditions. Use it like the native `change` event on an input field.

Event Example

Here's a simple example on how to trigger events in your web component.

class MyCustomComponent extends HTMLElement {
    // ...
    somethingHapppened(newValue) {
        // update the value in the form
        this.dispatchEvent(new CustomEvent('cfy-input', {detail: {value: newValue}}));
        // trigger cfy-change event to run validations 
        this.dispatchEvent(new CustomEvent('cfy-change'));
    }

    // ...
}

Example Web Component

The following example is a simple web component with the tag name my-custom-component including an input form field which a configurable font color.

class MyCustomComponent extends HTMLElement {

    inputElement = null;

    configuration = null;
    entity = null;

    constructor() {
        super();

        this.attachShadow({mode: 'open'});
        this.initComponent();
    }

    set value(value) {
        this.inputElement.value = value;
    }

    get value() {
        return this.inputElement.value;
    }

    connectedCallback() {
        if (this.configuration.color) {
            this.inputElement.style.color = this.configuration.color;
        }
    }

    initComponent() {
        const template = document.createElement('template');

        template.innerHTML = `
            <input type="text">
        `;

        this.shadowRoot.appendChild(template.content.cloneNode(true));
        this.inputElement = this.shadowRoot.querySelector("input");

        this.inputElement.addEventListener('input', () => {
            this.dispatchEvent(new CustomEvent('cfy-input', {detail: {value: this.value}}));
        });

        this.inputElement.addEventListener('change', () => {
            this.dispatchEvent(new CustomEvent('cfy-change'));
        });
    }

}

window.customElements.define('my-custom-component', MyCustomComponent);

Register your Component in the Entity App Form

When you have built a web component you can use it in the entity app form configuration by using the AddCustom method like in the following example.


//this is just one example of how to obtain your js-source
var assembly = this.GetType().Assembly;
var resourceName = assembly.GetManifestResourceNames()
    .SingleOrDefault(p => p.EndsWith("my-custom-component.js"))
                   ?? throw new InvalidOperationException("my-custom-component.js missing in resources. Is the frontend built? \ud83d\ude43");
using var stream = assembly.GetManifestResourceStream(resourceName)!;
using var reader = new StreamReader(stream);
byte[] jsFileContent = System.Text.Encoding.UTF8.GetBytes(reader.ReadToEnd());

tab.AddCustom(p => p.Name, "my-custom-component",
        "my-custom-component.js", jsFileContent)
    .Label("A custom component")
    .Tooltip("With a tooltip")
    .Comment("And here's a comment")
    .WithConfiguration(new { Color = "#ff0000" })
    .Validate(v => v.NotNull());

With the method WithConfiguration() you can provide any type of configuration to your form element, which will be available via the configuration property on your web component.