ui

The ui folder sits alongside the app.yml file in your app folder. The ui folder is where you store the LiveCode binary stacks for your user interface along with their behavior scripts.

Contents

• What is a UI component?
• Set up a UI component
• Set behavior and stackScripts properties
• Update ui section in app.yml
• Examples

What is a UI component?

A UI (User Interface) component in Levure is a folder containing a LiveCode binary stack along with its associated script-only stack behaviors. Most Levure applications will have at least one UI component that serves as the user interface for the application.

The binary stack in a UI component typically contains few or no scripts. Instead of having scripts embedded in the binary stack where they are inaccessible to version control, the scripts are separated out into script-only stacks and employed as behaviors. When the UI binary stack is opened, the scripts are attached to their corresponding objects (stack, cards, groups, buttons, etc.) as behaviors.

Set up a UI component

Let's set up a hypothetical UI component named app_ui which provides the user interface for an application. In the ui folder it might look something like this:

• 📂 app
  • 📂 ui
    • 📂 app_ui
      • app_ui_binary_stack.livecode
      • 📂 behaviors
        • app_ui_stack_behavior.livecodescript
        • app_ui_card_behavior.livecodescript
        • app_ui_group_behavior.livecodescript
        • app_ui_button_behavior.livecodescript

We see that the UI component is a folder named app_ui. In that folder is a binary stack named app_ui_binary_stack.livecode which contains the UI for the application without any scripts. Alongside the binary stack is a behaviors folder which contains all the scripts.

When the binary stack is opened, we want all the behaviors to be automatically loaded and attached to their corresponding objects in the binary stack. For that to happen, we must set the stackScripts and behaviors properties in the binary stack.

Set behavior and stackScripts properties

For the script-only stacks in the UI component's behaviors folder to load properly, there are two conditions:

1. The behavior property must be set correctly in the binary stack and any of its objects that require scripts.

2. The stackFiles property of the binary stack must be set to include references to all of the component's script-only behavior stacks.

Update ui section in app.yml

Whenever you add or remove UI components be sure to update the ui section of the app.yml file. This enables the framework to properly load your UI components at startup.

# app.yml
...
ui:
  1:
    filename: [relative path to a specific component folder or a stack file within components folder]
    encrypt: Optional parameter that can override the `encrypt stacks` setting for this stack.
  2:
    folder: [path to folder containing components]
    encrypt: Optional parameter that can override the `encrypt stacks` setting for all stacks in the folder.
...

Examples

When a UI component is loaded, the UI binary stack is opened and the associated behavior scripts are opened and attached to their corresponding objects in the stack. The UI binary stack along with its behaviors is now in memory and available to your application.

There are three ways to load UI components in app.yml. The first way is to specify a folder that contains UI component folders. The second way is to target a specific UI component folder. The third way is to target a specific binary stack file within a UI component folder.

Example 1

If you specify a folder containing UI component folders, then all UI components in the folder will be loaded.

To load all UI components in the ui folder, specify this in your app.yml:

ui:
  1:
    folder: ./ui

Example 2

The second method allows you to target a single UI component to load.

For example, to load an about UI component, specify this in your app.yml:

ui:
  1:
    folder: ./ui/about

Example 3

The third method allows you to target a single stack file to load. This is useful if you need to have a different encryption setting for a particular stack file.

For example, if your application is encrypted with a password but you have a UI component stack that shouldn't be password protected then you could do this:

ui:
  1:
    filename: ./ui/about/about.livecode
    encrypt: false
  2:
    folder: ./ui

The stack you target with filename will be added to the list of stack files first along with the encryption setting. Then the folder of UI components will be loaded. The framework will see that the ui/about/about.livecode stack file has already been loaded and will skip it when loading the stack files in the ./ui folder thus leaving it unencrypted.