Nextmatch

<et2-nextmatch> | Et2Nextmatch

Nextmatch shows entries with filtering and context menus. Et2Nextmatch uses Et2Datagrid to show application entries using a row template. Rows must be read-only, we do not allow inputs in the rows.

Overview

Named Template Mode

Use the template attribute when you already have a classic eTemplate rows template:

<et2-nextmatch id="nm" template="addressbook.index.rows"></et2-nextmatch>

      

      
    

The row/header structure is read from that template and converted for et2-datagrid.

Slotted Template Mode

(WIP) When template is not set, et2-nextmatch reads slotted child markup from its light DOM.

<et2-nextmatch id="nm">
    <et2-box slot="header">Custom toolbar / filters / actions above grid</et2-box>

    <tr class="th" slot="columns">
        <et2-nextmatch-sortheader id="n_family" label="Name"></et2-nextmatch-sortheader>
        <et2-nextmatch-header id="note" label="Note"></et2-nextmatch-header>
    </tr>

    <tr class="$class $cat_id" slot="row">
        <et2-description id="n_family" noLang="1"></et2-description>
        <et2-textarea id="note" readonly="true" noLang="1"></et2-textarea>
    </tr>

    <tr slot="loader">
        <td colspan="2">
            <sl-skeleton effect="sheen" style="width:100%"></sl-skeleton>
        </td>
    </tr>
</et2-nextmatch>

      

      
    

Full details for columns, rows, expression syntax, wrapper behaviour, and loader slots are documented in:

• Et2Datagrid

Row expansion

et2-nextmatch maps the existing Nextmatch hierarchy contract onto et2-datagrid row expansion. There is no separate client or server contract for recursive expansion:

• rows are expandable when the row data has is_parent: true, or when the configured settings.is_parent field matches settings.is_parent_value;
• child rows are fetched through the existing child-provider path, which sends parent_id to the server;
• every child level uses the same expansion semantics as its parent; only the parent_id scoped to that level changes.

Expanded content is an embedded <et2-datagrid> that reuses the parent Nextmatch row template, column snapshot, row customizer, and row styles. The child grid is embedded-virtualized, so it does not create a nested scrollbar. It reserves its own full virtualized height inside the parent scrollport while rendering only the visible child rows.

Expansion is recursive for acyclic hierarchy data. If a child row is marked as a parent by the same is_parent / configured marker contract, that child row can expand into another embedded datagrid using the same contract. Each level keeps its own total; child totals are not rolled up into the root total.

The server must not return cyclic hierarchy data such as A → B → A or a row as its own child. Recursive expansion documents this as a data requirement; it does not add a runtime cycle/depth guard.

Notes

• If both a template attribute and slotted templates are provided, template wins.
• setRows() can preload initial rows; otherwise rows are fetched through the bound Nextmatch data provider.

Printing

When its page is printed, et2-nextmatch asks which columns, how many rows (up to 100 by default) and which page orientation to print, remembers the columns and orientation as the user’s print preference, and prints exactly those rows.

To always print a list the same way without asking, set printOptions from the app’s JS, eg. in et2_ready():

nm.printOptions = {columns: "all", rowCount: 100, orientation: "portrait"};

      

      
    

• columns: "all" for every column the column selection offers (also ones the user has hidden), or the column keys to print, in that order.
• rowCount: the maximum number of rows to print.
• orientation: "portrait" or "landscape".

Options left out use the dialog’s defaults: the saved print columns (or the visible ones), up to 100 rows, portrait. Nothing is saved as print preference.

Row value bindings

Row templates bind in two ways, and the distinction is worth keeping straight:

• An id gets you a value. id="title" is the widget’s stable id and names the row field it shows, so the datagrid supplies rowData.title as the widget value. This is the recommended form for row values.
• $ and @ expressions set attributes and properties. They work in any row-template attribute, and each widget then applies its normal interpretation of the resolved value.

$field reads field from the current row and $[parent.child] reads a nested value. @field returns the content entry stored under that key, and @@field reads it from the root content instead of the current namespace.

<row class="$class $[category.css_class]">
    <et2-description id="title" noLang="1"></et2-description>
    <et2-date-time id="modified" readonly="true"></et2-date-time>
    <et2-image src="$icon" label="$type_label"></et2-image>
    <et2-description class="priority_$priority" id="status" noLang="1"></et2-description>
</row>

      

      
    

value is an ordinary property, so an expression can set it like any other. Reach for that only when the value comes from a differently named or nested row field - when the id already names the field, it is redundant:

<et2-description id="summary" value="$[details.short]" noLang="1"></et2-description>

      

      
    

Keep action and compound ids as ids, for example id="delete[$id]"; they are not row-value bindings.

An id on a namespace-opening widget - a box, a grid, a nested nextmatch - scopes its children instead of naming a value of its own, so nested row data can be addressed by nesting the template. Given row data {id: 1, sub: {name: "cheese"}}:

<row>
    <et2-description id="id"></et2-description>
    <et2-vbox id="sub">
        <et2-description id="name"></et2-description>
    </et2-vbox>
</row>

      

      
    

the inner description binds sub.name. Whether an id scopes or binds is the widget’s own answer (_createNamespace()), the same question etemplate asks everywhere else - so an ordinary widget’s id still names a value even when the template nests markup inside it, and an unnamed container is pure layout that never affects the path. Flat row data stays flat no matter how deeply it is wrapped: {id: 1, name: "cheese"} still binds through <et2-vbox><et2-hbox><et2-description id="name"/></et2-hbox></et2-vbox>.

Attribute expressions are never namespaced: $field and ${row}[field] always address the row itself, wherever they are written.

Existing templates do not need a bulk rewrite. Legacy ${row}[title], {$row}[title], $row_cont[title], and $row.title continue to work in row templates. Use them only when documenting or maintaining legacy markup; new examples and template edits should use direct bindings.

Styling Rows

et2-nextmatch renders rows inside et2-datagrid, so normal application CSS does not automatically reach row contents. Put row-specific styles in an et2-styles element inside the row template definition. et2-nextmatch extracts those styles and adopts them into the datagrid row shadow DOM.

<template id="app.index.rows">
    <grid>
        ...
    </grid>

    <et2-styles src="row.css"></et2-styles>
</template>

      

      
    

The et2-styles element can be anywhere inside the row template definition, not only inside <row>. Bare filenames such as row.css resolve relative to the .xet file containing the template.

The application’s app.css is never loaded into the datagrid row shadow DOM, with or without et2-styles. A row template without et2-styles gets only the framework row styles.

Row-template-local stylesheets have these advantages:

• fewer unrelated app rules inside row shadow DOM
• clearer ownership for styles used only by one row template
• smaller stylesheet parse cost for large app.css files
• fewer accidental matches between edit/view CSS and list rows
• easier deletion when a row template is removed or replaced

For the full set of row styling options, including exportparts, see Et2Datagrid: Styling Row Contents.

Anti-example: Styling Row Descendants Through ::part(row)

Do not try to style widgets inside rows from outside the datagrid shadow DOM by selecting descendants of the exported row part. ::part() exposes the part element itself, not arbitrary descendants inside that part, so this selector will not style row links:

et2-nextmatch {
  ::part(row) {
	/* Links in nextmatch should be blue */

	et2-link, et2-link-string {
	  color: var(--sl-color-sky-900);
	}
  }
}

      

      
    

Because the rows are managed by et2-datagrid inside its shadow DOM, you cannot style them from outside the datagrid.

• et2-nextmatch::part(row) { ... } can style the row elements themselves, but not their descendants.
• et2-nextmatch::part(row) et2-link { ... } cannot style links inside the row.
• et2-nextmatch::part(exported-part) { ... } can style explicitly exported parts.

For framework-level row styles, add to Et2Nextmatch.row.styles.ts. For app-specific row styles, use the app’s row-template et2-styles. app.css does not reach rows.

For application rules generated at runtime, create a constructable stylesheet and add it through the nextmatch:

const style = new CSSStyleSheet();
style.replaceSync("tr.dynamic-state { color: var(--dynamic-color); }");
nextmatch.addRowStylesheet(style);

      

      
    

The stylesheet is adopted after the static row styles and is retained if the row template is reloaded.

Greying Out Inactive Entries

For an entry that is still listed but no longer in effect - a revoked application password, a deleted calendar event, a disabled policy - add the class rowInactive to the row. The framework row styles show it in a muted, italic font, the same in every app, so the app needs no CSS of its own for it.

if ($row['token_revoked'])
{
	// "revoked" stays for the actions' enableClass/disableClass, "rowInactive" greys the row out
	$row['class'] = 'revoked rowInactive';
}

      

      
    

<row class="$row_cont[class]">

      

      
    

Add rowInactive next to the app’s own class rather than replacing it, since actions and app code usually key on the app’s class.

Highlighting an Overdue Entry

Have the server add an overdue class for rows that need attention, then style that class via CSS.

<row class="$class">
    <et2-description class="task-title" id="title" noLang="1"></et2-description>
    <et2-description class="task-due" id="due" noLang="1"></et2-description>
</row>

      

      
    

.overdue .task-title {
	font-weight: var(--sl-font-weight-semibold);
}

.overdue .task-due {
	color: var(--sl-color-danger-700);
}

      

      
    

Letting Users Show Or Hide Row Details

For a list option such as “show details”, set a CSS custom property on the nextmatch widget when the option changes. The row stylesheet can then use that value for every row, including rows that are rendered later while scrolling.

show_details(show, nextmatch : Et2Nextmatch)
{
	nextmatch?.style?.setProperty("--task-details-display", show ? "block" : "none");
}

      

      
    

<row class="$class">
    <et2-description class="task-title" id="title" noLang="1"></et2-description>
    <et2-description class="task-details" id="description" noLang="1"></et2-description>
</row>

      

      
    

.task-details {
	display: var(--task-details-display, none);
	max-height: 5em;
	overflow: clip;
}

      

      
    

This is the same pattern InfoLog uses to show or hide description rows without updating each row individually.

Wrapping Contact Details

If the row contains a widget with internal layout, expose the part you need and style it from CSS.

<row class="$class">
    <et2-hbox class="contact-methods" exportparts="base:contact-methods__base">
        <et2-url-phone id="tel_work" readonly="true"></et2-url-phone>
        <et2-url-phone id="tel_cell" readonly="true"></et2-url-phone>
        <et2-url-email id="email" readonly="true"></et2-url-email>
    </et2-hbox>
</row>

      

      
    

et2-nextmatch::part(contact-methods__base) {
	flex-wrap: wrap;
	row-gap: var(--sl-spacing-2x-small);
}

      

      
    

Slots

Learn more about using slots.

Properties

Learn more about attributes and properties.

Inherited properties (21)

Et2Widget

Name	Description
accesskey	Accesskey provides a hint for generating a keyboard shortcut for the current element. The attribute value must consist of a single printable character.
actions	Set Actions on the widget Each action is defined as an object: move: { type: “drop”, acceptedTypes: “mail”, icon: “move”, caption: “Move to” onExecute: javascript:mail_move” } This will turn the widget into a drop target for “mail” drag types. When “mail” drag types are dropped, the global function mail_move(egwAction action, egwActionObject sender) will be called. The ID of the dragged “mail” will be in sender.id, some information about the sender will be in sender.context. The etemplate2 widget involved can typically be found in action.parent.data.widget, so your handler can operate in the widget context easily. The location varies depending on your action though. It might be action.parent.parent.data.widget To customise how the actions are handled for a particular widget, override _link_actions(). It handles the more widget-specific parts.
align	Used by Et2Box to determine alignment. Allowed values are left, right
class	CSS Class. This class is applied to the outside, on the web component itself. Due to how WebComponents work, this might not change anything inside the component.
data	Set the dataset from a CSV
deferredProperties	Any attribute that refers to row content cannot be resolved immediately, but some like booleans cannot stay a string because it’s a boolean attribute. We store them for later, and parse when they’re fully in their row. If you are creating a widget that can go in a nextmatch row, and it has boolean attributes that can change for each row, add those attributes into deferredProperties
disabled	Defines whether this widget is visibly disabled. The widget is still visible, but clearly cannot be interacted with. Widgets disabled in the template will not return a value to the application code, even if re-enabled via javascript before submitting. To allow a disabled widget to be re-enabled and return a value, disable via javascript in the app’s et2_ready() instead of an attribute in the template file.
dom_id	Get the actual DOM ID, which has been prefixed to make sure it’s unique.
full	Take every column of a layout, the same as span="all". Boolean rather than a bare marker so it can be driven from content the way the rest of the template can - full="@is_wide" resolves through the array manager like any other boolean attribute. That does mean it needs a value: write full="true", since an empty full="" resolves to false and removes the attribute again. Reflects for the same reason grow does.
grow	How much of a layout’s leftover space this widget should take. Only means anything inside a container that has a layout (see Et2LayoutController): a bare grow or grow="1" takes an equal share of whatever the non-growing children left over, grow="2" takes twice what a grow="1" sibling does. It has to reflect. The layout stylesheet matches the [grow] attribute - CSS cannot see a property - and transformAttributes() only calls setAttribute() for an attribute the element already carries or a property declared as reflecting. Widgets built from a .xet are created with document.createElement() and handed their attributes as an object, so they carry none at that point: without this declaration grow="1" lands as an inert JS property and nothing in the layout ever matches it.
hidden	The widget is not visible. As far as the user is concerned, the widget does not exist. Widgets hidden with an attribute in the template may not be created in the DOM, and will not return a value. Widgets can be hidden after creation, and they may return a value if hidden this way.
id	Get the ID of the widget
label	The label of the widget This is usually displayed in some way. It’s also important for accessability. This is defined in the parent somewhere, and re-defining it causes labels to disappear
noLang	Disable any translations for the widget
parentId	Parent is different than what is specified in the template / hierarchy. Widget ID of another node to insert this node into instead of the normal location
span	How many of a layout’s columns this widget should take. span="all" is every column wherever the widget landed, span="end" / span="*" is from its own column to the end of its line. Only means anything inside a container that has a layout, and only for the column layouts - stack gives every child the full width anyway. The same name is also read straight off the XML node by the legacy <grid> widget, for the unrelated job of counting table cells to merge; that path never looks at the widget, so declaring it here does not disturb it. Reflecting it does mean a legacy grid’s span="all" cells now carry the attribute too, which matches nothing outside a layout. Reflects for the same reason grow does.
statustext	Tooltip which is shown for this element on hover
styles	WebComponent *
options	Get property-values as object
supportedWidgetClasses	et2_widget compatability

LitElement

Name	Description
updateComplete	A read-only promise that resolves when the component has finished updating.

Events

Learn more about events.

Methods

Learn more about methods.

Inherited methods (23)

Et2Widget

Name	Description
checkCreateNamespace()	Checks whether a namespace exists for this element in the content array. If yes, an own perspective of the content array is created. If not, the parent content manager is used. Constructor attributes are passed in case a child needs to make decisions
clone()	Creates a copy of this widget.
createElementFromNode()	Create a et2_widget from an XML node. First the type and attributes are read from the node. Then the readonly & modifications arrays are checked for changes specific to the loaded data. Then the appropriate constructor is called. After the constructor returns, the widget has a chance to further initialize itself from the XML node when the widget’s loadFromXML() method is called with the node.
getArrayMgr()	Returns the array manager object for the given part
getArrayMgrs()	Returns an associative array containing the top-most array managers.
getChildren()	Get child widgets Use .children to get web component children
getInstanceManager()	Returns the instance manager
getPath()	Returns the path into the data array. By default, array manager takes care of this, but some extensions need to override this
getRoot()	Returns the base widget Usually this is the same as getInstanceManager().widgetContainer
getWidgetById()	Extend the normal widget-tree lookup with the datagrid, e.g. header widgets built from the row template (like a sum in a column header) are Et2Datagrid’s children, not ours.
loadFromXML()	Loads the widget tree from an XML node
loadingFinished()	Needed for legacy compatability.
parseXMLAttrs()	The parseXMLAttrs function takes an XML DOM attributes object and adds the given attributes to the _target associative array. This function also parses the legacyOptions. N.B. This is only used for legacy widgets. WebComponents use transformAttributes() and do their own handling of attributes.
set_label()	NOT the setter, since we cannot add to the DOM before connectedCallback() TODO: This is not best practice. Should just set property, DOM modification should be done in render https://lit-element.polymer-project.org/guide/templates#design-a-performant-template
setArrayMgr()	Sets the array manager for the given part
setArrayMgrs()	Sets all array manager objects - this function can be used to set the root array managers of the container object.
setInstanceManager()	Set the instance manager Normally this is not needed as it’s set on the top-level container, and we just return that reference
_createNamespace()	Force namespace creation for nested widgets. Nextmatch behaves as a container and must always scope children.
_handleClick()	Click handler calling custom handler set via onclick attribute to this.onclick
destroy()	et2_widget compatability
set_class()	Set the widget class
set_disabled()	Wrapper on this.disabled because legacy had it.
set_statustext()	supports legacy set_statustext

Custom Properties

Learn more about customizing CSS custom properties.

Parts

Learn more about customizing CSS parts.

Belongs to

Nextmatch