Faceplait Docs: Start with a Page
When it comes to rendering views for a web application, the ability to produce a consistent look-and-feel for related views is very beneficial. Faceplait is a lightweight layout management library which seamlessly "decorates" HTML pages with a layout.
This process of course, starts with a page that you would like to have wrapped in a layout. The Faceplait API provides a small cohesive set of interfaces that represent the concept of a Page, a Layout and a View.
Below is a simplified version of an HTML page. We're going to use this as a jumping-off point.
This is the actual page that we're going to decorate with a layout. Notice how we're not using HTML fragments as the subject - but an actual, complete, syntactically correct HTML page that on it's own would have no problem being renedered in a browser.
Save that content as a .cfm file named test-page.cfm in a /pages/ directory. Of course technically, this file can be located anywhere you like, it's parent directory doesn't need to be named /pages/.
Get your scratchpad.cfm page ready where we can play around with this a bit. The Faceplait library includes a default implementation of Page in which understands HTML called HTMLPage. This is what we'll use to represent our view.
There, now the information contained within our simple HTML page is now encapsulated within our Page instance. The filePath argument accepts the relative path from your web root to the page itself. You can ask for the contents again by invoking the getContents() method - but that of course would simply give us back the contents of the original HTML page which at this point, doesn't really do us any good - we need to pair this Page with a Layout in order to get the results we want.
It's important to note that you are not required to provide a file location to initialize a Layout or a Page. You can establish content for both types by simply passing in the conent to the setContents() method on either object.
Injecting Local Variables
In an attempt to not make too many assumptions as to how you'll implement the Faceplait library, the API also allows you to inject local, or variables scoped variables into your HTML page. We'll change our original HTML page (which now technically is a .cfm file) to include the use of such variables;
In order to account for this local variable, we now need to inject it into the page with the the constructor argument pageVars;
You can inject as many local variables as needed in the pageVars constructor argument as long as each is accounted for in the structure, otherwise you'll get the familiar Undefined Variable exception.