Fusebox Scaffolding - The XML Specification

Posted At : February 5, 2007 3:23 PM | Posted By : Kevin Roche
Related Categories: Scaffolding,Fusebox

Introduction

This document is a proposed specification for a Fusebox plug-in which will allow a basic maintenance application to be created for a database table. The application will provide facilities to list records from the table, to display individual records, to add, edit and delete records.

The scaffolder is intended to be the first of a number of applications that will provide a facility to generate code automatically, based on a high-level domain specific language.

Specification of the process

The scaffolder is triggered by an entry in the fusebox.appinit.cfm file.

The scaffolder takes the following parameters:

· The file path to the scaffolding.xml file,

· The name of the datasource,

· The database username,

· The database password,

· The names of the base tables for which scaffolding is to be generated.

The first step of the process is to check for presence of a scaffolding.xml file. If one is found it is read and will be updated if necessary. If it is not found then a dummy one is created.

The next step is to introspect the database tables and for each one build a list of fields, which are added to the XML file.

Scaffolding XML

The scaffolding.xml file will contain a configuration block, which has the details of the datasource to be used, and an objects block, which has details of the objects that are to be maintained and the tables that they relate to.

Here is a sample XML file:

<?xml version="1.0" encoding="UTF-8"?>
<scaffolding>
       <config>
              <project value="Scaffolding"/>
              <persistance value="reactor" />
              <dsn value="CMS01AdsTags"/>
              <type value="mssql"/>
              <mapping value="/Scaffolding "/>
              <mode value="development"/>
              <!-- These config values are optional -->
              <username value="myusername"/>
              <password value="mypassword"/>
       </config>

       <objects>
                        <object name="Fuseaction">
                               <oneToMany name="Tag">
                                           <relate from="Fuseaction_Id" to="Fuseaction"/>
                               </oneToMany>
                               <manyToMany name="TagType">
                                           <link name="Tag" from="Fuseaction" to="TagType"/>
                               </manyToMany>
                               <manyToOne name="Site">
                                           <relate from="Site_Id" to="SiteId"/>
                               </manyToOne>

<field alias="Fuseaction_Id"
       formType="Hidden" 
       format="None" 
       label="Fuseaction Id" 
       name="Fuseaction_Id" 
       required="false" 
       showOnForm="true" 
       showOnList="true" 
       size="0" 
       primaryKeySeq="1" 
       identity="true"/>

<field alias="Circuit"
     formType="Text" 
     format="Trim" 
     label="Circuit" 
     name="Circuit" 
     required="false" 
     showOnForm="true" 
     showOnList="true" 
     size="30"/>

<field alias="Fuseaction_Name" 
     formType="Text" 
     format="Trim" 
     label="Fuseaction Name" 
     name="Fuseaction_Name" 
     required="false" 
     showOnForm="true" 
     showOnList="true" 
     size="30"/>

<field alias="Page_Title"
     formType="Text" 
     format="Trim" 
     label="Page Title" 
     name="Page_Title" 
     required="false" 
     showOnForm="true" 
     showOnList="true" 
     size="30"/>

<field alias="Site_Id" 
     formType="Dropdown" 
     format="Trim" 
     label="Site Id" 
     name="Site_Id" 
     required="false" 
     showOnForm="true" 
     showOnList="true" 
     size="1" parent="Site" 
     display="SiteName" />

                   </object>

                   <object name="Site">
                             <oneToMany name="Fuseaction">
                                    <relate from="SiteId" to="Site_Id"/>
                             </oneToMany>
                            	<field alias="SiteId" name="SiteId"/>
                             <field alias="SiteName"      name="SiteName"/>
                             <field alias="RootDir" name="SiteRootDirectoy"/>
                             <field alias="ImagePath"      name="SiteImagePath"/>
                       <field alias="AttachmentPath" name="SiteAttachmentPath"/>
                        </object>
            </objects>

</scaffolding>

The data in the xml file config block is as follows:

project	The name of the project
persistance	The name of the object relational mapping tool that is to be used. Valid values are currently: reactor
dsn	The name of the datasource.
type	The type of DBMS. Valid values are currently: mssql
mapping	The path to the application from the web root.
mode	The mode parameter controls the generation of code. Valid values are currently: development, production It is set to development during the development phase of the project and should be changed to production to prevent code generation once live running.
username	The DBMS login name (optional)
password	The DBMS password (optional)

The objects block will contain an object entry for each object to be managed. The object tag has the following attributes:

name	The name of the table that represents this object.
alias	The name it will be known as in your CFML.

Each object tag can contain the following tags:

oneToMany	Describes a one to many relationship with another table. The other table is also known as a child table.
manyToOne	Describes a many to one relationship with another table. The other table is also known as a parent.
manyToMany	Describes a many to many relationship with another table.
oneToOne	Describes a one to zero/one relationship with another table.
field	Describes a column in the table, which will become a fixed property of the object.
property	Describes an object property that is implemented by a relationship with another table. This allows properties to be implemented that are optional properties and can vary by object. (not yet implemented.)

Within each of the relationship defining tags there is either a set of relate tags or a link tag.

relate	Used to show which fields in each of the tables relate to each other.
link	Used to indicate that the relationship is via another table and to define the name of the two relationships involved.

The field tag takes a number of attributes that specify the type of field and the rules for validation and presentation of it.

alias	The name by which this property will be called in cold fusion
formType	The type of presentation that will be used when showing the field on a form.
format	The format to be used when displaying the value.
label	The name that will be used to label the filed on the generated pages.
maxlength	For string fields. Code will limit what can be entered to the specified number of characters.
name	The name of the field in the table.
required	Specifies whether the field is required or not. Valid values: true, false.
showOnForm	Specifies whether the field is to be represented on the form or not. Valid values: true, false.
showOnList	Specifies whether the field is to be represented on the list page or not. Valid values: true, false.
size	For those fields that require a size specification. This will specify the width of text boxes and the height of list boxes.
primaryKeySeq	This attributes indicates that the field is part of the primary key for the table. Each primary key field is labelled in order of its place in the key.
identity	Specifies that the field is an identity generated by the database. Valid values: true, false.

Notes:

Once the xml has been generated it can be edited manually, if desired, to modify the generated application.

If the xml file already exists when the appinit process is run the xml will be updated with any additional fields found in the specified tables. Existing fields and relationships will not be modified, except to add further attributes if necessary.

It is recommended that the relationships be manually defined, as in many cases the database may not contain a complete description of the relationships.

Code Generation

The following code will be generated from the XML:

Filename	Description
reactor.xml	Reactor configuration file (when reactor has been specified as ORM).
datasource.xml	Transfer datasource configuration file (when transfer has been specified as ORM).
transfer.xml	Transfer configuration file (when transfer has been specified as ORM).
circuit.xml	Fusebox controller circuit file.
dsp_display_alias.cfm	Fusebox display fuse for displaying a single record.
dsp_form_alias.cfm	Fusebox form fuse for adding and editing records.
dsp_list_alias.cfm	Fusebox list fuse for displaying multiple records.

Required Lexicon

In order to make use of the generated code you must also have the ORM lexicon for the Object Relational Mapper you wish to make use of. Currently only reactor is supported, but an ORM is planned for reactor.

Comments (4) |

Send |

del.icio.us |

Digg It! |

Linking Blogs | 1237 Views

Comments

[Add Comment]

I like the ideas here Kevin.
Can I suggest some more settings?
As well as maxlength why not add minlength or maybe regex as a validation option?
Could there be a displayPrefix option? I prefer a plain "dsp" rather than "dsp_".
On that note how about a spacer option? I prefer to camel case my fuse names so I would set spacer to "" rather than the default "_".
Following on again could there be a prefixList option? The default would be "display,form,list" but I would set it as "Detail,AddEdit,Default".
As a result with my preference applied my files would be called...
dspDetailAlias.cfm
dspAddEditAlias.cfm
dspDefaultAlias.cfm

I'd be happy to beta test anything you produce.

# Posted By dickbob | 2/12/07 1:29 PM

dickbob,

I was thinking of a way to add a piece of validation code so that each field could have it own validation routine.

On the other point. You would like to be able to change the name of the file. I will see what can be done.

Kevin

# Posted By Kevin | 2/12/07 3:42 PM

Hm...
It's a big piece of code... But it has helped me a little and so...
thank you, Mr Roche....

http://golfclubz.info/sitemap.php

# Posted By Andrew | 9/13/07 7:17 PM

That's good to know. Thanks. Did you have any problems with it?

# Posted By Kevin Roche | 9/24/07 9:07 AM