$w.UploadButton

$w.UploadButton

An upload button enables users to upload files to your site.

Typical File Upload Scenario

In a typical scenario, the page from which files are uploaded contains an upload button and another element, such as a regular button. The user chooses which file to upload by clicking the upload button and selecting the file in a native file chooser dialog. At that point the file is stored in the upload button's value property as a File object. Then the user triggers an event, such as a button click, on the other element. That element's event handler calls the startUpload() function to perform the actual upload. The upload will either succeed and and give you an UploadedFile object, or fail and give you an UploadError object.

Examples

Typical file upload scenario

This example uploads a file when the user clicks on a button. First it checks to see if the user has chosen a file. If a file was chosen, it triggers the upload and logs the status of the upload when it completes successfully or with an error.

JHcoJyNteUJ1dHRvbicpLm9uQ2xpY2soICgpID0+IHsKICBpZiAoJHcoIiNteVVwbG9hZEJ1dHRvbiIpLnZhbHVlLmxlbmd0aCA+IDApIHsgIC8vIHVzZXIgY2hvc2UgYSBmaWxlCiAgICBjb25zb2xlLmxvZyhgVXBsb2FkaW5nICckeyR3KCIjbXlVcGxvYWRCdXR0b24iKS52YWx1ZVswXS5uYW1lfSdgKTsKICAgICR3KCIjbXlVcGxvYWRCdXR0b24iKS5zdGFydFVwbG9hZCgpCiAgICAgIC50aGVuKCAodXBsb2FkZWRGaWxlKSA9PiB7CiAgICAgICAgY29uc29sZS5sb2coIlVwbG9hZCBzdWNjZXNzZnVsLiBGaWxlIGlzIGF2YWlsYWJsZSBoZXJlOiIpOwogICAgICAgIGNvbnNvbGUubG9nKHVwbG9hZGVkRmlsZS51cmwpOwogICAgICB9ICkKICAgICAgLmNhdGNoKCAodXBsb2FkRXJyb3IpID0+IHsKICAgICAgICBjb25zb2xlLmxvZyhgRmlsZSB1cGxvYWQgZXJyb3I6ICR7dXBsb2FkRXJyb3IuZXJyb3JDb2RlfWApOwogICAgICAgIGNvbnNvbGUubG9nKHVwbG9hZEVycm9yLmVycm9yRGVzY3JpcHRpb24pOwogICAgICB9ICk7CiAgfQogIGVsc2UgeyAgLy8gdXNlciBjbGlja2VkIGJ1dHRvbiBidXQgZGlkbid0IGNob3NlIGEgZmlsZQogICAgY29uc29sZS5sb2coIlBsZWFzZSBjaG9vc2UgYSBmaWxlIHRvIHVwbG9hZC4iKQogIH0KfSApOwo=
$w('#myButton').onClick( () => {
  if ($w("#myUploadButton").value.length > 0) {  // user chose a file
    console.log(`Uploading '${$w("#myUploadButton").value[0].name}'`);
    $w("#myUploadButton").startUpload()
      .then( (uploadedFile) => {
        console.log("Upload successful. File is available here:");
        console.log(uploadedFile.url);
      } )
      .catch( (uploadError) => {
        console.log(`File upload error: ${uploadError.errorCode}`);
        console.log(uploadError.errorDescription);
      } );
  }
  else {  // user clicked button but didn't chose a file
    console.log("Please choose a file to upload.")
  }
} );

Mixes In

$w.FormElement, $w.HiddenCollapsedMixin, $w.DisabledMixin, $w.FocusMixin, $w.StyleMixin, $w.RequiredMixin

Contents

buttonLabel Sets or gets the label on the upload button.
collapsed Indicates if the element is collapsed or expanded.
enabled Indicates if the element is enabled or disabled.
fileType Sets or gets the type of file that a user can upload.
global Indicates if an element appears on all pages or only on the current page.
hidden Indicates if the element is visible or hidden.
id Gets the elements's ID.
isVisible Indicates if the element is actually visible.
parent Gets the element's parent element.
rendered Indicates if an element is currently displayed.
required Sets or gets whether an input element is required to have a value.
style Gets an object containing information about the upload button's styles.
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 Returns a list of files that are pending upload.
blur( ) Removes focus from the element.
collapse( ) Collapses the element and sets its collapsed property to true.
disable( ) Disables the element and sets its enabled property to false.
enable( ) Enables the element and sets its enabled property to true.
expand( ) Expands the element and sets its collapsed property to false.
focus( ) Places focus on the element.
hide( ) Hides the element and sets its hidden property to true, using an effect if specified.
onBlur( ) Adds an event handler that runs when the element loses focus.
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.
onFocus( ) Adds an event handler that runs when the element receives focus.
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.
reset( ) Clears the files that are pending upload.
resetValidityIndication( ) Resets the element's visual validity indication.
scrollTo( ) Scrolls the page to the element using an animation.
show( ) Shows the element and sets its hidden property to false, using an effect if specified.
startUpload( ) Uploads the files that the user has chosen.
updateValidityIndication( ) Updates the element's visual validity indication based on it's current validity state.
File The object used by the value property that represents files ready for upload.
UploadedFile The object returned by the startUpload() function's Promise that contains the URL of the successfully uploaded file.
UploadError The object returned by the startUpload() function's Promise when an upload fails.
buttonLabel

buttonLabel

Sets or gets the label on the upload button.

Syntax

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

Type

String

Examples

Get an upload button's label

bGV0IGxhYmVsID0gJHcoIiNteVVwbG9hZEJ1dHRvbiIpLmJ1dHRvbkxhYmVsOyAgLy8gIkNob29zZSBGaWxlIgo=
let label = $w("#myUploadButton").buttonLabel;  // "Choose File"

Set an upload button's label

JHcoIiNteVVwbG9hZEJ1dHRvbiIpLmJ1dHRvbkxhYmVsID0gIkNob29zZSBGaWxlIjsK
$w("#myUploadButton").buttonLabel = "Choose File";
collapsed

collapsed

Indicates if the element is collapsed or expanded.

Syntax

get collapsed(): boolean

Description

If collapsed is true, the element is not displayed on the page under any circumstances. A collapsed element, unlike a hidden element, does not take up any space on the page. When collapsed, elements positioned within 70 pixels below the collapsed element and each other will move up to take the collapsed element's place where possible. The elements that move up maintain their positions relative to one another.

If collapsed is false, the element may be displayed on the page. Elements that moved up to take the collapsed element's place on the page are moved back down.

However, an expanded element (an element whose collapsed property is false) will still not be displayed if:

Even if the element will not be displayed due to the conditions mentioned above, if its collapsed property is false, it will be displayed when the conditions no longer apply.

To set the collapsed property on an element, use the element's collapse() and expand() functions.

If you select Collapsed on load in the element's Properties panel in the Editor, the collapsed property is set to true when the page loads.

Type

Boolean

Examples

Get an element's collapsed status

bGV0IGlzQ29sbGFwc2VkID0gJHcoIiNteUVsZW1lbnQiKS5jb2xsYXBzZWQ7IC8vIGZhbHNlCg==
let isCollapsed = $w("#myElement").collapsed; // false

Toggle an element's collapsed state

aWYoICR3KCIjbXlFbGVtZW50IikuY29sbGFwc2VkICkgewogICR3KCIjbXlFbGVtZW50IikuZXhwYW5kKCk7Cn0KZWxzZSB7CiAgJHcoIiNteUVsZW1lbnQiKS5jb2xsYXBzZSgpOwp9Cg==
if( $w("#myElement").collapsed ) {
  $w("#myElement").expand();
}
else {
  $w("#myElement").collapse();
}

Default Value

false

Mixed In From

$w.HiddenCollapsedMixin

See Also

collapse( ), expand( ), hide( ), show( ), hidden

enabled

enabled

Indicates if the element is enabled or disabled.

Syntax

get enabled(): boolean

Description

If enabled is true, users can interact with the element.

If enabled is false, users cannot interact with the element.

When an element is disabled:

  • Its color is faded or grayed out.
  • Animations that the element normally exhibits when being interacting with will not occur.
  • Actions that the element has been configured to perform, such as opening a link, will not occur.
  • Event handlers that have been bound to the element, such as with onMouseIn, will not run.
  • If the element is an input element, such as a dropdown or text box, users cannot interact with it.

To set the enabled property of an element, use the element's enable() or disable() functions.

The enabled property can also be set in the Editor using the Properties panel.

Type

Boolean

Examples

Get an element's enabled status

bGV0IGlzRW5hYmxlZCA9ICR3KCIjbXlFbGVtZW50IikuZW5hYmxlZDsgLy8gdHJ1ZQo=
let isEnabled = $w("#myElement").enabled; // true

Toggle an element's enabled state

aWYoICR3KCIjbXlFbGVtZW50IikuZW5hYmxlZCApIHsKICAkdygiI215RWxlbWVudCIpLmRpc2FibGUoKTsKfQplbHNlIHsKICAkdygiI215RWxlbWVudCIpLmVuYWJsZSgpOwp9Cg==
if( $w("#myElement").enabled ) {
  $w("#myElement").disable();
}
else {
  $w("#myElement").enable();
}

Default Value

true

Mixed In From

$w.DisabledMixin

See Also

disable( ), enable( )

fileType

fileType

Sets or gets the type of file that a user can upload.

Syntax

get fileType(): FileType
set fileType(value: FileType): void
type FileType = "Image" | "Document"

Description

Setting the fileType property sets the type of file that a user can upload. The value of fileType can be set to either "Image" or "Document".

Getting the fileType property returns the current type of file that a user can upload.

The file types of the images and documents that can be uploaded are listed here.

Type

String

Examples

Get an upload button's type

bGV0IGZpbGVUeXBlID0gJHcoIiNteVVwbG9hZEJ1dHRvbiIpLmZpbGVUeXBlOyAgLy8gIkltYWdlIgo=
let fileType = $w("#myUploadButton").fileType;  // "Image"

Set an upload button's type

JHcoIiNteVVwbG9hZEJ1dHRvbiIpLmZpbGVUeXBlID0gIkRvY3VtZW50IjsK
$w("#myUploadButton").fileType = "Document";
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.FormElement

hidden

hidden

Indicates if the element is visible or hidden.

Syntax

get hidden(): boolean

Description

If hidden is true, the element is not displayed on the page under any circumstances. A hidden element, unlike a collapsed element, continues to take up the same space on the page as it did when it was visible.

If hidden is false, the element may be displayed on the page.

However, an element whose hidden property is false will still not be displayed if:

Even if the element will not be displayed due to the conditions mentioned above, if its hidden property is set to false, it will be displayed when the conditions no longer apply.

To determine if the element is actually visible, use the isVisible property.

To set the hidden property on an element, use the element's hide() or show() functions.

If you select Hidden on load in the element's Properties panel in the Editor, the hidden property is set to true when the page loads.

Type

Boolean

Examples

Get an element's hidden status

bGV0IGlzSGlkZGVuID0gJHcoIiNteUVsZW1lbnQiKS5oaWRkZW47ICAvLyBmYWxzZQo=
let isHidden = $w("#myElement").hidden;  // false

Toggle an element's hidden state

aWYoICR3KCIjbXlFbGVtZW50IikuaGlkZGVuICkgewogICR3KCIjbXlFbGVtZW50Iikuc2hvdygpOwp9CmVsc2UgewogICR3KCIjbXlFbGVtZW50IikuaGlkZSgpOwp9Cg==
if( $w("#myElement").hidden ) {
  $w("#myElement").show();
}
else {
  $w("#myElement").hide();
}

Default Value

false

Mixed In From

$w.HiddenCollapsedMixin

See Also

hide( ), show( ), collapse( ), expand( ), collapsed, rendered

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

isVisible

isVisible

Indicates if the element is actually visible.

Syntax

get isVisible(): boolean

Description

If isVisible is true, the element is displayed on the page.

If isVisible is false, the element is not displayed on the page.

The value of the isVisible property is calculated based on the hidden, collapsed, and rendered properties of the element and all of its ancestors. It will be true only if the conditions exist in the element's property values and the property values of its ancestors such that the element is actually displayed on the page.

Type

Boolean

Examples

Get whether an element is visible

bGV0IGlzVmlzaWJsZSA9ICR3KCIjbXlFbGVtZW50IikuaXNWaXNpYmxlOyAgLy8gdHJ1ZQo=
let isVisible = $w("#myElement").isVisible;  // true

Default Value

true

Mixed In From

$w.HiddenCollapsedMixin

See Also

hidden, collapsed, rendered

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

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

See Also

collapsed, hidden, isVisible

required

required

Sets or gets whether an input element is required to have a value.

Syntax

get required(): boolean
set required(value: boolean): void

Description

Setting the required property to true causes the element to be invalid if it doesn't contain a value. Setting it to false allows the element to be valid even if it doesn't contain a value. The validity of the element can be checked using it's validity property.

Getting the value of the required property returns whether the element is required.

You can also set an input element to be required by using the element's Settings pane in the Editor.

Type

Boolean

Examples

Set an element to be required

JHcoIiNteUVsZW1lbnQiKS5yZXF1aXJlZCA9IHRydWU7Cg==
$w("#myElement").required = true;

Get whether an element is required

bGV0IGlzUmVxdWlyZWQgPSAkdygiI215RWxlbWVudCIpLnJlcXVpcmVkOyAvLyB0cnVlCg==
let isRequired = $w("#myElement").required; // true

Mixed In From

$w.RequiredMixin

See Also

validity

style

style

Gets an object containing information about the upload button's styles.

Syntax

get style(): Style

Description

The following styles can be used with upload buttons:

Getting or setting an upload button's styles, gets or sets the styles of the upload button's regular state. It does not set the styles of the upload button's hover, focus, error, or disabled states.

Type

Style

Examples

Set the background color

JHcoIiNteUVsZW1lbnQiKS5zdHlsZS5iYWNrZ3JvdW5kQ29sb3IgPSAicmdiYSgyNTUsMCwwLDAuNSkiOwo=
$w("#myElement").style.backgroundColor = "rgba(255,0,0,0.5)";

Get the background color

bGV0IGJnQ29sb3IgPSAkdygiI215RWxlbWVudCIpLnN0eWxlLmJhY2tncm91bmRDb2xvcjsK
let bgColor = $w("#myElement").style.backgroundColor;
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.FormElement

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

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

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

See Also

validationMessage

value

value

Returns a list of files that are pending upload.

Syntax

get value(): File[]

Description

Returns a list of File objects that a user has selected to upload after pressing the upload button.

See how value is used in a typical file upload scenario.

Type

File[ ]

Examples

Get the files pending upload

bGV0IGZpbGVzID0gJHcoIiNteVVwbG9hZEJ1dHRvbiIpLnZhbHVlOwoKbGV0IGZpbGVOYW1lID0gZmlsZXNbMF0ubmFtZTsgLy8gIm15cGljLmpwZyIKbGV0IGZpbGVTaXplID0gZmlsZXNbMF0uc2l6ZTsgLy8gNDU5NDEK
let files = $w("#myUploadButton").value;

let fileName = files[0].name; // "mypic.jpg"
let fileSize = files[0].size; // 45941

Full file upload scenario

This example uploads a file when the user clicks on a button. First it checks to see if the user has chosen a file. If a file was chosen, it triggers the upload and logs the status of the upload when it completes successfully or with an error.

JHcoJyNteUJ1dHRvbicpLm9uQ2xpY2soICgpID0+IHsKICBpZiAoJHcoIiNteVVwbG9hZEJ1dHRvbiIpLnZhbHVlLmxlbmd0aCA+IDApIHsgIC8vIHVzZXIgY2hvc2UgYSBmaWxlCiAgICBjb25zb2xlLmxvZyhgVXBsb2FkaW5nICckeyR3KCIjbXlVcGxvYWRCdXR0b24iKS52YWx1ZVswXS5uYW1lfSdgKTsKICAgICR3KCIjbXlVcGxvYWRCdXR0b24iKS5zdGFydFVwbG9hZCgpCiAgICAgIC50aGVuKCAodXBsb2FkZWRGaWxlKSA9PiB7CiAgICAgICAgY29uc29sZS5sb2coIlVwbG9hZCBzdWNjZXNzZnVsLiBGaWxlIGlzIGF2YWlsYWJsZSBoZXJlOiIpOwogICAgICAgIGNvbnNvbGUubG9nKHVwbG9hZGVkRmlsZS51cmwpOwogICAgICB9ICkKICAgICAgLmNhdGNoKCAodXBsb2FkRXJyb3IpID0+IHsKICAgICAgICBjb25zb2xlLmxvZyhgRmlsZSB1cGxvYWQgZXJyb3I6ICR7dXBsb2FkRXJyb3IuZXJyb3JDb2RlfWApOwogICAgICAgIGNvbnNvbGUubG9nKHVwbG9hZEVycm9yLmVycm9yRGVzY3JpcHRpb24pOwogICAgICB9ICk7CiAgfQogIGVsc2UgeyAgLy8gdXNlciBjbGlja2VkIGJ1dHRvbiBidXQgZGlkbid0IGNob3NlIGEgZmlsZQogICAgY29uc29sZS5sb2coIlBsZWFzZSBjaG9vc2UgYSBmaWxlIHRvIHVwbG9hZC4iKQogIH0KfSApOwo=
$w('#myButton').onClick( () => {
  if ($w("#myUploadButton").value.length > 0) {  // user chose a file
    console.log(`Uploading '${$w("#myUploadButton").value[0].name}'`);
    $w("#myUploadButton").startUpload()
      .then( (uploadedFile) => {
        console.log("Upload successful. File is available here:");
        console.log(uploadedFile.url);
      } )
      .catch( (uploadError) => {
        console.log(`File upload error: ${uploadError.errorCode}`);
        console.log(uploadError.errorDescription);
      } );
  }
  else {  // user clicked button but didn't chose a file
    console.log("Please choose a file to upload.")
  }
} );
blur( )

blur( )

Removes focus from the element.

function blur(): void

Description

The blur() function removes focus from the element and fires a blur event.

The blur event handlers set on this element by the onBlur( ) function or in the Editor will called.

Removing focus through a call to this function is equivalent to a user clicking on another element or tabbing out of the element manually.

If blur() is called on an element that is not in focus, it has no effect. The element in focus remains in focus and the onBlur event handlers are not called.

Examples

Remove focus from an element

JHcoIiNteUVsZW1lbnQiKS5ibHVyKCk7Cg==
$w("#myElement").blur();

Mixed In From

$w.FocusMixin

See Also

onBlur( ), focus( ), onFocus( )

collapse( )

collapse( )

Collapses the element and sets its collapsed property to true.

function collapse(): Promise<void>

Description

The collapse() function returns a Promise that is resolved when the element's collapsed property has been set to true.

To learn about the behavior of a collapsed element, see the collapsed property.

You can also collapse an element when the page loads by using the Properties panel in the Editor.

Return Value

Returns a Promise

On fulfillment void When the element's collapsed property has been set to true.

Examples

Collapse an element

JHcoIiNteUVsZW1lbnQiKS5jb2xsYXBzZSgpOwo=
$w("#myElement").collapse();

Collapse an element and log a message when done

JHcoIiNteUVsZW1lbnQiKS5jb2xsYXBzZSgpCiAgLnRoZW4oICgpID0+IHsKICAgIGNvbnNvbGUubG9nKCJEb25lIHdpdGggY29sbGFwc2UiKTsKICB9ICk7Cg==
$w("#myElement").collapse()
  .then( () => {
    console.log("Done with collapse");
  } );

Toggle an element's collapsed state

aWYoICR3KCIjbXlFbGVtZW50IikuY29sbGFwc2VkICkgewogICR3KCIjbXlFbGVtZW50IikuZXhwYW5kKCk7Cn0KZWxzZSB7CiAgJHcoIiNteUVsZW1lbnQiKS5jb2xsYXBzZSgpOwp9Cg==
if( $w("#myElement").collapsed ) {
  $w("#myElement").expand();
}
else {
  $w("#myElement").collapse();
}

Mixed In From

$w.HiddenCollapsedMixin

See Also

expand( ), collapsed, hide( )

disable( )

disable( )

Disables the element and sets its enabled property to false.

function disable(): Promise<void>

Description

The disable() function returns a Promise that is resolved when the element's enabled property has been set to false.

To learn about the behavior of a disabled element, see the enabled property.

Return Value

Returns a Promise

On fulfillment void When the element's enabled property has been set to false.

Examples

Disable an element

JHcoIiNteUVsZW1lbnQiKS5kaXNhYmxlKCk7Cg==
$w("#myElement").disable();

Disable an element and log a message when done

JHcoIiNteUVsZW1lbnQiKS5kaXNhYmxlKCkKICAudGhlbiggKCkgPT4gewogICAgY29uc29sZS5sb2coIkVsZW1lbnQgbm93IGRpc2FibGVkIik7CiAgfSApOwo=
$w("#myElement").disable()
  .then( () => {
    console.log("Element now disabled");
  } );

Toggle an element's enabled state

aWYoICR3KCIjbXlFbGVtZW50IikuZW5hYmxlZCApIHsKICAkdygiI215RWxlbWVudCIpLmRpc2FibGUoKTsKfQplbHNlIHsKICAkdygiI215RWxlbWVudCIpLmVuYWJsZSgpOwp9Cg==
if( $w("#myElement").enabled ) {
  $w("#myElement").disable();
}
else {
  $w("#myElement").enable();
}

Mixed In From

$w.DisabledMixin

See Also

enable( ), enabled

enable( )

enable( )

Enables the element and sets its enabled property to true.

function disable(): Promise<void>

Description

The enable() function returns a Promise that is resolved when the element's enabled property has been set to true.

To learn about the behavior of an enabled element, see the enabled property.

Return Value

Returns a Promise

On fulfillment void When the element's enabled property has been set to true.

Examples

Enable an element

JHcoIiNteUVsZW1lbnQiKS5lbmFibGUoKTsK
$w("#myElement").enable();

Enable an element and log a message when done

JHcoIiNteUVsZW1lbnQiKS5lbmFibGUoKQogIC50aGVuKCAoKSA9PiB7CiAgICBjb25zb2xlLmxvZygiRWxlbWVudCBub3cgZW5hYmxlZCIpOwogIH0gKTsK
$w("#myElement").enable()
  .then( () => {
    console.log("Element now enabled");
  } );

Toggle an element's enabled state

aWYoICR3KCIjbXlFbGVtZW50IikuZW5hYmxlZCApIHsKICAkdygiI215RWxlbWVudCIpLmRpc2FibGUoKTsKfQplbHNlIHsKICAkdygiI215RWxlbWVudCIpLmVuYWJsZSgpOwp9Cg==
if( $w("#myElement").enabled ) {
  $w("#myElement").disable();
}
else {
  $w("#myElement").enable();
}

Mixed In From

$w.DisabledMixin

See Also

disable( ), enabled

expand( )

expand( )

Expands the element and sets its collapsed property to false.

function expand(): Promise<void>

Description

The expand() function returns a Promise that is resolved when the element's collapsed property has been set to false.

To learn about the behavior of an expanded element, see the collapsed property.

Return Value

Returns a Promise

On fulfillment void When the element's collapsed property has been set to false.

Examples

Expand an element

JHcoIiNteUVsZW1lbnQiKS5leHBhbmQoKTsK
$w("#myElement").expand();

Expand an element and log a message when done

JHcoIiNteUVsZW1lbnQiKS5leHBhbmQoKQogIC50aGVuKCAoKSA9PiB7CiAgICBjb25zb2xlLmxvZygiRG9uZSB3aXRoIGV4cGFuZCIpOwogIH0gKTsK
$w("#myElement").expand()
  .then( () => {
    console.log("Done with expand");
  } );

Toggle an element's collapsed state

aWYoICR3KCIjbXlFbGVtZW50IikuY29sbGFwc2VkICkgewogICR3KCIjbXlFbGVtZW50IikuZXhwYW5kKCk7Cn0KZWxzZSB7CiAgJHcoIiNteUVsZW1lbnQiKS5jb2xsYXBzZSgpOwp9Cg==
if( $w("#myElement").collapsed ) {
  $w("#myElement").expand();
}
else {
  $w("#myElement").collapse();
}

Mixed In From

$w.HiddenCollapsedMixin

See Also

expand( ), collapsed, show( )

focus( )

focus( )

Places focus on the element.

function focus(): void

Description

The focus() function places focus on the element and fires a focus event.

The focus event handlers set on this element by the onFocus( ) function or in the Editor will called.

Receiving focus through a call to this function is equivalent to a user clicking on or tabbing to the element manually.

Examples

Place focus on an element

JHcoIiNteUVsZW1lbnQiKS5mb2N1cygpOwo=
$w("#myElement").focus();

Mixed In From

$w.FocusMixin

See Also

onFocus( ), blur( ), onBlur( )

hide( )

hide( )

Hides the element and sets its hidden property to true, using an effect if specified.

function hide([effectName: Effect], [effectOptions: EffectOptions]): Promise<void>
type Effect = "arc" | "bounce" | "fade" | "flip"
| "float" | "fly" | "fold" | "glide" | "puff"
| "roll" | "slide" | "spin" | "turn" | "zoom"
type EffectOptions = ArcEffectOptions | BounceEffectOptions
| FadeEffectOptions | FlipEffectOptions | FloatEffectOptions
| FlyEffectOptions | FoldEffectOptions | GlideEffectOptions
| PuffEffectOptions | RollEffectOptions | SlideEffectOptions
| SpinEffectOptions | TurnEffectOptions | ZoomEffectOptions

Description

The hide() function hides the element and returns a Promise that is resolved when the effect is complete and the element's hidden property has been set to true.

To learn about the behavior of a hidden element, see the hidden property.

You can optionally apply an effect when hiding the element by providing an effectName value. You can also customize the effect by providing the optional effectOptions object.

Effects:

You can also hide an element when the page loads by using the Properties panel in the Editor.

Parameters

effectName (optional) String The name of the effect to play when hiding the item.
effectOptions (optional) ArcEffectOptions |
BounceEffectOptions |
FadeEffectOptions |
FlipEffectOptions |
FloatEffectOptions |
FlyEffectOptions |
FoldEffectOptions |
GlideEffectOptions |
PuffEffectOptions |
RollEffectOptions |
SlideEffectOptions |
SpinEffectOptions |
TurnEffectOptions |
ZoomEffectOptions
The effect's options.

Return Value

Returns a Promise

On fulfillment void When the effect is complete and the element's hidden property has been set to true.

Examples

Hide an element with no effect

JHcoIiNteUVsZW1lbnQiKS5oaWRlKCk7Cg==
$w("#myElement").hide();

Hide an element with the "fade" effect

JHcoIiNteUVsZW1lbnQiKS5oaWRlKCJmYWRlIik7Cg==
$w("#myElement").hide("fade");

Hide an element with an effect and log message when the effect is done

bGV0IGZhZGVPcHRpb25zID0gewogICJkdXJhdGlvbiI6ICAgMjAwMCwKICAiZGVsYXkiOiAgICAgIDEwMDAKfTsKCiR3KCIjbXlFbGVtZW50IikuaGlkZSgiZmFkZSIsIGZhZGVPcHRpb25zKTsK
let fadeOptions = {
  "duration":   2000,
  "delay":      1000
};

$w("#myElement").hide("fade", fadeOptions);

Hide an element with an effect and log message when the effect is done

JHcoIiNteUVsZW1lbnQiKS5oaWRlKCJmYWRlIikKICAudGhlbiggKCApID0+IHsKICAgIGNvbnNvbGUubG9nKCJEb25lIHdpdGggZmFkZSIpOwp9ICk7Cg==
$w("#myElement").hide("fade")
  .then( ( ) => {
    console.log("Done with fade");
} );

Toggle an element's hidden state

aWYoICR3KCIjbXlFbGVtZW50IikuaGlkZGVuICkgewogICR3KCIjbXlFbGVtZW50Iikuc2hvdygpOwp9CmVsc2UgewogICR3KCIjbXlFbGVtZW50IikuaGlkZSgpOwp9Cg==
if( $w("#myElement").hidden ) {
  $w("#myElement").show();
}
else {
  $w("#myElement").hide();
}

Mixed In From

$w.HiddenCollapsedMixin

See Also

show( ), hidden, collapse( )

onBlur( )

onBlur( )

Adds an event handler that runs when the element loses focus.

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

Description

An element loses focus (blurs) through user actions, such as clicking and tabbing, or programmatically, using the blur( ) function.

Parameters

handler function(event, $w) The name of the function or the function expression to run when the element losed focus.
event Event The event that occurred.
$w $w 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 lost focus

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

Mixed In From

$w.FocusMixin

See Also

blur( ), onFocus( ), focus( )

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

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

onFocus( )

onFocus( )

Adds an event handler that runs when the element receives focus.

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

Description

An element receives focus through user actions, such as clicking and tabbing, or programmatically, using the focus( ) function.

Parameters

handler function(event, $w) The name of the function or the function expression to run when the element receives focus.
event Event The event that occurred.
$w $w 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 received focus

JHcoIiNteUVsZW1lbnQiKS5vbkZvY3VzKCAoZXZlbnQsICR3KSA9PiB7CiAgbGV0IHRhcmdldElkID0gZXZlbnQudGFyZ2V0LmlkOyAvLyAibXlFbGVtZW50Igp9KTsK
$w("#myElement").onFocus( (event, $w) => {
  let targetId = event.target.id; // "myElement"
});

Mixed In From

$w.FocusMixin

See Also

focus( ), onBlur( ), blur( )

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

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

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

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

See Also

ViewportMixin-onViewportEnter( )

reset( )

reset( )

Clears the files that are pending upload.

function reset(): void

Description

The value of the upload button contains a list of files that have been selected to upload. The reset() function clears these files.

Examples

Clears the files pending upload

JHcoIiNteVVwbG9hZEJ1dHRvbiIpLnJlc2V0KCk7Cg==
$w("#myUploadButton").reset();
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 will remain invalid. The validity indication will show 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 will show the element as invalid if its value is not valid.

Mixed In From

$w.FormElement

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

show( )

show( )

Shows the element and sets its hidden property to false, using an effect if specified.

function show([effectName: Effect], [effectOptions: EffectOptions]): Promise<void>
type Effect = "arc" | "bounce" | "fade" | "flip"
| "float" | "fly" | "fold" | "glide" | "puff"
| "roll" | "slide" | "spin" | "turn" | "zoom"
type EffectOptions = ArcEffectOptions | BounceEffectOptions
| FadeEffectOptions | FlipEffectOptions | FloatEffectOptions
| FlyEffectOptions | FoldEffectOptions | GlideEffectOptions
| PuffEffectOptions | RollEffectOptions | SlideEffectOptions
| SpinEffectOptions | TurnEffectOptions | ZoomEffectOptions

Description

The show() function shows the element and returns a Promise that is resolved when the effect is complete and the element's hidden property has been set to false.

You can optionally apply an effect when showing the element by providing an effectName value. You can also customize the effect by providing the optional effectOptions object.

Effects:

Parameters

effectName (optional) String The name of the effect to play when showing the item.
effectOptions (optional) ArcEffectOptions |
BounceEffectOptions |
FadeEffectOptions |
FlipEffectOptions |
FloatEffectOptions |
FlyEffectOptions |
FoldEffectOptions |
GlideEffectOptions |
PuffEffectOptions |
RollEffectOptions |
SlideEffectOptions |
SpinEffectOptions |
TurnEffectOptions |
ZoomEffectOptions
The effect's options.

Return Value

Returns a Promise

On fulfillment void When the effect is complete and the element's hidden property has been set to false.

Examples

Show an element with no effect

JHcoIiNteUVsZW1lbnQiKS5zaG93KCk7Cg==
$w("#myElement").show();

Show an element with the "fade" effect

JHcoIiNteUVsZW1lbnQiKS5zaG93KCJGYWRlSW4iKTsK
$w("#myElement").show("FadeIn");

Show an element with the "fade" effect and custom options

JHcoIiNteUVsZW1lbnQiKS5zaG93KCJGYWRlSW4iKTsK
$w("#myElement").show("FadeIn");

Show an element with an effect and log message when the effect is done

bGV0IGZhZGVPcHRpb25zID0gewogICJkdXJhdGlvbiI6ICAgMjAwMCwKICAiZGVsYXkiOiAgICAgIDEwMDAKfTsKCiR3KCIjbXlFbGVtZW50Iikuc2hvdygiZmFkZSIsIGZhZGVPcHRpb25zKTsK
let fadeOptions = {
  "duration":   2000,
  "delay":      1000
};

$w("#myElement").show("fade", fadeOptions);

Toggle an element's hidden state

aWYoICR3KCIjbXlFbGVtZW50IikuaGlkZGVuICkgewogICR3KCIjbXlFbGVtZW50Iikuc2hvdygpOwp9CmVsc2UgewogICR3KCIjbXlFbGVtZW50IikuaGlkZSgpOwp9Cg==
if( $w("#myElement").hidden ) {
  $w("#myElement").show();
}
else {
  $w("#myElement").hide();
}

Mixed In From

$w.HiddenCollapsedMixin

See Also

hide( ), hidden, expand( )

startUpload( )

startUpload( )

Uploads the files that the user has chosen.

function startUpload(): Promise<UploadedFile>

Description

The startUpload() function triggers the upload of the files in the upload button's value property.

See how startUpload() is used in a typical file upload scenario.

The upload button will not accept files that are larger than 25MB.

Return Value

Returns a Promise

On fulfillment UploadedFile Resolves when the file upload is completed.
On rejection UploadError Rejects if the file upload fails.

Examples

Start a file upload

JHcoIiNteVVwbG9hZEJ1dHRvbiIpLnN0YXJ0VXBsb2FkKCkKICAudGhlbiggKHVwbG9hZGVkRmlsZSkgPT4gewogICAgbGV0IHVybCA9IHVwbG9hZGVkRmlsZS51cmw7ICAvLyAid2l4OmltYWdlOi8vdjEvNjhkM2E5XzFkZTc1MjljNDQ0YjRjOWViMzg0MDFmOGVmZTBjYWQyLmpwZy9mbG93ZXJzLmpwZy8jb3JpZ2luV2lkdGg9MTk3MCZvcmlnaW5IZWlnaHQ9MTEyMCIKICB9ICkKICAuY2F0Y2goICh1cGxvYWRFcnJvcikgPT4gewogICAgbGV0IGVyckNvZGUgPSB1cGxvYWRFcnJvci5lcnJvckNvZGU7ICAvLyA3NzUxCiAgICBsZXQgZXJyRGVzYyA9IHVwbG9hZEVycm9yLmVycm9yRGVzY3JpcHRpb247CS8vICJFcnJvciBkZXNjcmlwdGlvbiIKICB9ICk7Cg==
$w("#myUploadButton").startUpload()
  .then( (uploadedFile) => {
    let url = uploadedFile.url;  // "wix:image://v1/68d3a9_1de7529c444b4c9eb38401f8efe0cad2.jpg/flowers.jpg/#originWidth=1970&originHeight=1120"
  } )
  .catch( (uploadError) => {
    let errCode = uploadError.errorCode;  // 7751
    let errDesc = uploadError.errorDescription;	// "Error description"
  } );

Full file upload scenario

This example uploads a file when the user clicks on a button. First it checks to see if the user has chosen a file. If a file was chosen, it triggers the upload and logs the status of the upload when it completes successfully or with an error.

JHcoJyNteUJ1dHRvbicpLm9uQ2xpY2soICgpID0+IHsKICBpZiAoJHcoIiNteVVwbG9hZEJ1dHRvbiIpLnZhbHVlLmxlbmd0aCA+IDApIHsgIC8vIHVzZXIgY2hvc2UgYSBmaWxlCiAgICBjb25zb2xlLmxvZyhgVXBsb2FkaW5nICckeyR3KCIjbXlVcGxvYWRCdXR0b24iKS52YWx1ZVswXS5uYW1lfSdgKTsKICAgICR3KCIjbXlVcGxvYWRCdXR0b24iKS5zdGFydFVwbG9hZCgpCiAgICAgIC50aGVuKCAodXBsb2FkZWRGaWxlKSA9PiB7CiAgICAgICAgY29uc29sZS5sb2coIlVwbG9hZCBzdWNjZXNzZnVsLiBGaWxlIGlzIGF2YWlsYWJsZSBoZXJlOiIpOwogICAgICAgIGNvbnNvbGUubG9nKHVwbG9hZGVkRmlsZS51cmwpOwogICAgICB9ICkKICAgICAgLmNhdGNoKCAodXBsb2FkRXJyb3IpID0+IHsKICAgICAgICBjb25zb2xlLmxvZyhgRmlsZSB1cGxvYWQgZXJyb3I6ICR7dXBsb2FkRXJyb3IuZXJyb3JDb2RlfWApOwogICAgICAgIGNvbnNvbGUubG9nKHVwbG9hZEVycm9yLmVycm9yRGVzY3JpcHRpb24pOwogICAgICB9ICk7CiAgfQogIGVsc2UgeyAgLy8gdXNlciBjbGlja2VkIGJ1dHRvbiBidXQgZGlkbid0IGNob3NlIGEgZmlsZQogICAgY29uc29sZS5sb2coIlBsZWFzZSBjaG9vc2UgYSBmaWxlIHRvIHVwbG9hZC4iKQogIH0KfSApOwo=
$w('#myButton').onClick( () => {
  if ($w("#myUploadButton").value.length > 0) {  // user chose a file
    console.log(`Uploading '${$w("#myUploadButton").value[0].name}'`);
    $w("#myUploadButton").startUpload()
      .then( (uploadedFile) => {
        console.log("Upload successful. File is available here:");
        console.log(uploadedFile.url);
      } )
      .catch( (uploadError) => {
        console.log(`File upload error: ${uploadError.errorCode}`);
        console.log(uploadError.errorDescription);
      } );
  }
  else {  // user clicked button but didn't chose a file
    console.log("Please choose a file to upload.")
  }
} );
updateValidityIndication( )

updateValidityIndication( )

Updates the element's visual validity indication based on it's 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.FormElement

File

File

The object used by the value property that represents files ready for upload.

Type

Object

Properties

name String The file's name.
size String The file's size in bytes.

Examples

Get the files pending upload

bGV0IGZpbGVzID0gJHcoIiNteVVwbG9hZEJ1dHRvbiIpLnZhbHVlOwoKbGV0IGZpbGVOYW1lID0gZmlsZXNbMF0ubmFtZTsgLy8gIm15cGljLmpwZyIKbGV0IGZpbGVTaXplID0gZmlsZXNbMF0uc2l6ZTsgLy8gNDU5NDEK
let files = $w("#myUploadButton").value;

let fileName = files[0].name; // "mypic.jpg"
let fileSize = files[0].size; // 45941

See Also

value

UploadedFile

UploadedFile

The object returned by the startUpload() function's Promise that contains the URL of the successfully uploaded file.

Type

Object

Properties

url String The Wix URL of the uploaded file.

Examples

Get uploaded file information

JHcoIiNteVVwbG9hZEJ1dHRvbiIpLnN0YXJ0VXBsb2FkKCkKICAudGhlbiggKHVwbG9hZGVkRmlsZSkgPT4gewogICAgbGV0IHVybCA9IHVwbG9hZGVkRmlsZS51cmw7ICAvLyAid2l4OmltYWdlOi8vdjEvNjhkM2E5XzFkZTc1MjljNDQ0YjRjOWViMzg0MDFmOGVmZTBjYWQyLmpwZy9mbG93ZXJzLmpwZy8jb3JpZ2luV2lkdGg9MTk3MCZvcmlnaW5IZWlnaHQ9MTEyMCIKICB9ICkKICAuY2F0Y2goICh1cGxvYWRFcnJvcikgPT4gewogICAgbGV0IGVyckNvZGUgPSB1cGxvYWRFcnJvci5lcnJvckNvZGU7ICAvLyA3NzUxCiAgICBsZXQgZXJyRGVzYyA9IHVwbG9hZEVycm9yLmVycm9yRGVzY3JpcHRpb247CS8vICJFcnJvciBkZXNjcmlwdGlvbiIKICB9ICk7Cg==
$w("#myUploadButton").startUpload()
  .then( (uploadedFile) => {
    let url = uploadedFile.url;  // "wix:image://v1/68d3a9_1de7529c444b4c9eb38401f8efe0cad2.jpg/flowers.jpg/#originWidth=1970&originHeight=1120"
  } )
  .catch( (uploadError) => {
    let errCode = uploadError.errorCode;  // 7751
    let errDesc = uploadError.errorDescription;	// "Error description"
  } );

See Also

startUpload

UploadError

UploadError

The object returned by the startUpload() function's Promise when an upload fails.

Type

Object

Properties

errorCode String Numeric The error's code.
errorDescription String The error's description.

Examples

Get upload error information

JHcoIiNteVVwbG9hZEJ1dHRvbiIpLnN0YXJ0VXBsb2FkKCkKICAudGhlbiggKHVwbG9hZGVkRmlsZSkgPT4gewogICAgbGV0IHVybCA9IHVwbG9hZGVkRmlsZS51cmw7ICAvLyAid2l4OmltYWdlOi8vdjEvNjhkM2E5XzFkZTc1MjljNDQ0YjRjOWViMzg0MDFmOGVmZTBjYWQyLmpwZy9mbG93ZXJzLmpwZy8jb3JpZ2luV2lkdGg9MTk3MCZvcmlnaW5IZWlnaHQ9MTEyMCIKICB9ICkKICAuY2F0Y2goICh1cGxvYWRFcnJvcikgPT4gewogICAgbGV0IGVyckNvZGUgPSB1cGxvYWRFcnJvci5lcnJvckNvZGU7ICAvLyA3NzUxCiAgICBsZXQgZXJyRGVzYyA9IHVwbG9hZEVycm9yLmVycm9yRGVzY3JpcHRpb247CS8vICJFcnJvciBkZXNjcmlwdGlvbiIKICB9ICk7Cg==
$w("#myUploadButton").startUpload()
  .then( (uploadedFile) => {
    let url = uploadedFile.url;  // "wix:image://v1/68d3a9_1de7529c444b4c9eb38401f8efe0cad2.jpg/flowers.jpg/#originWidth=1970&originHeight=1120"
  } )
  .catch( (uploadError) => {
    let errCode = uploadError.errorCode;  // 7751
    let errDesc = uploadError.errorDescription;	// "Error description"
  } );

See Also

startUpload