MGDoc, a Model-Glue documentor

If you haven't guessed it yet, I'm all about the Model-Glue. If I wasn't married, I'd ask Model-Glue to marry me. We would settle down in a small, ranch style house in the mid-west. I'd gladly stay at home so Model-Glue could go out into the work place, quickly and efficiently helping ColdFusion developers create better applications. Alas, it is a forbidden love...

As much as I love Model-Glue, one thing that bugs me is large XML config files. I've worked on a few sites now where the ModelGlue.xml files gets to be so huge, it's hard to navigate. That's why I've created MGDoc, a CFC that will parse your ModelGlue.xml file and create documentation from it.

This documentation is heavily based on the documentation you get with CFCs. So, um, Adobe, don't sue me, ok? I love Photoshop! By default the documentation is generated in HTML, but you can use PDF and Flash Paper as well. (For the Flash Paper I cribbed some code from Jared Rypka-Hauer's excellent cfcToPrinter UDF.) For an example in PDF, here is the config file from the ColdFusion Cookbook:

http://ray.camdenfamily.com/downloads/mg.pdf

The code is not quite done yet. It is missing a few of the optional things you can supply to views and broadcasts. But - play with it - and let me know. I think the text is a bit big in PDF format, but in general, I think the layout is nice. (Although again I can't take credit for the table styles.)

Archived Comments

Comment 1 by Dan Sorensen posted on 3/31/2006 at 4:50 AM

Hey, that works pretty well! :-) I been following along with your MG series and I just deployed my first MG app today, and now I can print out documentation too!

By the way, I just started using Reactor with MG and I'm already impressed. I'm sure you'll like it as much as MG once you get some time to play with it.

Comment 2 by Dan Sorensen posted on 3/31/2006 at 6:19 AM

It seems this little utility needs a simple front end so that documentation can be generated on the fly from a form. It doesn't look that difficult. When I get some time, I might look into that.

Comment 3 by Critter posted on 3/31/2006 at 7:10 AM

Dude,

You are weird

Comment 4 by Raymond Camden posted on 3/31/2006 at 7:15 AM

Not I. ;)

Comment 5 by Sean Corfield posted on 3/31/2006 at 7:29 AM

So I haven't looked at the code yet but I sure hope you just have a single XSL file that you transform the ModelGlue.xml with, into HTML, right? :)

Comment 6 by Raymond Camden posted on 3/31/2006 at 7:36 AM

Ugh. No. Although that would have made sense. ;)

Comment 7 by Wayne Graham posted on 3/31/2006 at 6:20 PM

I actually did something along these lines with XSLT a while back (http://swem.wm.edu/blogs/wa....

Generating the documentation with XSL is really pretty simple...and the PDFs are even easier now that you don't have to use FO to generate them.

Comment 8 by Raymond Camden posted on 3/31/2006 at 6:50 PM

To be fair, I did have one good reason to do it by hand - I wanted the funcs that grab stuff (settings, events, controllers) to be public so that if you wanted to, you could get that data. I can't imagine anyone doing that at runtime, but hey, it's there if you want it. :)

Wayne, I like yours as well. I didn't know you had built one at well, but hey, the more alternatives out there the better.

Comment 9 by Mark Drew posted on 3/31/2006 at 7:16 PM

That is awesome stuff!

I am thinking of writing a CF(Eclipse) plugin for Model Glue and this documentor would be a great way of viewing your MG app.

The XSLT route might be easier for Eclipse development though.

Any other ideas for something to help you build your MG app let me know! (IDE wise I mean :))

Comment 10 by Raymond Camden posted on 3/31/2006 at 7:20 PM

Oh yea - an Eclipse plugin that worked like the CFC view would kick butt.

Comment 11 by Mark Drew posted on 3/31/2006 at 7:33 PM

I was thinking that is one way to do it, but we could do it a bit more interesting, like the plugin.xml editor (or how Flex Builder does it). You can see a screenshot if you havent seen it before here: http://www.markdrew.co.uk/i...

notice the tabs at the bottom, this lets you flick between the actual code and the sections, so for example at the bottom we could have the following tabs: config | controllers | event-handlers | modelglue.xml

You would hit each to add/edit each of the items in each section.

If you added a new controller you could select the CFC, and then add listners -> functions (from a drop down) kind of thing.

Just some thoughts....

Comment 12 by Mark Drew posted on 3/31/2006 at 7:33 PM

I should have added that the last one would be a documentation map of the modelglue.xml app, as you have done!

Comment 13 by Raymond Camden posted on 3/31/2006 at 7:46 PM

That's pretty slick. I'm always amazed at how well built the Eclipse framework is.

Comment 14 by Chris posted on 4/2/2006 at 4:31 PM

Here is a nice FAQ for Model Glue - http://awads.net/wp/2005/06...

Comment 15 by doug sims posted on 4/21/2006 at 7:01 AM

Thanks for this resource Ray.....

Mark,
The MG plugin Idea is a great one, even more reson to switch to cfeclipse.......

Comment 16 by wrvishnu posted on 11/3/2007 at 7:49 AM

Hi
Not able to downlaod the docs and pdf from the link too

Comment 17 by Raymond Camden posted on 11/4/2007 at 1:25 AM