Componyx.UI

Componyx.UI is a library of components that work directly with plain HTML. Declare a component with an attribute on any element and it renders, no build step, no virtual DOM, no framework required underneath it. Components share a common base, so the same properties, events and detection mechanism apply everywhere, whether it's a Button or a Grid.

Attributes

Component settings are configured through ui-* attributes on the element, the strict form, data-ui-*, is equivalent. Newer components are built as standard Web Components, so they're written as custom elements, like <cui-form>, while other components require the ui-type attribute.

ui-type - the component to render, for example ui-type="Button".
ui-action - whether the component is only rendered (render), rendered and shown (show, the default) or only instantiated to clone its properties onto another component (clone). A Menu's buttonId setting, for example, clones a button's properties without that button ever needing to render on its own.
ui-template - marks an element as a template, identified by the given id (e.g. Header). Which templates a component supports is documented on its own page.
ui-cloneable - whether that template is cloned for every use (true) or rendered once (false).
ui-contentFrom - the id of the element whose content to use as the template, instead of the template element's own children.

Every other ui-* attribute maps to a property on the component. JSON attribute values, like ui-item-list, are parsed automatically and a whole set of properties can be passed at once as a single JSON object through ui-settings.

CSS and theming

Styling is split into two layers. A structural stylesheet defines the layout every component needs to render correctly, spacing, sizing, positioning and is required. A separate theme stylesheet defines visual appearance, colors, borders, shadows and can be overridden or replaced entirely without touching the structural layer.

This shows up as two CSS classes on a component's root element: .theme for the structural layer, .theme.theme-default for the default skin. Swap in your own skin by pointing the theme class elsewhere, the structural layer stays untouched.

Theme tokens

The default theme is driven entirely by CSS custom properties, so retheming rarely means touching component CSS at all. These are the base theme tokens, colors follow a surface/on-surface pairing, a --cui-color-* token sets a background or fill and the matching --cui-color-on-* token sets whatever sits on top of it, usually text.

--cui-color-surface: rgb(255, 255, 255);
--cui-color-surface-overlay: rgb(39, 53, 55);
--cui-color-neutral: rgb(245, 245, 245);
--cui-color-primary: rgb(16, 163, 189);
--cui-color-accent: rgb(208, 55, 98);

/* ON COLORS (usually text) */
--cui-color-on-surface: rgb(72, 72, 72);
--cui-color-on-surface-overlay: rgb(255, 255, 255);
--cui-color-on-primary: rgb(255, 255, 255);
--cui-color-on-accent: rgb(255, 255, 255);

Override a token at any scope, the whole page, a section or a single component and every component beneath that scope picks up the change automatically. Every other CSS variable in the default theme, spacing, radii, a specific component's own accent, is ultimately built from these base tokens. For customizing something more specific than a page-wide color swap, see the full list of CSS variables in the theming reference.

Avoiding CSS conflicts

Every component wraps its markup in a root element named after the component itself, such as .grid, .app-skin or .combo-box. Component styles are scoped under these classes rather than generic selectors, so keep your own selectors specific enough to avoid conflicts with a component's internal structure.

Avoid global resets that target every element, such as * { box-sizing: border-box; }. Components size and position their internal parts assuming the browser's default box model, a global override could break those calculations in ways that are hard to trace back to the cause. Scope resets to your own markup instead of applying them page-wide.

Lazy loading resources

A component's script and CSS load the first time that component is actually detected or created. This keeps a page's initial load scoped to what it actually renders, a page using only a Button loads only what a Button needs.

This is transitive. A component can depend on others internally, a Grid might pull in DataPager or Menu depending on which settings are used and those are lazy loaded the same way, on demand, only if not already present on the page.

Loading the bundled ui.min.js covers the JS side of this entirely, every component's script is already present, so there's nothing left to fetch. Its CSS counterpart ships unbundled by default, so component CSS keeps lazy loading on its own, configurable separately if you'd rather bundle that too.

Serving lazy-loaded resources

Lazy loading fetches a component's script and CSS from a path pattern, with {0} standing in for the component name.

npm setup

The npm package's files sit one folder per component, Button/Button.js, Button/Button.css, Button/Themes/Default.css, matching the {0} pattern directly. One call, pointed at the package's folder, configures every component.

componyx.UI.setResourcePath(
    '/node_modules/componyx-ui/{0}/{0}.js',
    '/node_modules/componyx-ui/{0}/{0}.css',
    1, // ThemeOption.DEFAULT
    '/node_modules/componyx-ui/{0}/Themes/Default.css'
);

.NET

app.UseResource() registers the middleware that serves these resources from the assembly, mapped to /src by default, overridable through its path argument.

app.UseResource(); // maps to /src by default
app.UseResource("/resources"); // or a custom path

This runs alongside, not instead of, the <componyx-ui-resources> tag helper : the tag registers the base scripts up front, the middleware serves everything lazy loaded after that.

Creating a component

A component can be declared in markup with ui-* attributes or created directly in JavaScript with $UI.createComponent(). Both produce the same instance, the difference is just where that instance comes from, an attribute Componyx.UI detects for you, or a call your own code makes.

Example

<div id="demoComboHtml" ui-type="ComboBox" ui-placeholder="- Select -"
    ui-item-list='[ { "text": "Small" }, { "text": "Medium" }, { "text": "Large" } ]'
    ui-events='{ "onItemSelect": "$bindary.controller.intro.itemSelect", 
    "onItemDeselect": "$bindary.controller.intro.itemDeselect" }'>
</div>
<p>Last event: <span id="demoComboHtml_Result">none yet</span></p>

const combo = $UI.createComponent(componyx.UI.ComboBox, {
    id: 'demoComboJs',
    placeholder: '- Select -',
    itemList: [{ text: 'Small' }, { text: 'Medium' }, { text: 'Large' }],
    containerElement: $('#comboJsContainer')
});

combo.events.onItemSelect.add(ctrl.intro.itemSelect);
combo.events.onItemDeselect.add(ctrl.intro.itemDeselect);

combo.show();

Result

Last event: none yet

The HTML tab needs nothing beyond the markup, $UI.detect() finds and renders it on page load, as shown above. The JavaScript tab produces the same instance imperatively; it needs the ComboBox script already loaded, guaranteed here since the markup above already uses one. To guarantee it regardless, pass loadScript: true in a fourth options argument and give the component's name as a string instead of a class reference, $UI.createComponent() then dynamically imports the script first and returns a Promise resolving to the created instance.

const grid = await $UI.createComponent('Grid', {
    id: 'demoGrid',
    dataSource: rows,
    containerElement: document.body
}, null, { loadScript: true });

Reach for the JavaScript form when a component needs to be created in response to something happening at runtime, rather than existing in the markup from the start. Otherwise the declarative form stays easier to read and is picked up automatically, no extra code needed.

Events

The ComboBox above is already wired to onItemSelect and onItemDeselect through ui-events. Every component exposes its events through an events property and every event supports the same three methods: add() to subscribe, once() to subscribe for a single occurrence and remove() to unsubscribe.

const combo = $UI.store.demoComboHtml;

combo.events.onItemSelect.add(function (comboBox, args) { console.log('selected', args.item); });
combo.events.onItemDeselect.once(function (comboBox, args) { console.log('deselected once', args.item); });

A handler always receives the component instance first, an args object second. What args holds varies per event, for onItemSelect and onItemDeselect it's args.item; some events pass null. The component's TypeScript definitions document the exact shape for each event.

Base events, shared by every component regardless of type, cover the render and interaction lifecycle:

onPreRender
onPostRender
onShow
onHide
onDestroy
onClick

Individual components add their own on top, a ComboBox adds:

onItemSelect
onItemDeselect
onClear

The demo above wires the first two. onClear fires right alongside onItemDeselect when a selection is cleared, so wiring both here would just mean one message immediately overwriting the other.

The declarative ui-events form is useful when the component is declared in markup and there's no reference to the instance yet to call add() on directly.

Detecting components

$UI.detect(container) scans a container for undetected components, elements carrying a ui-type attribute or a cui-* custom tag and renders each one it finds. container is optional, omit it to scan the whole page and the call is awaitable. It runs automatically on DOMContentLoaded, no call needed on a static page rendered by the server and left alone. Set $UI.autoDetect to false before DOMContentLoaded fires to opt out and call $UI.detect() manually instead.

That automatic pass only happens once. Any HTML injected afterward, a template applied, a fragment fetched and inserted, a route loaded by a client-side router, needs its own call to $UI.detect(), scoped to the container that was just added.

container.innerHTML = newHtml;
$UI.detect(container);

Bindary calls this for you after a route's view is injected, so components declared inside a route's HTML are detected without any manual wiring. Building on top of a different routing system or injecting HTML some other way, call $UI.detect() yourself once the new markup is in the DOM. Passing the smallest container that actually changed keeps detection fast, since it skips everything already rendered outside of it.

Waiting for a specific component

A component created in JavaScript already gives you a direct hook, its own events.onPostRender fires once that specific instance is done, no polling or guessing needed.

const combo = $UI.createComponent(componyx.UI.ComboBox, { id: 'demoCombo', containerElement: document.body });

combo.events.onPostRender.once(() => combo.focus());
combo.show();

A component declared in HTML renders through the automatic detection pass instead. Check renderState to see whether that pass has already reached it and fall back to the global $UI.onPostRender, which fires once a whole batch of detected components finishes rendering, to catch the moment it does.

if ($UI.store.myButton?.renderState == 2) // RenderState: 0 NONE, 1 RENDERING, 2 RENDERED
{
    $UI.store.myButton.enable();
}
else
{
    $UI.onPostRender.add(() => $UI.store.myButton.enable());
}

The numeric states are also available as $base.static.RenderState.NONE, .RENDERING and .RENDERED, if you'd rather reference the enum than the literal.

With $UI.autoDetect set to false, UI components have not been detected yet on page load. So a component declared in HTML is guaranteed not to be rendered until you call $UI.detect() yourself, the same pattern used for a route or view change below.

Detecting after a route or view change

A server-rendered page with no client-side router only ever needs the automatic pass above. A single-page application needs its own $UI.detect() call after each new view's HTML lands in the DOM, this applies to any router that injects views separately, Bindary included, only where that call belongs differs per router.

Bindary's routes expose a postLoad event for this, firing once the route's view is rendered. Paired with $UI.onPostRender here so code waiting on a specific component runs whether that component was already detected by the time this handler executes, or gets detected moments later.

ctrl.postLoad = async () =>
{
    if (!_UIDetected)
    {
        $UI.onPostRender.once(() =>
        {
            _UIRendered = true;
            $UI.store.myButton.enable();
        });

        _UIDetected = true;
        let detected = await $UI.detect(); // detect UI controls

        if (!detected.length)
            $UI.onPostRender.fire();
    }
};

_UIDetected and _UIRendered are plain flags the route's own controller defines to guard against detecting the same view twice, not part of Componyx.UI itself. The last check matters: $UI.onPostRender only fires once a detected batch finishes rendering, so a view with nothing left to detect fires it manually to unblock the handler above.

Templates and interpolation

Some components let you replace part of their internal markup wholesale, a header, a footer, a preloader, how a single item renders, rather than reaching for CSS. Every component that supports this exposes named setter methods, setHeaderTemplate(), setItemTagTemplate(), on FormField it's setLabelTemplate() and setFieldTemplate(). Each is a thin wrapper around addTemplate(id, content, cloneable, interpolate), which every component inherits from the shared base.

combo.setNoResultTemplate('<p class="empty">Nothing matched that search.</p>');

cloneable decides whether the template is copied for every use or rendered once. An item template inside a repeating list needs one clone per item, true. A header, footer or label is typically single-use, false and has to be if its content contains anything with a fixed identity, an element with a hardcoded id or a nested component, cloning that would put two elements with the same id on the page at once. Cloneable is on by default, so single-use templates need ui-cloneable="false" set explicitly.

interpolate turns on interpolation tags inside the template's own HTML, curly-bracket markers get replaced with values off the item being rendered during that pass. {text} reads item.text, {customProperty} falls back to item.attributes.customProperty. A component's own documented interpolation tags sit on top of this, ComboBox's item template additionally supports {checkBox} and {icon} alongside the standard item properties. Interpolation is on by default, so if a template's content includes literal curly braces that aren't meant as interpolation tags, JSON embedded in an attribute value, for example, set ui-interpolate="false" on that template to turn it off. If the same template also needs real {tag} interpolation elsewhere, minified JSON with no whitespace can be mistaken for a tag, since a tag is just a brace, non-whitespace content and a closing brace. Keeping normal spacing in the JSON, a space after {, after commas, after colons, is enough to tell the two apart, so both can be left interpolating at the same time.

combo.setItemTagTemplate('<span class="tag">{icon}{text}</span>');

Templates can also be declared directly in markup, with ui-template, ui-cloneable and ui-interpolate on an element nested inside the component. Most components have a handful of static, single-use templates like this, a header, a footer. Some, ComboBox, Menu and Grid among them, also support an item template, one clone rendered per data item. For that, ui-item-template-id on the component itself points it at the template id to render each item with.

<div id="myCombo" ui-type="ComboBox" ui-item-template-id="CustomItem">
    <div ui-template="CustomItem" ui-cloneable="true" ui-interpolate="true">
        <span class="tag">{icon}{text}</span>
    </div>
</div>

What's next

Every component is documented on its own page, with a working demo and its full set of properties, events and methods, listed in the menu on the left. See the Componyx.UI API reference for the complete method and property index.