Element: <oj-form-layout>

Oracle® JavaScript Extension Toolkit (JET)
17.1.0
G12196-01

Since:
  • 4.1.0
Module:
  • ojformlayout

QuickNav

Slots

Attributes

Methods

Other Topics


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.

Accessbility

For a form control to be accessible, it should be labelled, which can be a visible label or, in the case there is no visible label, an aria-label or aria-labelledby attribute.

oj-form-layout or form controls can dynamically create labels at different locations based on the combinations of label-edge and label-hint. Refer to the documentation of the label-edge and label-hint attributes for details.

If a form control has label-edge=“none” and a label-hint attribute but no labelled-by, aria-label, or aria-labelledby attribute, the label-hint value will be used as the aria-label.

Migration

Read about current Core Pack limitations to decide when to migrate.
Please make note of the following:

To migrate from oj-form-layout to oj-c-form-layout, you need to revise the import statement and references to oj-c-form-layout in your app. Please note the changes between the two components below.

The oj-c-form-layout is not compatible with legacy form components, only core pack form components. If you are using a mix of legacy and core pack components, you will need to use legacy oj-form-layout.

ColspanWrap attribute

The colspan-wrap attribute was removed because oj-c-form-layout only supports wrap for components spanning more than one column.

LabelWidth attribute

The LabelWidth attribute has been renamed to LabelStartWidth but has the same functionality.

oj-label-value not supported

  • non form controls - currently only Core Pack form controls are supported in oj-c-form-layout. If you are using oj-label-value to add other components you'll need to stick to legacy oj-form-layout for now
  • column spanning - all Core Pack form components and oj-c-form-layout have a column-span attribute, so oj-label-value is not needed for column spanning


Usage

Signature:

interface FormLayoutElement

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

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

For additional information visit:

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>

CSS Variables

See JET CSS Variables for additional details.
Name Type Description
--oj-form-layout-margin-bottom <length> Bottom margin of each row in a form layout
--oj-form-layout-column-min-width <length> Form layout column min width
--oj-form-layout-column-max-width <length> Form layout column max width
--oj-form-layout-start-edge-column-min-width <length> Form layout column min width when label-edge is set to start
--oj-form-layout-start-edge-column-max-width <length> Form layout column max width when label-edge is set to start
--oj-form-layout-column-gutter <length> Gutter between form layout columns
--oj-form-layout-top-edge-label-to-value-padding <length> Vertical padding between the label and value when label-edge is set to top in a form layout
--oj-form-layout-start-edge-label-text-align start | end Label text align when label-edge is set to start in a form layout
--oj-form-layout-start-edge-value-text-align start | end Value text align when label-edge is set to start in a form layout
--oj-form-layout-start-edge-label-to-value-padding <length> Horizontal padding between the label and value when label-edge is set to start in a form layout
--oj-form-layout-horizontal-margin <length> Form layout horizontal margin
--oj-form-layout-divider-width <length> Form layout divider width
--oj-form-layout-divider-margin <length> Form layout divider margin

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

columns :number

Specifies the absolute number of columns and overrides max-columns, if the value is positive. If the value is not positive, then this attribute is ignored and max-columns is used to determine the number of columns. This attribute should only be used in special circumstances where you need a specific number of columns even if the fields will be narrower than the suggested minimum (a nested form layout might be an example).

Default Value:
  • 0
Names
Item Name
Property columns
Property change event columnsChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-columns-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. The oj-form-layout component uses the MetadataTypes.PropertyBinding provide property to provide its label-edge attribute to any descendent form components and oj-form-layout. It also uses MetadataTypes.ProvideProperty transform property to transform the label-edge attribute to its descendent form components. The form components and the oj-form-layout are configured to consume the label-edge property if it is not explicitly set. For example, if the oj-form-layout's label-edge attribute is set to "top" or "start", and a descendent form component does not have its label-edge attribute set, the form component's label-edge will be the transformed value "provided".

When using the oj-form-layout custom element inside of a VDOM application, this property will not propagate down to the child components. This is because binding propagation is Knockout-based, and VDOM applications are not Knockout-based.

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's label-edge is not explicitly set. 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‘s label-edge is not explicitly set. 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.

When using the oj-form-layout custom element inside of a VDOM application, this property will not propagate down to the child components. This is because binding propagation is Knockout-based, and VDOM applications are not Knockout-based.

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.

When using the oj-form-layout custom element inside of a VDOM application, this property will not propagate down to the child components. This is because binding propagation is Knockout-based, and VDOM applications are not Knockout-based.

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 will be responsively determined based on the viewport size and the column width specified in the theme. Note that max-columns will be ignored if columns has a positive value.
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 component uses the MetadataTypes.PropertyBinding provide property to provide its readonly property to any descendent components that are configured to consume it. The form components and the oj-form-layout are configured to consume the readonly property if it is not explicitly set. For example, if the oj-form-layout's readonly attribute is set to true, and a descendent form component does not have its readonly attribute set, the form component's readonly will be true.

When using the oj-form-layout custom element inside of a VDOM application, this property will not propagate down to the child components. This is because binding propagation is Knockout-based, and VDOM applications are not Knockout-based.

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')

Note: This attribute is not supported in the following themes: Alta

Specifies the density of the form layout'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 component uses the MetadataTypes.PropertyBinding provide property to provide its user-assistance-density property to any descendent components that are configured to consume it. The form components and the oj-form-layout are configured to consume the user-assistance-density property if it is not explicitly set. For example, oj-form-layout's user-assistance-density defaults to 'efficient', so all its oj-form-layout and form control descendants will have user-assistance-density='efficient' by default.

When using the oj-form-layout custom element inside of a VDOM application, this property will not propagate down to the child components. This is because binding propagation is Knockout-based, and VDOM applications are not Knockout-based.

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