Light Dark System

Customfields

<et2-customfields> | Et2Customfields

Renders editable customfield widgets. Field widgets render in light DOM so eTemplate widget lookup, validation, and event paths can discover generated child widgets. Each generated widget carries its own label rather than getting one from a sibling element: a custom element is not labelable, so a <label for="#name"> beside it would neither focus it on click nor name it for a screen reader. This widget is the submitted input, not the widgets it generates: Customfields::validate() reads one {"#name": value} map out of our own id, so the generated widgets stay out of the eTemplate widget tree and we report their values together.

Overview

et2-customfields renders an application’s custom fields as editable widgets. You do not declare the individual fields - the widget is given the application’s customfield definitions and generates a widget per field, choosing the tag and attributes from each field’s configured type.

There are three widgets in this family, one per context:

Widget Renders
et2-customfields editable fields, for an edit dialog
et2-customfields-list the same fields read-only, for a Datagrid row
et2-customfields-filters the filterable ones as filter controls

They share one visibility contract, described below, which the Nextmatch customfield header (et2-nextmatch-header-customfields) also uses so that the column chooser and the rendered fields never disagree.

Choosing which fields appear

Custom fields are visible by default. Each of the attributes below narrows that, and they combine:

Attribute Effect
fields an explicit selection, as an object or a comma-separated list
exclude removes named fields from whatever is otherwise visible
typeFilter keeps only fields belonging to a given entry type
tab keeps only fields assigned to a named tab 
<!-- every custom field, editable -->
<et2-customfields id="customfields"></et2-customfields>

<!-- just two of them -->
<et2-customfields id="customfields" fields="contract,region"></et2-customfields>

<!-- everything except one -->
<et2-customfields id="customfields" exclude="internal_note"></et2-customfields>

<!-- only the fields belonging to one tab of the edit dialog -->
<et2-customfields id="customfields" tab="details"></et2-customfields>

The decisions themselves live in Et2CustomfieldsController, so all four widgets answer “is this field visible?” the same way. typeFilter also accepts the legacy "previous" value for compatibility with older templates.

Field type to widget

Which widget a field becomes is decided by Et2CustomfieldWidgetMapper.ts, which turns a field’s configured type into a tag name plus attributes. A date field becomes an et2-date, a selection becomes an et2-select, and so on, in each of the four rendering contexts.

Light DOM

et2-customfields and et2-customfields-list deliberately render their generated children into the light DOM rather than a shadow root, because eTemplate’s widget lookup, validation and event handling all need to find those generated widgets in the normal tree. Their styles are rendered into the light DOM for the same reason.

This matters if you are styling them: the usual shadow-DOM boundary is not there, so ordinary selectors from your application’s CSS do reach the generated fields.

Properties

Name Description Reflects Type Default
DEFAULT_ID
Id used when a template places <customfields/> without one. Some templates do - infolog’s edit dialog, filemanager’s file dialog - and the server reads their values from this key (Customfields::GLOBAL_ID) rather than a per-widget one. string "custom_fields"
field Show just this one customfield, by name. <et2-customfields field="Mitgliedsart" label="Membership type"/> is the readable way to place a single field. It becomes our id, which is where the server reads the value back from - the server builds the same id from the same attribute. string ""
layout How the fields are arranged - see Et2LayoutController. 2-column puts two fields side by side while the dialog is wide enough and collapses to one when it is not, which is what a tab full of customfields wants. The default stays stack so a template that says nothing keeps one field per row, as the table this replaced did. Et2LayoutName "stack"
onchange Handler for a change to any of the customfields. It is put on each generated widget rather than on this one, so widget in the handler is the input that changed - templates read its value and options. any -
prefix Key prefix the values are submitted under, eg. #name. An application always uses #; importexport’s filter stores customfields under its own prefix, and the server reads back whatever this says. string CUSTOMFIELD_PREFIX
readonly Show the customfields as text rather than as inputs. Print and view templates ask for this. Et2Widget has no readonly of its own, so without declaring it here readonly="true" would stay an inert DOM attribute. boolean false
subApp
sub-app 		Application the customfields belong to, when they are not the current application’s. string ""

Learn more about attributes and properties.

Inherited properties (24)

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.
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 Label for a customfields widget placed as a single field, eg. field="Mitgliedsart". It names that one field instead of what the customfield itself is called, which is how templates give a customfield a context-specific name. With more than one field showing there is nothing for it to name, so it is ignored.
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
statustext Tooltip which is shown for this element on hover
styles WebComponent *
options Get property-values as object
supportedWidgetClasses et2_widget compatability

Et2CustomfieldsBase

Name Description
customfields Customfield metadata keyed by unprefixed field name.
exclude Comma-separated field names that should be hidden.
fields Visibility map keyed by unprefixed field name.
tab Optional tab restriction for rendered customfields.
typeFilter Type filter, array of filters, or previous filter reuse.
value Customfield values keyed by prefixed field name, e.g. #cf_name.

LitElement

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

Methods

Name Description Arguments
isDirty() et2_IInput: true once any generated field has been changed. -
isValid() et2_IInput: ask each generated field, since none of them is in the widget tree to be asked on its own. messages: String[]
resetDirty() et2_IInput: take the current values as the unchanged ones. -
get_value() et2_IInput: every editable customfield’s value, keyed the way the server stores them. Customfields::validate() looks this map up under our own id, so the whole set is reported here rather than one widget per field. Readonly fields are left out, as the server has nothing to validate for them.
Legacy et2_customfields_list method name, kept for templates whose onchange handlers still call it. Use getValue() instead. 		-

Learn more about methods.

Inherited methods (21)

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
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
_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

Parts

Name Description
base Container around all customfield rows.
field Container for one rendered customfield widget.

Learn more about customizing CSS parts.

Belongs to

Custom fields

These widgets are related by naming but not by inheritance or sub-widget composition.