layoutManager Mach-II plugin
Usage
Place layoutManager.cfc in the MachII plugins folder. Place this in the plugins section of the Mach-II configuration file (typical usage):
<plugin name="layoutManager" type="MachII.plugins.layoutManager"> <parameters> <parameter name="defaultLayoutEvent" value="layout.main" /> <parameter name="finalOutputKey" value="request.content.final" /> </parameters> </plugin>
In the event-handlers section:
<event-handler event="layout.main" access="private"> <view-page name="layout.main" contentKey="request.content.final" /> </event-handler>
This will announce layout.main at the end of the event queue. If you need to use a different layout event (such as for popups where you don’t require the normal site layout) set an event argument named layoutEvent to your chosen alternate layout event name. You can also set an event argument named skipLayoutEvent to true if you wish skip the layout altogether (such as when the output is an XML file or an image).
The final content (contained in request.content.final) will be stripped of all unnecessary whitespace. You can disable this by not setting the finalOutputKey parameter and not specifying a content key for the final layout view.
Plugin parameters
| Parameter | Data type | Opt. | Default | Description |
|---|---|---|---|---|
| defaultLayoutEvent | string | No | N/A | Name of event to be announced at the end of the queue |
| defaultContentType* | string | Yes | text/html; charset=utf-8 | Default content type for output |
| finalOutputKey* | string | Yes | N/A | Name of content key to which the final content is written |
| optimizeWhitespace* | boolean | Yes | true | Enables/disables whitespace optimisation |
| preserveWhitespaceTagList* | list of strings | Yes | pre, textarea | List of tags where content is left untouched by whitespace optimisation |
| defaultDispositionMethod* | string | Yes | attachment | Default disposition method when forcing a download to the browser ("attachment" or "inline") |
| argumentPrefix | string | Yes | empty string | Prefix for all event arguments used by layoutManager |
*These parameters have no effect when the finalOutputKey parameter is omitted.
Event arguments used by layoutManager
Note: Use the argumentPrefix parameter to modify the following argument names. This can be helpful to avoid clashes with other event args such as form and url values. For example, if you set argumentPrefix to "LM_" the following argument names will be LM_layoutEvent, LM_contentType, etc).
| Event argument | Data type | Description |
|---|---|---|
| disableLayoutManager | boolean | When set to true, disables the plugin for the current request |
| layoutEvent | string | Overrides the default layout event for the current request |
| skipLayoutEvent | boolean | When set to true, layoutManager doesn’t announce the layoutEvent (whitespace optimisation and other actions on the final output are still active) |
| contentType* | string | Overrides the default content type for the current request |
| optimizeWhitespace* | boolean | Enables/disables whitespace optimisation for the current request |
| forcedFileName* | string | Pushes the final output as a download and fakes the file name in the "Save as…" dialog |
| dispositionMethod* | string | Overrides the default disposition method for the current request ("attachment" or "inline") |
*These event arguments have no effect when the finalOutputKey parameter is omitted.
Notes
Exceptions
When an exception is thrown and the exception event is announced, layoutManager will still announce the layout event at the end of the queue. If you are using the finalOuputKey method, your exception event has to write content to this content key. If the error was thrown by the layout event, you will get a white screen of death. A possible solution to this would be to add an event mapping in your layout event-handler to redirect all exceptions to an event that disables the layoutManager (using the disableLayoutManager event argument).
CFCONTENT
When using the finalOutputKey method, layoutManager always includes a cfcontent tag just before outputing the content. This means that you shouldn’t use cfcontent elsewhere in your code.
If you have any problems using this plugin don’t hesitate to post comments on this page.
October 6th, 2004 at 4:56 pm
Nice plugin. Do you mind if I add a listing for this in the Mach-ii.info Exchange? (http://mach-ii.info/index.cfm?event=exchange)
May 18th, 2005 at 4:22 pm
Well done!
May 27th, 2005 at 7:35 pm
Phil, when setting an event (popup) I used the following code:
Where I used skipLayoutEvent. Yet when run, I get the following error:
Exception
Message cannot convert the value “” to a boolean
This references line 38 in the plugin. Any ideas?
May 27th, 2005 at 8:00 pm
Oops, caught my mistake. Its fixed now. Thanks.
May 28th, 2005 at 4:02 am
By the way Sami, Phil is not the author of this plugin. I am. Phil runs the MachII.info site and has kindly linked to my blog from his exchange section.
June 29th, 2005 at 10:11 am
Nice and very usefull PugIn, thanks for that work.
There is one thing I get confused. As soon as use the plugIn and got an exception, in the exception Message from Mach-II I don’t get the real exception message anymore.
Whatever exceptions occured, I get “Element CONTENT is undefined in REQUEST”, which is the content variable in the mainLayoutpage.
How do I configure the plugIn to show me the the exception messages.?
July 6th, 2005 at 2:13 pm
I’m quite new to mach-ii (2 days) and I’m strugging to piece together all the required elements. I’ve gone through Trond Ulseth’s 2 tutorials which were great, but now I’m trying to figure out how to apply this to my current project.
I’m used to using included for headers, footers and menu’s and I’m not sure how to properly handle this using mach-ii. Also, what is the proper way to refer to the CSS, etc.
I’m looking over your layoutManager.cfc and trying to understand if this is what this file is for. There isn’t alot of documentation on plugins and filters (unless you could direct me).
Thanks for contributing to mach-ii. I would say congratulations on winning the Olympic bid, but given your home country, I’m sure you are of two minds.
September 7th, 2005 at 10:54 pm
Martin,
Is there a list we can be on to receive notification when new releases of code come out?
Sami
September 18th, 2005 at 12:13 pm
Thanks for the plug-in. Do know why this doesn’t work:
-or-
Neither one works.
Thanks,
Mike
September 18th, 2005 at 12:14 pm
Cool, my XML was stripped out from my config. Can I email it to you?
December 23rd, 2005 at 11:25 am
Hello,
I have followed the instructions on this page to implement the layout-plugin, but it does not seem to work, or I don’t get it.
When I run a default page event, I place the content in the request.content.final key. The layoutmanager then runs, opens layout.main and should parse the key on my page. But only the content in de first event is shown, never the content from layout.main? Am I missing something? I am using the latest version of Mach-II.
December 23rd, 2005 at 8:24 pm
I think the problem here is that it should be your layout.main event that writes to request.content.final The final contentKey is the final output of the request. You should use a different contentKey for the content that is nested in your main layout view. Don’t hesitate to write back if this doesn’t work.
February 10th, 2006 at 10:36 pm
Just checked this out. If you are using Mach II ver 1.1, you need to change the event part to the following:
February 10th, 2006 at 10:38 pm
I see code is stripped out. Change event to event-handler and change name= to event=. Also you should probably add access=”private”.
February 10th, 2006 at 11:08 pm
MGW: you’re absolutely right. I haven’t looked at this page in a long time. I can’t even remember whether this was valid in an older version of Mach-II. Was it?