Element: <oj-form-layout>

Oracle® JavaScript Extension Toolkit (JET)
9.0.0
F24343-01

Signature:

class ojFormLayout

QuickNav

Slots

Attributes

Methods

JET Custom Elements

JET components are implemented as custom HTML elements. In addition to the component attributes documented in this page, JET components also support standard HTML global attributes like id and aria-label.

The JET data binding syntax can be used to define both component and global attributes through the use of dynamically evaluated expressions. All attributes (component and global) support attribute-level binding by prefixing the attribute name with ":" (e.g. :id="[...]"). When using attribute-level binding, all expression values are treated as strings. Additionally, component attributes support property-level binding by using the attribute name directly with no ":" prefix. When using property-level binding, the expressions should evaluate to the types documented by the corresponding attributes. Property-level binding is strongly recommended over attribute-level binding for component attributes.

A detailed description of working with custom HTML elements can be found in: JET Custom Element Usage.


Version:
  • 9.0.0
Since:
  • 4.1.0
Module:
  • ojformlayout

Module usage

See JET Module Loading for an overview of module usage within JET.

Typescript Import Format
//To typecheck the element APIs, import as below.
import {ojFormLayout} from "ojs/ojformlayout";

//For the transpiled javascript to load the element's module, import as below
import "ojs/ojformlayout";

JET In Typescript

A detailed description of working with JET elements and classes in your typescript project can be found at: JET Typescript Usage.


JET FormLayout

The oj-form-layout element is used to layout groups of label/value pairs in an organized layout that can be optimized for multiple display sizes via attribute value settings. The following describes how child elements are handled:

- The following JET components have a label-hint attribute that allows them to be treated as a label/value pair with an oj-label element dynamically created from the label-hint and help-hints:
oj-checkboxset, oj-color-palette, oj-color-spectrum, oj-input-date, oj-input-date-time, oj-input-time, oj-input-number, oj-input-text, oj-text-area, oj-input-password, oj-combobox-one, oj-combobox-many, oj-radioset, oj-select-one, oj-select-many, oj-slider, oj-switch
- An oj-label element, followed by any element. The oj-label element will be in the label area and the next element will be in the value area
- An oj-label-value child component allows the developer to place elements in the label and/or value area as 'label' and 'value' slot chilren.
- All other elements will span the entire width of a single label/value pair. To have a form element span multiple columns, add an oj-label-value component as a child of the oj-form-layout add the component that you want to span multiple columns as a child of the oj-label-value. The colspan attribute on the oj-label-value is used to specify the number of columns to span, and the direction attribute on the oj-form-layout must be set to "row". NOTE: To minimize the need for adding a style attribute to achieve a max-width of 100% on the column spanning component and to facilitate start and end field alignment, the default max-width for form controls is changed to 100% when all of the following conditions are met: - direction == "row" - max-columns > 1 - there is at least one oj-label-value child with a colspan attribute specified.

For example: 


<oj-form-layout max-columns='2' label-edge='start' label-width="50%">
  <oj-input-text id="inputcontrol" required value="text" label-hint="input 1"></oj-input-text>
  <oj-text-area id="textareacontrol" value='text' rows="6" label-hint="textarea"></oj-text-area>
  <oj-input-text id="inputcontrol2" value="text" label-hint="input 2"></oj-input-text>
  <oj-input-text id="inputcontrol3" value="text" label-hint="input 3 longer label"></oj-input-text>
  <oj-label>oj-label in label area</oj-label>
  <p>Next element in value area</p>
  <oj-label-value id="labelonly">
    <p slot="label">Some text in the label area</p>
  </oj-label-value>
  <oj-label-value id="valueonly">
    <p slot="value">Some text in the value area</p>
  </oj-label-value>
  <p>Some text that spans the label/value area</p>
</oj-form-layout>

The oj-form-layout element currently supports custom element children that support the label-hint and help-hints attributes (oj-input-text, oj-text-area, etc.). For each custom element child with label-hint, FormLayout will generate an oj-label element and pair them together in the layout.

Note: Application logic should not interact with the component's properties or invoke its methods until the BusyContext indicates that the component is ready for interaction.

Styling Classes

.oj-formlayout-full-width
In Redwood by default a form layout has a max width, add this class if you'd like to opt out and have the form layout to stretch the full width.
Example
<oj-form-layout class="oj-formlayout-full-width">
</oj-form-layout>

Slots

JET components that allow child content support slots. Please see the slots section of the JET component overview doc for more information on allowed slot content and slot types.

Default

The <oj-form-layout> element only accepts element children in the Default slot. Content in <oj-form-layout>'s Default slot will be laid out in a row/column style form layout.

Since:
  • 4.1.0

Attributes

colspan-wrap :nowrap|wrap

Specifies how to fit components with colspan attribute in the form layout, when there are fewer columns left in the current row than the colspan value specifies.

The default value depends on the theme.

Supported Values:
Value Description
nowrap The component will occupy the remaining columns in the current row.
wrap The component will start from the first column of the next row.
Names
Item Name
Property colspanWrap
Property change event colspanWrapChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-colspan-wrap-changed

direction :column|row

Specifies the layout direction of the form layout children.

The default value depends on the theme.

Supported Values:
Value Description
column Components are laid out in columns
row Components are laid out in rows
Names
Item Name
Property direction
Property change event directionChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-direction-changed

label-edge :inside|start|top

Specifies how the label is created and aligned with its form control.

The default value varies by theme, and it works well for the theme in most cases. If this attribute is set to an explicit value, The label-edge attribute on all form controls should also be set to an explict value. For example, if this attribute is set to "start" or "top", the label-edge attribute of all form controls should be set to "provided".

Supported Values:
Value Description
inside oj-form-layout will not create any label. Label will be created by the form control if the form control has its label-edge set to "inside". Please see the specific form control's label-edge attribute documentation for details.
start oj-form-layout will create a label that's before the start of the form control if the form control has its label-edge set to "provided". If the form control specifies "inside" or "none" as its label-edge, no label will be created by oj-form-layout.
top oj-form-layout will create a label that's on top of the form control if the form control has its label-edge set to "provided". If the form control specifies "inside" or "none" as its label-edge, no label will be created by oj-form-layout.
Names
Item Name
Property labelEdge
Property change event labelEdgeChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-label-edge-changed

label-width :string

Specifies the label width.

This specifies the width of the oj-label elements. This can be any legal CSS width.

Default Value:
  • "33%"
Names
Item Name
Property labelWidth
Property change event labelWidthChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-label-width-changed

label-wrapping :truncate|wrap

Specifies if the label text should wrap or truncate.
Supported Values:
Value Description
truncate Label will truncate if needed
wrap Label will wrap if needed
Default Value:
  • "wrap"
Names
Item Name
Property labelWrapping
Property change event labelWrappingChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-label-wrapping-changed

max-columns :number

Specifies the maximum number of columns. The actual number of columns may be less, depending on the direction attribute.

If direction is "column", the layout is responsive and browsers automatically reduce the number of columns to fit the width of the viewport.

If direction is "row", the number of columns is fixed to the max-columns value. Applications can choose to make it responsive by using ResponsiveKnockoutUtils to adjust the value. See the oj-form-layout - Across demo for an example.

Default Value:
  • 1
Names
Item Name
Property maxColumns
Property change event maxColumnsChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-max-columns-changed

readonly :boolean

Specifies whether the form is readonly. A readonly form has no reserved rows for user assistance text.

The oj-form-layout provides its readonly attribute value and the form components consume it if it is not already set explicitly. For example, if oj-form-layout is set to readonly='true', all the form components it contains will be readonly='true' by default.

Default Value:
  • false
Names
Item Name
Property readonly
Property change event readonlyChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-readonly-changed

user-assistance-density :('reflow'|'efficient'|'compact')

Specifies the density of the form component's user assistance presentation. It can be shown inline with reserved rows to prevent reflow if a user assistance text shows up, inline without reserved rows, or it can be shown compactly in a popup instead.

The oj-form-layout provides its user-assistance-density attribute value or its default value and the form components consumes it if it is not already set explicitly. For example, if oj-form-layout is set or defaults to user-assistance-density='efficient', all the form components it contains will be user-assistance-density='efficient' by default. This is why when a form component is inside an oj-form-layout component the form component's user-assistance-density is 'efficient', and when a form component is not inside an oj-form-layout component, the form component's user-assistance-density is 'reflow'.

A form component can explicitly set its own user-assistance-density attribute which will take precedence over the oj-form-layout's.

This attribute is ignored in the Alta theme.

Supported Values:
Value Description
compact messages, help, hints, and required will not be shown inline; they will show in a mode that keeps the screen more compact, like a popup for the messages, and a required icon to indicate Required.
efficient messages, help, hints, and required are all shown inline under the field with reserved space underneath.
reflow If reflow, messages, help, hints, and required are all shown inline under the field with no reserved space.
Default Value:
  • "efficient"
Names
Item Name
Property userAssistanceDensity
Property change event userAssistanceDensityChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-user-assistance-density-changed

Methods

getProperty(property) : {any}

Retrieves a value for a property or a single subproperty for complex properties.
Parameters:
Name Type Description
property string The property name to get. Supports dot notation for subproperty access.
Returns:
Type
any

refresh() : {void}

Refreshes the visual state of the component.
Returns:
Type
void

setProperties(properties) : {void}

Performs a batch set of properties.
Parameters:
Name Type Description
properties Object An object containing the property and value pairs to set.
Returns:
Type
void

setProperty(property, value) : {void}

Sets a property or a single subproperty for complex properties and notifies the component of the change, triggering a [property]Changed event.
Parameters:
Name Type Description
property string The property name to set. Supports dot notation for subproperty access.
value any The new value to set the property to.
Returns:
Type
void