Run Script

By triggering the Run Script through an Event handler, you can achieve sequential execution of operations and perform different actions based on different condition.

How-to

Demo

Run and fork

https://illa.ai/app/ILAfx4p1C7Ac/detail

Use case: Login and redirect to different pages

Run and fork

https://illa.ai/app/ILAex4p1C7Eh/detail

ILLA custom functions

Trigger action

Structure

const exampleData = await actionName.trigger();

The actionName is the string shown in the screenshot, as follows.

Description

In Run Script, the variable exampleData is the same as actionName.data.

Example

For example, we use the action postgresql1 to query James' email.

Trigger the action via Run Script

postgresql1.data is

[
  {
    "email": "James@outlook.com",
    "id": "1",
    "img": "https://images.pexels.com/photos/1222271/pexels-photo-1222271.jpeg?auto=compress&cs=tinysrgb&w=1600",
    "name": "James"
  }
]

When we need to use JavaScript to retrieve an email in the component's Inspect or elsewhere, we can use the following: {{postgresql1.data[0].email}}

And when we need to use the email in the "Run Script" after executing the statement const exampleData = await postgresql1.trigger();, we can directly use exampleData[0].email.

Show a success notification when the query is successful and the result is unique. Show a failure notification when the query result is not unique or when it fails.

const exampleData = await postgresql1.trigger();
//show email via notification when the length of the resulting array is 1.
if(exampleData.length==1){
utils.showNotification(
  {
    type:"info",
    title:"Retrieved successfully",
    description:exampleData[0].email,
    duration: 4500}
);
  }else{
  //else, show a failed notification
utils.showNotification(
  {
    type:"info",
    title:"Failed to retrieve",
    duration: 4500
  }
);
  };

Show notification

Structure

utils.showNotification(
{
type: "info",
title: "Congratulations",
description: "Retrieved successfully",
duration: 4500
}
)

Description

Parameter	Description	Data type	Example
type	Used to set the icon type in the notification.	String, one of the following values:"info"default"success""error""warning"	type: "info"
title	Used to set the title of the notification	String	title: "Congratulations"
description	Used to set the description	String	description: "Retrieved successfully"
duration	Used to set the display duration of the notification.	Number, In milliseconds (ms)	duration: 4500

Example

Show notification when clicking the button:

It is the same as the Show notification action, as the following screenshot shows:

Control component

Structure

componentDisplayName.function()

componentDisplayName is the string shown in the screenshot, as follows.

Description

setValue(parameter)

Used to set the value. The parameter could be a string or number or object or boolean or array which depends on the component type.

Supported components

Component	Parameter type	Example
Input, Editable Text, Text Area, Divider, Select, Radio Group, Radio Button, Radio Buttonm, Date, Date Time, Steps, Text, Bar Progress, Circle Progress	string	input1.setValue("Hello world")
JSON Editor	string	jsonEditor1.setValue({ "firstName": "Chuck", "lastName": "Norris", "age": 80, "bio": "Roundhouse kicking asses since 1940", "password": "noneed", "telephone": "1-800-KICKASS" })
Timeline	string, Separate the values of different nodes via comma (,)	timeline1.setValue("The first milestone,The second milestone")
Number Input, Slider, Rate	number	numberInput1.setValue(1000)
Switch	boolean	switch1.setValue(false)
JSON Schema Form, Form	object	jsonSchemaForm1.setValue({ "firstName": "Chuck", "lastName": "Norris", "age": 80, "bio": "Roundhouse kicking asses since 1940", "password": "noneed", "telephone": "1-800-KICKASS" })
Checkbox Group, Cascader	array	cascader1.setValue(["media_source_2","campaign_2-1"])

clearValue()

Used to clear the value

Supported components

Input, Number Input, Editable Text, Text Area, Upload, JSON Editor, JSON Schema Form, Switch, Select, Multiselect, Checkbox Group, Cascader, Radio Group, Radio Button, Date, Date Range, Data Time, Date Time, Text, Rate, Bar Progress, Circle Progress, Timeline, Divider

Example

input1.clearValue()

focus()

Used to focus on the component

Supported components

Input, Number Input, Editable Text, Text Area, JSON Editor, Rich text editor, Radio Group,

Example

input1.focus()

validate()

When you have set validation conditions for a component, such as email format, URL format, or required field, you can use the validate() function to determine if it meets the requirements. If it does not meet the requirements, a validation message will be displayed.

Set the validation conditions:

Display the validation message:

Supported components

Input, Number Input, Editable Text, Text Area, Upload, Select, Multiselect, Checkbox Group, Radio Group, Radio Button, Date, Date Range, Date Time, Form, Rate

Example

input1.validate()

clearValidation()

Used to clear the validation message.

Supported components

Input, Number Input, Editable Text, Text Area, Upload, Select, Multiselect, Checkbox Group, Radio Button, Date, Date Range, Date Time, Rate

Example

input1.clearValidation()

setSelectedValue(array)

Used to set the selected value of Multiselect. The parameter should be an array.

Supported components

Multiselect

Example

multiselect1.setSelectedValue(["Option 1", "Option 3"])

submit()

Submit form data. When the submit method is triggered, we will first validate the form data. If there are validation errors, the form submission will be prevented, and the corresponding error messages will be displayed. Only after successful validation does the submission proceed.

Supported components

JSON Schema Form, Form

Example

form1.submit()

toggle()

Used to switch the value from true to false or from false to true.

Supported components

Switch

Example

switch1.toggle()

setStartOfRange(number)

Used to set the default start value of the range slider

Supported components

Range Slider

Example

rangeSlider1.setStartOfRange(1)

setEndOfRange(number)

Used to set the default end value of the range slider

Supported components

Range Slider

Example

rangeSlider1.setEndOfRange(9)

setStartValue(string)

Used to set the default start value

Supported components

Date Range, Time Range

Example

dateRange1.setStartValue("2023-09-09")

setEndValue(string)

Used to set the default end value

Supported components

Date Range, Time Range

Example

dateRange1.setEndValue("2023-10-09")

setValueInArray(array)

Used to set the switches whose value is true

Supported components

Switch Group

Example

switchGroup1.setValueInArray(["Option 1", "Option 3"])

selectPage(number)

Used to set the index of the page to display. The index is a number starting from ０.

Supported components

Table

Example

table1.selectPage(1)

selectRow(number)

Used to set the index of selected row. The index is a number starting from ０.

Supported components

Table

Example

table1.selectRow(1)

clearSelection()

Used to clear the selected row.

Supported components

Table

Example

table1.clearSelection()

setFilters(array of objects, string)

Used to set filters.

The first parameter is an array of objects. Each object represents a filtering condition. It includes three attributes:

id : This refers to the id of this column. If this column is a result of a database query, then the id would be the column name you retrieved from the query. For example, if the query is SELECT email AS user_email FROM users and rename email as Email using the right-hand panel of the table, the id of the column would still be user_email If this column is manually added using the Add Column button in the right-hand panel, you can check its id in the displayedData section of the left-hand panel. Typically, it will be a randomly generated string starting with column such as column-320169e8-225a-482d-9853-ad34b3040220.

filterFn : the match type of the filter. We support the following types: equalTo which is the same as = in SQL, notEqualTo which is the same as <> in SQL, contains which is the same as LIKE '%value%' in SQL, does NotContain which is the same as NOT LIKE '%value%' in SQL, lessThan which is the same as < in SQL, notLessThan which is the same as >= in SQL, notMoreThan which is the same as <= in SQL, empty which is the same as IS NULL in SQL, notEmpty which is the same as IS NOT NULL in SQL, before is used to compare time or date, which is the same as > in SQL, after is used to compare time or date, which is the same as < in SQL.

value : used to set the value to compare.

The second parameter: when there are multiple filter condition objects, it determines whether they have an "AND" relationship or an "OR" relationship. Set it as a string and for an "AND" relationship, and or for an "OR" relationship.

Supported components

Table

Example

table1.setFilters([{"id":"month", "filterFn":"equalTo", "value":"May"}, {"id":"month", "filterFn":"equalTo", "value":"June"}], "or")

clearFilters()

Used to clear all filters

Supported components

Table

Example

table1.clearFilters()

setSort(string, string)

Used to set the sort. The first parameter is the id of the column to sort which is a string value. The id is the same as the id mentioned in setFilters(array of objects, string). The second parameter is the sorting order, either ascending or descending. It is set using a string value ascend or descend.

Supported components

Table

Example

table1.setSort("incomes", "descend")

setCurrentViewKey(string)

Use the key which is a string value of the view to set the shown view.

Supported components

Container

Example

container1.setCurrentViewKey("View 2")

setCurrentViewIndex(number)

Use the index which is a number value starting from 0 of the view to set the shown view.

Supported components

Container

Example

container1.setCurrentViewIndex(1)

showNextView(boolean)

Used to show the next view. The parameter is a boolean value that determines whether to loop from the end back to the start.

Supported components

Container

Example

container1.showNextView(true)

showNextVisibleView(boolean)

Used to show the next visible view. Unlike the behavior of the showNextView(boolean) function, this function offers improved view switching functionality by skipping any hidden views during the transition. The parameter is a boolean value that determines whether to loop from the end back to the start.

Supported components

Container

Example

container1.showNextVisibleView(false)

showPreviousView()

Used to show the previous view. The parameter is a boolean value that determines whether to loop from the start back to the end.

Supported components

Container

Example

container1.showPreviousView(true)

showPreviousVisibleView()

Used to show the previous visible view. Unlike the behavior of the showPreviousView(boolean) function, this function offers improved view switching functionality by skipping any hidden views during the transition. The parameter is a boolean value that determines whether to loop from the start back to the end.

Supported components

Container

Example

container1.showPreviousVisibleView(true)

reset()

Used to reset the value to default value.

Supported components

Form

Example

form1.reset()

resetValue()

Used to reset the value to default value.

Supported components

Steps

Example

steps1.resetValue()

openModal()

Used to open a modal

Supported components

Modal

Example

modal1.openModal()

closeModal()

Used to close a modal

Supported components

Modal

Example

modal1.closeModal()

setImageUrl(string)

Used to set the Image source URL. It can be a Base64 or a URL pointing to an image on the web.

Supported components

Image

Example

image1.setImageUrl("https://cloud-api.illacloud.com/drive/f/83095b77-1180-487e-86db-ff117e6083e5")

image1.setImageUrl("data:image/png;base64,iVBORw0KGgoAA...II=")

clearReplyMessage()

Used to clear the quoted reply message above the input box.

Supported components

Chat

Example

chat1.clearReplyMessage()

setPrimaryValue(number)

Used to set the primary value of statistics.

Supported components

Statistics

Example

statistic1.setPrimaryValue(100)

resetPrimaryValue()

Used to reset the primary value to the default primary value of statistics.

Supported components

Statistics

Example

statistic1.resetPrimaryValue()

setFileUrl(string)

Used to set the file URL. It can be a Base64 or a URL pointing to a PDF on the web.

Supported components

PDF

Example

pdf1.setFileUrl("https://upload.wikimedia.org/wikipedia/commons/e/ee/Guideline_No._GD-Ed-2214_Marman_Clamp_Systems_Design_Guidelines.pdf")

play()

Used to play video or audio.

Supported components

Video, Audio

Example

video1.play()

pause()

Used to pause video or audio.

Supported components

Video, Audio

Example

video1.pause()

showControls(boolean)

Used to set whether to show the controls.

Supported components

Video

Example

video1.showControls(true)

setVideoUrl(string)

Used to set the video's URL. It can be a Base64 or a video URL on media websites.

Supported components

Video

Example

video1.setVideoUrl("https://youtu.be/8sUovZlBh_M")

setVolume(number)

Used to set the volume. The parameter is a number value between 0 to 1.

Supported components

Video, Audio

Example

video1.setVolume(0.5)

setSpeed(number)

Used to set the speed. The parameter is a number value between 0.25 to 2.

Supported components

Video, Audio

Example

video1.setSpeed(0.5)

setLoop(boolean)

Used to set whether to loop the playback.

Supported components

Video, Audio

Example

video1.setLoop(false)

seekTo(number)

Used to seek to a specific time position. The parameter is a number value, measured in seconds (s). For example, to seek to the time position 5:35, you would use the value 335.

Supported components

Video, Audio

Example

video1.seekTo(335)

mute(boolean)

Used to set mute or not.

Supported components

Video, Audio

Example

video1.mute(true)

setAudioUrl(string)

Used to set the audio's URL. It can be a Base64 or a video URL on media websites.

Supported components

Audio

Example

video1.setAudioUrl("https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3")

slickNext()

Used to switch to the next image.

Supported components

Carousel

Example

carousel1.slickNext()

slickPrevious()

Used to switch to the previous image.

Supported components

Carousel

Example

carousel1.slickPrevious()

setSrc()

Used to set the source URL of IFrame.

Supported components

IFrame

Example

iframe1.setSrc("https://www.nasa.gov/")

setMarkers(array)

Used to set the markers on the map. The parameter should be an array of objects. The latitude and longitude fields in each object should be same as the fields set in the right-hand panel

Supported components

Map

Example

map1.setMarkers([
{
    "lat":57.14009563040699,
    "lng":-114.6018657894011
 },{
     "lat":55.40432513713809,
     "lng":-112.98252263795787
 },{
     "lat":57.841288754888545,
     "lng":-103.3518657894011
 }
 ])

resetMarkers()

Used to reset the markers to the default markers.

Supported components

Map

Example

map1.resetMarkers()

Go to URL

Structure

utils.goToURL({
url:string,
newTab:boolean
})

Description

Use an object to set it. There are 2 attributes in the object. The first attribute is url. Its value is a complete URL, including 'https://' or 'http://', and it is of type string. The second attribute is newTab. It is a boolean used to set whether to open the URL in a new tab.

Example

utils.goToURL({
url:"https://www.illacloud.com",
newTab:true
})

Copy to clipboard

Structure

utils.copyToClipboard(string)

Description

Used to copy a string

Example

utils.copyToClipboard("The text to copy")

Set router

Structure

utils.setRouter({
pagePath:string;
viewPath:string
})

Description

Used to change the page in ILLA Apps. There are 2 attributes in the object.

The first attribute is pagePath. The value of pagePath is shown on the following screenshot without /.

The second attribute is viewPath. The value of viewPath is shown on the following screenshot without /.

Example

utils.setRouter({
pagePath:"page2", 
viewPath:"sub-page1"
})

Save to ILLA Drive

Structure

utils.saveToILLADrive({
fileName:string,
fileData:string,
fileType:string,
folder:string,
allowAnonymous:boolean,
replace:boolean
})

Description

Used to save a file to ILLA Drive.

fileName: Name with extension of the file after uploading to ILLA Drive.

fileData: Base64 or raw file data, such as JSON, CSV, plain text, etc.

fileType: One of the following values: Auto, Plain text, JPEG, PNG, SVG, JSON, CSV, TSV, Excel(.xlsx). When using "Auto," we will attempt to determine the file type based on either the file extension or the file data.

folder: Destination folder for file upload. Leave it blank to upload to the root folder.

allowAnonymous: Used to set whether anonymous user access is allowed. If you plan to set your application as public, anonymous access must be enabled. For the security of your data, files or folders accessible anonymously must be placed in the anonymous folder.

replace: Used to set when there are files with the same name in the same directory, replace the existing file with new file or automatically rename the new file.

Example

//use upload1 to pick files from device and upload to apps folder. 
utils.saveToILLADrive({
fileName:upload1.files[0].name,
fileData:upload1.files[0].dataURI,
fileType:"PNG",
folder:"apps",
allowAnonymous:false,
replace:true
})

//upload a text file.  
utils.saveToILLADrive({
fileName:"test.txt",
fileData:"abc",
fileType:"Plain text",
folder:"apps",
allowAnonymous:false,
replace:true
})

Download from ILLA Drive

Structure

utils.downloadFromILLADrive({
    downloadInfo:[{
        tinyURL:string,
        fileID:string
        }],
    asZip:boolean
})

Description

Used to download files from ILLA Drive.

downloadInfo: an array of objects including tinyURL and fileID. You can use the component Drive file picker to pick files from ILLA Drive and get the downloadInfo via drivePicker1.value

asZip: used to set whether to download the files as a Zip.

Example

utils.downloadFromILLADrive({
    downloadInfo:drivePicker1.value,
    asZip:true
})

Download

Structure

utils.downloadFile({
    fileType:string,
    fileName:string,
    data:anyType
})

Description

Used to export data to your device.

fileType: One of the following values: Auto, Plain text, JPEG, PNG, SVG, JSON, CSV, TSV, Excel(.xlsx). When using "Auto," we will attempt to determine the file type based on either the file extension or the file data.

fileName: a name with extension.

data: data of the file.

Example

//download the data of table as a CSV
utils.downloadFile({
    fileType:"CSV",
    fileName:"text.csv",
    data: table2.dataSourceJS
})

//download image
utils.downloadFile({
    fileType:"PNG",
    fileName:"text.png",
    data: image1.imageSrc
})

Set global data

Set global data value

Structure

utils.setGlobalDataValue({
key:string, 
value:any
})

Description

Used to set the value of gobalData

key: the displayName of globalData as the following screenshot shows.

value: the value to set

Example

//use input5 to get the user input value and set as the value of stringState. 
utils.setGlobalDataValue({
key:"stringState", 
value:input5.value
})

Set global data in

Structure

utils.setGlobalDataIn({
key:string, 
path:string, 
value:any
})

Description

When the global data is an array or object, use setGlobalDataIn to modify the value corresponding to a specific index in an array or to modify the value corresponding to a specific key in an object.

key: the displayName of globalData.

path: the index of the value you intend to update in the array or the key in the object. For example, to set the second value in array, the path is 1 (the index). To set the value of the attribute named key1, the path is key1.

value: the value to set

Example

//objectState is an object: {"key1":"value1", "key2":"value2"}, to set the 
utils.setGlobalDataIn({
key:"objectState", 
path:"key2", 
value:input7.value
})

Built-in libraries

Library	Doc	How to use it in ILLA Builder	Example
Lodash	https://lodash.com/docs/4.17.15	_	_.concat(array, 2, [3], [[4]]);
Day.js	https://day.js.org/	dayjs	dayjs(new Date())
uuid	https://www.npmjs.com/package/uuid	uuid	uuid.parse()
numbro	https://numbrojs.com/	numbro	numbro(1000).format({thousandSeparated: true})
Papa	https://www.papaparse.com/docs	Papa	Papa.parse(url, {download: true, // rest of config ... })

Value of actions, components...

Use displayName.xxx to use the value of actions, components, or other globalData. Please note that in the Run Script, these variables can be directly accessed without using {{ references.

utils.downloadFromILLADrive({
    downloadInfo:{{drivePicker1.value}},//❌ 
    asZip:true
})

utils.downloadFromILLADrive({
    downloadInfo:drivePicker1.value,//✅
    asZip:true
})