Allaire Cold Fusion Connector
User Guide
For NetObjects Fusion 4.0
Allaire™ Corporation
One Alewife Center
Cambridge, MA 92140
(617) 761-2000
http://www.allaire.com
Introduction
The Allaire Cold Fusion Connector™ is a connectivity kit that extends NetObjects Fusion, a popular graphical Web development tool marketed by NetObjects, Inc. Once installed, The Allaire Cold Fusion Connector enables you to use Cold Fusion® Application Server to incorporate dynamic elements into a NetObjects Fusion Website directly from within the NetObjects Fusion user interface.
Contents
Introduction*
Contents*
Overview*
New Features for NetObjects Fusion 4.0*
Requirements*
Installation*
ODBC*
About the User Guide*
New To Web application development?*
Experienced NetObjects Fusion User?*
Want to Know more about Cold Fusion?*
Allaire Cold Fusion Connector Documentation*
Cold Fusion Documentation*
Acrobat Files*
Learning More About Cold Fusion*
Allaire Developer Services*
Contacting Allaire*
Getting Started*
For Current NetObjects Designers*
For Current Cold Fusion Developers*
Integration Framework*
Component Usage*
Example*
Cold Fusion Concepts*
Staging*
Components*
Cold Fusion Form Toolbar*
Cold Fusion Toolbar*
Nonvisual Components*
Common Errors*
Reading From File in Browser*
Forgetting to use the Cold Fusion Publish Component*
Misspelled field in CF Query*
Mismatched data type in the SQL Where Clause*
Misspelled Query Name in an Output Component*
Misspelled Field Name in an Output Component*
Overview
Cold Fusion is a rapid application development system for professional developers who want to create dynamic Web applications and interactive Web sites. It provides the fastest way to integrate browser, server, and database technologies into powerful Web applications. With Cold Fusion, you can build everything from simple search engines to sophisticated business systems.
Cold Fusion web applications are deployed with Cold Fusion Application Server. You must have Cold Fusion Application Server installed on the same system that runs your web server in order for the dynamic elements created with the Allaire Cold Fusion Connector to operate properly.
Cold Fusion Application Server is sold separately. It is available for purchase from Allaire and from authorized resellers. If you have not licensed Cold Fusion Application Server, an evaluation version is available from the Allaire web site: http://www.allaire.com.
The Allaire Cold Fusion Connector is a connectivity kit that enables you to use the Cold Fusion Application Server to incorporate dynamic elements into a NetObjects Fusion Website directly from within the NetObjects Fusion user interface.
The Allaire Cold Fusion Connector 2.0 includes 22 components listed in the "Components" section as well as a Data Entry Wizard. Some of the components directly correspond to Cold Fusion Markup Language (CFML) tags. CFML is a powerful 4GL that uses an intuitive tag-based syntax, similar to HTML, which is ideal for dynamic Web development. Other components are a combination of CFML and HTML. These components allow you to create common dynamic elements in a number of ways, including lists, tables, and dialog boxes.
The Allaire Cold Fusion Connector includes several features for advanced users. All components have an HTML Edit mode that allows advanced designers to manually modify the code generated by the component. Additionally, the components include an Expression Builder that assists you in writing Cold Fusion Functions.
New Features for NetObjects Fusion 4.0
The Allaire Cold Fusion Connector, formerly Fusion2Fusion, now includes:
- Live database connectivity: you may now view the
results of your query as you work within NetObjects.
- Query Builder: the components include a query
builder that assists you in the creation of queries.
- Record viewing: you may now view the results that
will be placed in visual components from the components themselves.
- Default and HTML Edit modes for most components: you
may now view and manually edit the code generated by the components.
- Expression Builder: hundreds of Cold Fusion
functions are now just a click away.
- Table Tool: You may now use the standard NetObjects
table editing capabilities to format your tables.
- Wizards: Wizards have been included to perform
common tasks such as the creation of a data entry form.
- Help: Web based online help for each component.
Requirements
For the Allaire Cold Fusion Connector (site development):
- PC compatible with Pentium processor (Pentium II
recommended).
- Microsoft Windows NT 4.0 or Windows 95 or Windows 98
- ODBC
- 12 MB disk space
- 48 MB RAM required for Windows 95 or 98 (64 MB
recommended)
- 64 MB RAM required for Windows NT 4.0 (128
recommended)
- CD-ROM drive
- Mouse or compatible pointing device
- NetObjects Fusion 4.0
For Web server (site deployment)
- Cold Fusion Application Server 3.1 or above must be
installed on server
- A Web server that supports ISAP, NSAPI or WSAPI must be installed on the server.
Note: For development, it is recommended that the
designer place NetObjects Fusion, the Allaire Cold Fusion Connector and the Cold
Fusion Application Server on the local design PC. This allows rapid prototyping
without publishing the site to a remote server. This requires a separate license
of Cold Fusion Application Server. Microsoft’s IIS Web server is provided
with Windows NT 4.0 and Personal Web server is provided with Windows 98. Cold
Fusion may be installed on either of these Web servers.
Installation
To install the Allaire Cold Fusion Connector, follow these steps.
- Run setupex.exe.
- The setup program will prompt you for the location of the NetObjects Fusion components directory. Indicate the location where you installed NetObjects Fusion 4.0 and append Components\. This directory will most likely be:
C:\NetObjects 4.0\Components\
or
C:\Program Files\NetObjects 4.0\Components\
ODBC
The Allaire Cold Fusion Connector may access ODBC data sources available to your local machine. If you are developing locally and publishing remotely, you should create a system data source on your local PC with the same name as the target data source on your server. See the tutorial provided with NetObjects 4.0 for step-by-step instructions for creating a data source.
About the User Guide
The Allaire Cold Fusion Connector User Guide describes how the Allaire Cold Fusion Connector works, introduces the basic functionality, and explains advanced features. The User Guide includes:
- A brief overview of the Allaire Cold Fusion
Connector
- The framework used for integrating NetObjects Fusion
and Cold Fusion
- Instructions on how to locally stage your site so
that you can prototype your dynamic site on your local system without
publishing to your server
- Basic Cold Fusion concepts needed to use the Allaire
Cold Fusion Connector
- A Short Component Reference that describes basic functionallity for each component. Full component reference is provided in the online help function of each component.
New To Web application development?
The Allaire Cold Fusion Connector User Guide and the documentation for the Cold Fusion Application Server includes all you need to learn about Web application programming. But, if you also want access to experienced Cold Fusion developers, you can participate in the Allaire Online Forums where you can post messages and read replies on all subjects relating to CF. Check out the forums at http://www.allaire.com.
Experienced NetObjects Fusion User?
Take a look through the components so that you understand what you can do with the Allaire Cold Fusion Connector. Take a look at the Component Reference Sections on CFQuery and some of the components that let you manage the output of your query, such as the CFSelect and Text components. As you work, refer to the Component Reference to see what other capabilities The Allaire Cold Fusion Connector brings to your site.
Want to Know more about Cold Fusion?
The Cold Fusion User Guide is a good place to start learning about how to build a Cold Fusion Web application. If you want a quick summary of features, take a look at Getting Started with Cold Fusion, which also includes a quick tutorial on creating a first Cold Fusion application.
Allaire Cold Fusion Connector Documentation
HTML versions of the Allaire Cold Fusion Connector documentation can be found by dropping a Browser Based Help component onto the current page in NetObjects Fusion 4.0.
Cold Fusion Documentation
HTML versions of Cold Fusion3.1 documentation can be viewed online:
Getting Started with Cold Fusion
http://your_server/cfdocs/getting started/index.htm
Cold Fusion User Guide
http://your_server/cfdocs/user/index.htm
Cold Fusion Language Reference
http://your_server/cfdocs/lang/index.htm
The HTML Reference Library
http://your_server/cfdocs/html reference/index.htm
Acrobat Files
Acrobat versions of all Cold Fusion documentation can be downloaded from the Allaire Web site, http://www.allaire.com
Learning More About Cold Fusion
In addition to Cold Fusion documentation, a number of resources are available for Cold Fusion Developers
Allaire Developer Services
Resource |
Description |
Allaire Web Site
Www.allaire.com |
General information about Allaire products
and services |
Technical Support
Www.allaire.com/support/ |
Allaire offers a wide range of professional
support programs. This page explains all of the available
options. |
Professional Education
Www.allaire.com/education/ |
Information about classes, on-site training,
and online courses offered by Allaire. |
Developer Community
Www.allaire.com/developers/ |
All of the resources you need to stay on the
cutting edge of Cold Fusion development, including online discussion
groups, Knowledge Base, Component Exchange, Resource Library,
technical papers and more. |
Allaire Alliance
Www.allaire.com/partners/
|
The growing network of solution providers,
application developers, resellers, and hosting services creating
solutions with CF. |
Contacting Allaire
Corporate headquarters
Allaire Corporation
One Alewife Center
Cambridge, MA 02140
Tel 617.761.2000 voice
Fax 617.761.2001 fax
Technical Support
Toll Free 888.939.2545
Tel 617.761.2100
Sales
Toll Free 888.939.2545
Tel 617.761.2100
Fax 617.761.2101
Email: sales@allaire.com
Web: http://www.allaire.com/store/
Getting Started
The Allaire Cold Fusion Connector connectivity kit joins the visual development environment of NetObjects Fusion 4.0 with some of the web application development capabilities of Cold Fusion Application Server. 3.1 to create dynamic, visually pleasing web sites.
For Current NetObjects Designers
The kit allows the inclusion of dynamically generated from within NetObjects 4.0. Dynamic objects, such as select lists generated from data in an ODBC database, can now be incorporated into existing sites. These objects are visually consistent with other NetObjects Page view objects. They may be drag-and-dropped, resized or copied using the same methods used to create and modify standard objects.
For Current Cold Fusion Developers
The kit provides a visual RAD environment that allows the rapid creation of sites within NetObjects Fusion. Templates (CFML pages) may be rapidly prototyped and modified by simply filling in Cold Fusion variables for the most commonly used Cold Fusion tags. These Cold Fusion tags may then be placed anywhere on the page using a simple drag-and-drop interface.
For web developers creating data-driven sites, the kit provides a complete visual project environment. All project attributes, from images and styles to database commands, are stored in one file. Additionally, the graphical site representation of NetObjects Fusion facilitates routine housekeeping takes as well as logical application documentation..
In short, the Allaire Cold Fusion Connector allows designers to create data-driven sites using a purely visual interface.
Integration Framework
The Allaire Cold Fusion Connector allows designers to store all CFML tags within their NetObjects site. Designers may use all the graphic functions of NetObjects Fusion to create and maintain a distinctive site appearance. All of the accessible CFML variables are stored in the site (*.nod) file.
Components are groups into two classifications:
- Non-visual components
– These components
perform database and programmatic activities (queries, inserts, updates and
mail) and have no direct visual output. When the server processes the Cold
Fusion page, it executes these components prior to the visual
components.
– These components
display dynamic variables. These variables may include information retrieved
from an ODBC database.
Additionally, components may be grouped as:
- Plain Cold Fusion Tag Components -- These Components generate the CFML for a single Cold Fusion tag. The designer may read more detail about the tag in the Cold Fusion Documentation. An example of such a component is the CFInsert component.
- Hybrid CFML HTML Components – These components use a combination of HTML and CFML to generate a visual HTML element. An example of such a component is the Dynamic List component which mixes standard HTML list tags with the Cold Fusion CFOUTPUT tag.
Component Usage
The page component toolbars used to access the Allaire Cold Fusion Connector are displayed from the Page view by selecting the View menu, then selecting the View Toolbars option, and then selecting the Components option. There are two Cold Fusion toolbars.
The Data Entry Wizard is accessed from the Site view by selecting the File menu, and then selecting the Run Site Component option.
The Cold Fusion Publish component is selected from the Publish view by clicking on the Settings button, then selecting the Components tab, and then selecting the check box for the Cold Fusion Publish component.
IMPORTANT: The Cold Fusion Publish component MUST be
selected prior to publishing or staging your site. If the Cold Fusion Publish
component is not selected, errors will occur when you view your Cold Fusion
pages from a browser.
It is sometimes necessary to specify the order of execution for non-visual components. This typically occurs when the designer wishes to insert or update a record and then query against that record. When the order to execution is required, use the ordering function of the Nonvisual Component Manager.
For more detailed information about using NetObjects 4.0 components, refer to the NetObjects User Guide.
Example
The following example demonstrates how visual and nonvisual components interact on a page. To create a formatted table displaying a list of distributors contained in a database requires:
- Retrieving a list of all distributors held in the
distributors table in a database.
- Displaying the distributors in a dynamically generated table.
To accomplish this, the designer adds a Nonvisual Component Manager to the Layout area of a NetObjects Fusion page. The icon for the Nonvisual Component Manager component is displayed in the Page view and may be placed anywhere in the Layout area. When the site is staged or published, this object will not be displayed. The Nonvisual Component Manager "holds" the nonvisual page components. The designer then adds a CFQuery component to the manager and builds a query that returns a list of distributors from the distributors table. The SQL Wizard may be used to generate the query.
Next, the designer creates a dynamic HTML table by placing a Dynamic Table component in the Layout area of the same page. The table will display the distributors from the previously created query. The designer then displays the Dynamic Table component’s dialog and selects the name of the query from a list of available queries. Next, the designer selects the fields to display in the table. For instance, using the Sports Jaques data source provided with the tutorial, the designer could elect to display the distributor’s name, city and state.
Once the Dynamic Table component’s dialog has been closed, the designer may format the table and individual cells using NetObject’s formatting tools.
When the site is ready to be staged, the designer goes to the Publish view and selects the Setup button. Next, the designer selects the Components tab and selects the checkbox for the Cold Fusion Publish component.
The site is then published to a web server running Cold Fusion as described in the Staging section of this document.
Cold Fusion Concepts
This brief section does not purport to be an introduction the Cold Fusion Markup Language. Instead, it covers one basic concept that useful in working with the Allaire Cold Fusion Connector. For full documentation, refer to the Cold Fusion User Guide and the reference material listed in the "About the User Guide" section of this document.
It is possible to perform simple tasks in Cold Fusion using the Allaire Cold Fusion Connector without explicitly referring to variables. For instance, the Data Entry Wizard will automatically create a form and CFInput tag without the user having to manually reference the form fields. As the designer starts to perform more difficult tasks, he will need to use variables. For instance, the designer may run the Data Entry Wizard to create a guest book and then wish to display a personalized thank you message using the visitor’s first name.
To do this, the designer will need to refer to the form field variable named something like FirstName (the actual name will depend on the form field’s name). To display the value of the a form field variable "firstName", the designer would place a Dynamic Text component on the form’s results page. Next, the designer would select Form for the Variable type and type firstName for the Variable Name attribute.
Variables may be explicitly referenced by using the following notation:
#VariableType.VariableName#
The designer may wish to explicitly refer to a variable in this way for a number of reasons. For instance, form variables are often used in the Where clause of a SQL query. To use a variable in the Where clause of a query, use the SQL Wizard to generate the SQL statement you wish to use and then append a Where clause that will select records based on the user’s input. For instance:
WHERE Distributors.DistributorName = ‘#Form.DistributorName#’
Staging
NetObjects Fusion provides a Preview function that generates the page/site, launches a default browser, and displays the generated HTML. This is performed from the Page view by clicking on the Preview button. In general, NetObjects Fusion designers use this feature frequently in the iterative process of creating the page/site. However, as the browser reads from a file, not a server, Cold Fusion pages are not processed and are displayed as regular, unprocessed HTML. Dynamic elements will not be displayed in the browser’s file mode. This affects only Cold Fusion pages and will not have any impact on regular HTML pages.
If the designer wishes to have Preview functionality on a local machine and to display dynamic pages, as well as standard pages, the designer must stage to a local PC and view a local versions of the dynamic site from a Web server. There are several Web servers available that run on local PCs under either Windows 95, Windows 98 or Windows NT. Microsoft’s Personal Web Server ships with Windows 98 and Microsoft’s IIS ships with Windows NT.
Staging Setup
It is highly recommended that the designer configure the computer to allow staging. The steps are outlined below.
- Install Web server software on your local PC.
Microsoft’s Personal or IIS are excellent for this purpose and
installs under either Windows 98 and Windows NT respectively.
- Install a copy of Allaire’s Cold Fusion
Application Server 3.1 on the PC where NetObjects Fusion resides.
- Instead of using the Preview function in NetObjects
Fusion, go to the Publish view. Select settings. A dialog box will appear.
Select Local and indicate the \cfdocs\ directory on your Web server’s
document directory. For instance, Microsoft’s Personal Web server uses
the following as the \cfdocs\ directory: c:\webshare\wwwroot\cfdocs\. Create
a working directory under this location and use it for staging. For example,
use \stage\ .
- Stage the site. NetObjects will automatically launch
your browser in file mode. Type the URL that corresponds to the file
location on your local drive. For instance, using the previous example, the
URL would be http://127.0.0.1/cfdocs/stage/
- Bookmark this location for future access.
Note: File locations and URLs will vary depending
upon server software. Refer to your server documentation.
Components
The Allaire Cold Fusion Connector components are grouped into two toolbars.
- Cold Fusion Forms: Cold Fusion Form tags and dynamic
form elements
- Cold Fusion: Non-form elements.
The Cold Fusion toolbar contains the Nonvisual Component Manager. This component is used to manage components that do not have a visual representation in NetObjects. These components correspond to the Cold Fusion tags bearing the same names.
Cold Fusion Form Toolbar
Component |
Description |
Dynamic Text Field |
Provides a text field based on a query. |
Dynamic Text Area |
Provides a text area based on a query. |
File Form Field |
Provides a file input form field. |
CFSelect |
Provides a dynamically generated dropdown or list box based on a query. Based on CFSelect tag. |
CFSlider |
Provides a slider control based on the CFSlider tag. |
CFInput Text |
An enhanced text field. Based on the CFInput tag. |
Cold Fusion Toolbar
Component |
Description |
Nonvisual Component Manager |
Component used to manage nonvisual components. |
Browser Based Help |
Displays help. |
Verity Site Search |
A Verity based site search utility for your NetObjects site. |
Dynamic Text |
Displays dynamic text based on a query or other variable. |
Dynamic List |
Displays dynamic HTML list based on a query or other variable. |
Dynamic Table |
Displays dynamic HTML table based on a query or other variable. |
Nonvisual Components
Nonvisual components correspond to the Cold Fusion tag bearing the same name.
Component |
Description |
CFQuery |
Executes a SQL statement. |
CFInsert |
Inserts a record into an ODBC data source based on a form. |
CFUpdate |
Updates a record in an ODBC data source based on a form. |
CFIndex |
Corresponds to the CFIndex tag. |
CFSearch |
Corresponds to the CFSearch tag. |
CFMail |
Sends e-mail based on a form or query. |
CFFile |
Performs file operations on the server. |
CFLocation |
Redirects user to another page. |
CFApplication |
Used for session state and client state management. |
Common Errors
The most common errors involve either misspelling of variables or data type mismatches. These errors are very common in the CFQuery component. The following gives examples of common Cold Fusion errors.
Reading From File in Browser
Error
The browser does not display dynamic data. Instead it displays many words with pound signs (#) around them like: #ClientName#.
Solution
Cold Fusion is not processing the page.
First check to see if your browser is in HTTP mode by looking at the URL line in your browser. If the URL begins with a drive name like C:, enter the URL to the file.
If the problem persists, verify the page has a .cfm extension. Pages with other extensions (i.e. .html) are not processed by Cold Fusion. Rename the page extension in NetObjects and republish.
If the problem still persists and neither of the first two solutions apply, verify that the directory that you published to has the Cold Fusion service running.
Forgetting to use the Cold Fusion Publish Component
Error
Dynamic tables do not show query results and have extra characters. Form fields created using the components do not display.
Solution
Select the Cold Fusion Publish component before publishing.
Misspelled field in CF Query
Error message
ODBC Error Code = 07001 (wrong number of parameters) [Microsoft] [ODBC Microsoft Access 97 driver] Too few parameters. Expected 1.
Hint: The cause of this error is usually that your
query contains a reference to field that does not exist. You should verify that
the fields included in your query exists and that you have spelled their names
correctly.
SQL = "Select Fooda FROM Clients GROUP BY Food ORDER BY Food" Data Source = "Coffee Valley"
Solution
The filed name Food has been misspelled in the SQL statement in the CFQuery component (Fooda). Correct the spelling.
Mismatched data type in the SQL Where Clause
Error message
ODBC Error Code = 37000 (Syntax error or access violation) [Microsoft] [ODBC Microsoft Access 97 Driver] Syntax error (missing operator) in query expression on ‘food-Full kitchen’ SQL = "Select" FROM Clients WHERE food=Full Kitchen ORDER BY Clientname" Data Source = "Coffee Valley" Solution
The data type for the field Food is text. Therefore single quotations are required in the Where clause so the data types match. Include single quotes (‘) around #form.food#’.
Note: Full Kitchen is the processed value for
#form.food#. The Where clause should be: Food =
‘#form.food#’.
Misspelled Query Name in an Output Component
Error message
Invalid QUERY specified in CFOUTPUT tag.
The query named ‘GETFOODS’ has not yet executed. Please define this query in your template file above the places where you use it.
Solution
The correct Query name was GetFood. Correct the spelling in the output component.
Misspelled Field Name in an Output Component
Error message
Error resolving parameter FOODASDF
Cold Fusion was unable to determine the value of the parameter. This problem is very likely due to the fact that either:
- You have misspelled the parameter name, or
- You have not specified a QUERY attribute for a CFOUTPUT, CFMAIL, or CFTABLE tag.
Solution
There is no field named Foodasdf. Correct the spelling.
Copyright Notice
© Allaire Corporation. Portions © Fundere, Inc. All rights reserved.
This manual, as well as the software described in it, is furnished under license and may be used or copied only in accordance with the terms of such license. The content of this manual is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Allaire Corporation. Allaire Corporation assumes no responsibility or liability for any errors or inaccuracies that may appear in this book.
Except as permitted by such license, no part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written permission of Allaire Corporation.
Cold Fusion is a registered trademark and Allaire, Allaire Cold Fusion Connector, HomeSite, the Cold Fusion logo and the Allaire logo are trademarks of Allaire Corporation in the USA and other countries. NetObjects Fusion and NetObjects Fusion logo are trademarks of NetObjects, Inc. Microsoft, Windows, Windows NY, Widows 95, Microsoft Access, and FoxPro and registered trademarks of Microsoft Corporation. All other products or name brands are the trademarks of their respective holders. Solaris is a trademark of Sun Microsystems Inc. UNIX is a trademark of Novell Inc. PostScript is a trademark of Adobe Systems Inc.
|