User Guide

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:

  1. Live database connectivity: you may now view the results of your query as you work within NetObjects.
  2. Query Builder: the components include a query builder that assists you in the creation of queries.
  3. Record viewing: you may now view the results that will be placed in visual components from the components themselves.
  4. Default and HTML Edit modes for most components: you may now view and manually edit the code generated by the components.
  5. Expression Builder: hundreds of Cold Fusion functions are now just a click away.
  6. Table Tool: You may now use the standard NetObjects table editing capabilities to format your tables.
  7. Wizards: Wizards have been included to perform common tasks such as the creation of a data entry form.
  8. Help: Web based online help for each component.

 

Requirements

For the Allaire Cold Fusion Connector (site development):

  1. PC compatible with Pentium processor (Pentium II recommended).
  2. Microsoft Windows NT 4.0 or Windows 95 or Windows 98
  3. ODBC
  4. 12 MB disk space
  5. 48 MB RAM required for Windows 95 or 98 (64 MB recommended)
  6. 64 MB RAM required for Windows NT 4.0 (128 recommended)
  7. CD-ROM drive
  8. Mouse or compatible pointing device
  9. NetObjects Fusion 4.0

For Web server (site deployment)

  1. Cold Fusion Application Server 3.1 or above must be installed on server
  2. 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.

  1. Run setupex.exe.
  2. 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.
  • 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.

  1. 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.
  2. Install a copy of Allaire’s Cold Fusion Application Server 3.1 on the PC where NetObjects Fusion resides.
  3. 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\ .
  4. 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/
  5. 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:

  1. You have misspelled the parameter name, or
  2. 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.

 

BuiltByNOF