ui

The ui folder is where all stacks that can be displayed to the end user are stored. To add a user interface stack to your application do the following:

1. Create a folder in the ui folder that describes the stack(s) you want to add.
2. Create one or more stacks and place them in the folder you just created.

The next time you open your application in the LiveCode IDE you can reference the stacks by name in order to open them. Here is an example of what the ui folder would look like with with a stack in it:

• 📂 app
  • 📂 ui
    • 📁 document_editor
      • document_editor.livecode

If you plan on using version control software or prefer to edit your LiveCode scripts in a text editor then there are some additional steps:

1. Create a behaviors folder inside of the folder you created in step 1.
2. Store the scripts used in the ui stacks in the behaviors folder as script only stacks. Use the extension .livecodescript. The exception to this would be the scripts you attach to buttons or other controls that only call handlers stored in the script only stacks.
3. In the LiveCode IDE open the user interface stack and open the stack property inspector. Navigate to the Stack Files tab and add the script only stacks from the behaviors folder to the stackfiles property. This will allow the engine to load the script only stacks when opening the user interface stack.
4. Assign the script only stacks as the behavior of the appropriate controls in your user interface stack.

Here is an example of what the end result looks like in the file system:

• 📂 app
  • 📂 ui
    • 📁 document_editor
      • document_editor.livecode
      • 📁 behaviors
        • card.livecodescript
        • stack.livecodescript

While this is a bit of work to set up, you can now track changes made to your scripts using version control software. In LiveCode 9 the behaviors interface in the property inspector will have the ability to perform all of the above operations for you.

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

The default app.yml file that is created for a new application will automatically load any ui components located in the app/ui folder. You will only need to update the app.yml file if you need to change the load order, the encryption setting, or if you have stored the ui component elsewhere. Here are some syntax examples:

# app.yml
...
ui:
  - 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.
  - 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:
  - 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:
  - 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:
  - filename: ./ui/about/about.livecode
    encrypt: false
  - 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.