In my last entry I talked about how to install the Fusebox framework and how to create a basic Fusebox application install using the skeleton. I confirmed that the skeleton worked (you can see it here) and now I want to dig down a bit more into what actually goes on when you run the application.
I read - a few times - the documentation on the Fusebox life cycle. (As a note - the docs refer to Fusebox 4 still. This is a known bug.) What follows is my take on what I read in the docs, and how it compares to Model-Glue.
So the docs split up the life cycle (or in simpler terms, what the heck happens when I run the page) into 4 sections: Runtime, Loader, Transformer, and Parser.
The Runtime simply determines which of the other three guys need to run. As a developer I don't have to worry about this too much. It is the framework itself (or thats how I see it). The Runtime also takes care of joining any URL or Form data into the ATTRIBUTES scope. In Model-Glue world this would be the event object. I assume folks know why this is a Good Idea(tm) so I won't go over it.
The Loader does what it says - loads the configuration information. In Model-Glue this would be the Model-Glue.xml file. This loads the fusebox.xml (note that in the skeleton this is actually a fusebox.xml.cfm file) file and any other xml file necessary. This is all cached though, again, like Model-Glue.
Question - is there a URL key to force Fusebox to refresh? Is there a configuration setting in fusebox.xml to force a refresh on each hit? The doc on the XML file says there is - but the doc doesn't match what I see in the XML file. The doc mentions I should use a value of development or production, but my skeleton shows a value of development-circuit-load.
So at this point I admit I get a bit lost. The docs say:
At this point Fusebox 4 takes a leap forward from earlier versions. In all previous versions, the fuseaction at this point was operated on directly: "do A. OK, done with A. Now do B. Ok, done with B. Now do C. OK, done with C." Effectively, the developer was limited to execution of a single fuseaction, and it was difficult (or at least cumbersome) to share common fuses among multiple fuseactions which could make use of it.
The docs haven't (as of yet) talked about a fuseaction. The previous page in the documentation does mention fuseaction once, but only as a query string variable. I get that the fuseaction is a message. But what is a fuse? What does it even mean to share it among multiple fuseaction? I will admit I'm being a bit facetious here. I know from talks with other FB developers a bit about what is going on here. But from a newbie perspective, this is a not a gentle introduction. At this point (if I were writing the docs), I would have simply said:
At this point Fusebox will look at the fuseaction being requested and determine how it will be processed. The XML determines what each fuseaction does.
The docs continue on to the Transformer. The Transformer creates what is called a Fuse Queue (or FuseQ). I think this is simply the list of what to do - based on the fuseaction which defined what is being done for the event.
Lastly the Parser will take the Fuse Queue and "outputs a full language-specific version of the application you wrote in XML". Now I'm really confused. Is Fusebox generating code for me like an ORM? Is it simply translating the XML into a set of cfincludes? I may have Model-Glue too much in my mind - but I don't get what this means. In Model-Glue, our event has a series of actions (messages, views, results). So in Fusebox this would be the Fuseaction which becomes a Fuse Queue. I'm with ya there, Fusebox. But it sounds like Fusebox actually translates this list into a script. I can maybe see that being useful for speed - but I don't think I have a handle on it yet.
Summary: All in all this part of the documentation really threw me for a loop. The first page was rather simple, but the second page seems to be way complex. I'd rather see a one or two paragraph simple explanation of what is going on in the request with links to further information about each part of the process. Also the docs throw around fuse, fuseaction, and circuit without doing a great job defining them.
So I'm a bit confused... but think I kind of get it. I know my readers will help clear this up! (And if others agree with me, maybe we can get the documentation improved a bit.)
Ray, what was it that you thought is a good idea, putting the vars in the attribute scope or in the event object? Thanks for the rest of the review. As one who is very intersted in frameworks, this is one that I have not touched on yet. I will be quite intrigued in looking forward to upcoming posts on Fusebox.
A better starting point for docs is...
Kevin Roche has also started a new set of docs (http://trac.fuseboxframewor....
You'll see a section on "New execution modes" which will explain the refresh functions you want.
There's also a Firefox plugin (http://cecf1.unh.edu/fusebox/) which will give you a right-click method of invoking them.
As I think Sean mentioned, there is a Team being set up to review the doc's.
@dick: Sean had pointed out the wiki to me. What I'm doing though is approaching this as a stranger and following the docs I see in the navigation. Most folks can't bug Sean when they need to. ;) I know its a bit anal - but I'm really trying to approach this as I think a normal developer would. Does that make sense?
So based on that - I can tell you I normally would not have followed a link with "WhatsNewInFusebox5". I mean - as someone who is new to all this - I couldn't tell you what was in Fusebox 4. Make sense?
The firefox plugin is sweet. I'd like to see that for Model-Glue.
@kyle: The idea is that the framework considers the stuff coming in (url/form) as attributes for the event. Your code shouldn't care where it came from, it should just work with the attributes. So in both MG/FB, there is an abstraction to these event attributes and you don't directly access form. or url.
I want to add one quick point. I'm definitely picking on Fusebox and it's docs. My docs aren't much to write home about. I'd also like to see improvements to the MG docs. Again though - I'm trying to describe my experience in picking this up. My only intent is to help - not tear down. :)
I don't think you're being too negative. When I first tried out fusebox I ran into many of the same pitfalls. I kind of got the idea from my own general research with other fusebox people, but the docs seemed to be a bit deeper water than the point you would be at starting from scratch over in the shallow end.
The point about Sean relates here too, me posting about my shortcomings with the docs doesn't get a more immediate reaction than yours will. Good to hear they are reviewing them though. :)
I completely agree with you regarding the documentation. At a minimum the Fusebox website should link to the best third party tutorials. I'm surprised how hard it is to find a good example of how to setup a required login screen or to display content in a layout fuse for example. Some docs suggest using a 'plugin' and others suggest using a 'global fuseactions'. ...er ok, what's the difference between a plugin and a fuseaction? I'm also being a little facetious, but it is a problem for those of us who don't have a long time 'fuseboxer' in my shop to show me the ropes.
That said, with some persistent searching on Google, I tracked down an excellent series of tutorials below that don't seem to be linked elsewhere.
That said, I've been really impressed with the framework as I learn more about it. It's primary limitation from what I can tell is simply documentation and examples.
having just recently gotten into using a framework (fusebox), i did find the documentation lacking.
haven't really brought it up, because it seems to be somewhat of a sore spot with some of the people who have invested time into the framework itself. i've seen the comment about lack of documentation met with the response of "we've put a lot of time into writing the framework, we have families, jobs, lives, etc". i understand this completely and sympathize. didn't want to sound unappreciative of the efforts that went into building (and maintaining) the framework, so i just kept quiet.
there are a lot of sample applications up on the fusebox site. no doubt about that. but for a n00b like me, that doesn't really do it. i can look at the sample code... but what am i getting out of it? i can see -how- it's been done but that doesn't explain -why- it's been done. sample code is a great complement to documentation, but it shouldn't really serve as documentation.
as some others have mentioned, teratech seems to be going balls-to-the-wall to do something about the documentation (or lack thereof). i filled out a survey a while back, and got a slew of e-mails yesterday (because i had indicated a willingness to help) about getting the process started.
not sure what i'll be able to contribute, but i'll be doing what i can to help out.
@dan: john's tutorials are -fantastic-, and probably played the biggest factor in me getting over a lot of hurdles. my only comment is that they're geared towards FB 4, and i came into a job using 4.1.
so my personal concern was "learning" 4.0 while my company was hoping i'd be able to pick up the 4.1 ball and run with it.
but no sleight to John. in fact, i tried to find a wish list link or a donate button on his blog but couldn't find either (john? got a link??) :)
The Fusebox folks had a meeting at the Frameworks conference. We divvied up a million tasks for Fusebox, one of the big ones is "documentation". We're going to have a breeze meeting in the next week to figure out what docs we currently have and what docs we're missing. Then we'll task out who's going to write the missing docs and who's going to assemble it all together.
I figure after 10 years we should consider writing documentation for Fusebox. Hopefully we'll be successful.
Steve, outside of the "normal" docs, I'd also recommend a Quick Start guide. I think the Model-Glue one is a perfect way to quickly get up to speed.
I'd like to add my 2 cents worth. This is not directed at the FuseBox guys, but all developers in general. When you write your docs, please, please provide them in a format that is useful. Preferably, HTML for online viewing and PDF for printing. Anything else is really unacceptable.
For those of you writing documentation, you may want to take a look at DocBook. It's a schema designed for writing technical documentation. It originated in SGML but has since been moved over to XML. All documentation is stored in XML files that can "easily" be saved out to various formats(pdf, html, ps, text, rtf, doc, etc).
Ditto Jeff. One of the main reasons I downloaded OpenOffice was for the one click PDF generation.
Fusebox does indeed generate CFML code that is cached and executed. Take a look inside your 'parsed' directory in your application folder. You'll see that the Fusebox Framework is actually creating files (and overwriting them if it needs to). The files are named with a specific convention: 'circuit.fuseaction.cfm'. If the Runtime determines that the configuration hasn't changed, then the parsed fuseaction template is executed.
There is also a configuration setting in 'fusebox.xml' that determine the frequency of re-generating these parsed files. It's a parameter named 'mode'. To get Fusebox to 'refresh' the configuration on each request, I set mine to:
<parameter name="mode" value="development-full-load" />
Damon, thanks. Someone needs to update the docs for valid values for mode. (Although that kind of stuff should be later in the docs anyway.)
Yeah, my tutorials are related to 4 but the main part hasn't changed all that much - that aside I am on the team tasked with the new documentation and i think we're going to come out with something really good! and we're only on the table of contents so far :)
@charlie - john at beynon dot org dot uk - paypal, itunes gift cards, cf licenses etc etc....mucho thanks in advance :)
To be fair, all the things you mentioned are actually located in the docs.
In the section labelled "New Execution Modes".
I had trouble too, figuring out how to make fusebox reload the xml file.
It tells you what url variables to use, and mentions the development mode vs. the production mode.
Granted one has to read the Readme file in the fusebox5 folder, to find the link.
I agree though, it could be more obvious, or laid out better.
Yup the Fusebox 4 docs on the site are pretty confusing and, as Steve says, we're working on it. Now that TeraTech has taken over Fusebox and there is a *very* active Team Fusebox group, you'll see a *lot* of changes over the coming months (probably even over the coming weeks!).
Take a look at this page to see just what is starting to happen:
Great stuff, Ray. Keep it up. And you've really hit the nail on the head in your lament over the docs.
Like Charlie G.'s experience, I too have looked at FB over the years and each time been dismayed by the lack of gentle introductory docs. And since I was looking at it as much to help others understand it, and to be able to recommend it (rather than having to learn it for some particular project), I just didn't have the energy to dig in on my own. As for recommending it to others, I was left feeling it "wasn't ready yet".
I certainly have respected those involved all along, so I too didn't want to decry it out loud but rather just lamented it and hoped things would improve. I would mostly just point out books like Jeff and Nat's "Fusebox: Developing ColdFusion Applications" as a good starting point and leave it for folks to decide for themselves.
When it was the only f/w game in town, the doc dilemma just left a lot of people on the outside looking in. With the tremendous new interest in f/w's (fascinating to watch the maturing of the community), there are certainly more people willing to give FB a look, so now is indeed the time to shine the welcome mat.
Ray's series of entries here look very promising. The resources identified in comments here (especially John B's--you go, boy!) are wonderful. And the news of the renewed docs efforts by the FB team are very encouraging.
As Ray says in his comment, the "what's new doc" Ali points to, while indeed useful for those going from one release to the next, is just really not at all suitable for someone coming to the f/w for the first time. That's where perhaps John B's tutorial being updated, or some other variant like the MG quickstart, will be SO helpful.
It would seem that even pointing folks to 3rd party resources (as Dan recommended) and the Wiki (and even the several books) would for now be better than leaving them with nothing more than the "what's new".
Some may say "ok, ok, the points been made, we said we're working on it". But I offer this, like Ray, to validate the feelings others may have had and reiterate the importance of the need. Even if it's been discussed to death within the ranks, those on the outside wouldn't know. This really isn't a "bash f/w" thread. Seems everyone here is instead trying to encourage--even bordering on doing an "intervention", or simply speaking "the truth in love". :-)
Looks like a new day dawning for FB. First with Sean's efforts, and now Teratech's and the community. I wish the effort well.
While some will come slinging mud from past experiences, I hope such people would give it as much due consideration as they would expect of (and defend) any tool they've long supported but which has matured to address rough spots. Indeed, it really seems this doc/intro aspect is the only glaring remaining long-standing problem, so the sooner it's resolved, the better.
Well said Charlie. Great post.