Helper Handlers

Helpers, as the name suggests, help you with tasks. Each helper file is simply a collection of handlers in a particular category. There are URL Helpers, that assist in creating links, there are Form Helpers that help you create form elements, String Helpers that assist in working with strings, Cookie Helpers set and read cookies, File Helpers help you deal with files, etc.

Generally each helper handler performs one specific task, with no dependence on other handlers, although there are exceptions.

revIgniter does not load Helper Files by default, so the first step in using a Helper is to load it. Once loaded, it becomes globally available in your controller.

Helpers are script only stacks typically stored in your system/helpers, or application/helpers directory. revIgniter will look first in your application/helpers directory. If the directory does not exist or the specified helper is not located there revIgniter will instead look in your global system/helpers folder.

Loading a Helper

Loading a helper file is quite simple using the following handler:

rigLoadHelper "name"

Where name is the file name of the helper, without the .livecodescript file extension or the "Helper" part.

For example, to load the URL Helper file, which is named urlHelper.livecodescript, you would do this:

rigLoadHelper "url"

A helper can be loaded anywhere within your controller handlers, as long as you load it before you use it.

Note: The Helper loading handler above does not return a result value, so don't try to assign the result to a variable. Just use it as shown.

Loading Multiple Helpers

If you need to load more than one helper you can specify them in a comma separated list, like this:

put "helper1,helper2,helper3" into tHelpers
rigLoadHelper tHelpers

Or you can specify them in an array, like this:

split tHelpers using comma
rigLoadHelper tHelpers

Auto-loading Helpers

If you find that you need a particular helper globally throughout your application, you can tell revIgniter to auto-load it during system initialization. This is done by opening the application/config/autoload.lc file and adding the helper to the autoload array.

Using a Helper

Once you've loaded the Helper File containing the handler you intend to use, you'll call it's handlers the way you would a standard LiveCode handler.

For example, to create a link using the rigAnchor() function (provided by the URL helper) in one of your controller files you would do this:

put rigAnchor("blog/comments", "Click Here") into gData["commentsAnchor"]

Where "Click Here" is the name of the link, and "blog/comments" is the URI to the controller/handler you wish to link to.

In your view file you would write this:

[[gData["commentsAnchor"]]]

"Extending" Helpers

To "extend" Helpers, create a file in your application/helpers/ folder with an identical name to the existing Helper, but prefixed with MY_ (this item is configurable, see below).

If all you need to do is add some functionality to an existing helper - perhaps add a handler or two, - then it's overkill to replace the entire helper with your version. In this case it's better to simply "extend" the Helper. The term "extend" is used loosely since LiveCode handlers cannot be extended in the traditional programmatic sense. Under the hood, this gives you the ability to add to the handlers a Helper provides.

For example, to extend the native Array Helper you'll create a file named application/helpers/MY_arrayHelper.livecodescript, and add your handlers

Note: All revIgniter script only stack files use "livecodescript" as file extension. This convention you should keep in mind when you build models, libraries, helpers etc.

Setting Your Own Prefix

The filename prefix for "extending" Helpers is the same used to extend libraries and Core libraries. To set your own prefix, open your application/config/config.lc file and look for this item:

put "MY_" into gConfig["sublibraryPrefix"]

Now What?

In the Table of Contents you'll find a list of all the available Helper Files. Browse each one to see what they do.