Soleil uses JavaScriptCore by Apple to run scripts. This documentation will change occasionally as more features are added!

All of your code must be in the main() function, that's what gets called by Soleil. The main function should also return a Collection

Functions

UpdateUI(collection)

Sets the UI of the JS block to be the collection passed to it.

SetID(string)

Sets the ID of the script, used for saving and retrieving user data.

SaveUserData(dictionary)

Saves the user data dictionary (in the form of [String: String]) for this script. SetID(string) must be set before running this function.

GetUserData() (dictionary)

Gets the user data dictionary (in the form of [String: String]) for this script. SetID(string) must be set before running this function.

Types

Collection

Every single JS UI element must be inside of a Collection. Think of them as tables

  • Collection.create() (class method)
    Creates a new Collection
  • Collection.create(rows, columns, items) (class method)
    Creates a new Collection with .rows set to the number of rows, .columns set to the number of columns, and .items set to UI elements
  • .columns (property) (int)
    Number of columns that should be in the Collection
  • .rows (property) (int)
    Number of rows that should be in the Collection
  • .scrollDirection (property) (string)
    Either "horizontal" or "vertical" if not specified, it's assumed to be "vertical"
  • .items (property) (Any)
    UI elements that should be displayed in the Collection
  • Example:
const collection = Collection.create()
collection.rows = 1
collection.columns = 1
collection.items = []
return collection

Text

  • Text.create(string) (class method)
    Returns a Text object that will display a string.
  • .fontSize (property) (int)
    Sets the font size of the text object.
  • Example:
// Creating the text
const text = Text.create("Hello, world")
text.fontSize = 100

// Creating a collection to put the text in
const collection = Collection.create()
collection.rows = 1
collection.columns = 1
collection.items = [text]
return collection

Button

  • Button.create(text, action) (class method)
    Creates a Button with a string text value, and a function action value
  • .text (property) (string)
    Sets the text of a Button
  • .action (property) (function)
    Sets the action of a Button, the action is called everytime a button is pressed
  • Example:
// Creating the button
const button = Button.create("Tap me!", function() {
    // Tapped
})

// Creating a collection to put the button in
const collection = Collection.create()
collection.rows = 1
collection.columns = 1
collection.items = [button]
return collection

TextField

  • TextField.create(placeholder, onValueChange) (class method)
    Creates a TextField with the string placeholder and a function onValueChange with the new TextField value being passed to it
  • .placeholder (property) (string)
    The placeholder of a TextField
  • .valueDidChange (property) (function)
    Called with the new value of the TextField when its dismissed
  • Example:
// Creating the Textfield
const textField = TextField.create("Previous number of taps", function(text) {
    // Do something with the text
})
// Creating a collection and putting textField in it
const collection = Collection.create()
collection.rows = 1
collection.columns = 1
collection.items = [button]
return collection

Examples

Tap counter:

// Called by Soleil
function main() {
    var count = 0 // Setting initial amount of taps
    const text = Text.create("Taps: " + count) // Creating a Text to show the amount of taps

    const button = Button.create("Tap me!") // Creating a button that updates amount of taps
    // Called whenever button is tapped
    button.action = function() {
        // Updating tapped value and setting the Text to the new count
        count = count + 1  
        text.text = "Taps: " + count
        // Displaying new
        const collection = Collection.create()
        collection.scrollDirection = "vertical"
        collection.rows = 1
        collection.columns = 2
        collection.items = [text, button]
    
        UpdateUI(collection) // This replaces the UI
    }
    
    // Displaying initial
    const collection = Collection.create()
    collection.scrollDirection = "vertical"
    collection.rows = 1
    collection.columns = 2
    collection.items = [text, button]
    return collection
}

Tap counter extended:

function main() {
    var count = 0 // Setting initial number of taps
    const numberOfTapsLabel = Text.create("Taps: " + count) // Creating a Text to show the amount of taps

    // Collection that will display all UI
    var collection = Collection.create() 
    collection.scrollDirection = "vertical"
    collection.rows = 1
    collection.columns = 3
    // Note: we didn't set the items of the collection here

    // Creating the textfield 
    const textField = TextField.create("Previous number of taps", function(text) {})

    // Creating a button
    const button = Button.create("Tap me!")

    // Setting the function of the textField after we initialize the UI elements
    textField.valueDidChange = function() {
        count = parseInt(text)
        numberOfTapsLabel.text = "Taps: " + count

        collection.items = [numberOfTapsLabel, button, textField] // We set the items here so we don't have to re-initialize the collection

        UpdateUI(collection) // Replace the UI 
    }
    // Every tap adds to the number of taps 
    button.action = function() {   
        count = count + 1
        numberOfTapsLabel.text = "Taps: " + count
        collection.items = [numberOfTapsLabel, button, textField] 
    
        UpdateUI(collection) // Replace the UI
    }

    // Initial UI
    collection.items = [numberOfTapsLabel, button, textField]
    return collection
}

Saving number of taps

// Called by Soleil
function main() {
    SetID("counter") // Setting the script id so we can retrieve and use user data
    var data = GetUserData() // Getting the user data
    var count = 0 // Setting initial data
    // If we have a value for `data["count"]` then parse the integer and set count to it
    if (data["count"] !== undefined) {
        count = parseInt(data["count"])
    }
    const text = Text.create("Taps: " + count) // Creating a Text to show the amount of taps

    const button = Button.create("Tap me!") // Creating a button that updates amount of taps
    // Called whenever button is tapped
    button.action = function() {
        // Updating tapped value and setting the Text to the new count
        count = count + 1  
        text.text = "Taps: " + count
        // Displaying new
        const collection = Collection.create()
        collection.scrollDirection = "vertical"
        collection.rows = 1
        collection.columns = 2
        collection.items = [text, button]
    
        UpdateUI(collection) // This replaces the UI
    }
    
    // Displaying initial
    const collection = Collection.create()
    collection.scrollDirection = "vertical"
    collection.rows = 1
    collection.columns = 2
    collection.items = [text, button]
    return collection
}

Last Update: October 05, 2024