Skip to main content

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.

1

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.

2

Trigger the action via Run Script

3

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}}

4

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.

5

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​

ParameterDescriptionData typeExample
typeUsed to set the icon type in the notification.String, one of the following values:"info"default"success""error""warning"type: "info"
titleUsed to set the title of the notificationStringtitle: "Congratulations"
descriptionUsed to set the descriptionStringdescription: "Retrieved successfully"
durationUsed to set the display duration of the notification.Number, In milliseconds (ms)duration: 4500

Example​

Show notification when clicking the button:

6

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

7

Control component​

Structure​

componentDisplayName.function()

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

8

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​
ComponentParameter typeExample
Input, Editable Text, Text Area, Divider, Select, Radio Group, Radio Button, Radio Buttonm, Date, Date Time, Steps, Text, Bar Progress, Circle Progressstringinput1.setValue("Hello world")
JSON EditorstringjsonEditor1.setValue({ "firstName": "Chuck", "lastName": "Norris", "age": 80, "bio": "Roundhouse kicking asses since 1940", "password": "noneed", "telephone": "1-800-KICKASS" })
Timelinestring, Separate the values of different nodes via comma (,)timeline1.setValue("The first milestone,The second milestone")
Number Input, Slider, RatenumbernumberInput1.setValue(1000)
Switchbooleanswitch1.setValue(false)
JSON Schema Form, FormobjectjsonSchemaForm1.setValue({ "firstName": "Chuck", "lastName": "Norris", "age": 80, "bio": "Roundhouse kicking asses since 1940", "password": "noneed", "telephone": "1-800-KICKASS" })
Checkbox Group, Cascaderarraycascader1.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:

9

Display the validation message:

10

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

11

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

12

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.

13

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.

14

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​

LibraryDocHow to use it in ILLA BuilderExample
Lodashhttps://lodash.com/docs/4.17.15__.concat(array, 2, [3], [[4]]);
Day.jshttps://day.js.org/dayjsdayjs(new Date())
uuidhttps://www.npmjs.com/package/uuiduuiduuid.parse()
numbrohttps://numbrojs.com/numbronumbro(1000).format({thousandSeparated: true})
Papahttps://www.papaparse.com/docsPapaPapa.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
})