helpers

A helper in the Levure framework is a folder containing a collection of files that add a specific feature to a Levure application. The folder can contain stack files meant to be used for UI, libraries, frontscripts, or backscripts. It can also contain externals or extensions. A good example of a helper is the preferences helper that ships with the framework. The ./framework/helpers/preferences helper folder has both a library stack and an external. Both files work together in LiveCode to provide the feature. As an app developer you only have to think about adding the helper folder to your project.

Creating a helper

Helpers consist of a folder with a helper.yml file in it. The helper.yml file is a YAML file that specifies what the other files in the folder should be used for. A helper can be made up of the following:

• ui
• libraries
• backscripts
• frontscripts
• behaviors
• externals
• extensions

A helper.yml file looks like this:

ui:
  1:
    filename: [relative path to stack file]
    encrypt: [Optional parameter that can override the `encrypt stacks` setting for all stacks in the folder]
libraries:
  1:
    filename: [relative path to stack file]
    encrypt: [Optional parameter that can override the `encrypt stacks` setting for all stacks in the folder]
    autoload: [set to false if you want the stack loaded into memory but not put in use]
frontscripts:
  1:
    filename: [relative path to stack file]
    encrypt: [Optional parameter that can override the `encrypt stacks` setting for all stacks in the folder]
    autoload: [set to false if you want the stack loaded into memory but not inserted into front]
backscripts:
  1:
    filename: [relative path to stack file]
    encrypt: [Optional parameter that can override the `encrypt stacks` setting for all stacks in the folder]
    autoload: [set to false if you want the stack loaded into memory but not inserted into back]
behaviors:
  1:
    filename: [relative path to stack file]
    encrypt: Optional parameter that can override the `encrypt stacks` setting for all stacks in the folder.
externals:
  macos:
    1:
      filename: [relative path to bundle]
      name: [name of external that appears in the externalPackages]
  windows:
    1:
      filename: [relative path to dll]
      name: [name of external that appears in the externalPackages]
  linux:
    1:
      filename: [relative path to library]
      name: [name of external that appears in the externalPackages]
extensions:
  1:
    filename: [relative path to .lcm file]
    resource folder: [optional relative path to folder containing resources that extension relies on]
    source file: [optional relative path to .lcb file]

If no helper.yml file is found then the framework will treat each stack file in the folder as a ui stack.

If your helper includes an extension then you can also specify a resource folder for the extension. This is the folder where any resources that your widget loads will come from. For example, if you use image from resource file mResource in your widget LiveCode Builder code and it is a relative reference then the LiveCode engine will look in the resource folder.

If no resource file is specified and a ./resources folder exists alongside your app.yml file then that folder will be used.

Adding new helpers to your application

Each helper is stored in the helpers folder that sits alongside the app.yml file in your app folder. The default app.yml file in a new project will automatically load any helper folders you place in the helpers folder.

Customizing the helpers section of the app.yml file

You can customize how helpers are loaded by modifying the helpers section of the app.yml file. For example, you can point to helpers that are stored in other directories or change the encryption settings to be different than the encryption setting for the reset of the application.

# app.yml
...
helpers:
  1:
    filename: [relative path to folder an individual `helper` folder]
    encrypt: Optional parameter that can override the `encrypt stacks` setting for all stacks in the `helper` folder.
  2:
    folder: [relative path a folder containing helper folders]
    encrypt: Optional parameter that can override the `encrypt stacks` setting for all stacks in each `helper` folder.
  ...
...