$w.FormElement

$w.FormElement

Provides functionality related to user input elements.

Mixes In

$w.Element, $w.ValidatableMixin, $w.ValueMixin

Contents

global Indicates if an element appears on all pages or only on the current page.
id Gets the elements's ID.
parent Gets the element's parent element.
rendered Indicates if an element is currently displayed.
type Gets the element's type.
valid Indicates if an input element's value is valid.
validationMessage Gets a message indicating why the element is invalid, or an empty string if the message is valid.
validity Gets a ValidityState object that contains detailed information about the validity states of the element.
value Sets or gets an element's value.
onChange( ) Adds an event handler that runs when an input element's value is changed.
onCustomValidation( ) Adds an event handler that runs when the element's validation is checked.
onMouseIn( ) Adds an event handler that runs when the mouse pointer is moved onto the element.
onMouseOut( ) Adds an event handler that runs when the mouse pointer is moved off of the element.
onViewportEnter( ) Adds an event handler that runs when an element is displayed in the viewable part of the current window.
onViewportLeave( ) Adds an event handler that runs when an element is no longer displayed in the viewable part of the current window.
resetValidityIndication( ) Resets the element's visual validity indication.
scrollTo( ) Scrolls the page to the element using an animation.
updateValidityIndication( ) Updates the element's visual validity indication based on its current validity state.
global

global

Indicates if an element appears on all pages or only on the current page.

Syntax

get global(): boolean

Description

If global is true, the element appears on all pages.

If global is false, the element only appears on the current page.

Type

Boolean

Examples

Get whether an element is displayed on all pages

bGV0IGlzR2xvYmFsID0gJHcoIiNteUVsZW1lbnQiKS5nbG9iYWw7IC8vIGZhbHNlCg==
let isGlobal = $w("#myElement").global; // false

Default Value

false

Mixed In From

$w.Element

id

id

Gets the elements's ID.

Syntax

get id(): string

Description

The ID is the element's unique identifier. It is used when selecting elements using the $w() function.

An element's id is set in the Editor using the Properties panel.

Type

String

Examples

Get the ID

bGV0IG15SWQgPSAkdygiI215RWxlbWVudCIpLmlkOyAvLyAibXlFbGVtZW50Igo=
let myId = $w("#myElement").id; // "myElement"

Mixed In From

$w.Element

parent

parent

Gets the element's parent element.

Syntax

get parent(): Node

Description

Some elements can contain other elements. This occurs when you drag an element onto a container element. The container is the parent of all the elements it contains.

Page, Header, and Footer are top-level elements and have no parent.

Type

Node

Examples

Get the parent element and the parent's ID

bGV0IHBhcmVudEVsZW1lbnQgPSAkdygiI215RWxlbWVudCIpLnBhcmVudDsKCmxldCBwYXJlbnRJZCA9IHBhcmVudEVsZW1lbnQuaWQ7IC8vICJwYWdlMSIK
let parentElement = $w("#myElement").parent;

let parentId = parentElement.id; // "page1"

Default Value

null

Mixed In From

$w.Element

See Also

children

rendered

rendered

Indicates if an element is currently displayed.

Syntax

get rendered(): boolean

Description

If rendered is true, the element is in the current DOM structure and can be used.

If rendered is false the element is not in the current DOM structure.

Some reasons the element might not be in the DOM inclue:

  • It is in a slide which is not currently showing.
  • It is in a mode which is not currently active. For example, it is in the hover mode of a hover box.

Type

Boolean

Default Value

false

Mixed In From

$w.Element

See Also

collapsed, hidden, isVisible

type

type

Gets the element's type.

Syntax

get type(): string

Type

String

Examples

Get the element's type

bGV0IG15VHlwZSA9ICR3KCIjbXlFbGVtZW50IikudHlwZTsgLy8gIiR3LlR5cGUiCg==
let myType = $w("#myElement").type; // "$w.Type"

Mixed In From

$w.Element

valid

valid

Indicates if an input element's value is valid.

Syntax

get valid(): boolean

Description

The valid property indicates if an element's value satisfies all conditions to pass a validation check. This includes basic validity conditions, such as whether the element has a value if it is required, and those specified in its onCustomValidation() event handler, if you defined one.

Note that validations other than required, including custom validations, are not run on input elements when they don't have a value.

Type

Boolean

Examples

Get whether the element is valid

bGV0IGlzVmFsaWQgPSAkdygiI215RWxlbWVudCIpLnZhbGlkOyAvLyBmYWxzZQo=
let isValid = $w("#myElement").valid; // false

Mixed In From

$w.ValidatableMixin

See Also

onCustomValidation( )

validationMessage

validationMessage

Gets a message indicating why the element is invalid, or an empty string if the message is valid.

Syntax

get validationMessage(): string

Description

Set the value of the validationMessage property using the reject() function of the onCustomValidation() event handler.

Type

String

Examples

Get the validation message

bGV0IG1zZyA9ICR3KCIjbXlFbGVtZW50IikudmFsaWRhdGlvbk1lc3NhZ2U7IC8vICJ2YWx1ZSBtaXNzaW5nIgo=
let msg = $w("#myElement").validationMessage; // "value missing"

Mixed In From

$w.ValidatableMixin

See Also

validity

validity

validity

Gets a ValidityState object that contains detailed information about the validity states of the element.

Syntax

get validity(): ValidityState

Type

ValidityState

Examples

Log ValidityState info

bGV0IHZhbGlkaXR5T2JqID0gJHcoIiNteUVsZW1lbnQiKS52YWxpZGl0eTsKCmxldCBjdXN0b21FcnJvciA9IHZhbGlkaXR5T2JqLmN1c3RvbUVycm9yOyAgICAgICAgICAvLyB0cnVlCmxldCB2YWxpZCA9IHZhbGlkaXR5T2JqLnZhbGlkOyAgICAgICAgICAgICAgICAgICAgICAvLyBmYWxzZQpsZXQgdmFsdWVNaXNzaW5nID0gdmFsaWRpdHlPYmoudmFsdWVNaXNzaW5nOyAgICAgICAgLy8gZmFsc2UKbGV0IHR5cGVNaXNtYXRjaCA9IHZhbGlkaXR5T2JqLnR5cGVNaXNtYXRjaDsgICAgICAgIC8vIGZhbHNlCmxldCBwYXR0ZXJuTWlzbWF0Y2ggPSB2YWxpZGl0eU9iai5wYXR0ZXJuTWlzbWF0Y2g7ICAvLyBmYWxzZQpsZXQgdG9vTG9uZyA9IHZhbGlkaXR5T2JqLnRvb0xvbmc7ICAgICAgICAgICAgICAgICAgLy8gZmFsc2UKbGV0IHRvb1Nob3J0ID0gdmFsaWRpdHlPYmoudG9vU2hvcnQ7ICAgICAgICAgICAgICAgIC8vIGZhbHNlCmxldCByYW5nZVVuZGVyZmxvdyA9IHZhbGlkaXR5T2JqLnJhbmdlVW5kZXJmbG93OyAgICAvLyBmYWxzZQpsZXQgcmFuZ2VPdmVyZmxvdyA9IHZhbGlkaXR5T2JqLnJhbmdlT3ZlcmZsb3c7ICAgICAgLy8gZmFsc2UKbGV0IGZpbGVOb3RVcGxvYWRlZCA9IHZhbGlkaXR5T2JqLmZpbGVOb3RVcGxvYWRlZDsgIC8vIGZhbHNlCmxldCBzdGVwTWlzbWF0Y2ggPSB2YWxpZGl0eU9iai5zdGVwTWlzbWF0Y2g7ICAgICAgICAvLyBmYWxzZQpsZXQgYmFkSW5wdXQgPSB2YWxpZGl0eU9iai5iYWRJbnB1dDsgICAgICAgICAgICAgICAgLy8gZmFsc2UK
let validityObj = $w("#myElement").validity;

let customError = validityObj.customError;          // true
let valid = validityObj.valid;                      // false
let valueMissing = validityObj.valueMissing;        // false
let typeMismatch = validityObj.typeMismatch;        // false
let patternMismatch = validityObj.patternMismatch;  // false
let tooLong = validityObj.tooLong;                  // false
let tooShort = validityObj.tooShort;                // false
let rangeUnderflow = validityObj.rangeUnderflow;    // false
let rangeOverflow = validityObj.rangeOverflow;      // false
let fileNotUploaded = validityObj.fileNotUploaded;  // false
let stepMismatch = validityObj.stepMismatch;        // false
let badInput = validityObj.badInput;                // false

Mixed In From

$w.ValidatableMixin

See Also

validationMessage

value

value

Sets or gets an element's value.

Syntax

get value(): string
set value(value: string): void

Type

String

Examples

Get an element's value

bGV0IG15VmFsdWUgPSAkdygiI215RWxlbWVudCIpLnZhbHVlOyAvLyAiNDIiCg==
let myValue = $w("#myElement").value; // "42"

Set an element's value

JHcoIiNteUVsZW1lbnQiKS52YWx1ZSA9IDQyOwo=
$w("#myElement").value = 42;
onChange( )

onChange( )

Adds an event handler that runs when an input element's value is changed.

function onChange(handler: EventHandler): Element
callback EventHandler(event: Event, $w: Function): void

Description

An element receives a change event when a user changes the value in an input element.

A change event is not triggered when you change an element's value using the element's value property.

Parameters

handler function(event, $w) The name of the function or the function expression to run when the element's value changes.
event Event The event that occurred.
$w $w Deprecated: A selector function. The $w function enables event handlers to work with elements in repeaters and in the global scope.

Return Value

Element The element on which the event is now registered.

Examples

Get the value of the element that was changed

JHcoIiNteUVsZW1lbnQiKS5vbkNoYW5nZSggKGV2ZW50LCAkdykgPT4gewogIGxldCBuZXdWYWx1ZSA9IGV2ZW50LnRhcmdldC52YWx1ZTsgIC8vICJuZXcgdmFsdWUiCn0pOwo=
$w("#myElement").onChange( (event, $w) => {
  let newValue = event.target.value;  // "new value"
});

Mixed In From

$w.ValueMixin

onCustomValidation( )

onCustomValidation( )

Adds an event handler that runs when the element's validation is checked.

function onCustomValidation(validator: Validator): void
callback Validator(value: string | File[] | boolean, reject: Function): void

Description

The onCustomValidation() function allows you perform custom validation in addition to any basic validation that was defined in the Editor.

To invalidate the element, call the reject() function that is passed into the validator callback function and pass it a validation message.

The element's validity is checked when the value of the element changes either by user interaction or programmatically.

Note that validations other than required, including custom validations, are not run on input elements when they don't have a value.

Parameters

validator function(value, reject) The name of the function or the function expression to run when the element's custom validation is checked.
value String |
File[ ] |
Boolean
The value of the element being validated.
reject Function A function that invalidates the element with the specified message.

Examples

Set an element to invalid if its value is "evil"

JHcoIiNteUVsZW1lbnQiKS5vbkN1c3RvbVZhbGlkYXRpb24oICh2YWx1ZSwgcmVqZWN0KSA9PiB7CiAgaWYodmFsdWUgPT09ICJldmlsIikgewogICAgcmVqZWN0KCJFdmlsIGlzIGludmFsaWQiKTsKICB9Cn0gKTsK
$w("#myElement").onCustomValidation( (value, reject) => {
  if(value === "evil") {
    reject("Evil is invalid");
  }
} );

Mixed In From

$w.ValidatableMixin

onMouseIn( )

onMouseIn( )

Adds an event handler that runs when the mouse pointer is moved onto the element.

function onMouseIn(handler: MouseEventHandler): Element
callback MouseEventHandler(event: MouseEvent, $w: Function): void

Parameters

handler function(event, $w) The name of the function or the function expression to run when the mouse pointer is moved onto the element.
event MouseEvent The mouse event that occurred.
$w $w Deprecated: A selector function. The $w function enables event handlers to work with elements in repeaters and in the global scope.

Return Value

Element The element to which the event handler was added.

Examples

Get the mouse event info when the mouse enters an element

JHcoIiNteUVsZW1lbnQiKS5vbk1vdXNlSW4oIChldmVudCwgJHcpID0+IHsKICBsZXQgY2xpZW50WCA9IGV2ZW50LmNsaWVudFg7ICAvLyAzNjIKICBsZXQgY2xpZW50WSA9IGV2ZW50LmNsaWVudFk7ICAvLyAyNDQKICBsZXQgb2Zmc2V0WCA9IGV2ZW50Lm9mZnNldFg7ICAvLyAxMAogIGxldCBvZmZzZXRZID0gZXZlbnQub2Zmc2V0WTsgIC8vIDEyCiAgbGV0IHBhZ2VYID0gZXZlbnQucGFnZVg7ICAgICAgLy8gMzYyCiAgbGV0IHBhZ2VZID0gZXZlbnQucGFnZVk7ICAgICAgLy8gMzc2CiAgbGV0IHNjcmVlblggPSBldmVudC5zY3JlZW5YOyAgLy8gMzg5NwogIGxldCBzY3JlZW5ZID0gZXZlbnQuc2NyZWVuWTsgIC8vIDM2Mgp9ICk7Cg==
$w("#myElement").onMouseIn( (event, $w) => {
  let clientX = event.clientX;  // 362
  let clientY = event.clientY;  // 244
  let offsetX = event.offsetX;  // 10
  let offsetY = event.offsetY;  // 12
  let pageX = event.pageX;      // 362
  let pageY = event.pageY;      // 376
  let screenX = event.screenX;  // 3897
  let screenY = event.screenY;  // 362
} );

Mixed In From

$w.Element

onMouseOut( )

onMouseOut( )

Adds an event handler that runs when the mouse pointer is moved off of the element.

function onMouseOut(handler: MouseEventHandler): Element
callback MouseEventHandler(event: MouseEvent, $w: Function): void

Parameters

handler function(event, $w) The name of the function or the function expression to run when the mouse pointer is moved off of the element.
event MouseEvent The mouse event that occurred.
$w $w Deprecated: A selector function. The $w function enables event handlers to work with elements in repeaters and in the global scope.

Return Value

Element The element to which the event handler was added.

Examples

Get the mouse event info when the mouse exits an element

JHcoIiNteUVsZW1lbnQiKS5vbk1vdXNlT3V0KCAoZXZlbnQsICR3KSA9PiB7CiAgbGV0IGNsaWVudFggPSBldmVudC5jbGllbnRYOyAgLy8gMzYyCiAgbGV0IGNsaWVudFkgPSBldmVudC5jbGllbnRZOyAgLy8gMjQ0CiAgbGV0IG9mZnNldFggPSBldmVudC5vZmZzZXRYOyAgLy8gMTAKICBsZXQgb2Zmc2V0WSA9IGV2ZW50Lm9mZnNldFk7ICAvLyAxMgogIGxldCBwYWdlWCA9IGV2ZW50LnBhZ2VYOyAgICAgIC8vIDM2MgogIGxldCBwYWdlWSA9IGV2ZW50LnBhZ2VZOyAgICAgIC8vIDM3NgogIGxldCBzY3JlZW5YID0gZXZlbnQuc2NyZWVuWDsgIC8vIDM4OTcKICBsZXQgc2NyZWVuWSA9IGV2ZW50LnNjcmVlblk7ICAvLyAzNjIKfSApOwo=
$w("#myElement").onMouseOut( (event, $w) => {
  let clientX = event.clientX;  // 362
  let clientY = event.clientY;  // 244
  let offsetX = event.offsetX;  // 10
  let offsetY = event.offsetY;  // 12
  let pageX = event.pageX;      // 362
  let pageY = event.pageY;      // 376
  let screenX = event.screenX;  // 3897
  let screenY = event.screenY;  // 362
} );

Mixed In From

$w.Element

onViewportEnter( )

onViewportEnter( )

Adds an event handler that runs when an element is displayed in the viewable part of the current window.

function onViewportEnter(handler: EventHandler): Element
callback EventHandler(event: Event, $w: Function): void

Description

An element enters the viewport when the page is scrolled to show any part of the element. An element also enters the viewport if it was hidden or collapsed and is then shown or expanded in the viewable part of the current window.

Parameters

handler function(event, $w) The name of the function or the function expression to run when the element enters the viewport.
event Event The event that occurred.
$w $w Deprecated: A selector function. The $w function enables event handlers to work with elements in repeaters and in the global scope.

Return Value

Element The element on which the event is now registered.

Examples

Get the ID of the element that has entered the viewport

JHcoIiNteUVsZW1lbnQiKS5vblZpZXdwb3J0RW50ZXIoIChldmVudCwgJHcpID0+IHsKICBsZXQgdGFyZ2V0SWQgPSBldmVudC50YXJnZXQuaWQ7IC8vICJteUVsZW1lbnQiCn0pOwo=
$w("#myElement").onViewportEnter( (event, $w) => {
  let targetId = event.target.id; // "myElement"
});

Mixed In From

$w.Element

See Also

onViewportLeave( )

onViewportLeave( )

onViewportLeave( )

Adds an event handler that runs when an element is no longer displayed in the viewable part of the current window.

function onViewportLeave(handler: EventHandler): Element
callback EventHandler(event: Event, $w: Function): void

Description

An element leaves the viewport when the page is scrolled so that the elements is completely out of view. An element also leaves the viewport if it was shown or expanded and is then hidden or collapsed from the viewable part of the current window.

Parameters

handler function(event, $w) The name of the function or the function expression to run when the element leaves the viewport.
event Event The event that occurred.
$w $w Deprecated: A selector function. The $w function enables event handlers to work with elements in repeaters and in the global scope.

Return Value

Element The element on which the event is now registered.

Examples

Get the ID of the element that has entered the viewport

JHcoIiNteUVsZW1lbnQiKS5vblZpZXdwb3J0TGVhdmUoIChldmVudCwgJHcpID0+IHsKICBsZXQgdGFyZ2V0SWQgPSBldmVudC50YXJnZXQuaWQ7IC8vICJteUVsZW1lbnQiCn0pOwo=
$w("#myElement").onViewportLeave( (event, $w) => {
  let targetId = event.target.id; // "myElement"
});

Mixed In From

$w.Element

See Also

ViewportMixin-onViewportEnter( )

resetValidityIndication( )

resetValidityIndication( )

Resets the element's visual validity indication.

function resetValidityIndication(): void

Description

Many elements have a visual cue that indicates whether they are valid or not. For example, a text input that usually has a black outline might have a red outline when its value is not valid.

The resetValidityIndication() function resets the validity indication of an element to show the element as valid. The actual validity state of the element is not affected. If the element was invalid, it remains invalid. The validity indication shows the element as valid until the element's validity is checked when the value of the element changes either by user interaction or programmatically. At that point, the element's validity indication shows the element as invalid if its value is not valid.

Mixed In From

$w.ValidatableMixin

scrollTo( )

scrollTo( )

Scrolls the page to the element using an animation.

function scrollTo(): Promise<void>

Description

The scrollTo() function returns a Promise that is resolved when the animated scroll is complete and the element is now in view.

To scroll to a specific location on the page, see the wix-window scrollTo() function.

Calling the scrollTo() function on an element in a repeated item that is selected from the global scope causes an error.

Return Value

Returns a Promise

On fulfillment void When the scroll is complete.

Examples

Scroll the page to an element

JHcoIiNteUVsZW1lbnQiKS5zY3JvbGxUbygpOwo=
$w("#myElement").scrollTo();

Scroll the page to an element and log message when done

JHcoIiNteUVsZW1lbnQiKS5zY3JvbGxUbygpCiAgLnRoZW4oICggKSA9PiB7CiAgICBjb25zb2xlLmxvZygiRG9uZSB3aXRoIHNjcm9sbCIpOwp9ICk7Cg==
$w("#myElement").scrollTo()
  .then( ( ) => {
    console.log("Done with scroll");
} );

Mixed In From

$w.Element

updateValidityIndication( )

updateValidityIndication( )

Updates the element's visual validity indication based on its current validity state.

function updateValidityIndication(): void

Description

Many elements have a visual cue that indicates whether they are valid or not. For example, a text input that usually has a black outline might have a red outline when its value is not valid.

Examples

Update an element's validatity indicator

JHcoIiNteUVsZW1lbnQiKS51cGRhdGVWYWxpZGl0eUluZGljYXRpb24oKTsK
$w("#myElement").updateValidityIndication();

Mixed In From

$w.ValidatableMixin