Controllers

Controllers are the heart of your application, as they determine how HTTP requests should be handled.

What is a Controller?

A Controller is simply a library file that is named in a way that can be associated with a URI.

Consider this URI:

example.com/index.lc/blog/

In the above example, revIgniter would attempt to find a controller named blog.lc and load it.

When a controller's name matches the first segment of a URI, it will be loaded.

Let's try it:  Hello World!

Let's create a simple controller so you can see it in action. Using your text editor, create a file called blog.lc, and put the following code in it:

<?lc

# PUT YOUR HANDLER NAMES INTO THE GLOBAL gControllerHandlers AS A COMMA SEPARATED LIST
put "index" into gControllerHandlers

command index
  put "Hello World!"
end index

Then save the file to your application/controllers/ folder.

Now visit your site using a URL similar to this:

example.com/index.lc/blog/

If you did it right, you should see Hello World!.

Handlers

In the above example the handler name is index. The "index" handler is always loaded by default if the second segment of the URI is empty. Another way to show your "Hello World!" message would be this:

example.com/index.lc/blog/index/

The second segment of the URI determines which handler in the controller gets called.

Let's try it. Add a new handler to your controller:

<?lc

# PUT YOUR HANDLER NAMES  INTO THE GLOBAL gControllerHandlers AS A COMMA SEPARATED LIST
put "index,comments" into gControllerHandlers

command index
  put "Hello World!"
end index

command comments
  put "Look at this!"
end comments

Important:  Don't forget to add the name of your new handler to the comma separated list of the variable gControllerHandlers.

Now load the following URL to see the comments handler:

example.com/index.lc/blog/comments/

You should see your new message.

Note:  There is currently a limitation with LiveCode Server which does not allow hyphens in handler names. So, don't use hyphens in your handler names as these yield an error.

Passing URI Segments to your Handlers

If your URI contains more than two segments you can retrieve them using the rigFetchSegment() function.

For example, lets say you have a URI like this:

example.com/index.lc/products/shoes/sandals/123

The function rigFetchSegment(3) will return "sandals" and rigFetchSegment(4) will return "123" (URI segments 3 and 4):

<?lc

# PUT YOUR HANDLER NAMES  INTO THE GLOBAL gControllerHandlers AS A COMMA SEPARATED LIST
put "index,shoes" into gControllerHandlers

command shoes
  put rigFetchSegment(3) && rigFetchSegment(4)
end shoes

Important:  If you are using the URI Routing feature, the re-routed segments must be retrieved using the rigFetchRsegment() function.

Defining a Default Controller

revIgniter can be told to load a default controller when a URI is not present, as will be the case when only your site root URL is requested. To specify a default controller, open your application/config/routes.lc file and set this variable:

put "blog" into gRoute[1]["defaultController"]

Where blog is the name of the controller library you want used. If you now load your main index.lc file without specifying any URI segments you'll see your Hello World message by default.

Remapping Handler Calls

As noted above, the second segment of the URI typically determines which handler in the controller gets called. revIgniter permits you to override this behavior through the use of the _remap handler:

command _remap
  -- Some code here...
end _remap

Important:  If your controller contains a handler named _remap, it will always get called regardless of what your URI contains. It overrides the normal behavior in which the URI determines which handler is called, allowing you to define your own handler routing rules.

The overridden handler call (typically the second segment of the URI) will be passed as a parameter to the _remap handler:

command _remap pHandler
  if pHandler is "someHandler" then
    do handler
  else
    do defaultHandler
  end if
end _remap

Processing Output

revIgniter has an output library that takes care of sending your final rendered data to the web browser automatically. More information on this can be found in the Views and Output library pages. In some cases, however, you might want to post-process the finalized data in some way and send it to the browser yourself. revIgniter permits you to add a handler named _output to your controller that will receive the finalized output data.

Important:  If your controller contains a handler named _output, it will always be called by the output library instead of puting the finalized data directly. The first parameter of the handler will contain the finalized output.

Here is an example:

command _output pOutput
  put pOutput
end _output

Please note that your _output handler will receive the data in its finalized state. Benchmark data will be rendered, cache files written (if you have caching enabled), and headers will be sent (if you use that feature) before it is handed off to the _output handler. If you are using this feature the page execution timer might not be perfectly accurate since it will not take into acccount any further processing you do. For an alternate way to control output before any of the final processing is done, please see the available handlers in the Output Library.

Private Handlers

In some cases you may want certain handlers hidden from public access. To make a handler private, simply add an underscore as the name prefix and it will not be served via a URL request. For example, if you were to have a handler like this:

command _utility
  -- some code
end _utility

Trying to access it via the URL, like this, will not work:

example.com/index.lc/blog/_utility/

Organizing Your Controllers into Sub-folders

If you are building a large application you might find it convenient to organize your controllers into sub-folders. revIgniter permits you to do this.

Simply create folders within your application/controllers directory and place your controller libraries within them.

Note:  When using this feature the first segment of your URI must specify the folder. For example, lets say you have a controller located here:

application/controllers/products/shoes.lc

To call the above controller your URI will look something like this:

example.com/index.lc/products/shoes/show/123

Each of your sub-folders may contain a default controller which will be called if the URL contains only the sub-folder. Simply name your default controller as specified in your application/config/routes.lc file

revIgniter also permits you to remap your URIs using its URI Routing feature.

Reserved Handler Names

Since your controller script will extend the main application controller you must be careful not to name your handlers identically to the ones used by that library. See Reserved Names for a full list.

Good Practice

It is good practice, though not mandatory, to load all needed libraries, databases, stacks, helpers, extensions, custom config files, language files and models in a handler named after the controller itself. This handler, if present, is called first and automatically by the front controller. So, this is a good place to load required libraries, helpers, models, a database etc. Let's say your controller is called "blog.lc", then your code would look like this:

<?lc

# PUT YOUR HANDLER NAMES  INTO THE GLOBAL gControllerHandlers AS A COMMA SEPARATED LIST
put "index,blog" into gControllerHandlers


command blog
  # LOAD REQUIRED LIBRARIES, MODELS, HELPERS ETC.
end blog

command index
  # REMEMBER TO PUT ALL THE VARIABLES TO BE MERGED WITH VIEWS INTO THE ARRAY VARIABLE gData
  -- do something here
end index



--| END OF blog.lc
--| Location: ./application/controllers/blog.lc
----------------------------------------------------------------------

That's it!

That, in a nutshell, is all there is to know about controllers.