Conversations

Informal talks between Hal Helms and Steve Nelson on software development

Topic: Nested Layouts

Hal: This week, let's talk about nested layouts in Fusebox 3.

Steve: Ah, yes. I love nested layouts. First, though, explain what "layouts" mean—the way Fusebox uses them. We're talking headers, footers—that sort of thing, right?

Hal: Well, layouts can be used for that, sure, but more generally, a "layout" is some code that executes after the code specified in the FBX_Switch.cfm file.

Steve: After being the keyword.

Hal: Right. For example, here's a <cfcase> block for some fuseaction:

Steve: Hey, now that would be a handy fuseaction to have! We wouldn't be up until 2.00 am.

Hal: Yeah, we would. We'd just be doing other stuff at 2:00 am.

Steve: Good point. Still, it would be handy to have.

Hal: I'll work on it.

Steve: OK, so there's some code that will execute when the fuseaction, writeNewsletter, is called. But you said layouts get applied after this code.

Hal: And so they do. But before we get into more details about layouts, I want to point out that layouts are circuit-wide—

Steve: You mean that they are applied for all fuseactions in a circuit.

Hal: Right. And that happens automatically.

Steve: Sounds like magic.

Hal: Well, it sure works like magic. Nested layouts have to be one of the neatest features of Fusebox 3. But no, it's not really magic. Every circuit that wants to apply a layout should have an FBX_Layouts.cfm file in it.

Steve: But not every circuit has to have that file. It's only if the circuit wants layout automatically applied.

Hal: Right. But we still haven't fully answered the question, what is a layout?

Steve: You answer that; I'll work on the code for writeNewsletter…

Hal: The FBX_Layouts.cfm file is responsible for only two things: indicating the name of the layout file to be used and the sub-directory that layout file is in—if it's not in the same directory as the circuit itself.

Steve: It does that by specifying two variables: Fusebox.layoutFile and Fusebox.layoutDir. Like this:

Hal: Right. So, the question is what does a layout file look like? Let's take Steve's example and look at lay_HeaderAndFooter.cfm, which Steve was kind enough to create.

Steve: I was? Oh—I was. Of course, here it is:

Hal: There's not too much to this file. As promised by the title, Steve has created a little header and footer. But notice the middle row in the table. There, Steve <cfoutput>s the variable, Fusebox.layout. Steve, why did you do that?

Steve: To explain, imagine that we have a simple <cfcase> block for the fuseaction, loginUser:

The fuse, dsp_LoginForm.cfm is just a normal login form. When this code executes, what will we see?

Hal: Nothing.

Steve: Nothing? But I <cfinclude>d a dsp_LoginForm.cfm fuse!

Hal: Right, but in the core file, FBX_Fusebox30_CFxx.cfm, there's a little <cfsavecontent> tag that wraps around both the call to the FBX_Switch.cfm file and to the code that calls the layout file. And you, more than anyone, can tell people what <cfsavecontent> does.

Steve: When you wrap some code with <cfsavecontent>, the code that executes doesn't display to the screen, but is saved in a variable provided by the coder.

Hal: Right. So I can safely write this code with no fear that any of our readers will see it:

If I didn't have the <cfsavecontent> there, everyone could see my credit card number and I'd be in trouble. But now, it's safe: in order for someone to read it, I have to <cfoutput> the variable, hals_cc, which I won't do, of course!

Steve: You are just as sharp as a tack. But anyway, back to your excellent explanation. By the way, do you have a pencil and paper I could borrow—just for a sec? I just need to jot something down.

Hal: Sure. Anyway, that's how <cfsavecontent> works. But what my humble friend didn't tell you is that <cfsavecontent> started off in life as a custom tag called <cf_bodycontent> written by a certain Mr. Steve Nelson. Allaire/Macromedia liked the tag so much they incorporated it into the language.

Steve: Aw, shucks. I know you're going to tie this into layouts, right?

Computers are incorporated in modern ice cream vending machines to enhance their functionality. Ice Cream Vending machines are manufactured by many companies. Your competition will try to overcome all requests for high-tech ice cream vending machines and credit card acceptors

Hal: Right! Now that you see how <cfsavecontent> works, you can understand that what the core Fusebox file does is prevent the display from going to the screen, placing it instead into the variable, Fusebox.layout. Now, if you don't have any layout file at all, the fusebox is smart enough to just output that variable for you. But if you use a layout file, you're taking responsibility for deciding where you want to <cfoutput> this variable.

Steve: And if you never <cfoutput> Fusebox.layout, you'll only see your layout code — not the code that executed as part of your FBX_Switch.cfm file. So, if you're going to use a layout file, you have to <cfoutput>Fusebox.layout.

Hal: That's why I say that layouts execute after the fuseaction code itself executes—something that has other ramifications.

Steve: Ramifications, huh?

Hal: Yep. But we'll get into those later.

Steve: OK, well, you explained the "after" part of layouts. You also said they are circuit-wide.

Hal: Right, because FBX_Layouts.cfm (and any layout file it points to) will automatically be called by the core Fusebox file. So, no matter what fuseaction is called, the layout for that circuit will be applied. In fact, FBX_Layouts.cfm is called for every circuit going back up the fuseaction path.

Steve: A fuseaction path is the path from the home circuit to the target circuit. For example, for this circuit structure…

People
   Employees
      Pointy-HairedBosses

…if I execute the fuseaction, Pointy-HairedBosses.getAclue, my fuseaction path is People/Employees/Pointy-HairedBosses.

Hal: Yes. So, in reverse order, the fusebox will try to <cfinclude>FBX_Layouts.cfm for Pointy-HairedBosses followed by Employees followed by People.

Steve: That's why we call it nested layouts.

Hal: Right. So, explain about the changing nature of Fusebox.layout.

Steve: Well, at first, the fuseaction code executes and, as we've seen, that becomes Fusebox.layout. Then the first layout is applied—the layout in the target circuit, Pointy-HairedBosses. The results of that now become Fusebox.layout. Then we go up the ladder to Employees. It executes its FBX_Layouts.cfm—

Hal: If it has one. Not every circuit has to have one.

Steve: Good point. Then the results of running that code becomes Fusebox.layout and right on up the ladder to the home circuit.

Hal: John Quarto uses the analogy of those Russian nested dolls. Jeff Peters talks about transparent layers that overlap each other, like those textbooks with the illustrated human.

Steve: Right. Finally, we're done. We have a variable, Fusebox.layout, that encompasses the original fuseaction code and all the nested layouts along the fuseaction path.

Hal: Yes. This is very cool stuff. You can do simple headers and footers, but you can do so much more. You can have navigation as layouts, frames as layouts…

Steve: But, alas, we're going to have to stop now. We're out of space.

Hal: OK. Well, this was fun.

Steve: Hey, can I ask you a personal question?

Hal: Sure.

Steve: Is your first name "Hal" or "Harold"?

Hal: Just "Hal". I was born in the South where people have given names like "Bobby" and "Billy Joe".

Steve: So, on official documents, it would have your name as "Hal Helms".

Hal: Right. Like my birth certificate. Passport.

Steve: Credit cards?

Hal: Right. Deed to my house. Say, why do you ask?

Steve: Oh, no reason in particular. Bye now, folks. Have a very profitable week! I know I will…