Getting Started Tutorial
From ColdExt
Contents |
Downloading and Extracting
To begin this tutorial you should download ColdExt from RIAForge and extract the contents of the zip to the web root of a new web site. You will end up with a directory structure that looks like this:
<wwwroot>/coldext - ColdExt tag library, required <wwwroot>/dictionary - CFEclipse Dictionary XML for tag insight <wwwroot>/docs - ColdExt Documentation and Demos <wwwroot>/ext - ExtJS library files, required
The coldext and ext folders are both required for ColdExt to function.
The demos and dictionary folders do not need to be in the web root when using ColdExt but we will just ignore them for now.
Tag insight in CFEclipse
Browse to the plugins/org.cfeclipse.cfml_1.3.1.5/dictionary directory inside your CFEclipse folder (your plugin version number may vary) and insert a copy of the ColdExt dictionary/coldext.xml file. Make a backup of the dictionaryconfig.xml (just in case) and then open it to make the following modification, inserting a single line to include the coldext.xml file:
<version key="cf8" label="Coldfusion 8">
<grammar location="cf8.xml" />
<grammar location="user.xml" />
<grammar location="coldext.xml" /> <!-- insert this line -->
</version>
Restart CFEclipse for the dictionary config changes to take effect.
Basic requirements and code structure
When developing with ColdExt there are 3 basic requirements which must be met. The ColdExt library must be included using the <cfimport> tag, all ColdExt code must be placed inside <ext:onReady> tags, and the ColdFusion Application scope must be available for use.
<cfimport prefix="ext" taglib="/coldext"> <html> <head> <title>Getting Started with ColdExt</title> </head> <body> <div id="out"></div> <ext:onReady> <!--- ColdExt tags go here ---> </ext:onReady> </body> </html>
<cfimport>: To use the tag library it must be imported using cfimport with the ext prefix. The ext prefix is required for tag insight to work in CFEclipse!
<ext:onReady>: The onReady tag is the root tag which all other ColdExt tags must be nested inside of, and so it must be declared with an opening and closing tag. It is synonymous with the ExtJS practice of passing an anonymous function as a parameter to Ext.onReady() so that your ExtJS code will run as soon as the browser DOM is ready. The <ext:onReady> tag also now implicitly calls the <ext:init> tag which makes the Ext JS JavaScript and CSS resources available by inserting them into the HTML head element.
Important Note: The final requirement for using ColdExt is that you have declared an Application Name so that ColdExt can make use of the Application scope. You can do this with either an Application.cfm or Application.cfc. See the Configuring_ColdExt_in_Application.cfc tutorial for a sample Application.cfc file.
Hello World (in a Panel)
Now for the obligatory Hello World app...
<cfimport prefix="ext" taglib="/coldext">
<html>
<head>
<title>ColdExt Hello World (in a Panel)</title>
<style type="text/css">
body { padding: 20px !important; font: 13px Verdana, sans-serif; }
</style>
</head>
<body>
<div id="out"></div>
<ext:onReady>
<ext:panel title="Panel" padding="10" renderTo="out">
Hello World!
</ext:panel>
</ext:onReady>
</body>
</html>
How rendering works
When a component is rendered it is attached to a node in the HTML DOM. In this example we have a DIV with id="out" which is a prime target for us to render a component (or append multiple components) to. The ColdExt tag introduced here is the <ext:panel> tag which we have given a title, padding, and some body text. Additionally we have also supplied the value "out" to the renderTo attribute which tells the panel to render itself to our DIV that has the matching ID. Too easy!
You also have the option of not rendering the component immediately and instead saving it for later use - by supplying the var attribute instead of the renderTo attribute - but that is for another tutorial!
Where to next?
At this point I would recommend looking at the demos that are bundled with ColdExt to get a feel for some of the tags and keep checking this wiki for more tutorials and other documentation :)
If you have any questions feel free to either use the Contact Form or post to the ColdExt Forums on RIAForge.
