Faceplait Docs: Creating a Layout Cache within the View Factory
In the last several steps, I showed you how to create a page, a layout and then have the factory produce a decorated view from both objects. This is all fine and good for one-off views perhaps, but when it comes to managing a large web application, implementing the library in your own app in such a manner could be tedious - which is exactly what we don't want.
This has been accounted for in the design of the HTMLViewFactory. This object, that we used to produce a decorated view, also has the ability to manage an internal registry of one or more Layouts. With this capability, instead of explicitly indicating which Layout to use when the factory getView() method is invoked, it will look for a layout instruction on the Page (in the form of a special plait tag) and look for an associated Layout in it's registry first in order to render resulting view.
When leveraging this functionality, it's important to implement the ViewFactory as a singleton in your application. This will avoid any unecessary overhead when creating the layout registry which technically only needs to happen once durring the life of your application.
HTMLViewFactory exposes the method setLayoutsDirectory() which is what we'll use to get the factory to create the registry. This argument can contain one of two possible values; either a fully-qualified system directory path, or a relative path from the web root. If you provide a relative file path, then the factory will attempt to determine the exact system file path. It will not recurse that directory and it will filter out any files that do not have an extension of ".cfm". The registry itself is created from filename of the layout. This is important when marking-up a layout to use inside of a Page. Let's ask the HTMLViewFactory to create an internal layout registry;
Refreshing your page should produce exactly the same results as before - the resulting view should still be decorated with our layout. That's because we're still explicitly passing in a layout on line 13. Passing in layout references always takes precedence over those registered internally in the factory. Go ahead and remove layout=layout from line 13 and refresh your page.
Now you're getting a view with the default and undesireable Faceplait layout. What happened? When the factory was trying to create the resulting View, it was unable to determine which layout to use for the specified Page. No worries - the final step in this process is now to declare on the page itself which layout it should use. This is done with the <plait:use layout="" /> tag;
You can place that tag anywhere on the page - it doesn't need to be at the top - although that location may make the most sense for the sake of clarity. The value of the layout attribute must coincide with the name of a layout template that exists within the layoutsDirectory argument passed to the setLayoutsDirectory() method on the factory, otherwise you'll get the default layout again. You can now create as many different layouts as you like and easily swap in and out the layouts a page uses by simply changing the value of the layout="" attribute on the <plait:use /> tag.
Similarly, you can have a page skip layout decoration entirely by providing a value of NONE for the layout attribute;