CF_easyFrame, CF_easySeparator
and CFX_easyFrame

v1.0

May/2004

DESCRIPTION
HOW DOES IT WORK?
INSTALLATION
SYNTAX
BROWSER COMPATIBILITY
EXAMPLES

DESCRIPTION

This tag is actually composed of three distinct tags:

easyFrame.frameDate = 20040502174504

Note

If you find this custom tag useful, or if you have any suggestion to make it even more useful, just let me know, I'll be glad to enhance it.

CF_easyFrame is the main tag that is usable to build dynamic frames around some content.
CF_easySeparator is an optional tag that can be embedded inside CF_easyFrame to create horizontal separator lines between areas inside the frame. The original image used to create the image elements must have been especially designed in order to use this option.
Finally, CFX_easyFrame is an installable DLL. This tag is not called directly by the programmer. It is automatically called by CF_easyFrame to create the images parts from the original. If this original image is not modified, CFX_easyFrame will be called only once. On the other hand, as soon as CF_easyFrame detects a change (ie. in the original image date), it will call CFX_easyFrame to refresh the different necessary elements. If the original image is not to be changed, CFX_easyFrame may not be installed on the production serve, it is only necessary on the development server. In this eventuality, all the image parts need to be send to the production server.

HOW DOES IT WORK?

easyFrame.frameDate = 20040502174504

	Notes
	CF_easyFrame does not create the image parts "on the fly". This will be done only the first time, and it is transparent to the user and the programmer. Most of the time, the tag will just create the HTML to display the frame in a table, and re-use the image parts it created the first time, just like if it was a static frame generated on the programmers working station.

	The original image must be in GIF format only.

Two types of frames can be created. In the simplest case, only a frame is used around one text area. But one can also create frames together with an horizontal separator, in order to get several separated zones in the text area.

Simple frames

CF_easyFrame first checks if all the elements necessary to build the frame are present and up to date in the location specified in the IMAGE attribute. If it is not the case (for example, the first time the tag is called), it then calls CFX_easyFrame in order to create all these elements once for all. You must supply one image from which CFX_easyFrame will extract all the image parts. This image must be in GIF format only.

There are 8 basic elements, like in the following example (for clarity, size is increased 3 times):

Original image:
Here, the original file is greenTorus.gif
the tag will generate all the sub files:

greenTorus_11.gif greenTorus_21.gif greenTorus_31.gif

This will be
the area
used for text greenTorus_12.gif greenTorus_32.gif
greenTorus_13.gif greenTorus_23.gif greenTorus_33.gif

easyFrame.frameDate = 20040430234210

And this is the kind of frame you can get just using this code:

<CF_easyFrame image="greenTorus" x=20 y=20 ALIGN="center" VALIGN="middle"> And this is the kind of frame you can get just using this code: </CF_easyFrame>

Frames with separators

When using separators, an extra row of 3 images is generated, the file names are ended with _14, _24 and _34.

Original image:
Here, the original file is goldenRing.gif
the tag will generate all the sub files:

goldenRing_11.gif goldenRing_21.gif goldenRing_31.gif

This will be
the area
used for text goldenRing_12.gif goldenRing_32.gif
goldenRing_14.gif goldenRing_24.gif goldenRing_34.gif

goldenRing_13.gif goldenRing_23.gif goldenRing_33.gif

easyFrame.frameDate = 20040501214906

And this is the kind of frame you can get just using this code:

with one,

or more separators.

<CF_easyFrame image="goldenRing" x=19 y=16 hSeparator="4" ALIGN="center" VALIGN="middle"> And this is the kind of frame you can get just using this code: <CF_easySeparator> with one, <CF_easySeparator> or more separators. </CF_easyFrame>

Text areas

There are three areas usable to display text:

The top area can be used to display some title. One must transmit this text through the TOPTEXT attribute, and use the TOPCLASS and TOPSTYLE to define styles to be used for this text. This area is shown on a blue background in the above tables.
The main area is the most central part in the 3x3 table. The tag display in this area all it will find between its opening and closing tags. One can use the AREACLASS and AREASTYLE to define styles to be used for this text. This area is shown on a green background in the above tables.
The bottom area can be used to display some footer in a box. One must transmit this text through the BOTTOMTEXT attribute, and use the BOTTOMCLASS and BOTTOMSTYLE to define styles to be used for this text. This area is shown on a yellow background in the above tables.

easyFrame.frameDate = 20040502230526

Examples

See these examples.

OTHER GENERATED FILE

Beside the image parts, CFX_easyFrame generates a WDDX associated file, with the same name passed in the IMAGE attibute, and the .wddx extension. This file will be read by subsequent calls to CF_easyFrame; it contains code to initialize CF variables with the size of the image parts, and the date they were generated.

REGENERATION OF IMAGE PARTS

All image parts, as well as the WDDX file, will be automatically regenerated by CFX_easyFrame every time one of the following conditions is met:

The associated file is not found;
The date found in the associated file is different from the date the original image file was created;

This property can be used to force the regeneration of all the sub files: if you modify the original image file, the regeneration process is automatic, but if you want to create a new configuration with the same image but new coordinates, just delete the WDDX associated file.

INSTALLATION

To use this tag, you need to take the included easyFrame.dll, install it on a drive on your server and make it known to the ColdFusion administrator.

You do this by going to the "CFX Tags" tab in the administrator,

click the "add" button.
Specify the name as CFX_easyFrame.
For the Server library(dll), specify the path to the .dll (the directory into which you copied easyFrame.dll.
It should say for "Procedure", "ProcessTagRequest".

That's it!

For more information refer to the ColdFusion documentation "Managing CFXs".

Then, you may install the two other CFML tags, easyFrame.cfm and easySeparator.cfm in the special Custom Tags directory in your ColdFusion server. This directory is generally named \Cfusion\CustomTags.

You may also store the file in a directory defined as a path for custom tags in the ColdFusion Administrator (CF 5.0+) or in the same directory as the calling template.

The other files are this documentation (easyFrameDoc.cfm) and a couple of example files; just store them in any convenient place in the HTTP area on your development server.

Finally, you will find some GIF files that you can use as example. Store them in the same directory as the samples cfm.

SYNTAX

<CF_easyFrame 
	IMAGE         = <full path name of the basic image file">
	[X]           = <abscise of the pixel where the left parts end>
	[Y]           = <ordinate of the pixel where the top parts end>
	[HSEPARATOR]  = <height in pixels of the horizontal separator>
	[ALIGN]       = "left"|"center"|"right"
	[AREAALIGN]   = "left"|"center"|"right"
	[AREAVALIGN]  = "top"|"middle"|"bottom"
	[AREACLASS]   = <Class name for the main text area>
	[AREASTYLE]   = <Style declaration for the main text area>
	[TOPTEXT]     = <text for the top text area>
	[TOPCLASS]    = <Class name for the top text area>
	[TOPSTYLE]    = <Style declaration for the top text area>
	[BOTTOMTEXT]  = <text for the bottom text area>
	[BOTTOMCLASS] = <Class name for the bottom text area>
	[BOTTOMSTYLE] = <Style declaration for the bottom text area>
	>
text to be displayed in the main area.
[<CF_easySeparator>]
[Text in the second area]
......
</CF_easyFrame>

TAG	ATTRIBUTE	CONTENT	REQUIRED	DEFAULT
<CF_easyFrame	IMAGE=	Path name of the original image file, realtive to the calling template, but with the ".gif" extension omitted, since it is always assumed to be .gif, and this root name will be used to create all image parts by appending suffixes. The path can be relative to the page calling the template.	Yes	N/A
X=	abscise (starting at 0) of the last pixel used in the three left elements to be extracted from the image (_11, _12 and _13). This is also the asbsisse of the one pixel used to create the two elements that will constitute the top and bottom center parts (_21 and _23, extended in a background). Finally, this is also the abscise of the first pixel in the three right elements (_31, _32 and _33). Note: the attributes X and Y are needed the first time an image is submitted to the tag, and every time an image is modified. Once the sub parts of the image have been generated, and as long as the image is not modified, they may be omitted.	First time only	Nothing
Y=	Ordinate (starting at 0) of the last pixel used in the three top elements to be extracted from the image (_11, _21 and _31). This is also the ordinate of the one pixel used to create the two elements that will constitute the left and right middle parts (_12 and _32, extended in a background). Finally, this is also the ordinate of the first pixel in the three bottom elements (_13, _23 and _33). (see note above)	First time only	Nothing
HSEPARATOR=	If the frame can use an horizontal separator, this is its height in pixels. The bottom element wil be extracted from the portion of the image immediately below this area of the image.	No	Nothing
ALIGN=	Sinte the frame is generated in a TABLE, the whole table can be "left", "center" or "right aligned, like any table.	No	Nothing
AREAALIGN=	This optional attribute will be transmitted to the TD enclosing the main text area between the opening and closing tag.	No	Nothing
AREAVALIGN=	This optional attribute will be transmitted to the TD enclosing the main text area.	No	Nothing
AREACLASS=	An optional class name for the text displayed in the main text area.	No	Nothing
AREASTYLE=	An optional style definition for the text displayed in the main text area.	No	Nothing
TOPTEXT=	An optional string to be displayed in the center top area.	No	Nothing
TOPCLASS=	An optional class name for the text displayed in the top area.	No	Nothing
TOPSTYLE=	An optional style definition for the text displayed in the top area.	No	Nothing
BOTTOMTEXT=	An optional string to be displayed in the center bottom area.	No	Nothing
BOTTOMCLASS=	An optional class name for the text displayed in the bottom area.	No	Nothing
BOTTOMSTYLE=	An optional style definition for the text displayed in the bottom area.	No	Nothing

BROWSER COMPATIBILITY

The code produced by these tags is 100% compatible with Explorer 5.5+, Mozilla and Netscape 6+. The output is also correct under Netscape 4.x if no styles or classes are used, due to the poor support of CSS in this antique version, which by the way has almost disappeared from the entire Web.

EXAMPLES

Original image Source Code Result

<CF_easyFrame image="roundCornerRed" x=10 y=8 hseparator=3> Text in a box </CF_easyFrame>
easyFrame.frameDate = 20040502222906

Text in a box

<CF_easyFrame image="roundCornerBlue" x=10 y=8 hseparator=3 ALIGN="center"> Text in a box <CF_easySeparator> With a separator </CF_easyFrame>
easyFrame.frameDate = 20040502223104

Text in a box

With a separator

CF_easyFrame can be used at multilevel
to obtain more sophisticated frames:
<CF_easyFrame image="wineDropShadow" x=14 y =14 width="200" ALIGN="center" VALIGN="middle"> <CF_easyFrame image="whiteParagraph" x=30 y=30 hSeparator="6" width="200"> Portuna lorem ipsum dolor sit amer, quid mestra ut suscipe melioram veritas. <CF_easySeparator> Dolore illum ex commodio consequat, qui nostra magna senza pomodoro ut studia felicitas in minim veniam. <CF_easySeparator> Portuna lorem ipsum dolor sit amer, quid mestra ut suscipe melioram veritas. Aliqua stratum in centra benedicto, recondus terrestra duis al ordina tuamem, nerus philema lux in gratia gratianem. <CF_easySeparator> Iusto odio dignissim qui blandit praesent luptatum duis dolore te felavit nulla facilisi. Dolore illum ex commodio consequat, qui nostra magna senza pomodoro ut studia felicitas in minim veniam. Portuna lorem ipsum dolor sit amer, quid mestra ut suscipe melioram veritas. </CF_easyFrame> </CF_easyFrame>
easyFrame.frameDate = 20040430183530

easyFrame.frameDate = 20040501231658

Portuna lorem ipsum dolor sit amer, quid mestra ut suscipe melioram veritas.

Dolore illum ex commodio consequat, qui nostra magna senza pomodoro ut studia felicitas in minim veniam.

Portuna lorem ipsum dolor sit amer, quid mestra ut suscipe melioram veritas. Aliqua stratum in centra benedicto, recondus terrestra duis al ordina tuamem, nerus philema lux in gratia gratianem.

Iusto odio dignissim qui blandit praesent luptatum duis dolore te felavit nulla facilisi. Dolore illum ex commodio consequat, qui nostra magna senza pomodoro ut studia felicitas in minim veniam. Portuna lorem ipsum dolor sit amer, quid mestra ut suscipe melioram veritas.