include

The first verb in the Fusebox grammar, include, is the most commonly used one. Most fuseactions access their component fuses by including the fuse. Let's look at a simple example:

The include tag has a single required attribute of template that is the name of the fuse to be included. The include tag also has an optional Boolean attribute of required which is true by default. Thus the example above can also be written as:

If the specified file does not exist an exception will be thrown. To silently by-pass this exception so that the requested fuse is included if it exists and ignored if it does not, set required to false, as in:

We can make use of Fusebox's built-in parameters to make the include command less platform-specific. In the earlier example we included a fuse, dspHello.cfm, that is clearly a ColdFusion template. With an eye on language independence, Fusebox will intelligently use the value of application.fusebox.scriptFileDelimiter in conjunction with the value of application.fusebox.maskedFileDelimiters.

The former defines the file ending for script templates through the application, whereas the latter specified which files should be masked from this effect. In a ColdFusion Fusebox application, scriptFileDelimiter would be set as cfm. If any templates are to be included that do not specify a file ending, then they will be assigned an extension of .cfm. Thus we might simply write:

The Fusebox core file will know that dspHello really means dspHello.cfm. When porting this application to, say, PHP, we would change the value of the scriptFileDelimiter to php and now the same instruction when executed by a PHP set of Fusebox core files will include the fuse dspHello.php. To protect, or "mask", certain files from this effect, use the maskedFileDelimiters parameter. This comma-delimited list determines which files not to apply this dynamic process to. Continuing our example, if maskedFileDelimiters were set to js,htm,cfm,cfml,php,asp then

would be translated into

because it does not end in any of the masked elements, but

would be left as it is because the file ends in one of the elements from the maskedFileDelimiters list—in this case, .js. Without the mask in place it would have been translated into:

which we likely do not intend.

If you set your masked list to include your most common script types, you can have the best of both worlds, which is particularly useful if you intend to port your Fusebox application across different platforms. Or, to effectively disable this feature entirely, just set the mask to *, which masks everything.

Two new (and related) attributes have been added to the include verb in Fusebox 4.1. First is the contentvariable attribute. By specifying a content variable name, you can capture the output produced by the included file as a variable. The second new attribute is append, which defines whether to append new content created by the current include to the end of a pre-existing content variable. The use of content variables with the include verb is the same as with the do verb, so please read through the section on the do verb for full details on content variables.

A circuit's fuses should all exist within that circuit's directory. Although the following are legal Fusebox 4 statements:

they are nevertheless poor programming practices since the application's successful execution is now coupled to the underlying directory structure, the decoupling of which is the entire point behind circuits.

In Fusebox 4.1 and 5 it is possible to include files in another circuit by use of the circuit parameter, this allows the inclusion without making them dependant on directory structure.

This looks in the directory of somecircuit (as specified by the path attribute in somecircuit's declaration in fusebox.xml) for the fuse somefuse.cfm and includes it. This can be useful in MVC-style applications that would otherwise have a lot of fuseactions that simply a single fuse but are used (via <do>) from other circuits. For example, View circuits often have many simple fuseactions that just <include> a display fuse (and Model circuits may have simple fuseactions that just <include> action or query fuses). The circuit= form of allows the Controller circuits to <include> display (or action / query) fuses directly without requiring the intermediate simple fuseaction in the View (or Model) circuits.

The most important optional attribute of include is contentvariable, a new feature in Fusebox 4.1. The contentvariable attribute allows Fusebox to save all of the generated output from that include into a variable rather than outputting it at the moment of its generation. It's a powerful way to create modular pieces of output that can be easily assembled into much larger pieces, while keeping fuses as small and focused as possible.

Here's an example of an include using a component variable:

Here, Fusebox will save any content generated by the fuse, dspnews.cfm. The results of this fuse might be a news story that also has some formatting to make it consistent with the design of the site. Other fuses might be called as well, perhaps each of them likewise saving their generated content to variables. At the end of the page request, a final fuseaction is called to assemble all the pieces together for output to the browser.

With the contentvariable attribute, you also have available two more optional attributes. The first, append, is a Boolean variable that determines if the content from the fuse specified by the action attribute should be appended to any content that might already be in the variable specified by the contentvariable. The value of append is false by default so that use of a content variable replaces any existing content being held by that variable.

The second optional attribute when using content variables with do is the Boolean variable, overwrite. This determines whether the fuse specified by the action attribute should even place its content into the content variable. In effect, it operates like a content variable version of ColdFusion's cfparam tag.

include

FuseboxWiki

New Sections