electronic.alchemy :: DocController
where the past meets the future
pike > Fins > DocController


Created by hww3. Last updated by hww3, 12 years ago. Version #4.

The standard FinsController provides basic event routing functionality, and is the building block for your application's user interface. Most applications provide some sort of content to render in the users browser for each event. When you're using FinsController to build an app like this, it can become tedious to get the view for each event and add it to the Response object. DocController exists to simplify building apps that use this common behavior.

A DocController is similar to a FinsController, with the exception that events have an extended signature:

public void myEvent(Request request, Response response, View view, array args);

For any given event, a DocController will search for an appropriate template, load it and add it to the Response. For example, if your root controller has an event called hello, DocController will look for the following template:


If you have an event without a template, an error will not be thrown, but a view will not be set or provided.

When using FinServe, an event that produces no output will return a "unable to find a handler" 404 error. The event will still fire, though.

You can have events defined in your controller without a corresponding template/view file. In this situation, the event will fire, but the view variable will be empty. Additionally, a message will be displayed in the debug log indicating that a view was not found (and what Fins thought the file should have been named). This behavior is designed to assist in troubleshooting during development. You may disable this warning message on a per-controller basis by setting the __quiet flag to true (that is, the integer 1).


In order to simplify the separation of layout from data presentation, you may define layouts that may be used as "chrome" around a view. You may wish to think of a layout as an easy way to apply a header and footer to all pages in your application (or on a per-controller basis).

A layout may be defined for each controller, as well as for an application as a whole, which will be used as a fallback if a given controller does not have its own layout.

The following paths are searched for layouts, which are standard template files.


If a layout is set and detected, you must reload to change the layout file name. templates detected and changed will be reloaded if the file content changes.

You can use the <%yield%> macro in your layout file to cause Fins to insert the view within its surroundings.

Additionally, you may use Template.View->set_view() instead, in your own non DocController apps in order to achieve layout functionality.

Not categorized | RSS Feed | BackLinks

comments powered by Disqus