EGroupware
Examples
Grouping widgets
Hiding a group
Aligning the contents
Aligning one child
Images do not stretch
An id opens a namespace
Slots
LitElement
Methods

Box

<et2-box> | Et2Box

A basic wrapper to group other widgets

et2-box is the plain wrapper. It has no visual appearance of its own - no border, no label, no padding - it just puts its children in a flex row and gets out of the way. Use it to keep a few widgets together so they can be shown, hidden, aligned or styled as one unit.

If you want a guaranteed direction and a gap between the children, use et2-hbox or et2-vbox instead. They are this same widget with the layout fixed.

Examples

Grouping widgets

Children are laid out in a row, in source order, and stretched to the same height.

<et2-box>
    <et2-button label="Save"></et2-button>
    <et2-button label="Apply"></et2-button>
    <et2-button label="Cancel"></et2-button>
</et2-box>

Hiding a group

hidden on the box takes the whole group out of the layout, which is the usual reason to wrap widgets in a box in the first place - one attribute instead of one per widget.

disabled does exactly the same thing here. A box has nothing to grey out, so it falls back to the base widget rule of display: none, unlike an input, where the two mean different things - see Disabled vs Readonly vs Hidden. Use hidden and say what you mean.

<et2-box id="box-hide-example">
    <et2-description value="Shipping address"></et2-description>
    <et2-textbox placeholder="Street"></et2-textbox>
</et2-box>
<et2-button id="box-hide-toggle" label="Toggle the box"></et2-button>
<script>
    const box = document.getElementById("box-hide-example");
    document.getElementById("box-hide-toggle").addEventListener("click", () =>
    {
        box.hidden = !box.hidden;
    });
</script>

Aligning the contents

align on the box moves all of its children to that end of the available width. Without it they start at the left.

<et2-box align="left" style="border: 1px solid var(--sl-color-neutral-300)">
    <et2-description value="left"></et2-description>
</et2-box>
<et2-box align="center" style="border: 1px solid var(--sl-color-neutral-300)">
    <et2-description value="center"></et2-description>
</et2-box>
<et2-box align="right" style="border: 1px solid var(--sl-color-neutral-300)">
    <et2-description value="right"></et2-description>
</et2-box>

Aligning one child

align on a child moves just that child, by giving it an automatic margin on the other side. This is how you get “everything left, one thing far right” without a spacer widget.

Note that it also reorders: a child with align="right" is moved to the end of the row and one with align="left" to the front, whatever their position in the source.

<et2-box style="border: 1px solid var(--sl-color-neutral-300)">
    <et2-description value="Order #4711"></et2-description>
    <et2-button align="right" label="Delete"></et2-button>
</et2-box>

Images do not stretch

Children get flex: 1 1 auto so they share the width, but img and et2-image are held at their natural size. Otherwise an icon next to a text field would end up half the row wide.

<et2-box style="border: 1px solid var(--sl-color-neutral-300)">
    <et2-image src="image"></et2-image>
    <et2-textbox placeholder="Subject"></et2-textbox>
</et2-box>

An id opens a namespace

A box with an id is a namespace: the ids of the widgets inside it are looked up below that key in the content array, not at the top level. This is useful when a sub-template or a repeating structure has its own slice of content.

It is also the most common way to accidentally blank out a whole section of a template. If $content['address'] does not exist, every widget in the box below reads from an empty array - @ references go falsy, autorepeat grids stop repeating - and nothing is logged.

<!-- street reads $content['address']['street'], not $content['street'] -->
<et2-box id="address">
    <et2-textbox id="street"></et2-textbox>
    <et2-textbox id="city"></et2-textbox>
</et2-box>

If you only need the box for layout or to show and hide a group, leave the id off and use class or a parent widget to address it.

Slots

Name	Description
(default)	Any other widget

Learn more about using slots.

Inherited properties (18)

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`	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
`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.

Methods

Name	Description	Arguments
`getDetachedAttributes()`	Code for implementing et2_IDetachedDOM Individual widgets are detected and handled by the grid, but the interface is needed for this to happen	`_attrs: array`

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