• Purpose
• Whats in the Download?
• Requirements
• The Configuration
  • Step One: Define Images
  • Step Two: Define Selects, Radios, and Checkboxes
  • Step Three: Define Fields
  • Step Four: Define Layout and Retrieval Settings
• About viewType
• About queryExtention
• About eventsObj
• Using XML Configuration
• Creating New Themes
• Wrap Up
• Donations

Purpose

The aedCFC (add/edit/delete cfc) is a multipurpose ColdFusion component for managing various type of database tables in an efficient manor. aedCFC is not intended to be a Content Management System, however it is intended to be used as a key library capable of building a Content Management System and provide efficient solutions to repetitive database tasks(adding rows/editing rows/deleting rows from a table).

What You Will Find in the Download

In the root directory of the download you will find several .cfm files and the directory "aed". The .cfm files are simply examples of possible configurations. Within the "aed" directory you will find:

• the directory "templates"
• aed.cfc the nuts and bolts to this toy
• image.cfc by Rick Root
• tree.cfc handles tree manipulations
• formStruct.cfc which handles building form field requirements

Within the "templates" directory is where all of the themes are stored, we well as the fckeditor and dojo library.

Requirements

Cold Fusion and MySQL, MSSQL, Access(Oracle not tested yet).

The Configuration

The configuration is basically the file used to invoke the aed.cfc to perform the add/edit/delete. The file name is flexible as you can see by the files in the root of the download.

Step One: Define all image duplicates and resizes(if any)

You will need one array similar to this for every image copy. The size of the array [] indicates how many duplicates of the image. Here we are creating one duplicate, hence image1 has a size of 1. Each array iteration contains a struct with three elements: alias, x, y. "alias" indicates the addition to the file name to use, and "x" and "y" are the sizes to resize the image to.

Step Two: Define all select drop downs, radio buttons, or checkboxes(if any)

Each select, radio, and checkbox set will be given a structure with two elements: "value" and "name". "value" will be a list of the real values(the values you want to be placed into the database) and "name" will be a list of the same length for the textual description for the interface. One of these must be created for each select or each GROUP of checkboxes/radio buttons. Don't forget that you can convert a query to a list if you are pulling data from a related table to build these.

Step Three: Defining the fields

Here is where everything ties together. We must now create an array with each element of the array representing a field on the form. Each field will of type struct. This is probably the most lengthy part of the entire process, however the toughest part is keeping track of the parameters. The parameters are(in order):

name

the name of the column in the database

textName

the textual name to give this field on the UI("" is valid assignment)

inputType

the type of input this should be (text, hidden, radio, checkbox, select, selectmultiple, textarea)

sqlType

the type you would use when using cfqueryparam (cf_sql_integer, cf_sql_char, etc..)

charLength

(optional)the number of characters allowable(integer, 0 or "" is unlimited characters)

defaultValue

(optional)The default value to assign that field(leave blank if no default value)

isValidType

(optional)if the field is being required and isValid() may apply, what type(email, ssn, etc..)

dropdownQuery

(optional)the structure "radioField" we declared in step two if applicable, "" if not.

valueRequired

(optional)true/false if the value is required, if yes and no isValidType then checks for ""

wizywig

(optional)0,1,2 for the fckeditor. 0 is off, 1 is basic(bold,italic..), 2 is the full editor

altImages

(optional)the structure built in step 1 that applies to this image, "" if not applicable

Step Four: Defining layout and data retrieval settings

This is the final part of the configuration. We will now set variables pertaining to the datasource, location of the themes etc… The variables are as follows:

title

the title of this add/edit/delete

dsn

the datasource to be used(set in the ColdFusion administrator

table

the table in the database we are performing the aed on

pageName

the name of this configuration file(generally doesn't have to be changed)

imageDirectory

location of images

uploadDirectory

location to upload images

theme

the directory name containing the theme of choice (located in templates folder)

imageDisplayUrl

the url to use displaying images uploaded

pathToThemes

the path to the themes directory(used to access scripts CLIENT SIDE)

viewType

the type of view to use: default, move, tree(see section on view types)

key

the name of the primary key in table(I generally set tables up with "id" as key)

queryExtension

extra conditions to append to a WHERE clause on every query

eventsObj

a string of the absolute component path to a cfc providing extra functionality

About viewType

There are currently three different view types: default, move, tree. Each require a different table set up and serve their own purpose.

Default view is a simple aed with only a primary key required and no special functionality besides add/edit/delete.

Move view table structure requires a key and an additional field called weborder(integer). "weborder" provides ordering to your entries and allows you to reorder them any way you wish. When using this mode, the listings page will then allow you to move the entries.

Tree view is perhaps the most advanced. The table structure requires a primary key named "id", an integer named "parentId", an integer named "rgt", and an integer named "lft". This view will then allow you to create tree structures of any depth to create layered menus or anything with a hierarchical structure. Of course in addition to all of these required fields you need to include your own fields.

About queryExtension

"queryExtension" allows you to extend your queries by providing more and/or clauses, and can provide extra protection and security against hacking.

For Example: You have an intranet where there are multiple users who login. Each user has their own set of links that display on their intranet landing page that they are allowed to add/edit/delete. In our database table we have a field called employeeNum which is unique to each employee. Using a query extension and their session variable employeeNum we might use the following:

Now this user will never be able to add/edit/delete anyone's links but their own. (this is added to insert, delete, select, update queries EXCEPT in tree view since this could mess up the output of the table structure).

About eventsObj

The eventsObj is an optional cfc to provide extra functionality at the end of an add/edit/delete. Three event functions can optionally be defined in the cfc named "onAddEnd", "onEditEnd", and "onDeleteEnd". All three functions are passed the "variables" scope as a parameter. The variables scope will contain all of the parameters you have set, as well as the values of the form just submitted under "formValues" array. These functions are called via cfset, and will not be able to output anything.

Using XML Configuration

Using the optional XML configuration method uses the exact same steps as listed above with XML instead of ColdFusion function calls. When using the xml you can retrieve it from an external XML file or build the xml within the config file, just as long as you call initWithXml(xml) in the place of init(). See the example "xmlExample.cfm" in the download.

Creating New Themes

Creating new themes is relatively simple. There are seven required files: defaultView.cfm, deletion.cfm, footer.cfm, form.cfm, header.cfm, moveView.cfm, treeView.cfm. Be aware that even though this breaks the presentation layer up from the logic layer, there is still some logic required in these files. To avoid losing functionality it is suggested that you make a copy of the default theme and begin working off of the duplicate theme.

The name of your new directory will be the name of the theme. All variables that you have set in the config file will be accessible by the "variables" scope as you can see by the existing theme. Keep in mind that this template is not in the same directory as the config file, so client side includes need to use variables.pathToThemes string to reach these client side includes. "dojomove" theme is a good example of this.

Wrap Up

After one or two of these you realize you have cut out at least an hour of time creating custom add/edit/deletes since this does everything dynamically. Another thing to keep in mind is that this is a component, so use it as one. Place aedCFC into your library of other cfc's map it in the CF Administrator(no need to make copies everywhere).

Please don't hesitate to make any suggestions or report bugs.