Using ColdFusion Studio

Add to my manuals
180 Pages

advertisement

Using ColdFusion Studio | Manualzz

Using ColdFusion

Studio

ColdFusion Studio 4.0 for Windows

®

NT and Windows 95/98

2

Copyright Notice

Using ColdFusion Studio

© Allaire Corporation. 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.

ColdFusion is a registered trademark and Allaire, HomeSite, the ColdFusion logo and the Allaire logo are trademarks of Allaire Corporation in the USA and other countries.

Microsoft, Windows, Windows NT, Windows 95, Microsoft Access, and FoxPro are 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.

Part number: AA-4USST-RK

Contents

Preface: Welcome to ColdFusion Studio ........................................................1

Product Features .............................................................................................................................. 2

Developer Resources ....................................................................................................................... 3

About ColdFusion Documentation ................................................................................................ 4

ColdFusion Studio .................................................................................................................... 4

ColdFusion manuals ................................................................................................................ 5

Printing ColdFusion Documentation............................................................................................. 5

ColdFusion Server Acrobat files .............................................................................................. 5

ColdFusion Studio Acrobat files.............................................................................................. 6

Documentation Conventions ......................................................................................................... 6

Getting Answers ............................................................................................................................... 6

Contacting Allaire............................................................................................................................. 7

Chapter 1: Setting Up Studio...........................................................................9

Exploring the Studio Workspace................................................................................................... 10

Customizing the workspace .................................................................................................. 10

Using shortcut menus ............................................................................................................ 11

Using shortcut keys ................................................................................................................ 11

The Resources window .......................................................................................................... 11

Working in Edit, Browse, and Design modes ....................................................................... 12

The Results window ............................................................................................................... 12

Toolbars................................................................................................................................... 12

Getting the Most from Studio’s Online Help System .................................................................. 14

Extending the help system..................................................................................................... 15

Creating help files for custom tag editors............................................................................. 15

Tag help options ..................................................................................................................... 16

Managing Local Files ..................................................................................................................... 17

Opening files ........................................................................................................................... 17

Saving files............................................................................................................................... 18

Downloading Web pages............................................................................................................... 18

Managing Remote Files ................................................................................................................. 19

Connecting to an FTP server ................................................................................................. 19

Connecting to Remote Development Services .................................................................... 20

Working with remote files...................................................................................................... 21

iv

Using ColdFusion Studio

Configuring Browsers .....................................................................................................................22

Browser installation options ..................................................................................................22

Using server-based page processing .....................................................................................22

Setting server mappings .........................................................................................................23

Chapter 2: Creating Pages .............................................................................25

Building Pages.................................................................................................................................26

Entering tags, text, and other content ...................................................................................26

Commenting code...................................................................................................................26

Color-coding tags ....................................................................................................................26

Printing code and browser pages...........................................................................................27

Document Basics ............................................................................................................................27

Opening a new document ......................................................................................................27

Inserting a file into a document .............................................................................................27

Converting a text file ...............................................................................................................27

Copying text from a browser ..................................................................................................28

Converting Microsoft Office content.....................................................................................28

Selecting code and text blocks ...............................................................................................28

Setting colors for page elements ............................................................................................28

Setting Tag Help Options ...............................................................................................................29

Tag Insight ...............................................................................................................................29

Tag Completion .......................................................................................................................30

Tag validation ..........................................................................................................................30

Special characters....................................................................................................................30

Getting Started with Templates and Wizards...............................................................................30

Templates.................................................................................................................................31

HTML wizards .........................................................................................................................31

DHTML wizards ......................................................................................................................31

CFML Wizards .........................................................................................................................31

Working in Tag Chooser .................................................................................................................32

Inserting Tags from the QuickBar .................................................................................................32

Adding Media Content ...................................................................................................................34

Image files ................................................................................................................................34

OpenPix....................................................................................................................................35

Video.........................................................................................................................................35

Sound .......................................................................................................................................35

RealNetworks support ............................................................................................................36

Using SMIL tags.......................................................................................................................36

Saving Code Blocks as Snippets.....................................................................................................36

Sharing snippets ......................................................................................................................37

Adding snippet shortcut keys .................................................................................................37

Saving Keystrokes with Code Templates ......................................................................................37

Building CFML Expressions ...........................................................................................................38

Contents

Chapter 3: Accessing ColdFusion Data Sources...........................................39

Introduction to Database Tools.....................................................................................................40

Registering Data Sources................................................................................................................40

Connecting to Data Sources ..........................................................................................................40

Opening an ODBC Data Source.....................................................................................................41

Using Query Builder .......................................................................................................................41

Building a SELECT Query...............................................................................................................42

Inserting SQL into a Page ...............................................................................................................43

Running and Editing Queries.........................................................................................................44

Running a query ......................................................................................................................44

Editing Queries ........................................................................................................................44

Chapter 4: Editing Pages ...............................................................................45

Setting Editing Options ..................................................................................................................46

Keyboard Shortcuts ........................................................................................................................46

Editing Tools ...................................................................................................................................46

Tag Editors.......................................................................................................................................47

Tag Tree and Tag Inspector ...........................................................................................................47

Tag Tree....................................................................................................................................47

Tag Inspector ...........................................................................................................................48

Visual Editing in Design Mode.......................................................................................................49

Preserving Code Formats with CodeSweeper ..............................................................................50

Configuring CodeSweeper......................................................................................................50

Formatting Pages with Cascading Style Sheets ............................................................................52

Using the Style Editor..............................................................................................................52

Chapter 5: Debugging CFML Applications from Studio..............................55

Interactive Debugger Overview .....................................................................................................56

Configuring RDS from the Debugger ............................................................................................56

Creating RDS Mappings .................................................................................................................57

File mapping examples ...........................................................................................................57

Specifying Server Mappings...........................................................................................................59

Running the Interactive Debugger ................................................................................................60

Debug windows .......................................................................................................................61

Stepping through code............................................................................................................62

Evaluating expressions and setting watches.........................................................................62

Debugging across multiple pages ..........................................................................................63

Debugger Shortcut Keys .................................................................................................................64

Chapter 6: Testing and Maintaining Web Sites ...........................................65

Working in the Results Window.....................................................................................................66

Saving results ...........................................................................................................................66

Using Find and Replace..................................................................................................................66

Search commands...................................................................................................................66

Searching with Regular Expressions......................................................................................68

Checking Spelling ...........................................................................................................................72

v

vi

Using ColdFusion Studio

Validating Code...............................................................................................................................73

Verifying Page Links........................................................................................................................73

Using Site View to Check Page Links.............................................................................................75

Testing Page Download Times ......................................................................................................75

Chapter 7: Creating Projects for Site Management.....................................77

Why Use Projects?...........................................................................................................................78

The Projects Tab .............................................................................................................................78

Managing Files in a Project ............................................................................................................78

Verifying Links in a Project.............................................................................................................80

Uploading a Project ........................................................................................................................80

Chapter 8: Adding Source Control for Development Projects ...................81

Why Use Source Control?...............................................................................................................82

Implementing a Source Control System .......................................................................................82

Local and remote source control ...........................................................................................83

Standard source control commands .....................................................................................83

Choosing a Source Control Provider .............................................................................................83

Creating a Studio Project for Source Control ...............................................................................83

Establishing a working directory............................................................................................84

Adding a Studio project to source control.............................................................................84

Setting up server-side source control ....................................................................................85

Managing Files in Source Control .................................................................................................86

Check-in options .....................................................................................................................86

Command options ..................................................................................................................86

Adding files and subdirectories..............................................................................................87

Synchronizing files ..................................................................................................................87

Chapter 9: Customizing the Development Environment............................89

The Visual Tools Markup Language (VTML) ................................................................................90

Customizing Tag Chooser and Expression Builder......................................................................90

Customization objective.........................................................................................................90

Dialog Definition Files....................................................................................................................91

Category tag .............................................................................................................................92

Element tag ..............................................................................................................................92

Creating Tag Definitions ................................................................................................................93

Creating a tag definition file ...................................................................................................94

Defining attributes ..................................................................................................................94

Defining attribute categories..................................................................................................97

Building Tag Editors .......................................................................................................................97

Defining controls.....................................................................................................................98

Populating dialogs with tag data..........................................................................................101

Generating a tag ....................................................................................................................102

Variables passed to the layout template..............................................................................102

Special variables ....................................................................................................................103

Adding Tag Help ...........................................................................................................................104

Contents

Providing help from an external file ....................................................................................105

VTML Container/Control Reference...........................................................................................105

TabDialog container .............................................................................................................105

TabPage container ................................................................................................................106

Panel container......................................................................................................................107

Label control ..........................................................................................................................109

TextBox control .....................................................................................................................110

DropDown control ................................................................................................................111

FontPicker control.................................................................................................................112

ColorPicker control ...............................................................................................................113

CheckBox control ..................................................................................................................114

RadioGroup control ..............................................................................................................115

TextArea control ....................................................................................................................116

SQLTextArea control .............................................................................................................117

FileBrowser control ...............................................................................................................119

Image control.........................................................................................................................121

ActiveX control ......................................................................................................................122

Building Custom Wizards.............................................................................................................122

Saving wizard files .................................................................................................................123

Creating Wizard Definition Pages ...............................................................................................123

VTML for Wizards tag summary...........................................................................................123

VTML for Wizards tag reference...........................................................................................123

Dynamic expressions in tags ................................................................................................126

Bound controls ......................................................................................................................126

Wizard definition page example ..........................................................................................127

Creating Wizard Output Templates ............................................................................................129

Using WIZML.........................................................................................................................129

Parameters .............................................................................................................................129

Expressions and functions....................................................................................................129

WIZ Tags.................................................................................................................................131

Special considerations ..........................................................................................................131

WIZML reference...................................................................................................................131

Wizard Definition Page Library ...................................................................................................133

SelectNameAndLocation ......................................................................................................133

SelectDataSource ..................................................................................................................134

SelectTables ...........................................................................................................................135

SelectTable.............................................................................................................................136

SelectTableJoins ....................................................................................................................137

SelectFields ............................................................................................................................138

SelectField..............................................................................................................................139

Chapter 10: Scripting The Visual Tools Object Model ...............................141

Writing and Executing Scripts .....................................................................................................142

Writing Scripts .......................................................................................................................142

Executing Scripts ...................................................................................................................143

Application Object ........................................................................................................................143

Application (TAllaireClientApp) Object ..............................................................................143

DocumentCache Object ...............................................................................................................153

vii

viii

Using ColdFusion Studio

ActiveDocument Object ...............................................................................................................154

ActiveScripting examples .............................................................................................................158

JavaScript ...............................................................................................................................158

VBScript..................................................................................................................................160

Third-Party Add-Ins......................................................................................................................163

Appendix: Online Help Search Tips ........................................................... 165

Search Case Sensitivity .................................................................................................................166

Multiple Word Searches ...............................................................................................................166

Wildcards.......................................................................................................................................166

Operators .......................................................................................................................................167

NEAR operator.......................................................................................................................167

NEAR/N operator ..................................................................................................................167

OR operator............................................................................................................................168

PARAGRAPH operator ..........................................................................................................168

PHRASE operator ..................................................................................................................168

SENTENCE operator .............................................................................................................169

STARTS operator ...................................................................................................................169

SUBSTRING operator............................................................................................................169

WILDCARD operator.............................................................................................................169

WORD operator .....................................................................................................................170

Modifiers........................................................................................................................................171

CASE modifier........................................................................................................................171

MANY modifier......................................................................................................................171

NOT modifier.........................................................................................................................172

ORDER modifier ....................................................................................................................172

P

R E F A C E

Welcome to ColdFusion Studio

Preface

ColdFusion Studio is the integrated development environment (IDE) for ColdFusion.

It is a powerful and flexible tool for building, testing, and deploying dynamic Web content.

Studio is also an easy to use editor with support for HTML, DHTML, XML, VTML,

HDML, SMIL, and a variety of scripting languages.

Contents

Product Features ................................................................................................ 2

Developer Resources.......................................................................................... 3

About ColdFusion Documentation .................................................................. 4

Printing ColdFusion Documentation............................................................... 5

Documentation Conventions ........................................................................... 6

Getting Answers ................................................................................................. 6

Contacting Allaire............................................................................................... 7

2

Using ColdFusion Studio

Product Features

Studio has a great many uses, including:

As general-purpose editor for text files.

For HTML pages.

For scripting.

For developing static and dynamic Web sites.

Web Development Features

Editing — Access local and remote files, insert and convert files, set bookmarks, easy tag selection, automatically convert special characters.

Page Design — Visually layout page elements for quick edits and rapid prototyping. Convert content, such as lists and tables, from Microsoft Word and

Excel into equivalent HTML formatting.

CodeSweepers — Enforce code formatting with customizable rules.

Browsers — Preview pages in multiple browsers, automatic detection of installed browsers.

Proofing and Testing tools — Maintain site content with search and replace, spell checking, code validation, and link verification.

Enhanced Projects — Create, deploy, and manage local and remote Web sites.

Tag Inspector — Edit code in a customizable property sheet interface.

Tag Tree — View and navigate the current document's tag hierarchy.

Site View View, edit, and test links on the current page and in linked pages.

Style Editor — Easily create, edit, preview, and link Cascading Style Sheets.

Code templates — Quickly insert common text blocks and expand abbreviations.

Snippets — Save code blocks and content for reuse.

Templates and Wizards — Quickly create basic pages, tables, frames, JavaScript and DHTML elements, and synchronized RealAudio content.

Image preview — View Web images and their properties.

Application Development Features

SQL support — Work with local and remote data sources, run Query Builder to quickly write SQL statements and insert them in your application.

Interactive Debugging — Full-featured debugger for ColdFusion application development.

Code Validation — Configurable for multiple versions of HTML, CFML, SMIL, and browser-specific tags.

Preface

Color-coding — Customizable for HTML, CFML, and a wide range of scripting languages.

Version Source Control — Add projects to a source control system for team development.

User macros — Automate tasks by scripting the Visual Tools Object Model.

3

Developer Resources

Allaire Corporation is committed to setting the standard for customer support in developer education, technical support, and professional services. Our Web site is designed to give you quick access to the entire range of online resources.

Allaire Developer Services

Resource

Allaire Web site www.allaire.com

Technical Support www.allaire.com/support

Professional Education www.allaire.com/education

Developer Community www.allaire.com/developer

Allaire Alliance www.allaire.com/partners

Description

General information about Allaire products and services.

Allaire offers a wide range of professional support programs. This page explains all of the available options.

Information about classes, on-site training, and online courses offered by Allaire.

All of the resources you need to stay on the cutting edge of ColdFusion development, including online discussion groups, Knowledge

Base, Component Exchange, Resource Library, technical papers and more.

The growing network of solution providers, application developers, resellers, and hosting services creating solutions with ColdFusion.

4

Using ColdFusion Studio

About ColdFusion Documentation

ColdFusion documentation is designed to provide support for all components of the

ColdFusion development system. Both the print and online versions are organized to allow you to quickly locate the information you need. ColdFusion online documentation is provided in both HTML and Acrobat file formats.

ColdFusion Studio

Printed documentation

Getting Started with ColdFusion

Administering ColdFusion Server

Developing Web Applications with ColdFusion

CFML Language Reference

Online documentation

ColdFusion Studio contains a wide range of online assistance, including a complete collection of ColdFusion documentation. To view Studio online documentation, click the Help resource tab. You’ll see an expandable list of documents about ColdFusion

Studio, as well as a number of other areas that relate to Web programming:

Studio online documentation is searchable and individual pages can be bookmarked.

Preface

ColdFusion manuals

The core ColdFusion documentation set consists of the following titles.

Getting Started with ColdFusion

Covers system requirements and basic installation, describes ColdFusion development system components, and introduces the ColdFusion Markup Language

(CFML). Start here to learn how ColdFusion works, how to install ColdFusion server, and how to create your first ColdFusion application.

Administering ColdFusion Server

Describes configuration options for maximizing performance, managing data sources, setting security levels, and a range of development and site management tasks. If you are administering a ColdFusion site, you’ll need this book to help plan and implement

ColdFusion security, load balancing, and for details about tuning the ColdFusion application server.

Developing Web Applications with ColdFusion

Presents the fundamentals of ColdFusion application development and deployment, including an overview of CFML elements such as functions, expressions, arrays, scripting, and XML data exchange. Also includes detailed information about

ColdFusion data sources, user interfaces, and Web technologies.

CFML Language Reference

Provides the complete syntax, with example code, of all CFML tags and functions.

Using ColdFusion Studio

Documents everything you need to know about using ColdFusion Studio, including features like projects, source control integration, as well as the Studio workspace and interface.

ColdFusion Quick Reference Guide

A valuable quick reference to CFML tags, functions, and variables.

Printing ColdFusion Documentation

If you are working with an evaluation version of ColdFusion and would like printed documentation to read, locate the Adobe Acrobat files installed with both ColdFusion

Server and ColdFusion Studio. The Acrobat files offer excellent print output. You can print an entire manual or individual sections.

ColdFusion Server Acrobat files

Locate the ColdFusion Server Acrobat files by opening the following URL on the system hosting ColdFusion Server: http://127.0.0.1/cfdocs/AcrobatDocs/index.

5

6

Using ColdFusion Studio

ColdFusion Studio Acrobat files

ColdFusion Studio Acrobat files are not installed with ColdFusion Studio. They can be found on the product CD. To locate the files, load the product CD and click the browse option to browse the contents of the CD. You’ll find the Acrobat files in a folder called

“Studio Acrobat Files.”

Documentation Conventions

When reading, please be aware of these formatting cues:

Code samples, filenames, and URLs are set in a monospaced font.

Notes and tips are identified by bold type in the margin.

Bulleted lists present options and features.

Numbered steps indicate procedures.

Toolbutton icons are generally shown with procedure steps.

Menu levels are separated by the greater than (>) sign.

Text for you to type in is set in italics.

Getting Answers

One of the best ways to solve particular programming problems is to tap into the vast expertise of the ColdFusion developer community on the Allaire Forums. Other

ColdFusion developers on the forum can help you figure out how to do just about anything with ColdFusion. The search facility can also help you search messages going back 12 months, allowing you to learn how others have solved a problem you may be facing.

The Forums are a great resource for learning ColdFusion, but they’re also a great place to see the ColdFusion developer community in action.

Preface

Contacting Allaire

Corporate headquarters

Allaire Corporation

One Alewife Center

Cambridge, MA 02140

Tel: 617.761.2000

Fax: 617.761.2001

http://www.allaire.com

Technical support

Telephone support is available Monday through Friday 8 A.M. to 8 P.M. Eastern time

(except holidays).

Toll Free: 888.939.2545 (U.S. and Canada)

Tel: 617.761.2100 (outside U.S. and Canada)

Postings to the ColdFusion Support Forum ( http://forums.allaire.com

) can be made any time.

Sales

Toll Free: 888.939.2545

Tel: 617.761.2100

Fax: 617.761.2101

Email: [email protected]

Web: http://www.allaire.com/store

7

C

H A P T E R

1

Setting Up Studio

Chapter 1

This chapter provides you with a tour of Studio and pointers on how to customize the interface for your work style.

We’ll next look at user assistance options to help you quickly and accurately insert, edit, and validate code.

A big part of getting started is establishing access to your files and configuring browsers and we’ll step you through the basics of those tasks.

Contents

Exploring the Studio Workspace ..................................................................... 10

Getting the Most from Studio’s Online Help System ..................................... 14

Managing Local Files ....................................................................................... 17

Downloading Web pages ................................................................................. 18

Managing Remote Files ................................................................................... 19

Configuring Browsers ...................................................................................... 22

10

Using ColdFusion Studio

Exploring the Studio Workspace

Studio offers a highly customizable interface; you can set it up to suit your work style.

Nearly all of the workspace elements are movable, so you can move panes and toolbars and dock them in new locations. The main workspace areas are shown below.

Customizing the workspace

A development tool needs to provide a productive interface for its users, and the best way to do that is to give users the greatest possible flexibility to set up the interface in a way that works for them. Here are some options:

Press F9 or open the View menu to toggle the Resources window display.

Press Ctrl + F12 to toggle the Full Screen view.

To resize the Resources area, drag the side border and the divider between the top and bottom panes.

The Resources window can be moved by right-clicking on any of the Resources tabs and selecting a Dock position.

Right-click in the file list to set file display options.

Drag toolbars to any location or dock them vertically on the workspace borders.

Right-click in any toolbar to set display options and to organize and customize toolbars.

Chapter 1: Setting Up Studio 11

Open the Options > Customize dialog (Shift + F8) to change toolbar layout, keyboard shortcuts, and to add shortcut keys for code snippets.

Open the Options > Settings dialog (F8) to explore a wide range of interface settings and development options.

Using shortcut menus

Studio makes extensive use of Windows shortcut menus, so right-click (or left-click, if your mouse is set up that way) in any area of the interface to open a context-sensitive command menu.

Using shortcut keys

Studio offers a full set of keyboard commands for it’s tools and functions. You can change shortcut key combinations and add new ones by opening the Options >

Customize dialog (Shift + F8) and selecting the Keyboard Shortcuts tab.

A complete list of shortcut keys is included in the ColdFusion Quick Reference Guide. A separate listing of shortcut keys for the debugger is included, as well.

If you want to print the Quick Reference Guide, you will find it in the AcrobatDocs folder below your CFDOCS root. It’s a great resource to keep handy while you are working.

The Resources window

The tabs on this window control display for these Resources:

Local Files — The three panes display the local and network drives, directories, and files. Double-click a file to open it.

Remote Files — Displays directories and files in FTP and RDS servers. rightclick in the top pane to add a server.

DB — View data sources on the selected server, add RDS servers, and open the

Query Builder.

Projects — The three panes display existing projects, their directories and files.

Right-click in the panes to open and create projects and to add projects to your version source control system.

Site View — Displays a graphic representation of links in the current document.

Snippets — Stores code blocks for re-use. Snippets can be shared with other users.

Help — View ColdFusion documentation and other online resources. You can edit existing help files and add new files.

Tag Inspector — The top pane displays the Tag Tree, a customizable view of the document hierarchy. The bottom pane displays the Tag Inspector, which gives you an interactive “property sheets” mode for editing tags.

12

Using ColdFusion Studio

Working in Edit, Browse, and Design modes

Studio offers three document views:

Edit mode — This is the primary work space in Studio, use it to enter and edit tags and content. The vertical editor toolbar controls basic document commands.

Browse mode — Displays the page in the default internal browser. If you set development mappings, the page is processed by the Web server and the ColdFusion server. You can view, but not edit, the current page.

Design mode — Dynamically work with page elements, such as text blocks, tables, forms, and images. Changes are reflected in the HTML code. You can turn it off on the

Design tab of the Settings (F8) dialog.

The Results window

This tabbed interface is the work area for:

Matches from Extended Find and Replace operations

Code validation messages

Link checker list and toolbar

Thumbnails of image files in the current directory

Right-click in the Search, Validation, or Links tab and select Browse to create an HTML document containing the tab contents. You can then save and print the document for review.

Toolbars

Individual interface elements contain their own specialized toolbars. You can arrange the display of these toolbars to create a workspace for just the tasks you need to perform.

Positioning toolbars

Toolbars marked with a (D) in the list below are dockable, that is, you can move them to a new location on the workspace.

To dock a toolbar:

1.

Click and hold on the drag bar – the double lines located at the left end of the toolbar.

2.

Drag the toolbar to the new position.

3.

To place a toolbar on the workspace border, drag it to the edge of the border until the toolbar border changes to thin lines, then release the mouse button.

To return a toolbar to its previous location, double-click on its title bar.

Chapter 1: Setting Up Studio 13

The entire Resources window can be moved by right-clicking on any of the Resource tabs and selecting a Dock position.

Main (D)

Contains standard Windows toolbuttons plus additional buttons to set the workspace display and to run tools. Individual segments are dockable.

QuickBar (D)

Presents the principal interface for inserting HTML, CFML, and scripting code. The

QuickBar is organized by tabs for easy access, but you have complete control of how toolbuttons are arranged on individual tabs and how tabs are displayed.

To set display options and to organize and customize the QuickBar, just right-click on the QuickBar or select from the View menu. Individual tabs are dockable.

Edit

The editor toolbar, located on the vertical strip to the left of the editor pane, controls document navigation, tag validation, and user assistance options such as Tag Insight and Tag Completion.

Browse

Displays above the Browse pane and controls page navigation and access to URLs. It also includes options to display rulers on the page borders and to view the page at common resolutions.

Design

Controls for text formatting and HTML tables and forms.

Debugger (D)

Contains a full set of controls for application debugging. The debugger toolbar displays by default when you first run Studio, but the display can be toggled from the shortcut menu on any toolbar.

Link Verification (D)

This toolbar is enabled when the Links tab is selected on the Results window.

Projects (D)

A small set of project toolbuttons is available next to the Recent Projects listbox at the top of the Projects pane.

14

Using ColdFusion Studio

Help (D)

Controls display, search, and bookmarking options for the Help References.

Tag Inspector (D)

Set the formatting of the attributes list and open the Tag Definition editor from the buttons located to the left of the tag name at the top of the Tag Inspector pane.

Tag Tree (D)

This pane, located above the Tag Inspector, contains buttons to refresh the tree and to open the Outline Profile Editor. The Profile editor lets you specify the display of supported tags in the tree, including tag captions and icons.

Query builder

Use this toolbar to quickly assemble SQL statements, run queries, and manage query code.

Getting the Most from Studio’s Online Help System

Studio’s HTML help files are an extensible resource for learning about Studio’s features and for getting information on all the supported tag sets.

Click the Help tab in the Resources window to view the Help References. Expand the

"books" and double-click on a help document to open it. By default, help documents display in the internal browser window. To change the view, click the Browse help in separate panel button on the Help toolbar.

To use bookmarks:

1.

Right-click on a document title in the Help References list and select Add bookmark.

2.

To bookmark an external HTML file, click the Bookmarks button and select the

Add button in the Help Bookmarks dialog. You can type in the path or URL or paste it in from a browser.

3.

To go to a bookmark, click the drop-down list button next to the Bookmarks button and select from the list. This list also contains an Organize Bookmarks command that opens the Help Bookmarks dialog.

To search online references:

1.

Click the Search button on the Help toolbar to open the search dialog.

2.

The first time you open the search dialog you will be prompted to index the Help

References. We recommend doing this, as it greatly improves search engine performance.

Chapter 1: Setting Up Studio 15

3.

Enter a word or phrase. Click the Search Tips button to read about the sophisticated search operators that you can use.

4.

By default, the search looks for matches in all the Help References, but you can limit the search to one more references by selecting them.

5.

When you click the search button, the search results displays in the Help

References window. Double-click an entry to open it.

The last results list is saved until a new search is run, so you can return to the results list by clicking the Results button on the Help toolbar.

Tip

You can rerun a recent search by selecting from the dropdown list on the search keyword box. Click an entry and then click Search.

Each time Studio loads, it checks the Help References tree for changes and automatically re-indexes the documents if needed.

Search Tips information is contained in the Appendix: Online Help Search Tips. It is also available in VeritySearchTips.htm in the Allaire Support folder in the online Help

References.

Extending the help system

This brings us to one of Studio’s most useful features, especially for team development

– the extensibility of the help system.

You can write custom help files for your own use or to distribute to other HomeSite users. You can download help content and add it to the help system. The only requirement is that the files be in HTML format. Web graphics files (GIF, JPG, PNG) that are included will be viewable in the help browser.

To add HTML files to the Help References:

You have a number of options for expanding the contents of the help system:

Write an HTML help file and save it to a new or existing folder in the Studio

Help sub-directory.

Copy files into the Help sub-directory by switching to the Local tab, selecting the files, then right-clicking and selecting File > Copy To.

Press F5 to refresh the Help tree. The files can now be viewed and searched.

Creating help files for custom tag editors

Using Allaire’s Visual Tools Markup Language (VTML), you can change a tag editor’s interface or create a new editor. You can also add your own help text to editors. See

Chapter 9, “Customizing the Development Environment,” on page 89

for details.

16

Using ColdFusion Studio

Tag help options

You have easy access to user assistance options while writing code.

Using tag help

Tag tips give you a popup display of the syntax for the current tag. Press F2 to open a

Tag Tip and Esc to close it.

Tag Insight lets you select tag attributes as type in code.

See “Setting Tag Help

Options,” in Chapter 2 for details.

Using dialog help

The Tag Chooser contains a help window that displays syntax and usage information for each tag. See

“Working in Tag Chooser,” in Chapter 2

for details.

Using F1 help

Context-sensitive help is currently available for HTML/CFML tags and for CFML functions. Press F1 in the current tag or function to view the help file. You can view the help files either in the editor window or in the Help tab by clicking the "Browse help in separate pane" button on the Help toolbar in the Help References tab.

Using tag editor help

Click the Toggle Embedded Help button in a tag editor to view syntax and usage help.

Chapter 1: Setting Up Studio 17

Managing Local Files

The Local Files tab displays drives, folders, and files accessible from your PC. The right-click menu contains basic file handling commands and you can open Windows

Explorer directly to create folders, run searches, etc.

Opening files

The three pane Local files tab lets you quickly navigate local and network files.

To open local files:

1.

Click the Local Files tab in the Resources window.

2.

Navigate to the drive and directory you want to access.

3.

Double-click on a folder or click on the + sign to expand the view.

4.

Click on a folder to display its files in the bottom pane.

5.

Double-click on a file to open it in the editor.

Select View in the file list shortcut menu to set the display of file headers.

Note

Read-only files are marked with a red dot in the file list. Right-click on the file and select Properties to change a file’s attributes. This is not recommended if you are using a source control application to manage read and write privileges.

You can set the files list to show specific file types. The filter is a global setting for all directories.

To filter the file list:

1.

Right-click in the File list and choose Filter.

2.

Select a file type from the menu.

The file list refreshes to apply the filter.

Tip

Open the Options > Settings (F8) File Settings tab to check the default list of file extensions. You can edit this list as needed. The Web Images option displays Websupported graphic formats (currently, GIF, JPG,PNG).

Importing files from Windows Explorer

You can access files from the Explorer in a couple ways:

Drag a file into Studio’s editor to create a link to the file. This is the same as dragging it from the file list in the Local tab of the Resource window.

Hold Ctrl while dragging the file to open it. If the file is not a recognized text file, a dialog displays which lets you open it in the associated program for that file type.

18

Using ColdFusion Studio

Playing favorites

Studio gives you some handy options for speedy access to files:

Choose which folders and files to open each time Studio loads by setting options on the Startup tab of the Options > Settings dialog.

Add folders from local and network drives to the Favorite Folders list on the file list shortcut menu.

Select a file from the File > Recent Files list.

Saving files

Unsaved changes in a document are indicated by an "X" next to the file name in the

Document tab. Use the File menu commands or the Standard toolbar icons to save and close files. Open the Options > Settings (F8) dialog and select the File Settings tab to specify a format for saved files. The default is PC, but UNIX and Macintosh formats are available. You can set a default file extension on this tab, as well.

When you add links or images to a new file, you are prompted to save the file. This ensures that relative paths to these page elements are resolved correctly.

Downloading Web pages

You can download any HTML page and open it in the editor. These files cannot be saved back to the server. For remote file procedures, see

Managing Remote Files

.

To open a page from a Web site:

1.

Choose File > Open From Web.

2.

Enter the URL for the page or select from your Bookmarks or Favorites list.

3.

If the site is accessed via a proxy server, click Proxy and enter the server name and port number.

4.

You can optionally set a time-out limit for the connection.

5.

Click OK to open the file as an untitled document.

Tip

Use Windows copy and paste commands to select a block of text on a Web page and insert it into a Studio document. Page formatting is not preserved.

Chapter 1: Setting Up Studio 19

Managing Remote Files

Support for remote development is tightly integrated with Studio, eliminating the need for complicated network configurations or additional applications to access remote files. Studio provides two ways to work with remote files:

FTP — Create, open, edit, and save files on a remote server using the File

Transfer Protocol.

RDS — Access files and ColdFusion data sources via HTTP Remote

Development Services.

Connecting to an FTP server

Configure servers in the Remote Files tab. If you are connecting through an Internet

Service Provider (ISP), first obtain the correct server information from the provider.

If your connection is routed through a proxy server, complete the entries on the Proxy tab.

To add an FTP server:

1.

Click the Remote Files Resource tab.

2.

Right-click in the file pane and select Add FTP Server.

3.

Complete the fields in the Configure FTP Server dialog:

Description — The text that you want to display in the server list.

Host Name — The server domain name, such as allaire.com, or an

IP address . Servers that include ftp as part of the domain name require that you enter the complete name, such as ftp.somesite.com

.

Initial Directory — This entry is optional for accounts that default to the root directory of the FTP server, but is required if the account specifies an initial directory.

Relative from server-assigned directory — Check this box to specify whether the initial directory should be set from the server-assigned user directory or from the server root.

User Name — Your login name or "anonymous" for anonymous FTP servers. You will be prompted for a user name at login if this field is left blank.

Password — The password for the account. You will be prompted for a password at login if this field is left blank.

Root URL — Enter the http:// address of the site. This entry allows you to browse files that were opened from the remote server, edited, and saved.

Remote Port — The port used by the FTP server. Use the default 21 unless another is specified by the server administrator or ISP.

20

Using ColdFusion Studio

Request Timeout — Set a value for the amount of time Studio waits for a server connection to complete.

Assume UTC file times — Check this box if you see incorrect date/time information for files on the FTP server. It adjust for servers that use the

Universal Coordinated Time format.

Disable passive mode — Check this box if the server does not use passive connections.

4.

If you use a proxy server connection, click the Proxy tab and enter your user name, the proxy name, and the proxy port number.

5.

Click OK to complete the dialog.

To open a server’s configuration dialog, right-click on a server name in the Remote

Server list and select Properties.

Note

FTP server connection requirements vary greatly. The instructions above work in the majority of cases.

Connecting to Remote Development Services

Remote Development Services (RDS) provides a secure connection to the ColdFusion server environment and is a prerequisite to accessing CF data sources, using serverbased browsing, and running the interactive debugger.

To add an RDS server:

1.

Click the Remote Files tab.

2.

Right-click in the file list and select Add RDS Server.

3.

Complete the Remote Host fields in the Configure RDS Server dialog:

Description — The name that you want to appear in the server list.

Host Name — The server domain name, such as

IP address.

www.allaire.com

or an

Port — The Web server port. Use the default 80 unless another port is specified by the server administrator or ISP.

Use Secure Sockets Layer (SSL) — Allows exchanges between Studio and the server to be encrypted via SSL.

4.

Complete the ColdFusion RDS Security fields:

User Name — Required if the server is password-protected.

Password — Required if the server is password-protected. Open the

ColdFusion Administrator Server > Basic Security page to edit or disable the Studio password.

5.

Check Prompt for Password to enable these entries.

6.

Click OK to complete the dialog.

Chapter 1: Setting Up Studio 21

To open a server’s configuration dialog, right-click on a server name in the Remote

Server list and select Properties.

Working with remote files

Once you've added a remote server connection, it is easy to open that server and work with the files. You can work with remote files just as you do with local ones. When you save files, changes are saved to the remote server.

By default, the File > Open and File > Save dialogs are enabled for remote access. To change to local file access only, check the Use standard file dialogs box in the Settings >

General dialog (F8).

To open files on a remote server:

1.

Click the Remote Files tab.

2.

Double-click on a server name or right-click and choose Connect.

3.

Double-click on drives and directories to locate files.

4.

Double-click on a file to open it in the editor. A remote file is indicated by a green dot next to its name on the document tab at the bottom of the editor window.

To save a file to a remote server:

1.

Choose File > Save As.

2.

Click the Remote tab in the Save As dialog and select a server.

3.

Select the folder in which to save the file.

To create a folder, right-click in the directory list and select New Folder.

4.

Enter a filename and click OK.

22

Using ColdFusion Studio

Configuring Browsers

Studio makes it easy to view HTML documents and to process CFML application pages.

Browser installation options

The setup routine lets you select your basic browser environment:

If Internet Explorer is detected on your system, you are prompted to use it as the internal browser.

If you do not select the Internet Explorer option, a default internal browser is enabled.

The installation routine auto-detects a number of common browsers if they are installed on your system. Click Options > Configure External Browsers to review and edit the list.

If you install a new browser, open the Configure External Browsers dialog to add it to the list.

Note

A new control, developed by the Mozilla open-source community, allows the nextgeneration Netscape/Mozilla browser, codenamed NGLayout/Gecko, to be integrated as Studio’s internal browser. You can select a browser in the Browse tab (F8). To use the new control, you need to download the binaries from the Mozilla server at www.mozilla.org/binaries.html

. Please note that the Mozilla control in still under development and is limited in its functionality and stability.

Using server-based page processing

The default installation of both the internal and external browsers is adequate for simply viewing HTML pages. Most likely though, you will want to create a production environment for your output:

Route Web pages through a Web server

Process CFML in the ColdFusion Application Server

This requires mapping your physical file directories to one or more URLs.

Chapter 1: Setting Up Studio 23

Setting server mappings

Mappings associate physical directories where files are stored with the server that processes the files. These mappings can be to either a local or a remote machine.

To define a server mapping:

1.

Open the Browse tab in the Options > Settings dialog.

2.

By default, the ColdFusion Language Reference examples run from the localhost.

If your ColdFusion documentation is installed on another ColdFusion server, enter its address, for example, http://docserver. When you click the Example button on a Language Reference page, Studio runs the code from that server.

3.

Click the Development Mappings button to open the RDS mappings dialog.

4.

Open the ColdFusion Server dropdown list and select the server to map.

If it is not listed, click Add RDS Server on the list and add it in the Configure RDS

Server dialog. See the Managing Remote Files

section for detailed instructions on completing this dialog.

5.

In the Development Mappings dialog Studio Path field, enter the server name and your root directory path using the RDS prefix.

For example, rds://thatserver/apps/myfolder/. The root directory path is automatically entered in the CF Server Path field.

6.

In the Browser Path field, enter the root URL of the directory, using the http:// prefix.

7.

Click OK to add that mapping.

C

H A P T E R

2

Creating Pages

Chapter 2

This chapter describes how to write simple CFML application pages; it assumes a basic understanding of HTML and Web page creation.

For an overview of CFML development, see Getting Started with ColdFusion and

Chapter 2, "ColdFusion Fundamentals", in Developing Web Applications with

ColdFusion.

The CFML Language Reference contains the complete syntax, with example code, of all CFML tags and functions.

Contents

Building Pages .................................................................................................. 26

Document Basics ............................................................................................. 27

Setting Tag Help Options ................................................................................. 29

Getting Started with Templates and Wizards................................................. 30

Working in Tag Chooser................................................................................... 32

Inserting Tags from the QuickBar ................................................................... 32

Adding Media Content..................................................................................... 34

Saving Code Blocks as Snippets ...................................................................... 36

Saving Keystrokes with Code Templates ........................................................ 37

Building CFML Expressions ............................................................................ 38

26

Using ColdFusion Studio

Building Pages

ColdFusion Studio is designed to support many different development tasks, from writing simple HTML pages to designing, building, testing, and deploying complex dynamic Web sites.

This section describes some basic techniques and offers pointers to features and settings that can help you build ColdFusion pages in the most productive way.

Entering tags, text, and other content

You can use any combination of workspace options to get your work done:

Type directly in the editor, using shortcut keys for coding and formatting. A complete list of shortcut keys is included in the ColdFusion Quick Reference

Guide.

Set Tag Help options to quickly and accurately insert code.

Use templates and wizards for common page elements.

Keep the Tag Chooser (Ctrl +E) open to quickly insert HTML, CFML, HDML,

SMIL, VTML, and custom tags. Built-in syntax and usage help is available for each tag.

Use the QuickBar for tags and drag and drop images and links from the file list.

Use Design mode to quickly create HTML tables and forms and set font and image formatting.

Save and re-use code blocks as Snippets.

Create Code Templates (Ctrl + J) to insert expanded text.

Use the Expression Builder to develop and insert CFML expressions.

Open the Style Editor to design, preview, and link Cascading Style Sheets.

Commenting code

HTML requires that code comments be enclosed in these brackets: <!-- -->.

CFML comments require two additional dashes: <!--- --->.

Color-coding tags

Studio installs with default color-coding schemes for HTML, CFML, VTML, SQL, and a host of scripting languages. This makes it easier to scan complex code. The color schemes are grouped by file extensions.

You can change color schemes and font styles in the Color Coding tab of the Settings dialog (F8).

Chapter 2: Creating Pages 27

Printing code and browser pages

Select File > Print from Edit, Browse, or Design modes to print the code and text of the current document. You can set print options for numbering, page headers, and color.

You have two options for printing a page as it appears in the browser:

If you are using Internet Explorer as the internal browser, right-click on the document in Browse mode and select Print.

Open the document in an external browser (F11) and user that browser’s Print command.

Document Basics

By default, Studio opens a template containing just the code required for a valid HTML document. This default template is stored as

\Wizards\HTML\Default Template.htm

below your Studio root directory. You can edit this file and save it to change its content.

Opening a new document

Click the New button to open the default template. Alternatively, you can select File >

New to open the New Document dialog. Here you can choose a template or a wizard to begin your development work.

Inserting a file into a document

You can insert HTML, CFML, and a number of other file formats into a Studio document.

To insert a file:

1.

Choose File > Insert File.

2.

Open the dropdown list of supported file types to filter file list.

3.

Locate the file and click OK to insert the file contents in the current document.

4.

Use the Editor toolbar or the Selection item on the shortcut menu to format the document as needed.

Converting a text file

Select File > Convert Text File and locate a locate or remote file with a TXT extension.

When you click OK, the file is opened in the editor surrounded by basic HTML tags.

You can then add formatting or link to a style sheet.

28

Using ColdFusion Studio

Copying text from a browser

You can copy text in two ways:

Use Windows copy and paste commands to select a block of text on a Web page and insert it into a Studio document. Page formatting is not preserved.

If Internet Explorer and Studio are both visible on your desktop, hold the Ctrl key while you select a text block in IE and drag it into Studio.

Page formatting is not preserved by either method.

Converting Microsoft Office content

You can convert content such as lists, tables, and worksheet cells into their equivalent

HTML formatting by copying from Microsoft Word and Excel.

To convert Microsoft Word and Excel content:

1.

Select the content in Word or Excel.

2.

Paste the selection into the Design window at the location you want it to appear on the page.

3.

You can edit the new content visually, for example, click on a table border and drag a handle to resize it, or by switching to the editor to work directly in the code.

To explore this feature, you can experiment with inserting different types of content from Office documents and other Windows applications.

Selecting code and text blocks

You can use the mouse and standard Windows keyboard commands to highlight sections of a document or use these shortcuts to quickly select and edit tag blocks:

To select an entire code block, press Shift + Ctrl and double-click in either the start or end tag.

To select just a range of code and text, click at the start of the selection, then press Shift + Ctrl and click at the end of the selection.

Ctrl + double-click to select a tag.

Shift + double-click to select just the contents of the tag.

Setting colors for page elements

While Cascading Style Sheets are rapidly becoming the preferred method to control color in page elements, you can also set color values for tags using Tag Chooser, Tag

Inspector, Tag Insight, or individual tag editors.

Chapter 2: Creating Pages 29

The Color Palette is an easy to use tool for inserting color values. By default, named values are inserted by name. Open the HTML tab of the Settings dialog (F8) to display all colors as hexidecimal values only.

Click the Options button at the bottom of the palette to select a default palette, sort the color display, and edit the palette.

The Edit palette option lets you change colors on the current palette, create a new palette with the color picker, or create one using the Load from GIF feature to capture all the color values from the selected GIF file.

Click the Choose color button on an extended palette to create and insert custom colors.

To replace a color value in a tag:

1.

Highlight the color value you want to change.

2.

Open the Color Palette and click on a replacement color.

Tip

If you need colors beyond those in the default palette, click the Choose color button to create a custom color.

To import Studio 3.0 palettes:

1.

Copy the .pal files to the Studio4\UserData\Palettes folder.

2.

Rename the file with an .hpl extension.

The next time you load Studio, the palette will be in the Options list.

Setting Tag Help Options

ColdFusion offers a range of options to easily access code syntax. These productivity features can be configured on the Tag Help tab of the Options > Settings (F8) dialog.

You can toggle their use on the Editor toolbar or use shortcut keys.

Tag Insight

This tool is especially handy if you type in much of your code. You don’t want to have to type in long attribute strings or remember the syntax for every tag.

To enable Tag Insight:

1.

Open the Tag Help tab of the Settings dialog (F8) and check the Tag Insight box.

2.

Click Settings to set the time delay for the display and to review the tag list.

You can manage the list by adding and deleting tags.

To use Tag Insight:

This interactive feature can be used to write new code and to edit existing code:

30

Using ColdFusion Studio

When you type a start bracket (<), a tag list opens. After you choose a tag, press the Spacebar to open successive dropdown lists from which to select attributes and values.

When you place the cursor to the left of an end bracket (>) and press the

Spacebar, the dropdown attribute list opens.

You can close a list by pressing the Esc key.

If you just want to see the attributes and values, press F2 inside a tag to open a Tag Tip.

Press Esc to close the tip.

Tag Completion

You can have Studio automatically insert the end tag for the start tag that you type.

This feature is most helpful when you are typing HTML and CFML codes and text at the same time rather than editing isolated text and tags.

Tag Help tab of the Settings dialog box (F8) lets you set Tag Completion options:

Turn the feature on and off.

Edit the tag completion list.

Include ASP tags.

Close double quotes for attribute values.

Tag validation

Rather than wait until a document is completed to run the code validator, you can set it to run on a tag-by-tag basis.

Open the Validation tab on the Options > Settings dialog to set validation rules.

Special characters

You must use character entities to display special characters on Web pages. When enabled, this feature automatically converts characters above ASCII 127 to entity names for proper rendering in browsers.

Select View > Special Characters to open a palette of character entities that you can insert.

Getting Started with Templates and Wizards

Select File > New to select from an extensive collection of templates and wizards to help you get started building a site or an application.

Chapter 2: Creating Pages 31

Templates

Studio templates are similar to those used in word processing software; they provide a basic structure for different document types.

Use the File > Save As Template command to add the current document to the File >

New > Custom tab. You can then use it as a starting point for new documents.

HTML wizards

Many of the wizards listed here are also available on the QuickBar.

Quick Start — Build a page framework by entering meta information.

Tables — Define a table structure and properties and enter attributes for individual cells.

Frames — Design a frameset, make selections for frame layout and appearance, and specify a source URL for the frame content.

Open Browser window — Generates code for the JavaScript openWin function based on the specified URL and window attributes. Create links to display text and images in a custom browser window. The window display is browserdependent and should be tested.

Multimedia — Two wizards make it easy to synchronize RealAudio files with

HTML page display and to embed RealAudio controls on your pages.

DHTML wizards

Dynamic HTML wizards generate styles and JavaScript to create an outline or slide show. Click the DHTML tab on the File > New dialog to select a wizard:

Outline — Create a multi-level outline by typing in or pasting the outline text and defining properties for the display. The JavaScript code for the outline is inserted in the document head.

Slide Show — Build slide presentations that run in a browser. All the features of desktop presentation products – layout and duration control, transition options, and integrated images and text – are available.

Note

The JavaScript Wizard, which generates code for several navigation and page functions, is only accessible from the Script toolbar. Use the View menu to set toolbar display.

CFML Wizards

These wizards expedite many common ColdFusion development tasks. Click the

CFML tab on the File > New dialog to see the wizard set.

Custom Tag — Builds a parameter-checking framework for creating custom tags in CFML.

32

Using ColdFusion Studio

Data Entry — Creates a data entry application for a selected data source.

Specify a table and the fields you want to include. The wizard generates an entry form and an application page that inserts the data when the form is submitted.

Data Drill-Down — Produces an application that searches the selected data sources and returns results and detail pages.

Exception Handling — Generates a TRY-CATCH framework in which you can enter code for a CFTRY tag. You can optionally enable handling of database, template, included missing files, object, security, application-defined, and unexpected internal failures.

Table to JS — Generates a JavaScript object from the contents of a table in a registered ColdFusion data source.

LDAP — Enter LDAP server information and directory entries to create an application to view and edit directories and to submit a directory view form.

Library — Builds access to a file library for users.

Mailing List — Builds an email application from the selected data source of email addresses.

Record Viewer — Generates an application to manage, preview, and edit selected records in a table.

Tree Control — Produces a Java tree control from selected data sources.

Verity — Builds an application based on selected search criteria to generate an indexed collection of the specified data sources. This wizard can be used in conjunction with the Library Wizard to index library files.

Working in Tag Chooser

Open the Tag Chooser (Ctrl + E) for quick access to all supported tags. For convenience, the tags are grouped by the processes they support. You can view the entire set by clicking on the folder icon of the tag set you want to use.

To insert a tag double-click on it. A tag editor opens for tags that require attributes, other tags are inserted directly into the current document.

Another useful feature is the embedded help window below the tag list. It displays syntax and usage information for the selected tag. Click the Toggle Embedded Help button to control the display. To view the help in a separate window, click the companion button.

Inserting Tags from the QuickBar

When you click on a QuickBar icon, it either inserts the tag directly into the document or opens a dialog for tags that take attributes. Each dialog is tag-specific; it only displays supported attributes.

Chapter 2: Creating Pages 33

You can easily customize the QuickBar display and organize toolbuttons.

To move a QuickBar tab:

1.

Click and hold on the drag bar – the double lines located at the left end of the tab – on the tab you want to move.

2.

Drag the toolbar to the new position. To place the toolbar on a workspace border, drag it to the edge of the border until the toolbar border changes to thin lines, then release the mouse button.

3.

To return a toolbar to its previous location, double-click on its title bar.

To organize QuickBar tabs:

1.

Right-click in the QuickBar and select the tabs you want displayed.

2.

Right-click in the QuickBar and select Organize QuickBar.

3.

Use the up and down arrows to set the tab order.

To customize QuickBar tabs:

1.

Right-click in the QuickBar and select Customize.

2.

Double-click on a toolbar name in the Toolbars list.

3.

Drag and drop items from the Toolbuttons list onto the selected toolbar.

4.

Click the Add Separator button to add a vertical bar next to the last icon.

5.

Check the Show keyboard shortcuts in toolbutton hints box to display the key combination when you hover the mouse pointer over a toolbutton.

To add a toolbar:

1.

Click Add Toolbar in the Customize dialog.

2.

Enter a name for the new toolbar and click OK to add the toolbar to the Toolbars list.

3.

Select the new toolbar from the list and add toolbuttons as needed.

4.

Use the Organize QuickBar dialog to place the toolbar.

To add a custom toolbutton:

1.

Click Add Custom Button in the Customize dialog.

2.

Click the radio button to select an action for the toolbutton.

3.

Complete the entries for the selected action.

4.

Click OK to add the new toolbutton to the selected toolbar.

You can always return to the original QuickBar configuration by clicking the Reset to

Defaults button.

34

Using ColdFusion Studio

Adding Media Content

Well-integrated graphics, sounds, and video can make a site more attractive to visitors and can enhance the overall site content. This section show you how you can use

Studio to make these elements part of your site.

Image files

Studio supports the most common Web graphics formats, GIF, JPEG, and PNG, but note that these formats are not supported by all browsers.

The easiest way to add images is to drag and drop an image file from the file list into your document. You can also click the Image toolbutton on the QuickBar to open the

IMG dialog. First locate a source file, then enter values for the IMG tag attributes. The image is displayed in the dialog’s preview pane.

You can open the Style Editor to define formatting styles for the IMG element.

To add a background image for the entire document, use the BACKGROUND attribute of the document’s BODY tag.

For a full description of the IMG tag and its associated attributes, properties, methods and events, see the Images section of the HTML Reference.

Tip

For graphics files that you use often, such as navigation bars or icons, use Snippets to store and retrieve the code block.

Viewing image thumbnails

When you’re working with many graphics files, it’s helpful to be able to identify them visually. You can get a thumbnail view of all images in the current directory by clicking the Thumbnails toolbutton. The images appear in the Results window.

Right-click on a thumbnail image to see its properties or to view it In Edit or Design view, you can drag a thumbnail to add the image to your document.

Image maps

Image maps are graphics that contain “hot spots” that respond to user input, generally a mouse click. The hot spots can be mapped to both internal and external pages.

Image maps can make navigation easier and give visitors visual cues to content areas.

To add a client-side image map:

1.

Open the image editor and enter the image source file and attributes.

2.

Check the ISMAP box.

3.

If you use an external image map file, enter the path and file name in the Use Map text box. If you include the map file information in the document with the image, enter its name with a # prefix, such as

#mapfile01

. The map file text can be placed anywhere in the document before the </HTML> tag.

Chapter 2: Creating Pages 35

Note

Server-side image maps require processing of the map file on the server. The map file must contain a script to connect via HTTP to the locations specified in the image map.

OpenPix

Studio supports Hewlett-Packard’s OpenPix ImageIgniter. This technology makes it possible to quickly deliver high quality, interactive images to Web pages. For more information, see the OpenPix article on Allaire’s Developer site.

Video

You can add video clips in AVI format to your Web pages using the Image dialog box.

To add a video file to your Web page:

1.

Open the Image tag editor, click the Advanced tab, and enter the URL of the video file in the Dyn Source text box.

2.

Enter an image file name in the Source text box. This file displays as an alternate image if the user’s browser cannot run the video clip.

3.

In the Start box, select the user action that triggers the video.

4.

Check the Control box to display a control panel below the video window.

5.

In the Loop box, enter the number of times to play the video. To run the clip continuously, enter -1 or select the Infinite check box.

6.

In the Loop Delay box, enter a number for the time (in milliseconds) to pause between replays, and click OK.

Note

The DYNSRC attribute of the IMG tag is a Microsoft Internet Explorer extension and will not display in Netscape Navigator or other browsers.

Sound

Sound adds an exciting dimension to Web pages — to entertain, give audio cues, provide training instructions, or play audio files. You can add sound files in WAV, MIDI, or AU format.

To add a sound file to your Web page:

1.

Choose Tools > Tag Chooser and open the Page Elements list.

2.

Choose the BGSOUND tag for Internet Explorer, or the EMBED tag for Netscape

Navigator.

3.

In the tag editor for the BGSOUND or EMBED tag, enter the sound file’s source path and file name.

4.

In the Loop menu, choose either the number of times you want the file to play or

Infinite for continuous play.

36

Using ColdFusion Studio

Note

The BGSOUND attribute is a Microsoft Internet Explorer extension and will not work in Netscape Navigator and other browsers.

RealNetworks support

Studio offers two wizards to help you add sound to Web pages:

Choose File > New and select the Multimedia Synchronization wizard to set timings HTML content with audio files. For additional information on

RealPlayer, see the RealNetworks site at http://www.real.com

.

Choose File > New and select RealPlayer Control Wizard to embed a RealPlayer custom control for an audio event.

Using SMIL tags

Studio supports the Synchronized Multimedia Integration Language (SMIL) and offers a SMIL tag pack to help you add synchronized media objects to your site.

For more information on using SMIL tags in Studio, visit the SMIL page on the Allaire

Web site: http://www.allaire.com/products/smil/ .

Saving Code Blocks as Snippets

The Code Snippets feature offers a quick way to store and re-use code blocks and content. Comment your snippets just as you would any code block.

To create a code snippet:

1.

Click the Snippets tab in the Resource window and choose Create Folder from the shortcut menu.

2.

Enter a name for the folder.

3.

Right-click in the Snippets pane and choose Add Snippet to open the Snippet dialog.

4.

Enter a name for the snippet in the Description box. Note that snippet names cannot contain characters that are illegal in file names, such as slashes, special characters, double quotes, etc.

5.

In the Start Text window, type in or paste an opening code block. You can set a default spacing between the blocks by hitting the Enter key at the end of the start text and at the beginning of the end text.

6.

In the End Text window, enter a closing code block.

7.

Click OK. Right-click on a snippet to edit or delete it.

The default location for Snippets is the \UserData\Snippets folder below your Studio root directory.

Chapter 2: Creating Pages 37

Tip

Because snippets can be created as start and end blocks, you can use them to surround other tags and content. This is handy for inserting special formatting, navigation elements, and script blocks. Simply highlight the content you want to surround, then insert the snippet.

To insert a snippet, double-click on an entry in the Snippets tab or right-click and select Insert into document.

Use the snippets shortcut menus to manage snippets and folders.

Sharing snippets

You can share code snippets with other developers by giving them access to a shared folder on your machine or on another network machine.

To create a shared snippets folder:

1.

Open the Locations tab in the Options > Settings (F8) dialog.

2.

In the Shared Snippets box, use the Browse button to navigate to the shared folder location. Click OK.

3.

In the Snippets tab, right-click and choose Create Shared Folder. The folder icon changes color to show that it is shared.

Anyone with access to the shared folder can add, edit, and delete snippets.

Adding snippet shortcut keys

Open the Options > Customize dialog and select the Snippet Shortcut tab to enable a keyboard combination for a snippet. Select a snippet and press keys to enter the combination in the shortcut box.

If a combination is in use, the current command appears below the shortcut box. To overwrite a combination, click Apply.

Saving Keystrokes with Code Templates

Use the Code Templates feature as a shortcut to entering words that you type frequently. On the Code Templates pane of the Settings dialog box (F8), you can add and change these shortcuts, mapping abbreviations to commonly-used words or phrases.

To use the Code Templates feature while editing text, enter the abbreviation, for example, dt4, and press Ctrl-J. The abbreviation expands to the full phrase, in this case,

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> .

38

Using ColdFusion Studio

Building CFML Expressions

The Expression Builder is an invaluable tool for choosing and combining CFML functions, constants, operators, and variables.

To build expressions:

1.

Place the cursor at the point in the document where you want to insert the expression.

2.

Right-click and select Insert Expression or choose Tools > Expression Builder (Shift

+ Ctrl + E).

3.

In the Functions list, choose an expression type to display the expression elements in the adjoining pane. For example, select Date and Time to see all the ColdFusion functions for manipulating these values.

4.

Double-click an element to add it to the element list.

5.

Add operators by clicking on them in the operator toolbar.

6.

Click Insert to add the expression in the current document.

See Chapter 6, "Functions and Expressions" in Developing Web Applications with

ColdFusion

for information about ColdFusion functions and expressions.

For the full syntax of functions and expressions, see the CFML Language Reference.

The ColdFusion Quick Reference Guide is a handy source of information on CFML expressions.

C

H A P T E R

3

Chapter 3

Accessing ColdFusion

Data Sources

This chapter describes how to use Studio’s visual database tools to significantly accelerate development of the database components of ColdFusion applications.

Contents

Introduction to Database Tools ...................................................................... 40

Registering Data Sources ................................................................................. 40

Connecting to Data Sources............................................................................ 40

Opening an ODBC Data Source ...................................................................... 41

Using Query Builder......................................................................................... 41

Building a SELECT Query ................................................................................ 42

Inserting SQL into a Page................................................................................. 43

Running and Editing Queries.......................................................................... 44

40

Using ColdFusion Studio

Introduction to Database Tools

Studio’s visual database tools support application development using both local, network, and remote data sources. For ease of use, all data sources are treated as remote. Access to data sources becomes transparent when a server is configured in

Studio.

Studio's database tools support:

Remote database development

Data source schema and data browsing

Visual SQL query building

Registering Data Sources

A set of ODBC drivers and sample data is installed with all versions of ColdFusion.

Native database drivers are installed with the Enterprise version and OLE-DB drivers are installed with the Professional and Enterprise versions.

To register a data source:

1.

Open the ColdFusion Administrator.

2.

Select the ODBC or native drivers page under the data sources heading.

3.

Name the data source, select the appropriate driver, and click Add.

To test the connection, click the Verify link. A help message displays if the test connection fails.

When these steps are completed, you access the data source from Studio’s Database tab.

For more information on managing data sources, see Administering ColdFusion Server.

Connecting to Data Sources

Studio uses the Database Connection Manager in the ColdFusion Server to connect to remote data sources.

See “Managing Remote Files,” in Chapter 1 for detailed instructions on configuring a

server.

For a full discussion of developing with ColdFusion data sources, including requirements for native drivers, see Chapter 11, "Understanding Data Sources" in

Developing Web Applications with ColdFusion.

Chapter 3: Accessing ColdFusion Data Sources 41

Opening an ODBC Data Source

Once a data source is registered, you can work with it in Studio.

To open a data source:

1.

Click the Database tab in the Resources window and click the down arrow on the top pane to open the list of available ColdFusion servers.

2.

Click on a server name to open its data sources. This may take a moment for large databases on remote servers.

3.

Double-click on a data source name to expand it.

4.

To view the database schema, expand Tables list. Double-click on a table name to view the records in that table.

You can only browse data in the data browsing window. You cannot modify data or add new records.

Views are only available in databases that support creating views or tables stored as queries.

Tip

To insert column or table names into a page, just drag and drop the table or column into the editor. This is useful when you are building database reports.

Using Query Builder

Studio provides a powerful visual tool to build, test, and save SQL statements for use in data queries. Select a query type from the Query Builder toolbar or right-click in the

Table pane and choose from the Query Type list.

To open the Query Builder:

Right-click on a database or on a table in the Database (DB) Resource tab and choose New Query.

Click Tools > SQL Builder and select a database from the Select Database Query dialog.

Open the CFQUERY tag editor and click New Query.

The Query Builder is divided into three panes:

Table pane — Provides a view of the tables in your query and allows you to create joins between tables.

Properties pane — Allows you to set the properties of the query such as the columns that are being selected or the columns that are being updated.

SQL pane — Shows you the SQL that is being built by the query builder.

Query Builder opens a SELECT statement by default, since this is the most common type of query. If you have not chosen a table, you will be asked to select one.

42

Using ColdFusion Studio

Query Builder supports four types of SQL statements:

Select

Insert

Update

Delete

The SQL pane does not support reverse editing, so any changes you make in this pane will not be made to the query in the Properties pane or the Table pane.

Building a SELECT Query

SQL SELECT statements let you specify the data from which to build a recordset.

To create a SELECT statement:

1.

Open the Query Builder for the data source you want to query.

2.

When the Query Builder opens, select the first table you want to query.

3.

Right-click in the Table pane and choose Add Table or click the Add Table button in the tool bar to add additional tables to the query.

4.

Drag and drop column names between tables to create joins.

5.

Right-click on a join to delete the join or change it to an inner or outer join.

6.

Drag the columns you want to display onto the Column section of the Properties pane.

7.

Set additional query attributes in the Properties pane.

8.

Save or insert the query into your page.

To use a CFML variable in a SQL WHERE clause:

1.

Click in the Criteria column in the Properties pane for the column that you want use in the WHERE clause.

2.

Open the select box and choose CFVARIABLE.

3.

Double-click on the variable and rename it to the variable in your application.

To save a query:

1.

Click the Save Query button on the Query toolbar.

2.

Enter a name for the query in the dialog.

3.

Click Save.

Saved queries are stored on the ColdFusion Database Server. They can be edited and used by to everyone who has access to that server.

Chapter 3: Accessing ColdFusion Data Sources 43

If you edit a SQL statement in the SQL pane and then save the query, the changes are saved. However, if you modify the Table pane or change any values in the Properties pane, a new SQL statement is generated, overwriting any edits you made in the SQL pane.

Inserting SQL into a Page

You can use any of the following methods to insert a query directly into a CFML page from the Query Builder:

If you open the Query Builder from the CFQUERY tag editor, it prompts you to insert the query when you close the editor.

If you open the Query Builder from a CFML page, it prompts you to insert the query when you close it.

To insert just the SQL statement, click the Copy SQL to Clipboard button on the

Query toolbar. Close the Query Builder and paste the SQL into your page. You will be prompted to save the query.

To insert the SQL statement within a CFQUERY tag, click the Copy CFQUERY button. Close the Query Builder and paste the query into your page. You will be prompted to save the query.

To insert a saved query:

Use either of the methods listed below.

1.

Open the data source schema in the Database Resource tab.

2.

Open the Queries folder in the data source you want to use.

3.

Drag and drop the query onto the page.

Or

1.

Click the CFQUERY button on the CFML Basic tag toolbar or select CFQUERY from the Tag Chooser (Ctrl + E).

2.

Enter a name for the query.

3.

Click the Insert Query button.

4.

Choose a server from the select box.

5.

Open the Queries folder in the data source you want to use.

6.

Select a query and click Insert.

7.

Click Apply in the CFQUERY tag editor.

44

Using ColdFusion Studio

Running and Editing Queries

You can do a lot of work with SQL statements after building them.

Running a query

You can test your SQL code in Query Builder before inserting it in a page.

To run a query in the Query Builder:

1.

Click the Run Query button.

2.

You are prompted to enter values for any CFML variables in the query.

Warning

When you click the Run Query button, the SQL statement is actually processed. If you run an INSERT, UPDATE, or DELETE statement, the changes you coded in the SQL statement are made in the data source.

Editing Queries

If you save a query, you can edit it later. Pages that contain the edited query are not automatically updated, so you will need to re-insert the query for the changes to take effect.

To edit a query:

1.

Open the query folder for the data source you want to use.

2.

Double-click on the query you want to edit.

3.

Make changes in the Table pane and the Properties pane.

4.

Save the new query.

Note

The interactions among the Query Builder panes differ somewhat. If you write a query in the SQL pane and save it, the code is not reflected in the Properties or Table panes. If you take an action, such as adding a table, in the Properties or Table panes, the SQL pane is refreshed with the SQL generated from these panes.

C

H A P T E R

4

Editing Pages

Chapter 4

Studio is an extended version of HomeSite, Allaire’s award-winning HTML editor and brings a wealth of tools to the task of working with code and content.

This chapter covers the tools and offers some tips on using them productively.

Contents

Setting Editing Options.................................................................................... 46

Keyboard Shortcuts.......................................................................................... 46

Editing Tools ..................................................................................................... 46

Tag Editors ........................................................................................................ 47

Tag Tree and Tag Inspector .............................................................................. 47

Visual Editing in Design Mode ........................................................................ 49

Preserving Code Formats with CodeSweeper ................................................ 50

Formatting Pages with Cascading Style Sheets.............................................. 52

46

Using ColdFusion Studio

Setting Editing Options

The following features control the display of tags and text in the editor.

Color-coding tags — Studio installs a set of default color schemes. Check the Color

Coding tab of the Settings dialog (F8).

Word wrap — Controls line length of text in the Editor. Click the Word wrap icon on the

Editor toolbar.

Gutter — A space on the left side of the document used to keep track of bookmarks, line numbers, and debugger breakpoints. Click the Show Gutter button on the editor toolbar to open it. Press Ctrl + K to set and remove bookmarks and Ctrl + Shift + K to move to the next bookmark.

Convert tag case — Changes the case of all tags in the current document. Use the Edit

> Convert Tag Case menu command. You can set global options for lowercase on the

HTML tab of the Settings dialog (F8).

Use hexadecimal color values — Setting this option on the HTML tab of the Settings dialog inserts hex value of colors instead of named values.

Indenting code — Use the left and right arrow keys on the Editor toolbar set indents.

To automatically indent a line to the same level as the previous line, select Auto Indent on the Edit tab of the Settings dialog.

Keyboard Shortcuts

Studio offers keyboard shortcuts for many file management, editing, and debugging commands. You can also customize these shortcuts. Choose Options > Customize

(Shift + F8) and open the Keyboard Shortcuts tab to see the current keyboard mappings and edit them to suit your preferences.

You can print a complete list of shortcut keys from the ColdFusion Quick Reference

Guide.

Editing Tools

Working in the editor requires easy access to just the right tool for each job:

Tag Editors — Tag-specific dialogs for editing attributes.

Tag Tree — A configurable navigation aid for viewing and navigating a document’s tag hierarchy.

Tag Inspector — A property sheet-style tag editor.

Design mode — Visually edit page elements.

CodeSweeper — Configurable rules-based code formatting.

Style Editor — Create, edit, and link style sheets to documents.

Chapter 4: Editing Pages 47

Tag Editors

Editors are tag-specific dialogs that contain the attributes and values of the selected tag. Online help is available in each editor.

Because tag editors are written in Allaire’s Visual Tools Markup Language (VTML), developers can change the display properties and content of existing editors and create editors for custom tags.

For information on working in VTML, see

Chapter 9, “Customizing the Development

Environment,” on page 89

.

To open the editor for a tag, do any of the following:

Click on tag icon on the QuickBar.

Right-click in a tag and select Edit Tag.

Press Ctrl + F4 in a tag.

Click Tags > Edit Current Tag.

Tip

Right-click on an event handler in a tag, such as OnLoad, and select Navigate to

Function to highlight the function in the script block.

Tag Tree and Tag Inspector

The Tag Inspector Resource tab contains two integrated tools: Tag Tree and Tag

Inspector. By using them in combination, you can edit all the code in a document without having to work directly in the document.

Tag Tree

The Tag Tree, located in the top pane, is helpful for inspecting and navigating a document’s structure. It can be easily configured to display just the tags you want to work with.

To use the Tag Tree:

1.

Open the dropdown list at the top of the to filter the view.

1.

Use the plus and minus signs to expand and contract the view.

2.

Click on tag in the tree to quickly locate it in the document. Ctrl + click selects the entire tag block.

If the selected tag supports attributes, they are displayed, with their values, in the

Tag Inspector pane.

3.

Click the Refresh icon to update the tree as you edit the document.

48

Using ColdFusion Studio

To configure the Tag Tree display:

1.

Click the Configure Outline Profiles button at the top of the pane to open the

Outline Profiles dialog.

2.

Use the Add and Remove buttons in the Outline Profiles pane to edit the current tag sets.

3.

Use the Add and Remove buttons in the Recognized Tags pane to edit the tag list for the selected set.

4.

To add a caption and icon to a tag, make selections in the Tag Settings pane.

5.

Click Done to update the Tag Tree profiles.

The Tag Tree supports tag sets created in Allaire’s Visual Tools Markup Language

(VTML), or a Document Type Definition (using the DTD file extension) from an SGMLcompliant language, such as Extensible Markup Language (XML).

To import an Outline Profile:

1.

Click the Import button in the Configure Outline Profiles dialog.

2.

Select either a VTML definition file or a DTD file to import.

3.

Click Next.

The Wizard reports the status of the import process. If the process completes successfully, click Finish.

Tag Inspector

The Tag Inspector lets you edit code in a property sheet interface that will be familiar to Visual Basic and Delphi programmers. At the top of the Inspector pane are controls for the display.

To use the Tag Inspector:

1.

Click in a tag, either in the Tag Tree or in the editor, to see a list of its attributes.

2.

Click on an attribute name to type in a value or to select from a list if the attribute takes pre-defined values.

3.

Click outside the current field to enter the new value in your code.

Every tag that Studio installs includes a definition file. The files are written in VTML and specify the valid attributes for that tag and the content and formatting of the tag’s editor.

To change a tag definition file:

1.

Click the Edit Tag Definitions icon to open the dialog.

The left pane lists all the installed languages. You can edit the definitions list by using the Add and Remove buttons.

2.

Expand a language entry to view individual tags.

Chapter 4: Editing Pages 49

When you select a tag, the attributes and other components defined in its VTM file appear in the tabbed pane.

3.

Make changes in the tag definition fields and click Done to save the changes.

Scripting Event Handlers

Click on a event attribute, such as ONCLICK, for the selected tag and choose a script language option from the drop-down list. Enter a name for the event handler and click

OK to insert the handler ID in the tag and a starter script block in the <HEAD> section.

Visual Editing in Design Mode

Studio provides an optional visual editing view, called Design mode. Design mode which lets you edit HTML code while seeing how the results would look in a browser.

The Design view is most useful for:

Prototyping page layout.

Placing graphic elements on a page.

Creating complex tables and forms without having to code the tags.

Converting content such as lists, tables, and worksheet cells into their equivalent HTML formatting by copying from Microsoft Word and Excel.

Note

The Design view feature requires Microsoft’s Internet Explorer 4.01 or later. If you don’t have this browser installed, or if you don’t intend to use the Design view, you can disable it in the Design tab of the Settings (F8) dialog.

To edit a page in Design view:

1.

With a document open in the Edit window, save your changes and select the

Design tab in the editor.

The Design view opens, showing a browser view of the document that you can also use to edit text, styles, and graphics.

2.

Use the Design view toolbars to edit text, change styles, add colors, or create

HTML tables and form elements.

3.

If you’ve opened Design view and now prefer to cancel any changes, select the

Cancel Design View button to discard all changes and return to the Edit view.

4.

Use the Edit and Browse tabs to return to the Edit and Browse modes.

5.

To discard unsaved changes in Design view, click the Discard button.

To convert Microsoft Word and Excel content:

1.

Select the content in Word or Excel.

50

Using ColdFusion Studio

2.

Paste the selection into the Design window at the location you want it to appear on the page.

3.

Edit the new content visually. For example, you can click on a table border and drag a handle to resize it, or by switching to the editor to work directly in the code.

To explore this feature, you can experiment with inserting different types of content from Office documents and other Windows applications.

Preserving Code Formats with CodeSweeper

CodeSweeper automates the task of properly formatting your code. It can be very useful in a number of situations:

Visually editing page elements in Design view can change code formatting. You can set CodeSweeper to apply formatting rules when you leave Design view.

You can painlessly enforce coding styles for multiple developers by simply having them use the same settings.

You can easily clean up the code formatting of an existing project as you review the documents.

Click the CodeSweeper button from either Edit or Design modes to run the selected

CodeSweeper on the current document. You can also set it to run automatically when you leave Design mode.

See the Allaire Developer site for an interesting article on CodeSweeper features.

Configuring CodeSweeper

Click the CodeSweeper button or select Options > CodeSweeper Settings to choose from the list of available CodeSweepers. Studio installs three CodeSweepers:

HTML and CFML tags (this is the default)

HTML tags only

My CodeSweeper, a copy of the default CodeSweeper that you can use for testing.

When you have selected a CodeSweeper, you can then specify the formatting rules you want to use.

CodeSweeper settings

You can set the following formatting rules for all tags:

Set case for tag and attribute names. You can choose all upper or lower case or preserve case, which leaves the case unchanged.

The Format event names setting contains an additional option – Mixed Case – which applies to case-sensitive JavaScript event handler names like

Chapter 4: Editing Pages 51

OnMouseOver. If this code is correct in your document, select Preserve Case for this setting.

Set the use of quotes for values.

Trim white space between tags cleans up spacing produced by some code generation tools. It is enabled by default. We recommend leaving it on and disabling it for individual tags as needed.

Check the “Apply Current CodeSweeper when switching from Design view” box to automatically run CodeSweeper on the active document when you leave

Design view. Click the Update button to save these settings.

Tag-specific settings

A wide range of options is available for the individual tags contained in each

CodeSweeper. Note that if you set formatting for the "All Other Tags" entry in the tag list, those rules apply to every tag that appears in a document that is not in the list.

Insert a newline command for start and end tags.

Set indent by tabs or spaces — A newline is inserted automatically for each indented line when this option is checked.

Enable indenting of nested sub-tags.

Override the general trim white space setting by preventing trimming of white space around the selected tag.

Leave the selected tag unchanged when invoking CodeSweeper.

Strip tag from document — This is handy for getting rid of superfluous and unwanted tags inserted by code generation tools.

To set rules for a tag:

1.

Select a tag from the Tag-Specific Settings list in the CodeSweeper Settings dialog.

2.

Change the specific settings.

3.

Click Update Tag to save the settings for that tag.

To add a tag to a CodeSweeper:

1.

Click the Add Tag in the CodeSweeper Settings dialog.

2.

Enter the tag name and click OK.

3.

Change tag settings.

4.

Click Update Tag to save the settings.

Adding a new CodeSweeper

You can easily create custom CodeSweepers to fit specific document types or coding styles.

52

Using ColdFusion Studio

To add a new CodeSweeper:

1.

Click the Add button in the CodeSweeper Settings dialog.

2.

Enter a name for the new CodeSweeper.

3.

Change global and tag settings.

4.

Click Update to save the settings.

Formatting Pages with Cascading Style Sheets

Cascading Style Sheets (CSS) are rapidly becoming a significant component of Web site architectures because they offer so many advantages in site design and content management. The HTML 4.0 specification strongly encourages their use despite the limitations of CSS support in older browsers.

Style sheets can be added at any point in a site’s development process, but ideally the design specification for a site will be implemented via style sheets, eliminating the need to code and maintain formatting for individual tags. More significantly, CSS lets developers and content providers focus on organizational and navigation issues by separating formatting from content. As a site’s structure evolves, styles can be globally changed, added, and deleted, giving developers greater freedom (and more time!) to achieve design goals.

A site can be retrofitted with CSS, although this requires deleting in-place formatting code.

You can download a tutorial on Cascading Style sheet from the Allaire Documentation

Page at http://www.allaire.com/Documents/cf4docs.cfm

.

Using the Style Editor

The Style Editor is a standalone application that provides a complete interface for designing and implementing Cascading Style Sheets. You can quickly define and preview styles for HTML tags (selectors) and add new ones as needed.

To create a new style sheet:

1.

Click the Style Editor button or open File > New and select StyleEd from the HTML tab.

2.

The Editor opens with a default set of tag selectors. Use the Add, Rename, and

Delete selector buttons to maintain the list.

3.

Click on a selector and then click on an item in the Properties list. A button displays for properties that take pre-defined values. Click it to select a value.

4.

When the style sheet is completed, save it with the default CSS extension.

To link a style sheet to documents:

1.

Click the Link to External Files button.

Chapter 4: Editing Pages 53

2.

Link the current CSS file to individual files or to folders.

3.

Specify extensions for the selected files.

4.

Optionally require backups of affected files.

5.

Click OK to insert the style sheet link in the <HEAD> section of the specified files, using the relative path.

Note

The link engine does NOT update or overwrite an existing CSS link in a document. If you change the location of either the CSS file or the documents, you will need to delete the current link and rerun the Link dialog.

To edit existing styles:

You can use the following commands to perform style editing tasks:

Right-click in a <STYLE> block and select Edit Style Block.

Right-click on a link to a style sheet and select Edit Linked StyleSheet.

Right click on a CSS file in the file list with the CSS extension and select Edit

StyleSheet.

C

H A P T E R

5

Chapter 5

Debugging CFML Applications from Studio

Debugging information reported from the ColdFusion Application Server is often adequate for simple templates, but complex development tasks require a more powerful and immediate debugging interface.

Studio’s Interactive Debugger runs against dynamic pages on the ColdFusion Server.

You can set breakpoints and step through the code to isolate and correct problems.

A tabbed debug window gives you views of breakpoints, variables, recordsets, tag and page hierarchies, and page output. From these panes, you can set watches, change, disable, and delete breakpoints, and evaluate variables and expressions.

For information on setting server-side debugging options, see Administering

ColdFusion Server.

For information about debugging ColdFusion Applications, see Chapter 24,

"Debugging and Troubleshooting" in Developing Web Applications with ColdFusion .

Contents

Interactive Debugger Overview ...................................................................... 56

Configuring RDS from the Debugger ............................................................. 56

Creating RDS Mappings .................................................................................. 57

Specifying Server Mappings ............................................................................ 59

Running the Interactive Debugger ................................................................. 60

Debugger Shortcut Keys .................................................................................. 64

56

Using ColdFusion Studio

Interactive Debugger Overview

You can run the debugger against the ColdFusion application pages.

The debugger lets you:

Set breakpoints and watches

Evaluate variables and expressions

Step through lines of code

Investigate the code stack

Monitor recordsets

Observe variables in all scopes

Use the Debug menu or the Debug toolbar to run debugging processes.

Follow these steps to set up the debugging session:

Select the ColdFusion server against which to run the debugging session.

Provide mappings to specify the ColdFusion Studio path, the ColdFusion Server path, and the browser’s path to the files you are debugging.

Specify the first page in the application to be debugged.

Configuring RDS from the Debugger

To access a remote server from Studio, first configure the server and provide security login information if the server is protected through ColdFusion security.

To configure a remote development server:

1.

Open the first application page you would like to debug and choose Debug >

Debug Settings.

2.

Choose Add RDS Server from the drop-down list in the Debug Start pane of the

Remote Development Settings dialog box.

3.

Enter the description, host name, user name, password, and port of the remote server in the Configure RDS Server dialog box. You can optionally enable Secure

Sockets Layer.

4.

If the server is protected by ColdFusion RDS Security, enter the user name and password you use to access this protected resource.

5.

Click OK.

Chapter 5: Debugging CFML Applications from Studio 57

Creating RDS Mappings

You need to specify file mappings for the application directory so that the debugger, the ColdFusion Server, and the browser can properly translate local paths into server paths and URLs.

Studio Path — How does ColdFusion Studio see the directory?

Server Path — How does the Web server/ColdFusion server see the directory?

Browser Path — How does the browser see the directory?

File mapping examples

The following scenarios show how file mappings work when you have local or remote files matched with either local or remote servers:

ColdFusion Studio and Server on the same machine

ColdFusion Studio debugging on remote ColdFusion Server using drive mappings

ColdFusion Studio debugging on remote ColdFusion Server using Network

Neighborhood

ColdFusion Studio debugging on remote ColdFusion Server using RDS file access

Using local paths

Debugging against a local ColdFusion Server is the most common scenario. In most cases, this arrangement allows both the Server and Studio to see the directories in the same way.

For example, the local path c:\inetpub\wwwroot

translates to an identical server path

C:\inetpub\wwwroot

, and a URL path of http://215.180.21.1/

. The use of mappings in such a scenario is mainly for URL resolutions. The URL part of the mapping instructs ColdFusion Studio how a physical file can be viewed in a browser.

In this example, you would create a mapping as follows:

ColdFusion Server and Studio on same machine

Studio Path

C:\inetpub\wwwroot\

Server Path

Browser/URL Path

C:\inetpub\wwwroot\ http://215.180.21.1/

58

Using ColdFusion Studio

Using drive mappings

Developers often debug against a remote ColdFusion server across an internal network. In many cases, they use a network drive mapping.

For example, a user may have a remote drive

X:\

mapped to a network shared directory

\\MYSERVER\WEBPROJECTS\

where

WEBPROJECTS

is the name of the shared directory in the network server MYSERVER .

In such a scenario, a file that appears to Studio as

X:\App1\Index.cfm

May be viewed by the CF server as

C:\webprojects\App1\index.cfm

The browser may view it using the URL path http://215.180.21.1/App1/index.cfm

In order to resolve the communication between ColdFusion Studio and the Server, you need to create a mapping for the App1 directory as follows:

Studio access to a remote server using drive mappings

Studio Path X:\App1\

C:\webprojects\App1\

Server Path

Browser/URL Path http://215.180.21.1/App1/

Using UNC paths/Network Neighborhood

Developers can debug code against remote ColdFusion servers across an internal network. They often use the Network Neighborhood to access a file on a remote Cold

Fusion server. For example, a developer may be accessing a file on

\\myserver\webprojects\

where webprojects

is the name of the shared directory in the network server myserver .

In such a scenario, a file that appears to Studio as

\\myserver\webprojects\App1\Index.cfm

May be viewed by the ColdFusion server as c:\webprojects\App1\index.cfm

The browser may view it using the URL path http://215.180.21.1/App1/index.cfm

Chapter 5: Debugging CFML Applications from Studio 59

ColdFusion Studio and the Server need to understand how a file location appears to the parties involved. You therefore need to create a mapping for the App1 directory as follows:

Studio accesses files on remote CF server using UNC paths/Network

Neighborhood

Studio Path

\\MYSERVER\WEBPROJECTS\App1\

Server Path

Browser/URL Path

C:\webprojects\App1\ http://215.180.21.1/App1/

Using Remote Development Services

When developing outside local area networks, many developers access files on a

ColdFusion Server across the Internet using the RDS-based remote file access available from the Remote tab in ColdFusion Studio.

In such a scenario, a file that appears to Studio as

RDS://MY_RDS_SERVER/C:/webprojects/App1/index.cfm

May be viewed by the ColdFusion server as

C:\webprojects\App1\index.cfm

The browser may view it using the URL path http://215.180.21.1/App1/index.cfm

Although the server path can be inferred from the local RDS path, you still need to create a mapping. In special scenarios, ColdFusion Server to Studio path resolution could become ambiguous. You therefore need to create a mapping for the App1 directory as follows:

Studio accesses files on remote CF server using RDS remote file access

Studio Path

RDS://MY_RDS_SERVER/C:/WEBPROJECTS/App1/

Server Path

Browser/URL Path

C:\webprojects\App1\ http://215.180.21.1/App1/

Specifying Server Mappings

The debugger relies on these mappings to communicate the correct file paths of all files with breakpoints to the ColdFusion server. You create these mappings in the

Mappings pane of the Remote Development Settings dialog box.

60

Using ColdFusion Studio

To specify server and file mappings for debugging:

1.

Choose Debug > Development Mappings to open the Mappings pane of the

Remote Development Settings dialog box.

2.

In the ColdFusion Server list box at the top of the dialog box, choose the

ColdFusion server against which you’ll run the debugging session.

3.

In the Studio Path box, enter the file path ColdFusion Studio uses for the page you’re debugging. Click Add.

If you’re debugging against a local server, the Studio and ColdFusion Server paths are the same. So if you chose localhost, for example, in the ColdFusion Server list box above, the CF Server Path is the same as the Studio path you just entered.

4.

If you’re debugging against a remote server, enter the CF Server Path.

The CF Server path needs to be the same as the alias or virtual mapping your web server uses to access the file.

5.

Specify the Browser Path, or URL, of the application and click Add.

6.

Click OK.

Running the Interactive Debugger

Running the debugger helps you find problems in code by tracing the way ColdFusion evaluates the page, step by step. You do this by placing breakpoints in the page to stop execution of the page, and then step through subsequent lines of code, checking the values of variables and expressions to make sure the code is behaving as you’d expect.

After you’ve set up remote development settings and file mappings, you can use the commands on the Debug menu and the Debug toolbar to run the debugger.

Note

You cannot debug encrypted CFML templates.

To run the interactive debugger:

1.

Open the first page in the application you want to debug.

The Debug toolbar appears at the bottom of the application window. You can undock the toolbar by double-clicking on the undock bars on the left-hand side of the toolbar, drop it into the Quick Bar, or keep it docked.

2.

In your ColdFusion application page, set breakpoints in your code by clicking in the gutter on the left side of the editor window.

The breakpoint lines are colored red. Choose Debug > Toggle Breakpoints to turn breakpoints on and off. Use Debug > Clear Breakpoints to delete all breakpoints in the current document.

3.

In the Debug toolbar, hit the Start/Continue tool.

The Remote Development Settings dialog box appears. It shows the default local server.

Chapter 5: Debugging CFML Applications from Studio 61

4.

Specify the Start URL, which is the URL you use to view the page, and click OK.

The list box shows the pages currently open in ColdFusion Studio.

Enter a fully qualified file path relative to your local ColdFusion server -- for example, http://127.0.0.1/SomeServerPath/index.cfm.

The Debug Start dialog box displays every time you press the Start button in the

Debugger. Use the check box on the Debug Start pane to disable the display of this box the next time you hit the Run button.

Whenever possible, the Studio tries to calculate the URLs of open file using the

RDS development mappings, which you can set in the Mappings tab. These mappings are also required to develop on remote servers.

Based on the RDS Security settings at your site, you’ll see a login prompt to access protected resources.

5.

Enter a user name and password if necessary to access remote servers.

The debugger starts, and it forwards your URL to the Browse view. When the

ColdFusion server encounters the breakpoint, a blue bar appears at the breakpoint in the Edit view. At this point, the ColdFusion server has an open session, and it waits for your reply from ColdFusion Studio.

6.

To continue, hit the Start/Continue button again, and the server moves to the next breakpoint.

The final time you hit the Start/Continue button, ColdFusion executes the page and outputs it to the browser.

7.

To stop the debugging session, hit the End button.

Note

The debugger is active until you hit the End button on the Debug toolbar or choose

Debug > End. This allows you to debug across multiple pages.

Debug windows

Choose View > Debug Window to open the Debug window. There are several panes to this window:

Variables — Displays all scopes of local variables.

Watches — Use this window to set watches and evaluate expressions and variables.

Recordsets — Displays the list of recordsets initialized in the current application page. This pane tracks both CFQUERY-based database recordsets and dynamic recordsets generated programmatically.

Output — Shows the output of the page as it is being generated.

Breakpoints — Shows all the breakpoints that you have set in all files. You can view, disable, and remove breakpoints from this window, and edit their conditions.

Tag Stack — Shows a hierarchy of tag and page attributes, and values.

62

Using ColdFusion Studio

Each of these windows has an associated command button on the Debug toolbar.

You can undock these windows individually, so you can see breakpoints while you’re looking at the Watches, for example.

Stepping through code

You can use the Step Into, Step Over, Step Out, and Run to Cursor tools on the Debug toolbar to step through your code.

Step Into proceeds to the next unit of execution in your code. Use this command to walk through code line-by-line.

If the next step is inside an included file or CFX, the debugger steps into the next file.

Step Over operates in the same way as Step Into, except that it does not step into included files (CFINCLUDE, CFMODULE, or CFLOCATION) or custom tags. It executes the included code but does not trace through the included code step-by-step.

Step Out is used when you are inside a block of included code and want to step back to the point in your original page where you entered the included code.

Use Run to Cursor to execute up to the cursor position, without having to set a breakpoint. Note that cursor location must be beyond you. If there are breakpoints between your location and the cursor, Run to Cursor will stop at these intervening breakpoints.

Evaluating expressions and setting watches

You can use the evaluator box at the top of the Watches pane of the Debug window to evaluate arbitrary expressions when the debugger is suspended at a breakpoint. Use the evaluator when you want to know how an expression evaluates as you step through code, line by line.

Watches allow you to evaluate the same expression or variable every time you stop execution. When you set a watch, the debugger evaluates the watched expression. A hand pops up when the expression’s value changes from one line to the next as you step through code.

To set watches:

1.

Choose Debug > Watches or click the Watches button on the Debug toolbar. The

Watches pane appears.

2.

Cut and paste the expression or variable you want to watch into the list box at the top of the pane.

3.

Choose Evaluate to find the value of the expression at the next breakpoint or line where the Debugger stops.

Chapter 5: Debugging CFML Applications from Studio 63

The Evaluator window shows the results of the evaluation at the current point in processing the page.

4.

Choose Watch to add the expression in the evaluator list box to the list of watched expressions.

The Watch area shows the values of watched expressions and any error messages in resolving these parameters.

5.

Press the Start/Continue button to continue debugging.

6.

When you are finished debugging, press End.

Note

You can use the evaluator to change values of variables, create new variables, or to insert ColdFusion functions in your expressions.

Debugging across multiple pages

The debugger is active even after a page is loaded, and until you press the End button on the Debug toolbar or choose Debug > End.

This enables you to debug applications across multiple HTML and CFML pages. For example, you can test the submittal of an HTML form and its subsequent processing by a ColdFusion application page.

64

Debugger Shortcut Keys

Here is a complete listing of keyboard shortcuts.

Debugger Keyboard Commands

Command

Start/Continue

Start - No debugging

End

Restart

Step Into

Step Over

Run To Cursor

Variables

Watches

Recordsets

Stack

Output

Breakpoints

Toggle Breakpoint

Clear All Breakpoints

Debug Settings

Development Mappings

Using ColdFusion Studio

Key

Alt + R

Alt + K

Alt + P

Alt + B

Alt + X

Alt + F6

Alt + Y

Alt + M

Ctrl + F5

Ctrl + Alt + F5

Alt + F5

Ctrl + Shift + F5

Ctrl + F8

Ctrl + F9

Ctrl + F11

Alt + Q

Alt + W

C

H A P T E R

6

Chapter 6

Testing and Maintaining

Web Sites

The initial user experience that is so critical to a site’s success is often based on the visitor’s sense of how the site is performing. Testing links, evaluating page download times, checking the spelling of your content, and validating code help to ensure that user expectations are met.

As your site develops, you will inevitably need to make changes and Studio provides a powerful find and replace capability that works equally well for code and content.

Contents

Working in the Results Window ...................................................................... 66

Using Find and Replace ................................................................................... 66

Checking Spelling............................................................................................. 72

Validating Code ................................................................................................ 73

Verifying Page Links ......................................................................................... 73

Using Site View to Check Page Links .............................................................. 75

Testing Page Download Times ........................................................................ 75

66

Using ColdFusion Studio

Working in the Results Window

The Results window is a tabbed interface that opens to view the results when you run any of the following commands:

Extended Find and Replace

Code Validation

Link Verification

Image Thumbnails (see

“Adding Media Content,” in Chapter 2 for information

on using this command.)

Saving results

Results for each of these operations are preserved when you move from tab to tab and when you close the Results window. They are not saved if you repeat an operation or exit Studio. You can open the Results window at any time by clicking View > Results.

To generate an HTML document containing the Results, right-click in the Search,

Validation, or Links tab and select Browse. The document displays in the default browser.

Using Find and Replace

In word processors, the Search feature is considered an editing tool. You can certainly use it just that way while writing in Studio, but the extended search capabilities make it a powerful tool to update site content.

You can find and replace alphanumeric strings (including regular expressions) across folders and projects and choose how tags are processed by the search engine.

Search commands

Studio provides both basic and extended levels of search and replace to help you maintain your Web pages.

To search the current document:

1.

Select Search > Find (Ctrl + F) to open the Find dialog.

2.

Enter the text you want to locate in the Find what box.

If you highlight text in the editor, it displays in the Find what box.

3.

Set the Match case, Match whole words, and Direction options.

4.

Click the Find Next button to sequentially highlight each match.

5.

To resume the search from the current cursor position after the search dialog is closed, press F3.

Chapter 6: Testing and Maintaining Web Sites 67

To replace text in the current document:

1.

Select Search > Replace (Ctrl + R) to open the Replace dialog.

2.

Enter the Find and Replace text in their boxes.

3.

Set the Match case and Match whole words options.

In addition to the Up and Down Direction options, you can restrict the search to just a part of the document by highlighting a block of text in the editor and picking

Selection.

4.

You can do a selective Replace or choose to Replace All matches.

The last 10 items are saved in the Find what and Replace what dropdown lists.

Using extended search and replace features

For more complex operations across multiple documents, use the Extended Find or

Extended Replace commands. These commands offer a number of options to refine your search:

You can run either command against the current document, all open documents, folders, or projects.

Click the arrow button next to the Find what box to selectively save and reuse entries.

The In folders option lets you restrict searches to files with specified extensions and to just the root folder.

Check the Match Case option for case-sensitive searches.

Check Regular expressions to enable parsing of regular expression entries. See the section on Searching with Regular Expressions for details on Studio’s implementation of RegExp syntax.

Select the Skip Tags While Searching option to search the page content only, excluding the tags themselves. This option is not available when the Regular expressions option is enabled.

The Extended Replace dialog lets you backup files before making replacements at the folder or project level.

The Results pane displays a list of locations where the matched string was replaced.

Double-click on a match in the list to highlight it in the document. Right-click in the

Results pane to clear the pane or close it.

Note

The Extended Replace command skips read-only files.

Replacing special characters

Use the Search > Replace Special Characters command to either replace extended characters with their HTML equivalents, or replace HTML tags with the equivalent extended characters. This command works only in the current document.

68

Using ColdFusion Studio

Replacing double-spaced lines

Because of the way different operating systems treat carriage returns, text files saved on UNIX or Macintosh systems may become double-spaced when opened in Studio.

Use the Search > Replace Double Spacing with Single Spacing command to collapse double-spaced lines to single-spaced lines in the current document.

Searching with Regular Expressions

Studio supports searching with regular expressions (or RegExp) to match patterns in character strings in the Extended Find and Replace commands. Regular expressions allow you to specify all the possible variants in a search and to precisely control replacements. Ordinary characters are combined with special characters to define the pattern for the search. The RegExp parser evaluates the selected files and returns each matching pattern.

In the Find command, the matching pattern is added to the find list. In the Replace operation, it triggers insertion of the replacement string. When replacing a string, it is just as important to ensure what is not matched as what is. Simple regular expressions can be concatenated into complex search criteria. Note that enabling the Regular expressions option in the Extended dialogs disables the Skip tags while searching option.

Note

The rules listed in this section are for creating regular expressions in Studio and

ColdFusion. The rules used by other RegExp parsers may differ.

Studio’s RegExp engine processes the entire document, it does not parse on a line-byline basis. This affects the way the carat (^) and dollar sign ($) should be used.

Special characters

Because special characters are the operators in regular expressions, in order to represent a special character as an ordinary one, you need to precede it with a double backslash (\\)

Single-character regular expressions

This section describes the rules for creating regular expressions. You can use regular expressions in the Search > Extended Find and Replace commands to match complex string patterns.

The following rules govern one-character RegExp that match a single character:

Special characters are: + * ? . [ ^ $ ( ) { | \

Any character that is not a special character matches itself.

Use the keyboard (Tab, Enter) to match whitespace characters.

The asterisk (*) matches the specified characters throughout the entire document.

Chapter 6: Testing and Maintaining Web Sites 69

The carat (^) matches the beginning of the document.

The dollar sign ($) matches the end of the document.

A backslash (\) followed by any special character matches the literal character itself, that is, the backslash escapes the special character.

A period (.) matches any character, including newline. To match any character except a newline, use [^#chr(13)##chr(10)#], which excludes the ASCII carriage return and line feed codes. The corresponding escape codes are \r and \n.

A set of characters enclosed in brackets ([]) is a one-character RE that matches any of the characters in that set. For example, "[akm]" matches an "a", "k", or

"m". Note that if you want to include ] (closing square bracket) in square brackets it must be the first character. Otherwise, it won’t work even if you use

\].

Any regular expression can be followed by one of the following suffixes: {m,n} forces a match of m through n (inclusive) occurrences of the preceding regular expression. The suffix {m,} forces a match of at least m occurrences of the preceding regular expression. The syntax {,n} is not allowed.

A range of characters can be indicated with a dash. For example, “[a-z]” matches any lowercase letter. However, if the first character of the set is the caret (^), the RegExp matches any character except those in the set. It does not match the empty string. For example: [^akm] matches any character except “a”,

“k”, or “m”. The caret loses its special meaning if it is not the first character of the set.

All regular expressions can be made case insensitive by substituting individual characters with character sets, for example, [Nn][Ii][Cc][Kk].

Character classes

You can specify a character by using one of the POSIX character classes. You enclose the character class name inside two square brackets, as in this example:

“Allaire’s Web Site”,”[[:space:]]”,”*”,”ALL”

This code replaces all the spaces with *, producing this string:

Allaire’s*Web*Site

The following table shows the POSIX character classes that Studio supports.

Supported Character Classes

Character

Class

Matches

alpha upper

Matches any letter. Same as [A-Za-z].

Matches any upper-case letter. Same as [A-Z].

lower Matches any lower-case letter. Same as [a-z].

70

Using ColdFusion Studio

Supported Character Classes (Continued)

Character

Class

Matches

digit Matches any digit. Same as [0-9].

alnum xdigit space print punct graph cntrl

Matches any alphanumeric character. Same as [A-Za-z0-9].

Matches any hexadecimal digit. Same as [0-9A-Fa-f].

Matches a tab, new line, vertical tab, form feed, carriage return, or space.

Matches any printable character.

Matches any punctuation character, that is, one of ! ‘ # S % & ‘ ( ) * + , -

. / : ; < = > ? @ [ / ] ^ _ { | } ~

Matches any of the characters defined as a printable character except those defined to be part of the space character class.

Matches any character not part of the character classes [:upper:],

[:lower:], [:alpha:], [:digit:], [:punct:], [:graph:], [:print:], or [:xdigit:].

Multi-character regular expressions

You can use the following rules to build a multi-character regular expressions:

Parentheses group parts of regular expressions together into grouped subexpressions that can be treated as a single unit. For example, (ha)+ matches one or more instances of “ha”.

A one-character regular expression or grouped sub-expressions followed by an asterisk (*) matches zero or more occurrences of the regular expression. For example, [a-z]* matches zero or more lower-case characters.

A one-character regular expression or grouped sub-expressions followed by a plus (+) matches one or more occurrences of the regular expression. For example, [a-z]+ matches one or more lower-case characters.

A one-character regular expression or grouped sub-expressions followed by a question mark (?) matches zero or one occurrences of the regular expression.

For example, xy?z matches either “xyz” or “xz”.

The concatenation of regular expressions creates a regular expression that matches the corresponding concatenation of strings. For example, [A-Z][a-z]* matches any capitalized word.

The OR character (|) allows a choice between two regular expressions. For example, jell(y|ies) matches either “jelly” or “jellies”.

Chapter 6: Testing and Maintaining Web Sites 71

Braces ({}) are used to indicate a range of occurrences of a regular expression, in the form {m, n} where m is a positive integer equal to or greater than zero indicating the start of the range and n is equal to or greater than m, indicating the end of the range. For example, (ba){0,3} matches up to three pairs of the expression “ba”.

Backreferences

Studio supports backreferencing, which allows you to match text in previously matched sets of parentheses. A slash followed by a digit n (\n) is used to refer to the n th parenthesized sub-expression.

One example of how backreferencing can be used is searching for doubled words -- for example, to find instances of ‘the the’ or ‘is is’ in text. The following example shows the syntax you use for backreferencing in regular expressions:

(“There is is coffee in the the kitchen”,

”([A-Za-z]+)[ ]+\1”,”*”,”ALL”)

This code searches for words that are all letters ([A-Za-z]+) followed by one or more spaces [ ]+ followed by the first matched sub-expression in parentheses. The parser detects the two occurrences of is as well as the two occurrences of the and replaces them with an asterisk, resulting in the following text:

There * coffee in * kitchen

Anchoring a regular expression to a string

All or part of a regular expression can be anchored to either the beginning or end of the string being searched:

If a caret (^) is at the beginning of a (sub)expression, the matched string must be at the beginning of the string being searched.

If a dollar sign ($) is at the end of a (sub)expression, the matched string must be at the end of the string being searched.

Expression examples

The following examples show some regular expressions and describe what they match.

Regular Expression Examples

Expression

[\?&]value=

[A-Z]:(\\[A-Z0-9_]+)+

Description

A URL parameter value in a URL.

An uppercase DOS/Windows full path that (a) is not the root of a drive, and (b) has only letters, numbers, and underscores in its text.

72

Using ColdFusion Studio

Regular Expression Examples (Continued)

Expression

[A-Za-z][A-Za-z0-9_]*

([A-Za-z][A-Za-z0-9_]*)(\.[A-Za-z][A-Zaz0-9_]*)?

(\+|-)?[1-9][0-9]*

(\+|-)?[1-9][0-9]*(\.[0-9]*)?

(\+|-)?[1-9]\.[0-9]*E(\+|-)?[0-9]+ a{2,4}

(ba){3,}

Description

A ColdFusion variable with no qualifier.

A ColdFusion variable with no more than one qualifier, for example,

Form.VarName, but not

Form.Image.VarName.

An integer that does not begin with a zero and has an optional sign.

A real number.

A real number in engineering notation.

Two to four occurrences of ’a’: aa, aaa, aaaa.

At least three ’ba’ pairs: bababa, babababa, ...

Resources

An excellent reference on regular expressions is Mastering Regular Expressions by

Jeffrey E.F. Friedl, published by O’Reilly & Associates, Inc.

Checking Spelling

You can check the spelling of your document content and, optionally, code syntax, by using either the internal spell checker or the Microsoft Office spell checker, which is enabled if Office 95 or later is detected during installation. Open the Spelling tab in

Options > Settings (F8) > to set options.

You can download additional dictionaries for international languages and legal and medical terms from the Allaire Developer’s Exchange site.

To run the spell checker:

Click the Spell check tool button or select Tools > Spell Check (F7) or Spell

Check All. You can select commands from the Spell dialog for words not found in the dictionary.

Chapter 6: Testing and Maintaining Web Sites 73

Click the Mark spelling errors tool button or select Tools > Mark Spelling Errors

(Ctrl + F7) to toggle the display of misspellings. Right-click on a highlighted word and select from the Spelling suggested word list.

Validating Code

Studio’s code validation feature can be used to check and report on syntax errors in

HTML (including browser extensions), CFML, and SMIL. Double-click on an error message to highlight it in the document.

Open the Options > Settings (F8) Validation tab to select the validation levels for the current document. Click the Validator Settings button to review and change validation rules in the Validator Configuration dialog.

To run the validator:

Click the Validate current document toolbutton or select Tools > Validate

Document (Shift + F6). The Validation Results pane displays either a "No errors or warnings" message or lists the syntax errors it found.

Click the Tag validation icon on the Editor toolbar or Choose Tools > Validate

Current Tag (F6) to check the selected tag.

Support for the CSE Validator, used in previous releases of Studio, has been extended.

You can enable it for document level validation (HTML only) by checking the Use CSE

HTML Validator box in the Validation tab.

Verifying Page Links

Studio makes the job of maintaining internal links and links to other sites easier by letting you view and edit links in an individual document or for an entire project.

The Link Checker can verify the location of documents on Web sites, local HTML files, and dependencies for graphics and other media files. Links to secure pages (HTTPS)

FTP links, and mailto links cannot be verified. By default, all the links will be checked, but you can un-check as many links as you like to skip verifying them. Link tags in comments are not tested.

Note

Studio supports the third-party link verification tool Linkbot 4.0 from Tetranet

Software. You can use the tool via the Tools menu or the Linkbot toolbar to verify links on a single page or for an entire project. Linkbot version 4.0C is required for proper integration. You can get the most recent copy from the Linkbot site at www.linkbot.com

.

To verify links in the current document:

1.

Click the Verify Links tool button or select Tools > Verify Links. The Links tab of the

Results window opens and lists the following:

74

Using ColdFusion Studio

Source — the current document name proceeded by an icon identifying the link as a document or media file.

Link — the link as referenced in the document. Links set with the ANCHOR tag’s

NAME attribute are included.

Full URL — the path or IP address of the link.

Status — initially set to "Untested."

2.

Click the Start Link Verification button on the Link toolbar. Each link is checked in order. The Status column displays "OK" for successful links and returns a "File not found" message or the server-generated error code and message for failed links.

3.

The Stop button is enabled during the link test. Click it if you need to end the test before it completes.

Link verification options:

Select a link in the list and click the Set Full URL tool button to change the URL or the local directory Studio should use to process the relative link.

Entries made in this dialog are stored in the drop-drown list for future use.

Setting the root URL does not modify the source document, it is simply used to tell Studio how to test relative links.

Click the Set Timeout tool button to enter a time value after which the tester moves to the next link in the list.

Click the Set Proxy tool button and enter a server name and port number if the link is routed through a proxy server.

Click the Print button to produce a report of failed links.

The report displays in your default browser. You can publish the report, email it, or print it from the browser.

Right-click on a link in the list to select additional options.

Verifying links in a project:

1.

Right-click on a project name in the Projects tab of the Resource window and select Verify Links.

2.

In the Verify Links in Project dialog, choose a root URL option for the project files.

3.

Optionally set a timeout value for the processing of each link.

4.

Click OK to run verification routine.

The Results appear in the Links tab.

Chapter 6: Testing and Maintaining Web Sites 75

Using Site View to Check Page Links

Site View gives you a graphic representation of links, beginning in the current document. The configurable displays can be set to a tree view or chart view. Each link is identified by a file type icon (internal, Web, image, mailto, etc.) and the file name.

Links supported in Site View include:

Anchor tags

Image tags

APPLET tags that contain a CODE or CODEBASE attribute

FRAME tags that contain a SRC attribute

Selecting Options > Show <Title> item on the shortcut menu displays the contents of the TITLE tag instead of the link text.

To edit a link, click on it in Site View to highlight it in the document. Use the Refresh command on the shortcut menu to update the view after you make changes.

If you want to pursue links beyond the current document, double-click on a link or right-click on it and select Expand Links. The URL is processed and its links are displayed. This process can be continued across succeeding pages that themselves contain links. To view a linked page, click on the link in the Browse view of the current document.

You can drag the vertical window border to enlarge the viewing area as the link list expands. If the view gets too dense, use the Set as Root command to make the selected link the top item in the view.

Testing Page Download Times

Page download times are a frequently-cited metric of a site’s design and effectiveness.

If you are developing a public site, you need to be sensitive to achieving a balance between attractive content and tolerable page-loading times. Studio can help you find that balance by supplying real values for document download times across a range of modem speeds.

To test the current document’s download time:

1.

Select Tools > Document Weight. The file’s dependencies are listed along with file size and download times for a range of modem speeds. Tags in comments are not calculated.

2.

If the page’s download time exceeds the site’s requirements, edit the page to decrease the number or size of dependencies, and re-test.

Studio uses the Root URL setting in your FTP configuration to determine the relative path to files.

76

To set the root URL for an FTP server:

1.

Click the Remote Files tab in the Resources view.

2.

Right-click on a server name and select Server Properties.

3.

Complete the Root URL field.

Using ColdFusion Studio

C

H A P T E R

7

Chapter 7

Creating Projects for

Site Management

This chapter describes how to use the Studio’s project management tools to create, deploy, and maintain applications and Web sites.

Contents

Why Use Projects? ............................................................................................ 78

The Projects Tab ............................................................................................... 78

Managing Files in a Project ............................................................................. 78

Verifying Links in a Project .............................................................................. 80

Uploading a Project.......................................................................................... 80

78

Using ColdFusion Studio

Why Use Projects?

Organizing your documents and supporting files in a project can significantly increase your productivity in a number of ways:

Projects are created from your existing directories, so no changes to file structures are required.

Projects have no overhead costs since only a single project control file is created.

Multiple projects can be created and tracked.

Projects provide a quick and easy way to add and remove files on a site.

Maintenance chores such as search and replace operations and verifying links can be performed across an entire project.

An entire project can be deployed on the network or to a server via FTP.

Development mappings apply when browsing project files.

Projects can be integrated with version source control. You can use source control as part of team development or to keep track of changes to your site content.

The Projects Tab

Projects are created and used entirely through the Projects Resource tab. The Project

Resource tab has three panes:

The top pane is a dropdown lists of your projects.

The middle pane shows the project root and sub-folders.

The bottom pane lists the files in the selected folder.

Right-click in a pane to open it’s shortcut menu.

Managing Files in a Project

Projects are created and maintained within your existing directory structure, making it easy to control project contents. This allows you several options:

Create a new project in an existing directory, optionally including subdirectories.

Build a new directory structure specifically for the project and work directly in it or add folders and files as the project develops.

Build a project locally, on a network drive, or on a remote server.

Chapter 7: Creating Projects for Site Management 79

To create a project:

1.

Click the New Project icon at the top of the Projects window or select Projects >

New Project.

2.

Enter a project name.

3.

Enter a directory path or server name in the Location box or click the Browse button and select a location from either the Local or Remote tab.

4.

Optionally include sub-folders by clicking the checkbox.

5.

Enter file types for the project or select from the dropdown list.

6.

Click OK to create a configuration file with an apj extension is created in the selected directory. This directory becomes the project root.

Note

We recommend that you avoid using spaces in project folder and file names. Many servers do not recognize them properly.

To open a project:

1.

Click the Open Project icon or select from the dropdown list.

2.

Use the shortcut menu commands to open groups of project files in the editor.

3.

Double-click on individual files to open them.

To add a file to a project:

1.

Save the file to the project directory or move an existing file there.

2.

Select a project from the projects drop-down list.

3.

Right-click on the project and select Add Files to Project.

4.

Select files from the list. You can filter the display in the Add Files dialog by selecting from the Files of Type list.

5.

Click OK to add the file. The project configuration file is automatically updated.

Tip

The Projects > Synchronize Projects command is a quick and accurate way to automatically update a project when new files are added to the physical directories.

To remove a file from a project:

1.

Select one or more files in the file pane.

2.

Right-click and select Remove from Project.

Note

Using the Remove from Project command does not delete a file, it only removes the file from the project configuration file.

Similarly, the Delete Project command only deletes the project control file.

80

Using ColdFusion Studio

Verifying Links in a Project

Links in project files can be checked in a batch process.

To check the links in project files:

1.

Right-click in the project folder pane and select Verify Links.

2.

Select options for the files you want check.

3.

Run the verification.

See

“Verifying Page Links,” in Chapter 6 for more information on using the link

checker.

Uploading a Project

Since you can create and manage a project locally, on a network drive, or on a remote server, uploading a project really means saving the project files to the host machine. In a development environment that uses multiple servers, for example, development, testing, staging, and production servers, you can move the project through these processes using the upload options.

The project configuration file (.apj) remains on the host machine when project files are deployed.

To upload a project:

1.

Open the project in the Projects tab.

2.

Click the Upload Project tool button.

3.

Select a location for the project files.

4.

Check the appropriate file option boxes.

5.

Click OK.

Uploading large projects can take several minutes.

This procedure uploads to a single server for each upload. If you want to upload to multiple targets, you can write a script using Visual Tools Object Model (VTOM) that:

1.

Opens a project.

2.

Uploads to target 1.

3.

Uploads to target 2.

4.

Uploads to target n.

5.

Closes the project.

For details on scripting in VTOM, see

Chapter 10, “Scripting The Visual Tools Object

Model,” on page 141 .

C

H A P T E R

8

Chapter 8

Adding Source Control for

Development Projects

This chapter describes how to access a source control application in Studio to manage your ColdFusion pages and facilitate team development.

Contents

Why Use Source Control? ................................................................................ 82

Implementing a Source Control System......................................................... 82

Choosing a Source Control Provider............................................................... 83

Creating a Studio Project for Source Control ................................................. 83

Managing Files in Source Control................................................................... 86

82

Using ColdFusion Studio

Why Use Source Control?

Version source control for ColdFusion applications is an essential component for coordinating team development of complex projects. A source control system adds a layer of file management responsibility but it offers clear advantages for developers, managers, and support staff, including:

Sharing files on a LAN without overwriting work or accidentally modifying files simultaneously.

Tracking versions of files and modifications as files are changed.

Controlling the deployment of applications.

Replicating applications to a local workstation for development and testing.

Source control systems really are about control; they are designed to control file management in application development and related work. Common terms such as check-in, check-out, lock, and unlock accurately describe the security procedures required for an effective source control system.

Note

A commitment by network administrators, managers, development teams, and staff to support the system is essential to its success. Collaborative planning and implementation of a source control system ensures that user needs are truly met.

Implementing a Source Control System

There are several possible scenarios for adding source control to your application development work:

A new installation of both Studio and a source control application

Adding source control to an existing Studio installation

Adding Studio to an existing source control system

Note

The order of the steps required to use source control for Studio projects is determined by which of these scenarios applies to your development environment, but all of the following steps must be taken:

Install and configure the source control application.

Create a Studio project.

Establish a working directory.

Create a source control project or add an existing project to source control.

Add and manage project files under source control.

Chapter 8: Adding Source Control for Development Projects 83

Local and remote source control

Studio offers "local" access to a source control application on any available network drive and "remote" access, via HTTP, to a server-based system. These installations are covered in the following sections:

Local — See Adding a Studio project to source control

.

Remote — See

Setting up server-side source control

.

Standard source control commands

The standard source control commands are available to Studio projects from the main menu and the context menus in the Projects Resource tab:

Create a project and set its working directory.

Add and remove files.

Check-out a file to have exclusive editing rights.

Check-in a file to make it available to another user.

Get the latest version of a file without checking it out. You can view the file and edit it but the changes are not saved to the file in source control.

Open the source control application to set options.

Choosing a Source Control Provider

Studio uses the source-code control (SCC) interface to connect with a wide range of standard source control products including Microsoft Visual SourceSafe, Intersolv

PVCS, and StarBase Versions.

Currently, only Visual SourceSafe is supported for server-based source control systems.

Studio automatically populates a list of source control applications detected on your system. You can then select the appropriate provider from the list.

The interface and command structure for source control applications varies from vendor to vendor, so check the product documentation of your source control software for specific procedures and options.

Creating a Studio Project for Source Control

A Studio project is a collection of files that make up a development project. The actual physical location of project files and the types of files included in a project are determined by the needs of the development team. Typically, application code, documentation, media, testing materials, and other supporting files are included.

84

Using ColdFusion Studio

When you add a Studio project to source control for the first time, you are prompted to choose a source control provider based on the source control applications Studio detects on your system.

See

Chapter 7, “Creating Projects for Site Management,” on page 77

for information on projects.

Establishing a working directory

The working directory is the point of interaction for files in a project. If you create a project from an existing directory, that directory is automatically set as the working directory. You can build a working directory and create a project from it or create a new project first and then build the working directory.

The source control system is the central repository for your files once they are added to it. If you delete files from the working directory, they will not be deleted from source control unless you specifically remove them.

Note

Once you set the working directory for a project, you cannot change it. To change the working directory, you have to create a new project and move your files to that project.

Generally, you can create a working directory on your workstation to develop and test your Web applications. The following configuration is required on your system:

The working directory should be in the root of your Web server directory.

Your workstation must be running the ColdFusion Application Server (singleuser or full version) and a Web server. The Application Server should be configured to run the application that you are developing. This may mean connecting to network ODBC data sources.

To preview pages in a project, set the Project server mapping so that the working directory is mapped to the URL for your local machine.

When you get or check files out of source control, they go into that project's working directory on your local machine.

Adding a Studio project to source control

All source control work is done in Studio through the project management tools in the

Projects Resource tab. Once you have a source control system installed and a working directory configured for a Studio project, you can create a project and add it to source control. If you have an existing project that you to want put in source control, just open it instead of creating a new one in the following procedure.

Note

This procedure refers to Microsoft Visual SourceSafe dialogs and commands. You can adapt this procedure as needed to work with a different source control application.

To add a Studio project to Visual SourceSafe:

1.

Open the Projects tab.

Chapter 8: Adding Source Control for Development Projects 85

2.

Click the New Project icon and complete the New Project dialog. Be sure to enter the source control working directory in the Location field.

3.

Right-click on the project in the Projects pane and select Source Control > Choose

Source Control Provider.

4.

Right-click on the project and select Source Control > Map Project to Source

Control.

5.

Select the root project folder from the SourceSafe project to download list, then click the Browse button and select the local project folder. Click OK to complete the dialog.

6.

Right-click on the project in the Projects pane and select Source Control > Add

Project File to Source Control. This uploads the project control (apj) file.

7.

Right-click on the project in the Projects pane and select Source Control > Run

Source Control Application to manage your files.

Setting up server-side source control

Support for server-based access to Microsoft Visual SourceSafe requires ColdFusion

Server 4.0 and Studio 4.0.

Server installation:

1.

Install VSS on the ColdFusion Server machine. This is the recommended configuration. If you need to install VSS on a different machine, the ssapi.dll file must be registered on the CF Server machine and the CF RDS service must have permissions set to the VSS directories.

2.

Open the ColdFusion Administrator Source Control page to configure the remote system. This only requires entering paths to the VSS initialization file and the

Studio working directory. A default timeout is set.

Client installation:

1.

Open the Remote Files tab and, if needed, add the RDS server that you will use for source control operations.

2.

Open the Projects tab and create a new project, if necessary.

3.

Right-click on a project in the Projects tab, click the Choose Source Control

Provider command, and select the RDS server. If the server does not appear on the list, step back through the installation and check the server configuration dialog.

When these steps are completed, you can perform source control operations as on a local machine. Processing times for operations may take longer than on a local machine because of the system overhead required for HTTP access to the server.

86

Using ColdFusion Studio

Managing Files in Source Control

Although every source control system offers an array of options for managing source files, all systems provide three basic functions for files that are in the system:

Get — Copies the most recent version of a file from source control to the working directory. The default attribute is usually read-only.

Check-in — Returns the file to source control. You can set options for handling the files in your working directory, such as removing them or setting them to read-only. These options provide a level of protection if you try to work on a file that is not checked out.

Check-out — Overwrites the copy of the file on your working directory (if you chose to leave a copy there) with a read/write copy from source control. Most source control systems lock files that are checked out so that no one else can open them.

Check-in options

Some source control systems provide options for protecting the local copy of a file after it is added or checked in. The system can flag the local file as Read-Only or remove it from the local directory. If a local copy of a file is edited after it is checked in, the changes are overwritten when the file is checked out again. Check your source control system’s documentation for available options.

Command options

Studio provides a variety of ways to access source control commands:

Right-click on a file in the file pane, select Source Control on the context menu and select a command. The context menu contains the complete source control command set.

Select a file in the file pane, click Tools > Source Control on the main toolbar and select a command.

Double-click on a file to open the local copy of the file as read-only, check it out, or update the local file with the current version in source control and open it as read-only.

The availability of commands for the selected file is based on the file's current status in the source control system.

Chapter 8: Adding Source Control for Development Projects 87

Adding files and subdirectories

As your development project progresses, you can add files and subdirectories to source control.

To add a new file to source control:

1.

Save the new file in the appropriate sub-directory of the working directory.

2.

Add the file to the Studio project.

You will be prompted to add the file to source control.

To create a new subdirectory:

1.

Add the subdirectory to your working directory.

2.

Create a new folder in the correct location in the Studio project.

3.

Add a file to the subdirectory and then add the file to the appropriate folder in the

Studio directory.

4.

Add the file to source control. When you add the file, it automatically creates a new subproject for the new folder in the Studio project.

Synchronizing files

A significant feature of source control for team development is the ability to update your working directory as files are added, changed, and removed from source control by team members. You can run these maintenance procedures based on the level of source control activity of your team.

To synchronize project files with source control:

1.

Right-click on a project in the Project Folder pane to open the context menu.

2.

Select Synchronize with Source Control. The dialog contains tabs for adding and removing local files based on their status in source control.

To add files from source control to your working directory:

1.

Click the Add tab in the Synchronize Projects dialog.

The list shows files in source control that are not in your local project.

2.

Click the list check box of the files you want to add, click Add, and click Close to update the local project.

To remove local files:

1.

Click the Remove tab in the Synchronize Projects dialog.

The list shows local files that are not in the source control project.

88

Using ColdFusion Studio

2.

Click the list check box of the files you want to remove, click Remove, and click

Close to update the local project.

C

H A P T E R

9

Chapter 9

Customizing the Development

Environment

If you have used ColdFusion Studio awhile, you have probably taken advantage of its flexible interface to position toolbars, set tag color-coding, define validation levels, and a host of other options.

You can take this open interface several steps further by creating your own tag editors. Many CFML custom tag developers build tag editors to distribute with their tags. These can be identified in the Custom Tags section of Allaire’s Developer’s

Exchange by the <VTM> marker next to the tag name. You can also modify existing tag editors to suit your needs.

If you publish Web pages that require a lot of user input or if you develop ColdFusion applications, you can build custom wizards to gather user input.

Contents

The Visual Tools Markup Language (VTML).................................................. 90

Customizing Tag Chooser and Expression Builder ....................................... 90

Dialog Definition Files ..................................................................................... 91

Creating Tag Definitions .................................................................................. 93

Building Tag Editors ......................................................................................... 97

Adding Tag Help ............................................................................................. 104

VTML Container/Control Reference ............................................................ 105

Building Custom Wizards .............................................................................. 122

Creating Wizard Definition Pages ................................................................. 123

Creating Wizard Output Templates .............................................................. 129

Wizard Definition Page Library..................................................................... 133

90

Using ColdFusion Studio

The Visual Tools Markup Language (VTML)

VTML is a family of markup languages used to extend the Integrated Development

Environment (IDE) of HomeSite and ColdFusion Studio. Using VTML tags you can modify, as well as, add various elements of the IDE.

VTML can be used to customize:

Tag Inspector

Tag Tips

Tag Insight

Tag Editing Dialogs

Tag Outline Profiles

Wizards

Tag Chooser elements

Expression Builder

Customizing Tag Chooser and Expression Builder

The Tag Chooser and Expression Builder are important tools of a web developer. The

Tag Chooser is one of the primary interfaces to tag selection in ColdFusion Studio. The

Expression Builder is used to compose complex expressions in ColdFusion Studio.

Customization objective

The Tag Chooser dialog was designed to adapt flexibly to the new requirements imposed by the constant evolution of HTML and CFML, as well as to accommodate the emergence of new tag-based languages. In a similar way, the Expression Builder provides the user with a hierarchical view of various expression elements that grow with the evolution of ColdFusion, as well as other web technologies.

With the above in mind, both of the dialogs were designed to be fully customizable using VTML. The content, as well as the behavior of the dialogs is controlled by VTM templates:

MarkupTags.VTM

and

ExpressionElements.VTM

in the

\Extensions\ directory. Two VTML tags, CAT and E, let you customize the content of these dialogs.

Chapter 9: Customizing the Development Environment 91

Dialog Definition Files

The structure of the markuptags.vtm

and expressionelements.vtm

files is very simple. They both contain a set of category and element tags. Category tags can contain any number of elements or other nested category tags.

<CAT … main category>

<CAT … sub-category No.1>

<E … >

<E … >

<E … >

</CAT>

<CAT … sub-category No.2>

92

Using ColdFusion Studio

</CAT>

<E … >

<E … >

</CAT>

Every category represents a category in the category tree located on the left-hand side of the dialogs. The elements in turn represent the tags or expression elements included under each category. The following section explains how to create and update category and element tags.

Category tag

The CAT tag is used to define a category in the category tree. The following attributes can be used in the category tags.

Category Tag <CAT … >

CAPTION

DESC

The caption of the category.

The contents of the HTML help for the category. Notice that the

HELPFILE attribute can be used to specify the help as a separate file.

HELPFILE

ICON

EXPANDED

SHOWSUBELEMENTS

The relative path to the HTML help for the category.

( HELPFILE = "Docs/MyTag.htm" )

"Folder"|"Elements"|RelativeFilePath. Defines the icon used for the category. You can use a pre-defined Folder or Elements category. In addition, a relative file path can be provided to a custom BMP image (ICON ="images/custom.bmp"). By default, the Folder icon is displayed.

YES/NO Indicates that the category tree-item should be expanded the first time the dialog is displayed. By default this value is set to NO.

YES/NO. Indicates that when selected the elements of its subcategories will also be displayed on the right-hand side. For example, when the "HTML Tags" category is selected the right hand side displays all the tags included in all the HTML tag subcategories. By default, this value is set to YES.

Element tag

The E tag is used to define elements within a category. These elements are either Tags in the Tag Chooser or Expression Elements in the Expression Builder.

Chapter 9: Customizing the Development Environment 93

The following attributes define the behavior of an element:

Element Tag <E … >

CAPTION The caption of the element.

VALUE Tag Chooser — This value represents the tag string pasted when the tag is selected. If a visual editor exists for the tag, an incomplete tag string should be used to invoke the editor. For example,

VALUE="MATED"

would invoke the visual tag editor for MYTAG stored in mytag.vtm

. Expression Builder – This value represents the syntax of the expression element to be pasted into the expression textbox.

DESC The contents of the HTML help for the element. Notice that the HELPFILE attribute can be used to specify the help as a separate file.

HELPFILE The relative path to the HTML help for the element.

(

HELPFILE = "Docs/MyTag.htm"

)

Creating Tag Definitions

Various features of the development environment require the knowledge about a specific tag to operate properly. For instance the Tag Inspector feature cannot function properly unless it knows the attributes of the tag being entered. In addition, it needs to know the type of each tag attribute, and in special instances, even the enumerated values for a specific attribute. The Tag Inspector uses a set of tag definitions to learn about the specifics of various tags.

The tag definitions are stored in

\Extensions\TagDefs\

under the installation directory. VTML is used to create tag definitions. For instance, all the information about the APPLET tag is stored in

\Extensions\TagDefs\HTML\Applet.vtm

. The definition files are organized in language directories due to name conflicts between various markup languages. Users can customize existing tag definitions, as well as create new tag definition files.

Note

Whenever you make changes to a VTM file or create a new one, save the file, and then press Ctrl + Alt + Shift + C to make the changes take effect.

The following features use the tag definition files:

Tag Inspector

Tag Tips

Tag Insight

Tag Editing Dialogs

94

Using ColdFusion Studio

Creating a tag definition file

Every tag editor file contains the following markup structure:

<TAG>

<ATTRIBUTES>

… Defines tag attribute properties and behavior

</ATTRIBUTES>

<ATTRIBCATEGORIES>

… Defines logical grouping for tag attributes

</ATTRIBCATEGORIES>

<EDITORLAYOUT>

… Defines the layout of a tag editor

</EDITORLAYOUT>

<TAGLAYOUT>

… Defines the tag generation template

</TAGLAYOUT>

<TAGDESCRIPTION>

… HTML-based documentation for the tag

</TAGDESCRIPTION>

</TAG>

You can create the definition file in three ways:

Write it manually.

Create it from an existing tag definition file (a good way to learn).

Use the Tag Definitions Library dialog to add a tag and edit the generated file.

Defining attributes

The ATTRIBUTES block defines attributes inside the main TAG block. The

ATTRIBUTES block can only contain ATTRIB tags. The following example demonstrates the definition of four tag attributes: VALUE, TITLE, ALT, and ALIGN.

Chapter 9: Customizing the Development Environment 95

<ATTRIBUTES>

<ATTRIB NAME="VALUE">

<ATTRIB NAME="TITLE">

<ATTRIB NAME="ALT">

<ATTRIB NAME="ALIGN">

</ATTRIBUTES>

In most cases, features such as Tag Insight require to know more than just the names of the attribute. You can use the ATTRIB tag to define:

Attribute value types (e.g., color, file path)

Enumerated values (e.g., LEFT, RIGHT, TOP, BOTTOM for the ALIGN attribute)

Defining attribute value types

The value type for a specific attribute can be specified using the TYPE attribute in the

ATTRIB tag.

<ATTRIBUTES>

<ATTRIB NAME="VALUE" TYPE="text" />

<ATTRIB NAME="BGCOLOR" TYPE="color"/>

<ATTRIB NAME="FONTFACE" TYPE="font" />

</ATTRIBUTES>

The possible value types are:

TEXT — Free text content

ENUMERATED — A list of enumerated values

COLOR — A color value (name or hex)

FONT — Font name or font family

FILEPATH — A full file path

DIRECTORY — A directory path

FILENAME — File name only

RELATIVEPATH — A relative representation of the path

FLAG — An ON/OFF attribute containing no value

The following value types are available in ColdFusion Studio ONLY:

QUERYNAME — A ColdFusion record set name

EXPRESSION — A ColdFusion expression

Defining enumerated values

Enumerated values can be specified for attributes of TYPE="Enumerated." A subtag

ATTRIBOPTION is used to specify such values:

96

Using ColdFusion Studio

<ATTRIB NAME="CHARSET" TYPE="ENUMERATED">

<ATTRIBOPTION VALUE="iso-8859-1" CAPTION="Western" />

<ATTRIBOPTION VALUE="iso-8859-2" CAPTION="Central European (ISO)" />

<ATTRIBOPTION VALUE="iso-8859-8" CAPTION="Hebrew (ISO-Visual)" />

</ATTRIB>

The CAPTION attribute specifies the form in which the option appears in the dropdown lists while the VALUE attribute specifies the underlying value used by the attribute. The CAPTION attribute is optional.

ATTRIB Tag Attributes

NAME Name of the attribute.

TYPE (Optional) Type of the value expected for the attribute:

TEXT - free text content

ENUMERATED - a list of enumerated values

COLOR - a color value (name or hex)

FONT - font name or font family

FILEPATH - a full file path

DIRECTORY - a directory path

FILENAME - file name only

RELATIVEPATH - a relative representation of the path

FLAG - an ON\OFF attribute containing no value

CACHEFAMILY

CONTROL

Special Types Available in ColdFusion Studio ONLY:

QUERYNAME - a ColdFusion record set name

EXPRESSION - a ColdFusion expression

(Optional) The name of the cache family associated with the attribute.

(Optional) Use to populate the attribute value to a specific tag editor control when editing existing tags.

Use the following attributes to specify enumerated values:

ATTRIBOPTION Tag Attributes

VALUE

CAPTION

The value of the enumeration option.

(Optional) The visual representation of the option if different from VALUE.

Chapter 9: Customizing the Development Environment 97

Defining attribute categories

Use the ATTRIBCATEGORIES section to define attribute categories. The categories are used to organize the attributes when viewed in the Tag Inspector. The

ATTRIBCATEGORIES block can only contain ATTRIBGROUP tags. The following example demonstrates the definition of four categories.

<ATTRIBCATEGORIES>

<ATTRIBGROUP NAME="Appearance"

ELEMENTS="BACKGROUND,BGPROPERTIES,LEFTMARGIN,TOPMARGIN"/>

<ATTRIBGROUP NAME="Colors"

ELEMENTS="BGCOLOR,VLINK,ALINK,LINK,TEXT"/>

<ATTRIBGROUP NAME="Misc"

ELEMENTS="GIZMO"/>

</ATTRIBCATEGORIES>

Use the following attributes to specify the category attributes:

ATTRIBGROUP Tag Attributes

NAME

ELEMENTS

The name of the category.

The list of attributes included in the category.

Building Tag Editors

The definition of a Tag Editor is composed of three tasks:

Layout of dialog controls

Definition of how to populate controls with tag attributes

Definition of the tag generation template

Have a look at the editor file mytag.vtm

to see how this works. The following section will explain how to compose the editor file.

98

Using ColdFusion Studio

Defining controls

This section contains only two kinds of tags: CONTROL and CONTAINER tags.

CONTROL and CONTAINER tags represent graphical controls. The tags are identical in definition, with the exception that only CONTAINER tags have the capability to contain other CONTROL tags.

A Panel control is a good example of a control that can be a CONTAINER containing other CONTROLS, such as Labels or TextBoxes.

Look at the following example:

<TAG>

<EDITORLAYOUT HEIGHT=50 WIDTH=200>

<CONTAINER NAME="Panel1" TYPE="Panel" WIDTH=150 HEIGHT=50>

<CONTROL NAME="lblCode" TYPE="label" CAPTION="Code" DOWN=20

RIGHT=20 WIDTH=70/>

Chapter 9: Customizing the Development Environment

</CONTAINER>

</EDITORLAYOUT>

</TAG>

<CONTROL NAME="txtCode" TYPE="TextBox" ANCHOR="lblCode"

<CORNER="NE" WIDTH="30"/>

You can name the above template MYTAG.VTM and test it by attempting to edit an empty MYTAG tag. The tag editor dialog would look like this:

99

The example displays a single Panel CONTAINER containing Label and TextBox

CONTROLs. Only a few controls can be containers:

TabDialog — a tab dialog control capable of containing TabPage container controls.

TabPage — only used inside a TabDialog container control.

Panel — a general purpose panel container control. Can contain any regular or container controls.

You may have already noticed that the control represented by a CONTROL or a

CONTAINER tag is defined by the TYPE attribute. We can also see that WIDTH and

HEIGHT attributes determine the size.

The ANCHOR and CORNER attributes determine the point relative to which the control is positioned. The ANCHOR can be specified as the name of any control that was already laid down. The corner specifies the corner of the anchor control to be used for positioning. The possible choices are NE, NW, SE, and SW. The DOWN and RIGHT attributes then specify the pixel offset from the anchor control.

100

Using ColdFusion Studio

The following attributes are available for the Control and Container tags:

CONTROL\CONTAINER attributes

TYPE

NAME

ANCHOR

Type of the control/container. Available control types are:

Label

TextBox

CheckBox

RadioGroup

DropDown

TextArea

FontPicker

ColorPicker

Image

FileBrowser

SQLTextArea

ActiveX

Available container types are:

Panel

TabDialog

TabPage

Name of the control.

(Optional) The name of the control relative to which control is positioned. If omitted, control is positioned relative to the upper left corner of its container.

CORNER

DOWN

RIGHT

(Optional) Corner of the ANCHOR control relative to which offset position is calculated (NW, NE, SW, SE). The default is NW, the upper-left corner.

Offset in pixels down from the anchor point (corner).

Offset in pixels right from the anchor point (corner).

Chapter 9: Customizing the Development Environment 101

CONTROL\CONTAINER attributes (Continued)

WIDTH

HEIGHT

LFWIDTH

LFHEIGHT

Width of the control.

Can be specified in three ways:

In pixels (e.g., WIDTH=200).

As the name of another control (e.g.,

WIDTH="SomeControl"). In this case the width of the specified control is used. The control must be already positioned.

Set to maximum (WIDTH="MAXIMUM"). Stretches control to the right boundary of its container.

Height of the control.

Can be specified in three ways:

In pixels (e.g., HEIGHT =200).

As the name of another control (e.g., HEIGHT

="SomeControl"). In this case the height of the specified control is used. The control must be already positioned.

Set to maximum (HEIGHT ="MAXIMUM"). Stretches control to the bottom boundary of its container.

Width of the control used when user’s system is set to use large fonts.

Height of the control used when user’s system is set to use large fonts.

MAXWIDTHPADDING Used with WIDTH=MAXIMUM. Specifies the padding in pixels from the container’s right boundary.

MAXHEIGHTPADDING Used with HEIGHT=MAXIMUM. Specifies the padding in pixels from the container’s bottom boundary.

Populating dialogs with tag data

Once the layout of controls is completed one needs to define the way in which the editor controls are populated when you are editing an existing tag. This is done in the

ATTRIBUTES block of the main tag editor template.

The ATTRIBUTES block can only contain ATTRIB tags. The ATTRIB tag defines the way tag attribute values get filled into the dialog controls.

102

Using ColdFusion Studio

<ATTRIBUTES>

<ATTRIB NAME="VALUE" CONTROL="txtName"/>

<ATTRIB NAME="TITLE" CONTROL="txtTitle"/>

<ATTRIB NAME="TITLE" CONTROL="txtTitle2"/>

<ATTRIB NAME="ALT" CONTROL="txtAltText"/>

<ATTRIB NAME="ALIGN" CONTROL="dropAlign"/>

</ATTRIBUTES>

The name attribute of the ATTRIB tag specifies the name of the attribute, while

CONTROL specifies which control the value of that attribute should be assigned to.

Notice that you can have multiple ATTRIB tags with the same NAME. This is common for more complex tag editor dialogs where a single attribute value may have to be filled into multiple controls.

Special $$TAGBODY attribute name

There is one special tag attribute name ($$TAGBODY) which is used when a control needs to be populated by the body of a tag. An example of such a tag editor is the editor for the HTML tag TEXTAREA. The body of the TEXTAREA tag is filled into the txtTextAreaContent control using the following ATTRIB tag.

<ATTRIB NAME="$$TAGBODY" CONTROL="txtTextAreaContent"/>

Generating a tag

The final stage in the process of building a tag editor is the definition of how a tag gets generated from the date entered into the editor controls. The tag generation logic is stored in the TAGLAYOUT block. This block contains a short template used to generate the final tag string. The markup language used the TAGLAYOUT template that was originally designed for wizards and was therefore called Wizard markup language

(WIZML). Because of this, all the tags in this section begin with the WIZ prefix.

Consult the section for more info on WIZML. A good way to get started is to have a look at the TAGLAYOUT sections of existing HTML tag editors located in the

\Extensions\TagDefs\HTML

directory in the main installation directory.

Variables passed to the layout template

WIZML is described in a separate section though a few things should be noticed.

WIZML supports variables as well as functions. The value of each control of the tag editor is passed to the template using a variable with the same name. Therefore a

ColorPicker named colorBGColor will pass its value in colorBGColor variable. The

TAGLAYOUT template can then use this data to generate the tag string.

<TAGLAYOUT>

<MYTAG COLOR="$${colorBGColor}">

</TAGLAYOUT>

The above example shows a simple layout template for a hypothetical tag with a single attribute COLOR. Notice that in WIZML variables are embedded using the $${}

Chapter 9: Customizing the Development Environment 103 delimiters. If the user chose White in the colorBGColor ColorPicker, the above template would generate the following tag:

<MYTAG COLOR="White">

Special variables

In addition to the CONTROL variables, a few other parameters get sent to the tag layout template:

OPTIONLowerCaseTags — Returns ‘true’ or ‘false’. Specifies whether the tag should be generated using lowercase.

OPTIONLinearLayout — Returns ‘true’ or ‘false’. Specifies whether the tag should be generated with its attributes in a single line or indented vertically.

TAGDATAUnknownAttributes — A string containing all attributes which were contained in the edited tag string but are not recognized by the editor.

Using OPTIONLowerCaseTags

This parameter can be used to create a layout template, which generates a tag in lower or upper case based on user preferences. Here is a version of the MAYTAG layout template responding to case preferences:

<TAGLAYOUT>

<WIZIF OPTIONLowerCaseTags EQ ’true’>

<mytag color="$${colorBGColor}">

<WIZELSE>

<MYTAG COLOR="$${colorBGColor}">

</WIZIF>

</TAGLAYOUT>

Using OPTIONLinearLayout

Some people like their tag attributes in a single line while others like them indented.

Here is a version of the MAYTAG layout template responding to such preferences:

<TAGLAYOUT>

<WIZIF OPTIONLinearLayout EQ ’true’>

<WIZSET Spacer = ’ ’ >

<WIZELSE>

<WIZSET Spacer = Chr(13) & Chr(10) & ’ ’ >

</WIZIF>

<MYTAG COLOR="$${clrBGColor}"$${Spacer}FACE="$${fontFace}

"$${Spacer}SIZE="$${txtSize}">

</TAGLAYOUT>

The template would generate a tag based on the following layout preference:

104

Using ColdFusion Studio

LINEAR:

<MYTAG COLOR="White" FACE="Arial" SIZE="10">

NONLINEAR:

<MYTAG COLOR="White"

FACE="Arial"

SIZE="10">

Using TAGDATAUnknownAttributes

The TagDataUnknownAttributes tag contains the list of attributes that are contained in the original tag string but are not supported by the editor. For example, you may write an editor for the HTML tag INPUT. You may provide editing capabilities for all basic attributes, however the editor will not cover JavaScript event attributes (for example, onCLick= …, etc.) In order not to lose these "unknown" attributes during the editing process, the editor engine creates the TAGDATAUnknownAttributes variable containing a list of unknown attributes together with their original values. You can use this variable to ‘stamp’ all the unsupported attributes at the end of the tag you are generating.

<TAGLAYOUT>

<MYTAG COLOR="$${colorBGColor}"

<WIZIF TAGDATAUnknownAttributes NEQ

""> $${TAGDATAUnknownAttributes}</WIZIF>>

</TAGLAYOUT>

If you edited a tag <MYTAG COLOR="Blue" onClick="CallThis">, the above template would preserve the onClick attribute despite the fact that it is not supported in the editor. The editor is also intelligent enough to list the unknown attributes in a linear or indented format based on a user’s layout preferences, as described in the previous section.

Adding Tag Help

You can associate an HTML-based help document with a tag by embedding the help text inside the TAGDESCRIPTION block.

Here’s an example of a tag description block and the result in a Tag Editor:

<TAGDESCRIPTION HEIGHT=100>

<B>CFAPPLICATION</B>

<P>Defines scoping for a ColdFusion application and enables or disables storing client variables in the system registry. By default, client variables are disabled.

CFAPPLICATION is typically used in the Application.cfm

file to set defaults for a specific ColdFusion application.

</TAGDESCRIPTION>

Chapter 9: Customizing the Development Environment 105

Providing help from an external file

As the help content grows, it may become cumbersome to specify the entire body of the help inside the TagDescription block. In addition, large bodies of help embedded in the editor file will cause the editor dialog to open more slowly as more markup has to be parsed to compose the editor. Under these circumstances, it advisable to provide large help contents in a separate HTML file. Such files can then be referenced using a relative path from the tag editor template.

For example:

<TAGDESCRIPTION HELPFILE="Docs/TagHelpFile.htm"/>

VTML Container/Control Reference

This section contains the complete syntax, with examples, for VTML containers and controls.

TabDialog container

<CONTAINER TYPE="TabDialog" …

TabDialog control is a special container control, because it can only contain <CONTAINER

TYPE="TabPage"> tags. This is natural because one needs to specify the tab pages before embedding more controls on the tab dialog itself.

106

Using ColdFusion Studio

TabDialog example:

<CONTAINER NAME="MainTabDialog" TYPE="TabDialog" WIDTH=MAXIMUM

HEIGHT=MAXIMUM>

<CONTAINER NAME="TabPage1" TYPE="TabPage" CAPTION="TEXTAREA Tag">

... embedded controls

</CONTAINER>

<CONTAINER NAME="TabPage2" TYPE="TabPage" CAPTION="Content">

... embedded controls

</CONTAINER>

</CONTAINER>

TabPage container

<CONTAINER TYPE="TabPage" …

TabPage control is also special because it can only be contained inside a TabDialog

CONTAINER control.

CAPTION Caption displayed on the top of the tab.

Chapter 9: Customizing the Development Environment

TabPage example:

<CONTAINER NAME="MainTabDialog" TYPE="TabDialog" WIDTH=MAXIMUM

HEIGHT=MAXIMUM>

<CONTAINER NAME="TabPage1" TYPE="TabPage" CAPTION="TEXTAREA Tag">

... embedded controls

</CONTAINER>

<CONTAINER NAME="TabPage2" TYPE="TabPage" CAPTION="Content">

... embedded controls

</CONTAINER>

</CONTAINER>

107

Panel container

<CONTAINER TYPE="Panel" …

Panel is the most common container control. Panel can contain any control or container except TabPage, which is restricted to TabDialog.

CAPTION Caption displayed in the upper left corner of the panel boundary.

Panel example:

<EDITORLAYOUT HEIGHT=225>

108

Using ColdFusion Studio

<CONTAINER NAME="MainTabDialog" TYPE="TabDialog" WIDTH=MAXIMUM

HEIGHT=MAXIMUM>

<CONTAINER NAME="TabPage1" TYPE="TabPage" CAPTION="MYTAG Tag">

<CONTAINER NAME="Panel1" TYPE="Panel" DOWN=5 RIGHT=10

WIDTH="MAXIMUM" HEIGHT=125>

<CONTROL NAME="lblSource" TYPE="Label" CAPTION="Source:"

DOWN=17 RIGHT=10 WIDTH=50/>

<CONTROL NAME="txtSource" TYPE="TextBox" ANCHOR="lblSource"

CORNER="NE" WIDTH="MAXIMUM"/>

<CONTROL NAME="lblAlign" TYPE="Label" CAPTION="Align:"

ANCHOR="lblSource" CORNER="SW" DOWN=11 WIDTH=50/>

<CONTROL NAME="dropAlign">TYPE="DropDown" ANCHOR="lblAlign"

CORNER="NE" WIDTH=100>

<ITEM VALUE="TOP" CAPTION="TOP" />

<ITEM VALUE="MIDDLE" CAPTION="MIDDLE" SELECTED/>

<ITEM VALUE="BOTTOM" CAPTION="BOTTOM" />

</CONTROL>

</CONTAINER>

<CONTAINER NAME="Panel2" TYPE="Panel" CAPTION=" Panel 2 "

ANCHOR="Panel1" CORNER="SW" DOWN=5 WIDTH="MAXIMUM"

HEIGHT=MAXIMUM

</CONTAINER>

</CONTAINER>

<CONTAINER NAME="Advanced" TYPE="TabPage" CAPTION="Advanced">

</CONTAINER>

</CONTAINER>

</EDITORLAYOUT>

Chapter 9: Customizing the Development Environment 109

Label control

<CONTROL TYPE="Label" …

Panel is the most common container control. Panel can contain any control or container except TabPage, which is restricted to TabDialog.

CAPTION The text displayed by the label.

AUTOSIZE YES/NO. Automatically sizes the control to the text it contains. This option is overridden if WIDTH or HEIGHT are explicitly specified.

TRANSPARENT YES/NO. Makes label transparent.

ALIGN LEFT/CENTER\RIGHT. Specifies the horizontal alignment of text in the label.

VALIGN TOP/CENTER\BOTTOM. Specifies the vertical alignment of text in the label.

Label example:

<CONTROL NAME="lblSource" TYPE="Label" CAPTION="Source:" DOWN=17 RIGHT=10

WIDTH=50/>

110

Using ColdFusion Studio

TextBox control

<CONTROL TYPE="TextBox" …

A simple textbox control.

VALUE

AUTOSIZE

EDITABLE

AUTOSELECT

MAXLENGTH

PASSWORDCHAR

CHARCASE

VALIGN

The text displayed by the textbox.

YES/NO. Automatically sizes the control to the text it contains.

This option is overridden if WIDTH or HEIGHT are explicitly specified.

YES/NO. Enables or disables editing.

YES/NO. Decides whether contents get highlighted when the cursor enters the textbox.

Limits the amount of text in the textbox to a specific number of characters.

A character to be used to mask entered text. You can create a simple password box using PASSWORDCHAR="*".

NORMAL\UPPER\LOWER. Specifies whether entered text is automatically uppercased of lowercased. The default is

NORMAL, preserving entered case.

TOP/CENTER/BOTTOM. Vertical alignment of text in the label.

TextBox example

<CONTROL NAME="lblSource" TYPE="Label" CAPTION="Source:" DOWN=17 RIGHT=10

WIDTH=50/>

<CONTROL NAME="txtSource" TYPE="TextBox" VALUE="Some Value"

ANCHOR="lblSource" CORNER="NE" WIDTH="MAXIMUM"/>

Chapter 9: Customizing the Development Environment 111

DropDown control

<CONTROL TYPE="DropDown" …

A drop-down listbox. This tag requires <ITEM> sub-tags, which specify the list of items in the drop-down list. The item tag has CAPTION and VALUE attributes. CAPTION specifies the visible item text while VALUE specifies the underlying value for the option. SELECTED attribute specifies which item is initially selected. Then free-text is entered into an

EDITABLE DropDown, the actual text is considered to be the value of the control.

Example:

<CONTROL NAME="dropTagOptions" TYPE="DropDown" WIDTH="200">

<ITEM CAPTION="option1" VALUE="Value1"/>

<ITEM CAPTION="option2" VALUE="Value2" SELECTED/>

<ITEM CAPTION="option3" VALUE="Value3"/>

</CONTROL>

EDITABLE The EDITABLE attribute decides whether it behaves like an editable combo-box or a fixed listbox.

DropDown example

<CONTROL NAME="lblAlign"

TYPE="Label" CAPTION="Align:"

ANCHOR="lblSource" CORNER="SW" DOWN=11 WIDTH=50/>

<CONTROL NAME="dropAlign"

TYPE="DropDown" ANCHOR="lblAlign" CORNER="NE" WIDTH=100>

<ITEM VALUE="TOP" CAPTION="TOP" />

<ITEM VALUE="MIDDLE" CAPTION="MIDDLE" SELECTED/>

<ITEM VALUE="BOTTOM" CAPTION="BOTTOM" />

</CONTROL>

112

Using ColdFusion Studio

FontPicker control

<CONTROL TYPE="FontPicker" …

A simple drop-down list font picker.

EDITABLE The EDITABLE attribute decides whether a font name can be entered manually into the listbox.

FontPicker example

<CONTROL NAME="lblFace" TYPE="Label" CAPTION="Font:" DOWN=17 RIGHT=10

WIDTH=50/>

<CONTROL NAME="fontFace" TYPE="FontPicker" ANCHOR="lblFace" CORNER="NE"

WIDTH="MAXIMUM"/>

Chapter 9: Customizing the Development Environment

ColorPicker control

113

<CONTROL TYPE="ColorPicker" …

A simple drop-down color picker. Enables selection of a predefined color or special color code. Control returns value as a color name or hexadecimal value based on user’s preferences.

ColorPicker example

<CONTROL NAME="lblColor" TYPE="Label" CAPTION="Color:" ANCHOR="lblFace"

CORNER="SW" DOWN=11 WIDTH=50/>

<CONTROL NAME="colorColor" TYPE="ColorPicker" ANCHOR="lblColor"

CORNER="NE" WIDTH="MAXIMUM"/>

<CONTROL NAME="lblColor" TYPE="Label" CAPTION="Color:" ANCHOR="lblFace"

CORNER="SW" DOWN=11 WIDTH=50/>

<CONTROL NAME="colorColor" TYPE="ColorPicker" ANCHOR="lblColor"

CORNER="NE" WIDTH="MAXIMUM"/>

114

Using ColdFusion Studio

CheckBox control

<CONTROL TYPE="CheckBox" …

A simple checkbox control. Returns ‘true’ or ‘false’.

CAPTION Caption displayed next to the checkbox.

CHECKED YES/NO. Specifies initial status.

Checkbox example

<CONTROL NAME="checkNoShading"TYPE="CheckBox" CAPTION=" No Shading"

ANCHOR="numWidth" CORNER="NE" DOWN=4 RIGHT=20 WIDTH=MAXIMUM/>

Chapter 9: Customizing the Development Environment

RadioGroup control

<CONTROL TYPE="RadioGroup" …

A set of radio buttons. This tag requires <ITEM> sub-tags that specify the list of radio buttons. The item tag has CAPTION and VALUE attributes. CAPTION specifies the caption of the radio button, VALUE specifies the underlying value for the option.

The SELECTED attribute specifies which radio options should be pre-selected.

Example:

<CONTROL NAME="radioTagOptions" TYPE="RadioGroup" WIDTH="200">

<ITEM CAPTION="option1" VALUE="Value1"/>

<ITEM CAPTION="option2" VALUE="Value2" SELECTED/>

<ITEM CAPTION="option3" VALUE="Value3"/>

</CONTROL>

RadioGroup example

<CONTROL NAME="radioNameConflict"

TYPE="RadioGroup" CAPTION="Radio One"

ANCHOR="lblAccept" CORNER="SW" DOWN=35

HEIGHT=MAXIMUM WIDTH=MAXIMUM

<ITEM VALUE="ERROR" CAPTION="ERROR – The file will not be saved and ColdFusion will return an error." SELECTED="TRUE"/>

<ITEM VALUE="SKIP" CAPTION="SKIP – Neither saves the file nor throws an error."/>

<ITEM VALUE="OVERWRITE" CAPTION="OVERWRITE -

Replaces the existing file if name conflict occurs." />

115

116

Using ColdFusion Studio

<ITEM VALUE="MAKEUNIQUE" CAPTION="MAKEUNIQUE - Automatically generates a unique filename for the upload." />

</CONTROL>

TextArea control

<CONTROL TYPE="TextArea” …

A simple multi-line text entry control.

SCROLLBAR

WRAP

NONE/HORIZONTAL/VERTICAL/BOTH. Specifies which scrollbars should be displayed.

YES/NO. Enables wrapping of text.

TextArea example

<CONTROL NAME="txtContent" TYPE="TextArea"

DOWN=5 RIGHT=5

WIDTH=MAXIMUM HEIGHT=MAXIMUM

MAXWIDTHPADDING=5 MAXHEIGHTPADDING=5/>

Chapter 9: Customizing the Development Environment 117

SQLTextArea control

<CONTROL TYPE="SQLTextArea" … (ColdFusion Studio ONLY)

A multi-line text entry control that allows the user to execute an SQL statement. The control contains a button that the user can use to invoke the query builder.

SCROLLBAR NONE/HORIZONTAL/VERTICAL/BOTH. Specifies which scrollbars should be displayed.

DSNAMECONTROL

QUERYNAMECONTROL

WRAP

The name of the control that should be populated with the

Data Source name when a query is selected.

The name of the control that should be populated with the

Query Name when a query is selected.

YES/NO. Enables wrapping of text.

SQLTextArea example

<CONTAINER NAME="TabPage1" TYPE="TabPage" CAPTION="CFQUERY Tag">

<CONTAINER NAME="Panel1" TYPE="Panel" DOWN=5 RIGHT=10

WIDTH="MAXIMUM" HEIGHT=80>

<CONTROL NAME="lblQueryName"

TYPE="Label" CAPTION="Query Name:"

DOWN=17 RIGHT=10 WIDTH=80/>

<CONTROL NAME="lblDataSource"

TYPE="Label" CAPTION="Data Source:"

ANCHOR="lblQueryName" CORNER="SW"

DOWN=10 RIGHT=0 WIDTH=80/>

<CONTROL NAME="txtQueryName" TYPE="TextBox" ANCHOR="lblQueryName"

118

Using ColdFusion Studio

CORNER="NE" WIDTH=130/>

<CONTROL NAME="txtDataSource" TYPE="TextBox"

ANCHOR="lblDataSource" CORNER="NE" WIDTH=130/>

<CONTROL NAME="lblMaxRows" TYPE="Label" CAPTION="Max Rows:"

ANCHOR="txtQueryName" CORNER="NE" DOWN=0 RIGHT=10 WIDTH=70/>

<CONTROL NAME="lblTimeout" TYPE="Label" CAPTION="Timeout:"

ANCHOR="txtDataSource" CORNER="NE" DOWN=0 RIGHT=10 WIDTH=70/>

<CONTROL NAME="numMaxRows" TYPE="TextBox" ANCHOR="lblMaxRows"

CORNER="NE" WIDTH=30/>

<CONTROL NAME="numTimeout" TYPE="TextBox" ANCHOR="lblTimeout"

CORNER="NE" WIDTH=30/>

<CONTROL NAME="checkDebug" TYPE="CheckBox" CAPTION="Print debug info" ANCHOR="numTimeout" CORNER="NE" RIGHT=10 DOWN=4

WIDTH=MAXIMUM/>

</CONTAINER>

<CONTROL NAME="lblSQLStatement" TYPE="Label" CAPTION="SQL

Statement:" ANCHOR="Panel1" CORNER="SW"DOWN=10 RIGHT=0

WIDTH=110/>

<CONTROL NAME="txtSQLStatement" TYPE="SQLTextArea"

ANCHOR="lblSQLStatement" CORNER="SW" DOWN="8" WIDTH=MAXIMUM

HEIGHT=MAXIMUM DSNAMECONTROL="txtDataSource"

QUERYNAMECONTROL="txtQueryName"/>

</CONTAINER>

Chapter 9: Customizing the Development Environment 119

FileBrowser control

<CONTROL TYPE="FileBrowser" …

A textbox used to enter a file path. The control contains two toolbar buttons providing accessibility to local and remote file/directory browsing.

CAPTION

FILTER

The window caption that should displayed in the file/directory browsing dialogs. For example: CAPTION="Select File You Want

Uploaded".

The file filter that should be used by the file/directory browsing dialogs. For example: FILTER="*.gif;*.jpeg;*.jpg".

120

Using ColdFusion Studio

<CONTROL TYPE="FileBrowser" … (Continued)

DIRONLY

FILENAMEONLY

RELATIVE

YES/NO. Specifies that a directory is being selected. This option will convert the file dialogs accessible from the browse buttons to become directory-browsing dialogs. By default, file-browsing is assumed.

YES/NO. Specifies that only a file name should be entered into the textbox when a file is specified in a local or remote file dialog. By default the entire path would be pasted. The attribute is irrelevant when the DIRONLY attribute is used.

YES/NO. Instructs the control to calculate the relative path when a file or a directory path is selected. The relative path is calculated relative to the file currently opened. When a new file is being edited, it first has to be saved before a relative path can be calculated. By default, the absolute path is assumed.

FileBrowser example

<CONTROL NAME="lblSource" TYPE="Label"

CAPTION="Source:" DOWN=17 RIGHT=10

WIDTH=60/>

<CONTROL NAME="txtSource" TYPE="FileBrowser" ANCHOR="lblSource"

CORNER="NE" WIDTH="MAXIMUM" RELATIVE

FILTER="*.htm;*.html;*.cfml;*.cfm;*.asp" />

Chapter 9: Customizing the Development Environment 121

Image control

<CONTROL TYPE="Image" …

An image control capable of containing BMP images.

FILEPATH

AUTOSIZE

Specifies the relative path of the image file from the editor template.

YES/NO. Automatically sizes the control to the image it contains. This option is overridden if WIDTH or HEIGHT are explicitly specified.

TRANSPARENT YES/NO. Controls transparency.

CENTER YES/NO. Centers the image.

Image example

<CONTROL NAME="imgApplet" TYPE="Image" FILEPATH="Images/Applet.bmp"

DOWN=10 RIGHT=10 AUTOSIZE="Yes"/>

122

Using ColdFusion Studio

ActiveX control

<CONTROL TYPE="ActiveX" …

A container for an embedded ActiveX control. For an ActiveX control to function properly within a tag editor the ActiveX control must implement four methods:

• void SetValue(LPCTSTR sValue) - called to set the control value.

BSTR GetValue() - called to retrieve the control value.

• void SetFocus() - called to set focus to the control.

• void IntitializeFromMarkup(LPCTSTR strMarkup) – called to initialize the ActiveX control with the CONTROL tag in the Custom Markup application.

PROGID The ProgID of the ActiveX control.

ActiveX example

<CONTROL NAME="activexGizmoPicker" TYPE="ActiveX"

PROGID="company.Gizmo"/>

Building Custom Wizards

This section describes how to give users an easy way to enter information that can then be published on the Web or used to drive ColdFusion applications. Wizards are an integral part of many software products today because they invite users to perform complex tasks in an orderly, comprehensible interface. Another benefit is that a welldesigned wizard controls its input and ensures a high probability of user success.

Allaire makes extensive use of wizards in HomeSite and Studio and now extends that capability to developers. If you have worked with VTML to create or edit tag dialogs, you are familiar with building interface containers and controls and with defining page layout. You can now add the Wizard Markup Language (WIZML) to your skill set and add wizards to your applications.

To create a wizard:

1.

Write a wizard definition file (.vtm) to specify the pages, parameters, output, and logical flow.

2.

Implement one or more output template files (.wml) for the wizard.

3.

Create wizard graphic (.bmp) files.

Each of these steps is described in detail in the following sections.

Chapter 9: Customizing the Development Environment 123

Saving wizard files

The recommended way to organize wizards and supporting files is to save the .vtm and

.wml files in the

\Wizards\Custom

folder and to save the image files in the

\Wizards\Images

folder of your Studio directory.

Creating Wizard Definition Pages

The first step in building a custom wizard is to write a VTML file to define the interface and output parameters. This section describes the VTML tags used in this part of the process and presents an example definition file.

VTML for Wizards tag summary

The following is the hierarchy of the tag set for wizard definition files:

WIZARD — The enclosing tag for the entire file; it defines the new wizard with a name, caption and default image.

PARAM — When used as a sub-tag of the WIZARD tag, it defines a parameter that the wizard uses to generate its output. These parameters are then available for use with wizard output templates.

TEMPLATE — Defines an output template and identifies the file used for text output.

PAGE — Defines a wizard page that determines which page class to load.

PARAM — When used as a sub-tag of the PAGE tag, it sets the behavior of a page class.

This is useful for standard pages which are intended to be re-used across multiple wizards.

INPUT — Defines an input control on a wizard page. If the NAME attribute of the

INPUT control matches both the name of a control on the wizard page as well as the name of a PARAM defined within the WIZARD tag then the control is automatically

‘bound’ to the underlying parameter without requiring any explicit code.

NEXTPAGE — The NEXTPAGE tag allows for complex routing between pages based on the value of conditional expressions.

PAGELAYOUT — Same as VTML syntax for containers and controls.

VTML for Wizards tag reference

The following tables provide the complete VTML syntax for writing wizard definition files.

124

Using ColdFusion Studio

WIZARD

Attribute

NAME

CAPTION

IMAGE

Description

Optional. Used to resolve the names of pages that belong to a specific wizard. May be registered using the syntax

WizardName.PageName.

Optional. Caption to display in the wizard’s title bar.

Optional. Default bitmap to use for pages within the wizard.

PARAM (for WIZARD tag)

Attribute

NAME

VALUE

REQUIRED

Description

Name of the parameter.

Initial value of the parameter.

Optional. The wizard manager will not enable the Finish button until all required parameters are entered.

TEMPLATE

Attribute

NAME

OUTPUTFILE

OUTPUTPATH

DESCRIPTION

Description

File name of the wizard (.wml) output template.

Name of the file to which output to based on the results of processing the template.

Optional. Output directory for the file. Defaults to the value of the variable

LOCATION

. Note that you must provide a wizard page where the user can specify this value.

Optional. Description of the wizard page’s function for use in the output summary page.

Chapter 9: Customizing the Development Environment

PAGE

Attribute

TYPE

NAME

CAPTION

IMAGE

CONDITION

NEXTPAGE

Description

Required for dynamic wizards.

"Dynamic" - VTML layout

"PageName" - from Page Library (see the Wizard Definition

Page Library section below)

Name of the page.

Caption to display in the top portion of the page.

Optional. Override of the default wizard bitmap.

Optional. Conditional expression which determines if the page is displayed.

Optional. Name of page to go to after the current one. The default page is to the next page defined in the configuration file.

PARAM (for PAGE tag)

Attribute

NAME

VALUE

Description

Name of the parameter.

Value of the parameter.

INPUT

Attribute

NAME

PARAM

DEFAULT

REQUIRED

Description

Name of the form control to which the

INPUT

is bound.

Optional. Name of parameter to which the INPUT is bound.

Defaults is the NAME attribute).

Optional. Default value for the input.

Optional. Is the input required?

125

126

Using ColdFusion Studio

Attribute

VALIDATIONMSG

LISTCONTENTS

Description (Continued)

Optional. A message to display to the user if the input is required and a value is not entered.

Optional. If this is TCustomListBox or TCustomComboBox based input, then a comma-separated list will be used to populate the list with values.

NEXTPAGE

Attribute

NAME

CONDITION

Description

Name of a page to go to next.

Conditional expression that determines whether to go to the page.

If multiple NEXTPAGE tags are specified, then the first one to match a CONDITION will be the next page.

Dynamic expressions in tags

Any tag attribute may combine static, constant text with embedded dynamic expressions that reference parameters or input controls. To embed an expression within a text string, the following syntax is utilized:

$${ expression }

So, for example, to set the REQUIRED attribute of a parameter based on whether another value was set, you would use the following syntax:

<PARAM NAME="RowsPerPage" VALUE="10"

REQUIRED="$${ ParameterExists(’Customize’) }">

Or, to customize the OUTPUTFILE attribute of the TEMPLATE tag using a name attribute entered by the user, you would use the following syntax:

OUTPUTFILE="$${Name}Admin.cfm">

The expression syntax supported within the wizard configuration file is the same as the one supported in wizard output templates (see the reference section for more details).

Bound controls

One of the most powerful capabilities of wizard pages are bound controls. Bound controls allow you to place controls onto the wizard page and have their values automatically bound to wizard parameters. To do this, simply add an INPUT sub-tag to the PAGE tag for each control you wish to bind, making sure that the NAME attribute of the INPUT tag matches the Name property of the control. All controls specified in the layout can be bound.

Chapter 9: Customizing the Development Environment

Wizard definition page example

This sample wizard creates an HTML template.

<WIZARD NAME=”DefaultTemplate” CAPTION=”Default HTML Template”>

<!--- wizard parameters --->

<PARAM NAME=”sDocType” VALUE=”HTML 4.0” REQUIRED=”true”>

<PARAM NAME=”sTitle” VALUE=””>

<PARAM NAME=”bMetaDescr” VALUE=”false”>

<PARAM NAME=”sMetaDescr” VALUE=””>

<PARAM NAME=”bMetaKeywords” VALUE=”false”>

<PARAM NAME=”sMetaKeywords” VALUE=””>

<!--- WIZARD PAGE --->

<!--- attributes page --->

<PAGE NAME=”DocAttribs” TYPE=”DYNAMIC”

CAPTION=”HTML Document Attributes”

IMAGE=”..\\images\\main.bmp”>

<PAGELAYOUT>

<CONTROL NAME=”lblDocType” TYPE=”label”

DOWN=”10” RIGHT=”10”

WIDTH=”90”

CAPTION=”Document Type:”

/>

<CONTROL NAME=”ddDocType” TYPE=”DropDown”

EDITABLE=”no”

ANCHOR=”lblDocType” corner=”NE” WIDTH=”MAXIMUM” down=”-5”>

<ITEM CAPTION=”HTML 2.0” VALUE=”HTML 2.0”/>

<ITEM CAPTION=”HTML 3.2” VALUE=”HTML 3.2”/>

<ITEM CAPTION=”HTML 4.0” VALUE=”HTML 4.0”/>

</CONTROL>

<CONTROL NAME=”lblTitle” TYPE=”label”

ANCHOR=”lblDocType” CORNER=”SW” down=”20”

WIDTH=”90”

CAPTION=”Title:”

/>

<CONTROL NAME=”tbTitle” TYPE=”TextBox”

ANCHOR=”lblTitle” CORNER=”NE” WIDTH=”MAXIMUM” down=”-5”

/>

<CONTAINER NAME=”pnlMetaDescription” TYPE=”Panel”

CAPTION=”Meta Description”

ANCHOR=”lblTitle” CORNER=”SW” DOWN=”20”

WIDTH=”MAXIMUM” MAXWIDTHPADDING=”10” HEIGHT=”80”

LFHEIGHT=”90”>

<CONTROL NAME=”chkMetaDescr” TYPE=”CheckBox”

CAPTION=”Add meta description:”

127

128

Using ColdFusion Studio

DOWN=”20” RIGHT=”15”

WIDTH=”MAXIMUM”/>

<CONTROL NAME=”tbMetaDescr” TYPE=”TextBox”

ANCHOR=”chkMetaDescr” CORNER=”SW” DOWN=”8”

WIDTH=”MAXIMUM”/>

</CONTAINER>

</PAGELAYOUT>

<INPUT NAME=”ddDocType” PARAM=”sDocType”>

<INPUT NAME=”tbTitle” PARAM=”sTitle” REQUIRED=”yes” VALIDATIONMSG=

“Please enter a document title” or some equivalent message>

<INPUT NAME=”chkMetaDescr” PARAM=”bMetaDescr”>

<INPUT NAME=”tbMetaDescr” PARAM=”sMetaDescr”>

</PAGE>

<!--- attributes page --->

<PAGE NAME=”MetaKeywords” TYPE=”DYNAMIC”

CAPTION=”Meta Keywords”

IMAGE=”..\\images\\main.bmp”>

<PAGELAYOUT>

<CONTROL NAME=”chkMetaKeywords” TYPE=”CheckBox”

CAPTION=”Add meta keywords:”

DOWN=”15” RIGHT=”10”

WIDTH=”MAXIMUM”/>

<CONTROL NAME=”taMetaKeywords” TYPE=”TextArea”

ANCHOR=”chkMetaKeywords” CORNER=”SW” down=”10”

HEIGHT=”MAXIMUM” width=”MAXIMUM”/>

</PAGELAYOUT>

<INPUT NAME=”chkMetaKeywords” PARAM=”bMetaKeywords”>

<INPUT NAME=”taMetaKeywords” PARAM=”sMetaKeywords”>

</PAGE>

<!--- OUTPUT TEMPLATE --->

<TEMPLATE

NAME=”Custom.wml”

OUTPUTFILE=”MyFile.cfm”

DESCRIPTION=”New HTML file”>

</WIZARD>

Chapter 9: Customizing the Development Environment 129

Creating Wizard Output Templates

The Wizard Markup Language (WIZML) enables the customization of files produced by the wizards. WIZML is used inside the templates to dynamically create files based on the data provided by the wizard. For example, if a wizard generates a tag called

<GIZMO> with a single attribute FILEPATH, the template could look as simple as this:

<GIZMO FILEPATH="$${txtFilePath}">

This example will create a file with a single <GIZMO> tag. Notice the syntax

$${variablename}

that is used to populate the value of FilePath with the actual value entered in the wizard.

Using WIZML

WIZML output templates use a high-level markup syntax that works very much like

CFML. Supported tags include WIZSET, WIZELSE/WIZELSEIF, WIZLOOP, and

WIZINCLUDE. In addition, a simple expression syntax that is a subset of the

ColdFusion expression syntax and function library is supported within output templates.

Parameters

Output templates are driven by the values of parameters, much like ColdFusion templates are driven by the values of Form and URL parameters. Parameters can be output directly or can be used to customize the type of output generated. The values of these wizard parameters can originate from several locations:

From a value set by a PARAM tag provided by the wizard

From an embedded tag editor control

Through execution of the WIZSET tag within the output template

To output the value of a parameter within a template, use a double dollar sign escape sequence. For example, to output the value of a variable named Color you would use the syntax $${Color}. While this is the recommended syntax, you can use a simpler form when for a parameter value within the attribute of a WIZ tag. For example, <WIZIF

Color= “black”>

is valid.

Expressions and functions

In addition to outputting and manipulating simple parameter values, an expression syntax that includes support for a subset of the ColdFusion functions is also provided.

To output the value of an expression you add a set of curly braces to the $$ and include the expression within the braces, for example:

130

Using ColdFusion Studio

$${ ’This is the ’ & Color }

$$( ’The result of 7 divided by 22 is ’ & 7/22 }

$$( Left( ’FooBar’, 3 ) }

As you can see from the example above, these expressions are very similar to

ColdFusion expressions. Strings are delimited using the single quote character. The customary set of arithmetic and concatenation operators are supported (+,-,*,/,&). The comparison operators LT, LTE, GT EQ, and NEQ are supported, and logical comparisons using AND, NOT, and OR are supported.

The two main categories of functions currently supported are string and runtime.

String functions

Chr

Compare

CompareNoCase

Find

FindNoCase

LTrim

RTrim

Trim

LCase

UCase

Len

Left

Right

Mid

RepeatString

Runtime functions

ParameterExists

SetVariable

Evaluate

The syntax and behavior of all of these functions is identical to the equivalent functions in ColdFusion, except for ParameterExists, which takes a string argument rather than a direct variable reference.

Chapter 9: Customizing the Development Environment 131

WIZ Tags

The behavior of wizard output templates is controlled by the use of WIZ tags in the template. These tags are like ColdFusion tags except that they are prefixed with the characters WIZ instead of ColdFusion.

Supported tags

WIZSET — Sets a wizard parameter.

WIZINCLUDE — Includes another wizard output template.

WIZLOOP —Iterates over a set of output.

WIZBREAK/WIZCONTINUE — Assists in loop flow control.

WIZIF/WIZELSEIF/WIZELSE — Sets conditional flow control.

Special considerations

Strings used within an output template tag attribute use the C-language convention (\) for escaping special characters. For example, the following attribute uses a newline character to split the value into two lines:

CAPTION="This is line one\nThis is line two"

Other special characters of note include carriage-return (\r), tab (\t), and slash (\\). For example, the following attribute references a template in a directory two levels above the current directory:

TEMPLATE="..\\..\\Header.wml"

WIZML reference

Here is the complete Wizard Markup Language syntax:

WIZSET

WIZSET works the same way as the ColdFusion CFSET tag.

For example:

<WIZSET Color = ’Red’>

<WIZSET Pi = 7/22>

<WIZSET ShortName = Left( LongName, 5 )>

132

Using ColdFusion Studio

WIZINCLUDE

Attribute

TEMPLATE

Description

Required. The relative path of a template that is to be included in the currently executing template.

WIZLOOP, WIZBREAK, and WIZCONTINUE

The WIZLOOP tag supports several types of loops including:

Index-based (using the INDEX, FROM, TO, and STEP attributes)

Condition-based (using the CONDITION attribute)

List-based (using the INDEX and LIST attributes)

TStringList-based (using the INDEX and STRINGLIST attributes)

The attributes for the WIZLOOP tag are as follows:

WIZLOOP Tag Attributes

Attribute Description

INDEX Name of a variable for a loop to set on each iteration (required for index and list-based loops). It serves as a counter.

FROM

TO

STEP

CONDITION

LIST

STRINGLIST

Index to start looping from.

Index to loop to.

Step value for each increment (can be positive or negative).

Conditional expression to control whether the loop should be exited.

A list of CommaText format. This is the format that a Delphibased string list uses to store textual representations of itself.

The name of a parameter created with the SetObjectParameter function which is of type TStringList.

The WIZBREAK and WIZCONTINUE tags have no attributes, and can be placed anywhere within a WIZLOOP tag to either exit the loop (WIZBREAK) or move on to the next loop iteration (WIZCONTINUE).

Chapter 9: Customizing the Development Environment 133

WIZIF, WIZELSEIF, and WIZELSE

The WIZIF, WIZELSEIF, and WIZELSE tags work identically to the corresponding CFML tags. Any valid Boolean expression can be used in the WIZIF and WIZELSEIF tags.

<WIZIF sDocType eq "HTML 4.0">

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<wizelse sDocType eq "HTML 3.2">

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">

<wizelse sDocType eq "HTML 2.0">

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">

</WIZIF>

<HTML>

<HEAD>

<TITLE>$${sTitle}</TITLE>

<WIZIF bMetaDescr eq "true">

<META NAME="description" CONTENT="$${sMetaDescr}">

</WIZIF>

<WIZIF bMetaKeywords eq "true">

<META NAME="keywords" CONTENT="$${sMetaKeywords}">

</WIZIF>

</HEAD>

<BODY>

</BODY>

</HTML>

Wizard Definition Page Library

ColdFusion Studio contains a set of seven page definition files that you can use to quickly build data access capabilities into your wizards. The pages are based on the

Studio Drill-down Wizard available in the File > New dialog.

SelectNameAndLocation

Description

This page collects application name and location where the destination directory for the output templates. It allows the user to select the directory from the local or remote server. This page is required if any of the following pages are included in the wizard.

134

Using ColdFusion Studio

Exposes controls

editApplicationName (textbox) — After the page is submitted, the content of this textbox are copied to the SafeApplicationName parameter with all non-allowed characters stripped out. This value can be then used as part of the file names.

editLocation (textbox) — This control should be bound to the Location parameter. The value of this parameter is preset to the directory opened in the left pane.

Example

<PAGE name="SelectWizardNameAndLocation" type="SelectNameAndLocation" caption="Data Drill-Down Application" image="..\\images\\Main.bmp">

<INPUT name="editApplicationName" param="ApplicationName" required="yes" validationMsg="You cannot leave the Application Name field blank">

<INPUT name="editLocation" param="Location"required="yes" validationMsg="You cannot leave the Location field blank">

</PAGE>

SelectDataSource

Description

This page displays a list of available data sources on the selected local or remote server.

Uses controls

cbDataSources (dropdown) — This control lists all available data sources. The control exchanges with the bound parameter the name of the selected data source.

Reads parameters

ListBoxLabel — Caption for the dropdown control.

ListBoxDescription — More detailed description for the dropdown control.

ResetParams — Comma-delimited list of parameters that should be emptied if user reselects the data source.

RemoveParams — Comma-delimited list of parameters that should be removed if user reselects the data source.

Chapter 9: Customizing the Development Environment 135

Example

<PAGE name="DataSource" type="SelectDataSource" caption="Data Source" image="..\\images\\SelectData.bmp">

<PARAM name="ListBoxLabel" value="Select data source:">

<PARAM name="ListBoxDescription" value="Choose the data source from which you would like to display data.\n\nIf your database is not registered as ODBC data source, open the ODBC administrator in Control Panel and add system data source for this database.">

<PARAM name="ResetParams" value="Joins">

<PARAM name="RemoveParams" value="Tables,SearchFields,ResultFields,

DetailFields,UniqueIdentifier">

<INPUT name="cbDataSources" param="DataSource" required="yes" validationMsg="You did not select the data source. Please select one before proceeding.">

</PAGE>

SelectTables

Description

This page displays a list of tables in the specified data source and lets the user select one or more of them.

Exposes controls

lstTables (dropdown) — the control lists tables in the data source specified in the

DataSource parameter. The control exchanges with the bound parameter a commadelimited list of selected tables.

Reads parameters

DataSource (required) — name of the data source.

ListBoxLabel — caption for the dropdown control.

ListBoxDescription — more detailed description for the dropdown control.

MultiSelect — if “YES”, user is allowed to select more than one table.

ResetParams — comma-delimited list of parameters that should be emptied if user reselects the tables.

RemoveParams — comma-delimited list of parameters that should be removed if user reselects the tables.

136

Using ColdFusion Studio

Example

<PAGE name="Tables" type="SelectTables" caption="Tables" image="..\\images\\SelectTable.bmp">

<PARAM name="DataSource" value="$${DataSource}">

<PARAM name="ListBoxLabel" value="Select database tables:">

<PARAM name="ListBoxDescription" value="Please specify the tables which will be involved in this application. This should include any tables against which you would like to search or tables containing data that will be displayed on either the Result or Detail pages.\n\nPress Ctrl or

Shift together with the mouse click in order to select more than one table. Do not select unrelated tables.">

<PARAM name="MultiSelect" value="yes">

<PARAM name="ResetParams" value="Joins">

<PARAM name="RemoveParams" value="SearchFields,ResultFields,

DetailFields,UniqueIdentifier">

<INPUT name="lstTables" param="Tables" required="yes" validationMsg="You did not select any tables. Please select at least one before proceeding.">

</PAGE>

SelectTable

Description

This page lets the user select one of the tables from the specified data source.

Exposes controls

cbTables (dropdown) — the control lists tables in the data source specified in the

DataSource parameter.

The control exchanges with the bound parameter the name of the selected table.

Reads parameters

DataSource (required) — name of the data source

ListBoxLabel — Caption for the dropdown control

ListBoxDescription — More detailed description for the dropdown control

ResetParams — Comma-delimited list of parameters that should be emptied if user reselects the table.

RemoveParams — Comma-delimited list of parameters that should be removed if user reselects the table.

Chapter 9: Customizing the Development Environment 137

Example

<PAGE name="Table" type="Table" caption="Table" image="..\\images\\SelectTable.bmp">

<PARAM name="DataSource" value="$${DataSource}">

<PARAM name="ListBoxLabel" value="Select database table:">

<PARAM name="ListBoxDescription" value="Records from this table will be displayed in the record viewer.">

<PARAM name="RemoveParams" value="Table,ViewFields,EditFields,

UniqueIdentifier">

<INPUT name="cbTables" param="Table" required="yes" validationMsg="You didn’t select the table. Please select one before proceeding.">

</PAGE>

SelectTableJoins

Description

The page lets the user select fields from multiple tables for table joins.

Exposes controls

lstJoins (dropdown) — The control lists field pairs as selected from the dropdown field lists. This list can be pre-filled from the comma delimited list of items, where each item has format “table1.field1=table2.field2”.

Reads parameters

DataSource (required) — Name of the data source.

Tables (required) — Comma-delimited list of the tables.

ListContent (required) — Input parameter.

Example

<PAGE name="TableJoins" type="SelectTableJoins" caption="Table Joins" image="..\\images\\SelectJoins.bmp">

<PARAM name="DataSource" value="$${DataSource}">

<PARAM name="Tables" value="$${Tables}">

<PARAM name="ListContent" value="$${Joins}">

<INPUT name="lstJoins" param="Joins">

</PAGE>

138

Using ColdFusion Studio

SelectFields

Description

This page displays all fields from the specified tables and lets the user select one or more of them.

Exposes controls

lstFields (dropdown) — The control lists fields in the tables specified in the Tables parameter. The control exchanges with the bound parameter a comma-delimited list of selected fields, where each item is in format “table.field=type,size,required”. Type specifies the type of the table field can have following values (BIT, CHAR, MEMO, INT,

FLOAT, DATETIME. Size gives information about size of the field in bytes (this might not be true for certain DBMS and types). Required is “YES” if the field value cannot be

NULL.

Reads parameters

DataSource (required) — Name of the data source.

Tables (required) — Comma-delimited list of the tables.

ListBoxLabel — Caption for the dropdown control.

ListBoxDescription — More detailed description for the dropdown control.

MultiSelect — If “YES”, user is allowed to select more than one field.

Example

<PAGE name="SearchFields" type="SelectFields" caption="Fields for Search page" image="..\\images\\SearchCriteria.bmp">

<PARAM name="DataSource" value="$${DataSource}">

<PARAM name="Tables" value="$${Tables}">

<PARAM name="ListBoxLabel" value="Select the search fields:">

<PARAM name="ListBoxDescription" value="Choose all fields that should be included as search criteria on the Search page. Press Ctrl or Shift together with the mouse click in order to select more than one field.">

<PARAM name="MultiSelect" value="yes">

<INPUT name="lstFields" param="SearchFields" required="yes" validationMsg="You did not select any fields. Please select at east one before proceeding.">

</PAGE>

Chapter 9: Customizing the Development Environment 139

SelectField

Description

This page lets the user select one field from the list of fields. The list of fields contains all fields from the specified tables.

Exposes controls

cbFields (required) — The control lists fields in the tables specified in the Tables parameter. The control exchanges with the bound parameter the field information in the format “table.field=type.size.required” (see the SelectFields page)

Reads parameters

DataSource (required) — Name of the data source.

Tables (required) — Comma-delimited list of tables.

ListBoxLabel — Caption for the dropdown control.

ListBoxDescription — More detailed description for the dropdown control.

Example

<PAGE name="IDField" type="SelectField" caption="Unique Identifier" image="..\\images\\UniqueIDDetail.bmp">

<PARAM name="DataSource" value="$${DataSource}">

<PARAM name="Tables" value="$${Tables}">

<PARAM name="ListBoxLabel" value="Select the unique identifier for the Detail page:">

<PARAM name="ListBoxDescription" value="In order to ’drill-down’ to the detail page the wizard needs to know the unique identifier for the detail page. This is the field that determines which record should be displayed in detailed form.\n\nFor example, if you are building an application to search an employee database you might use a field called ’Employee_ID’ as the unique identifier.">

<PARAM name="MultiSelect" value="no">

<INPUT name="cbFields" param="UniqueIdentifier" required="yes" validationMsg="You did not select the unique identifier. Please select one before proceeding.">

</PAGE>

C

H A P T E R

1 0

Chapter 10

Scripting The

Visual Tools Object Model

Power users can write scripts to control Studio functions and developers can call

Studio functionality from their applications using Visual Tools Object Model.

Contents

Writing and Executing Scripts....................................................................... 142

Application Object ......................................................................................... 143

DocumentCache Object ................................................................................ 153

ActiveDocument Object ................................................................................ 154

ActiveScripting examples .............................................................................. 158

Third-Party Add-Ins ....................................................................................... 163

142

Using ColdFusion Studio

Writing and Executing Scripts

HomeSite 4.0 and ColdFusion Studio 4.0 introduce a new level of customizability by exposing an Object Model, enabling developers to manipulate either program from external applications. In addition, power users can now create scripts using JavaScript

(JScript) or VBScript and execute them from within the HomeSite and Studio environments, automating custom tasks.

Note

The internal scripting feature requires Microsoft’s ActiveScripting engine v3.1 or later, which is not installed by HomeSite or Studio. If you have Microsoft Internet Explorer

4.0 or later on your system, then you already have the correct ActiveScripting engine installed. Otherwise, you’ll need to download it from http://www.microsoft.com/ msdownload/scripting.htm

.

Writing Scripts

In order for a script to be executable from within HomeSite or Studio, it must contain a

Main routine. For example, if you’re using JavaScript, create a function Main, and if you’re using VBScript, create a Sub Main. This routine is the one that’s called when you execute a script within HomeSite or Studio, so without it the script will fail.

The program determines which language engine to use based on the extension of the script file. If the file extension is .bas, .vb or .vbs, then the VBScript engine is used to execute the script. Otherwise, it is assumed that the file contains JavaScript source.

In order to automate various HomeSite or Studio related tasks, you’ll need to familiarize yourself with the visual tools object model. The main object is the

Application object. The application object contains two important child objects, the

ActiveDocument object and the DocumentCache object. Using these three objects, you should be able to write scripts to run your most common tasks. In addition, the

Application object contains a number of toolbar-related functions, enabling you to create toolbars dynamically.

For best performance, you should create an application object variable and use it throughout the script rather than continually referencing the application object directly.

For example, using JavaScript: function Main() {

var app = Application; //create application object variable

app.WindowState = 3; //maximize the window

} or VBScript:

Sub Main

Dim app set app = Application ’create application object variable app.WindowState = 3 ’maximize the window

End Sub

Chapter 10: Scripting The Visual Tools Object Model 143

Note:

The Application object is only available from scripts that are executed within HomeSite or Studio. To access the application object from an external program, use your language’s equivalent of

CreateObject(“AllaireClientApp.TAllaireClientApp”

).

Executing Scripts

Once you’ve written your script, you’ll need to create a custom toolbutton in order to execute it from within the program. To do this, select “Customize” from the “Options” menu and switch to the “Toolbar” page. It’s a good idea to create a separate toolbar just for your custom scripts, so click the “Add Toolbar” button to create a new toolbar, giving it a name such as “Custom Scripts.” Next, click “Add Custom Button,” and select the “Execute an ActiveScript file” option. Then just select the external script file, and give the toolbutton a unique caption or image.

Now that you’ve created both the custom toolbar and toolbutton, make sure that the toolbar will be displayed by placing a checkmark next to it in the list of available toolbars on the Customization dialog. That’s it - you now have a toolbutton that will execute a script file.

If the scripting engine encounters an error while executing your custom script, the script file will be opened in the editor and the offending line will be selected. In addition, information about the error will be displayed in the status bar, helping you to debug the problem.

Tip

Buried in the list of keyboard shortcuts on the Customization dialog you’ll find a command called “Execute current document as ActiveScript.” Once a shortcut has been assigned to this command, you can pass the current document to the

ActiveScripting engine — turning the program into a powerful tool for debugging your scripts (provided, of course, that they start with the Main routine). As with toolbuttonbased scripts, the scripting language is determined by the file extension of the current document.

Application Object

Application (TAllaireClientApp) Object

Properties

ActiveDocument (object, read-only)

Returns the active document. See the ActiveDocument reference below for details.

AppPath (OleString, read-only)

Path to application executable.

CurrentFolder (OleString)

Path currently displayed in the local file list.

144

Using ColdFusion Studio

CurrentView (ITCurrentViewType)

Sets/gets the current view.

Allowed values are:

1 - vwEditSource

2 - vwPreview (browse)

3 - vwDesign

DocumentCache (array of objects, read-only)

See the Document Cache reference below for details.

DocumentIndex (Integer)

Tab index of current document.

DocumentCount (integer, read-only)

Number of open documents.

ExeName (OleString, read-only)

Filename of application executable, including path.

Height (integer)

Height of main window.

HInstance (integer, read-only)

Instance handle of the application.

hWnd (integer, read-only)

Handle to the main window.

IsColdFusionStudio (WordBool, read-only)

Returns True if the application is Cold Fusion Studio, False if HomeSite.

Left (integer)

Left (x-coordinate) of main window.

ResourceTabShowing (WordBool)

Specifies whether the resource tab is displayed.

ResultsShowing (WordBool)

Specifies whether the results tab is displayed.

Top (integer)

Top (y-coordinate) of main window.

VersionText (OleString, read-only)

Returns a string containing the application name and version

WindowState (integer)

Allowed values are:

1 - Normal

Chapter 10: Scripting The Visual Tools Object Model 145

2 - Minimized

3 - Maximized

Methods

BringToFront procedure BringToFront;

Brings the main window to the front of other applications.

BrowseText procedure BrowseText(sText, BaseHREF: OleVariant);

Displays the passed text in the internal browser. The

BaseHREF

parameter is used to interpret relative paths. For local files, BaseHREF should be the folder the file is in.

CloseAll function CloseAll(wbPromptToSave: WordBool): WordBool;

Closes all open documents. If wbPromptToSave

is True, the user will be prompted to save any changes. Returns True if successful (that is, the user didn’t cancel if wbPromptToSave

is True).

ExtractFileName function ExtractFileName(const wsFile: WideString): WideString;

Returns only the file portion of the passed filename.

ExtractFilePath function ExtractFilePath(const wsFile: WideString): WideString;

Returns the path of the passed file (includes trailing ‘\’).

GetImageSize function GetImageSize(const wsImageFile: WideString; var nHeight, nWidth:

Integer): WordBool;

Retrieves the size of the passed image. Returns False on error.

GetRelativePath function GetRelativePath(const wsBaseURL, wsFolderURL: WideString):

WideString;

Returns the relative path of a folder give a base URL. For example,

GetRelativePath(“http://www.allaire.com/”, “http://www.allaire.com/ products/”) returns “products/”.

GetTabIndexForFile function GetTabIndexForFile(const wsFile: WideString): Integer;

Returns the index in the document tab of the passed file. Returns -1 If the file isn’t open.

146

Using ColdFusion Studio

GetURL function GetURL(const wsURL: WideString): widestring;

Retrieves a URL and returns its contents.

GetURLStatus function GetURLStatus(const wsURL: WideString; var vResponse:

OleVariant): Integer;

Returns the HTTP status code for the passed URL. The text of the server response is returned in the second parameter.

HideProgress procedure HideProgress;

Hides the progress bar.

HTMLConvertTagCase function HTMLConvertTagCase(const wsHTML: WideString; const wbUpperCase:

WordBool): WideString;

Converts the case of the passed HTML string. Doesn’t change the contents of SCRIPT,

STYLE or COMMENT tags, and doesn’t change the case of attribute values.

HTMLGetAttribute function HTMLGetAttribute(const wsInTag, wsAttr: WideString): WideString;

Returns the value for a particular attribute of a tag. For example,

HTMLGetAttribute(“<TABLE WIDTH=100&gt”, “WIDTH”) returns 100.

HTMLGetTitle function HTMLGetTitle(const wsFile: WideString): WideString;

Returns the contents of an HTML file’s <TITLE> tag. Note that this only operates on local files.

InputBox

InputBox(const wsCaption, wsPrompt, wsDefault: WideString): WideString;

Displays a dialog for obtaining user input.

IsFileOpen function IsFileOpen(sFile: OleVariant): WordBool;

Returns True if the passed file is open in the document tab.

IsFileModified function IsFileModified(sFile: OleVariant): WordBool;

Returns True if the passed file is open in the document tab and has been modified.

InstallParserScript

Chapter 10: Scripting The Visual Tools Object Model 147

InstallParserScript(const wsScriptFile, wsFileExtAssoc: WideString):

WordBool;

Installs a parser (color-coding) script and associates it with the passed list of semicolon separated file extensions. If an existing parser is assigned to any of these extensions, they are removed from the existing parser and assigned to the new one.

The parser script is copied from the passed location to the application \Parsers subdirectory. Returns False on error.

MessageBox

MessageBox(const wsText, wsCaption: WideString; nType: Integer): Integer;

Displays a message dialog for obtaining a user response. The nType

parameter determines the type of dialog displayed, and should be a combination of the following sets of values:

MB_ICONINFORMATION = 64

MB_ICONWARNING = 48

MB_ICONQUESTION= 32

MB_ICONSTOP= 16

MB_ABORTRETRYIGNORE= 2

MB_OK = 0 (Default)

MB_OKCANCEL = 1

MB_RETRYCANCEL = 5

MB_YESNO = 4

MB_YESNOCANCEL = 3

The function’s result will contain the ID of the button that was pressed, which will be one of the following:

IDOK = 1

IDCANCEL = 2

IDABORT = 3

IDRETRY = 4

IDIGNORE = 5

IDYES = 6

IDNO = 7

IDCLOSE = 8

NewDocument procedure NewDocument(wbUseDefaultTemplate: WordBool);

Creates a new document, optionally from the default template.

OpenFile function OpenFile(const wsFile: WideString): WordBool;

Opens the passed file, returning True if successful. Note that this will return True if the file is already open. Passing an empty string to

OpenFile

will display the “Open File” dialog, enabling the user select the file(s) to open.

NextDoc procedure NextDoc;

Moves to the next document in the document tab. If the last document is showing, wraps to the first.

148

Using ColdFusion Studio

PreviousDoc procedure PreviousDoc;

Moves to the previous document in the document tab. If the first document is showing, wraps to the last.

Quit procedure Quit

This method will attempt to exit HS/CFS. It will prompt the user to save any unsaved documents prior to exiting.

RunCodeSweeper procedure RunCodeSweeper;

Runs the CodeSweeper on the active document using the active CodeSweeper. To change the active CodeSweeper, use

SetActiveCodeSweeper

.

SaveAll function SaveAll: WordBool;

Saves all open documents, returning True if successful.

SendToBack procedure SendToBack;

Sends the main window to the back of other applications.

SetActiveCodeSweeper function SetActiveCodeSweeper(const wsFileName: WideString): WordBool;

Changes the active CodeSweeper format file.

SetActiveResults procedure SetActiveResults(resType: TCurrentResultsType);

Sets the active page in the results tab.

Allowed values are: resSearch resValidator resLinks resThumbnails

SetProgress procedure SetProgress(nProgress: Integer);

Sets the position of the progress bar in the status area. Allowed values are 1-100.

SetStatusText procedure SetStatusText(sMessage: OleString);

Sets the text to be displayed in the status area.

StatusWarning

Chapter 10: Scripting The Visual Tools Object Model 149 procedure StatusWarning(const wsMsg: WideString);

Displays a warning message in the status bar - message will appear on a blue background and display for at least 5 seconds.

StatusError procedure StatusError(const wsMsg: WideString);

Displays an error message in the status bar - message will appear on a red background and display for at least 5 seconds.

ShowThumbnails procedure ShowThumbnails(sFolder: OleString);

Shows thumbnails for all images in the passed folder.

ShowProgress procedure ShowProgress;

Shows the progress bar.

ShellToApp function ShellToApp(const wsAppFileName: WideString): WordBool;

Executes an external application. Returns True if application launched successfully.

Note that command lines may be included in the filename parameter, so this is valid:

Application.ShellToApp(“notepad.exe “ +

Application.ActiveDocument.Filename)

ShellToAppAndWait procedure ShellToAppAndWait(const wsAppFileName: WideString);

Same as

ShellToApp

but waits for the external program to be closed before returning.

Note that the application will be locked until

ShellToAppAndWait

returns, so use with caution.

TagCase function TagCase(const wsTag: WideString): WideString;

Changes the case of the passed string based on the “Lowercase all inserted tags” preference (defined on the HTML page in Settings). Does not modify the case of attribute values.

Wait procedure Wait(nMilliseconds: Integer);

Pauses for given number of milliseconds. Use “Wait” to enable scripts to execute loops yet still allow access to the UI. The JavaScript sample below waits for the user to return to edit source view: var app = Application; while (app.CurrentView != 1) { app.Wait(100);

}

Here’s the same code in VBScript:

150

Using ColdFusion Studio

set app = Application while app.CurrentView 1 app.Wait (100) wend

Without the call to Wait in the loop, the application will appear locked and the user will be unable to change views.

Projects

ActiveProjectFile (read-only string)

Returns the filename of the active project, or the empty string if no project is open.

AddFileToProject function AddFileToProject(const wsFilename: WideString): WordBool;

Adds the passed file to the active project. Note that the file must be contained under the main project folder or a subfolder of the main project.

CloseProject function CloseProject(wbCloseOpenFiles: WordBool): WordBool;

Closes the active project, if any. If wbCloseOpenFiles

is True, then all open files are closed.

OpenProject function OpenProject(const wsProjectFile: WideString): WordBool;

Opens the passed project file, making it the active project. Pass an empty string to display the “Open Project” dialog.

RemoveFileFromProject function RemoveFileFromProject(const wsFilename: WideString): WordBool;

Removes the passed file from the active project.

ShowLastProjectError function ShowLastProjectError;

Displays an error message for the last project-related error.

UploadProjectDlg function UploadProjectDlg: WordBool;

Displays the upload project dialog for the active project.

UploadProject function UploadProject(const wsTargetDir: WideString; const wbForceLCase, wbUploadOnlyNewer, wbEncryptCFML: WordBool): WordBool;

Uploads a project based on the passed criteria. Note that wbEncryptCFML is specific to

ColdFusion Studio.

Chapter 10: Scripting The Visual Tools Object Model 151

Toolbars

Each toolbar is identified by name, which is the same as the title bar caption that appears when the toolbar is undocked. Names are unique, so two toolbars will never have the same name/caption. Toolbars are loaded from files in the toolbar directory, which can be obtained from the

ToolbarDir

property. Toolbars names are the same as their file names without the path or extension. For example, if the toolbar file is c:\homesite\toolbars\Custom.tbr

, then the toolbar name is "Custom". Also note that toolbutton captions are limited to two characters.

ToolbarDir (widestring, read-only property)

Returns the path where toolbar files are located.

CreateToolbar function CreateToolbar(wsToolbarName: WideString): WordBool;

Creates a new, undocked toolbar of the passed name. Fails if a toolbar of the same name already exists.

HideToolbar function HideToolbar(wsToolbarName: WideString): WordBool;

Hides a toolbar. Fails if the toolbar doesn’t exist.

DeleteToolbar function DeleteToolbar(wsToolbarName: WideString): WordBool;

Physically deletes the toolbar. Fails if toolbar doesn’t exist or if toolbar is one of the built-in toolbars (only works on custom toolbars - built-in toolbars can be hidden, but not deleted).

ShowToolbar function ShowToolbar(wsToolbarName: WideString): WordBool;

Displays a toolbar if it’s not already showing. Fails if the toolbar doesn’t exist.

AddAppToolbutton function AddAppToolbutton(wsToolbarName, wsExeFile, wsCmdLine, wsHint:

WideString): WordBool;

Adds a toolbutton for an external application to the passed toolbar. Fails if the toolbar doesn’t exist or if the toolbutton could not be added. Returns True if the same toolbutton (based on wsExeFile and

wsCmdLine

) already exists on the toolbar, but doesn’t add a duplicate button.

The JavaScript example below creates a toolbar named “Apps” if one doesn’t exist already, and then adds two custom toolbuttons to it. The first toolbutton launches

Windows Explorer, while the second one opens Windows Explorer at the current folder in the editor: function Main() { var TB_NAME = ‘Apps’; var app = Application;

152

Using ColdFusion Studio

if (!app.ToolbarExists(TB_NAME)) { app.CreateToolbar(TB_NAME);

} app.AddAppToolbutton(TB_NAME, ‘c:\\windows\\explorer.exe’, ",

‘Explorer’); app.AddAppToolbutton(TB_NAME, ‘c:\\windows\\explorer.exe’, app.CurrentFolder, ’Explorer - Current Folder’);

}

Here’s the same code in VBScript:

Sub Main const TB_NAME = “Apps”

Dim app set app = Application if not app.ToolbarExists(TB_NAME) then app.CreateToolbar TB_NAME end if app.AddAppToolbutton TB_NAME, “c:\windows\explorer.exe”, ““,

“Explorer” app.AddAppToolbutton TB_NAME, “c:\windows\explorer.exe”, app.CurrentFolder, “Explorer - Current Folder”

End Sub

AddTagToolbutton function AddTagToolbutton(wsToolbarName, wsTagStart, wsTagEnd, wsHint, wsCaption, wsImageFile: WideString): WordBool;

Adds a tag toolbutton (inserts tag pair when clicked) to the passed toolbar. Fails if toolbar doesn’t exist. Returns true if Toolbutton already exists, but doesn’t add duplicate button.

AddScriptToolbutton function AddScriptToolbutton(wsToolbarName, wsScriptFile, wsHint, wsCaption, wsImageFile: WideString): WordBool;

Adds a script toolbutton (executes passed JavaScript or VBScript file when clicked) to the passed toolbar. Fails if toolbar doesn’t exist. Returns true if Toolbutton already exists, but doesn’t add duplicate button.

AddVTMToolbutton function AddVTMToolbutton(wsToolbarName, wsScriptFile, wsHint, wsCaption, wsImageFile: WideString): WordBool;

Adds a VTM toolbutton (displays passed VTM dialog when clicked) to the passed toolbar. Fails if toolbar doesn’t exist. Returns true if Toolbutton already exists, but doesn’t add duplicate button.

ToolbarExists function ToolbarExists(wsToolbarName: WideString): WordBool;

Returns True if the passed toolbar exists.

SetToolbarDockPos

Chapter 10: Scripting The Visual Tools Object Model 153 function SetToolbarDockPos(wsToolbarName: WideString; nDockPos:

Integer): WordBool;

Sets the docking position of the toolbar. Allowed values for nDockPos

are:

1 = Top

2 = Bottom

3 = Left

4 = Right

Fails if the toolbar doesn’t exist.

DocumentCache Object

It is very important to understand the DocumentCache object when using the Visual

Tools Object Model. Although HomeSite and ColdFusion Studio enable you to open dozens of files at once, only the active document is kept in memory. When a document becomes inactive (that is, when the user switches to a different document in the document tab), the previously active document is cached in order to conserve resources.

Every open document has an element in the

Application.DocumentCache

array. To refer to a specific cached document, use

Application.DocumentCache(Index)

, where

Index is the index of the document in the document tab.

The JavaScript example below shows how to loop through the array: var app = Application; for (idx = 0; idx < app.DocumentCount; idx++) { sFile = app.DocumentCache(idx).Filename;

}

Here’s the same code in VBScript: set app = Application for idx = 0 to app.DocumentCount - 1 sFile = app.DocumentCache(idx).Filename

next

If you know the filename of an open document, you can retrieve its index by using the

Application.GetTabIndexForFile

function, like this: var app = Application; idx = app.GetTabIndexForFile(‘c:\docs\file.htm’); bReadOnly = app.DocumentCache(idx).ReadOnly;

In order to access more information about a cached document, you must first make it the active document and refer to it using the Application object’s ActiveDocument property. To do this, set the Application.DocumentIndex

property to the index of the cached document.

Properties

Note:

All properties of the DocumentCache object are read-only.

154

Using ColdFusion Studio

Text (OleString)

Returns the text (file contents) of the cached document.

Modified (WordBool)

Returns True if the cached document has been modified since it was last saved.

Filename (OleString)

Returns the filename of the cached document.

ReadOnly (WordBool)

Returns True if the cached document is read-only.

ActiveDocument Object

The ActiveDocument object is used to refer to the document currently being displayed in the editor. To access an open document that isn’t active, use the

Application.DocumentCache object.

Properties

CanUndo (WordBool, read-only)

Returns True if changes can be undone.

CanRedo (WordBool, read-only)

Returns True if changes can be re-done.

Filename (OleString, read-only)

Returns the filename of the active document.

Lines[Index: integer] (OleString)

Gets/sets the text of the line at the passed index.

Note

Iterating through a document using the Lines property may be slow, especially for large documents. It is recommend that you only use Lines to evaluate single lines of text. If you must use Lines to update many lines, you can boost performance by wrapping the update in a

BeginUpdate..EndUpdate

block.

LineCount (integer, read-only

Returns the number of lines in the active document.

Modified (WordBool, read-only)

Returns True if the document has been changed since it was last saved.

ReadOnly (WordBool, read-only)

Returns True if the active document is read-only.

SelStart (integer)

Chapter 10: Scripting The Visual Tools Object Model 155

Gets/sets the start of the current selection.

SelLength (integer)

Gets/sets the length of the current selection

SelText (OleString)

Gets/sets the text in the current selection.

TabIndex

Gets/sets the tab index of the document tab.

Text (OleString)

Gets/sets the complete document text.

Methods

BeginUpdate procedure BeginUpdate;

Turns off screen updating for the active document. This is useful if your script needs to make several changes to the active document at once - turning off screen updating during the procedure may significantly speed things up. To turn updating back on, use

EndUpdate .

Note

Use BeginUpdate...EndUpdate

with caution. If you fail to call EndUpdate after a call to

BeginUpdate

, or if you script crashes before

EndUpdate

is called, the user will be unable to see any changes made in the editor.

EndUpdate procedure EndUpdate;

Turns on screen updating for the active document.

Clear procedure Clear;

Clears all text form the active document.

Close function Close(wbPromptToSave: WordBool): WordBool;

Closes the active document. If wbPromptToSave

is True, the user is prompted to save any changes. Returns True if the document was closed (that is, the user didn’t cancel saving changes).

GetCaretPos procedure GetCaretPos(var x, y: integer);

Returns the caret pos (x=column, y=line).

GetNextChar function GetNextChar: OleVariant;

156

Using ColdFusion Studio

Returns the next character. Note that this function (along with

GetPreviousChar

) can be slow when used in long loops.

GotoNextStartTag function GotoNextStartTag(wbSelect: WordBool): WordBool;

Moves the next starting tag, selecting it if wbSelect

is True. Returns False if no tag found.

GotoPreviousStartTag function GotoPreviousStartTag(wbSelect: WordBool): WordBool;

Moves the previous starting tag, selecting it if wbSelect

is True. Returns False if no tag found.

GotoNextEndTag function GotoNextEndTag(wbSelect: WordBool): WordBool;

Moves the next end tag, selecting it if wbSelect

is True. Returns False if no tag found.

GetPreviousChar function GetPreviousChar: OleVariant;

Returns the previous character.

GotoPreviousEndTag function GotoPreviousEndTag(wbSelect: WordBool): WordBool;

Moves the previous end tag, selecting it if wbSelect

is True. Returns False if no tag found.

Indent procedure Indent;

Indents the current selection.

InsertTag procedure InsertTag(sStartTag, sEndTag: OleVariant; wbOverwriteSelection: WordBool);

Inserts the passed tag pair at the current cursor position, overwriting the selection if wbOverwriteSelection

is True. The cursor will be positioned between the start and end tags after this operation, and if wbOverwriteSelection is False, the current selection will be surrounded by the tags.

InsertText procedure InsertText(InsertStr: OleVariant; wbOverwriteSelection:

WordBool);

Inserts the passed string at the current cursor position, overwriting the selection if wbOverwriteSelection

is True.

Print procedure Print(wbNoPrompt: WordBool);

Chapter 10: Scripting The Visual Tools Object Model 157

Prints the active document. Prompts the user for print settings unless wbNoPrompt

is

True.

ReplaceAll function ReplaceAll(strSearch, strReplace: OleVariant; bMatchCase:

WordBool): Integer;

Replaces all occurrences of strSearch

with strReplace

, matching case if bMatchCase is True. Returns the number of replacements made.

Redo procedure Redo;

Performs a single redo operation.

Reload procedure Reload(wbPromptToSave: WordBool);

Reloads the active document, prompting to save changes if wbPromptToSave is True.

Save function Save: WordBool;

Saves changes to the active document, returning True if successful.

SaveAs function SaveAs(wsFileName: widestring): WordBool;

Saves changes to the active document to the file specified in the wsFileName parameter, returning True if successful. If wsFileName

is empty, the standard “Save As” dialog will be displayed to the user. Note that existing files will be overwritten by this function, so use with caution!

SelectAll procedure SelectAll;

Selects all the text in the active document,

SetCaretPos procedure SetCaretPos(x, y: Integer);

Sets the current column/line.

SelectLine procedure SelectLine(Index: Integer);

Highlights the passed line.

SelectCurrentLine procedure SelectCurrentLine;

Highlights the current line.

Undo procedure Undo;

158

Using ColdFusion Studio

Performs a single undo operation.

Unindent procedure Unindent;

Unindents the current selection.

Cursor Movement Procedures

Use these methods to position the cursor. If wbSelect

is True, then the current selection will be extended to the new cursor position.

procedure CursorLeft(wbSelect: WordBool); procedure CursorRight(wbSelect: WordBool); procedure CursorWordLeft(wbSelect: WordBool); procedure CursorWordRight(wbSelect: WordBool); procedure CursorDown(wbSelect: WordBool); procedure CursorUp(wbSelect: WordBool); procedure CursorPageDown(wbSelect: WordBool); procedure CursorPageUp(wbSelect: WordBool); procedure CursorDocStart(wbSelect: WordBool); procedure CursorDocEnd(wbSelect: WordBool); procedure CursorLineStart(wbSelect: WordBool); procedure CursorLineEnd(wbSelect: WordBool);

ActiveScripting examples

JavaScript

<html>

<head>

<title>JavaScript Example</title>

</head>

<body>

<pre>

//

//=============================================================

// ActiveScripting example (JavaScript)

//=============================================================

// Displays a table containing the filenames of all open documents,

// whether or not each document has been modified, and whether each

// document is read-only.

//============================================================= function Main() {

var newline = ‘\n’;

var br = ‘<br>’;

var tab = ‘\t’;

// create app reference. note that the Application object is only

// available from within HomeSite and Studio - to create the app object from an

Chapter 10: Scripting The Visual Tools Object Model 159

// external script, use

CreateObject(‘AllaireClientApp.TAllaireClientApp’)

var app = Application;

// save the index of the current document so it can be returned to

var nCurrentIdx = app.DocumentIndex;

// start the table

var sTable = ‘<b><font color=Blue>Names of all open’

+ ‘ documents:</font></b>’

+ br + newline + br + newline

+ ‘<table border=1 width=460>’

+ newline + ‘<tr>’

+ ‘<td><b>Document</b></td>’

+ ‘<td><b>Modified</b></td>’

+ ‘<td><b>Read-Only</b></td>’

+ ‘</tr>’ + newline;

// loop through all open documents (note that DocumentCount is 1based,

// whereas DocumentCache() is 0-based)

for (idx = 0; idx < app.DocumentCount; idx++) {

// get document name (uses function example)

fname = GetDisplayName(app.DocumentCache(idx).Filename);

sTable = sTable + tab + ‘<tr><td>’ + fname;

sTable = sTable + ‘</td><td>’;

// is this document modified?

if (app.DocumentCache(idx).Modified) sTable = sTable + ‘Yes’;

sTable = sTable + ‘</td><td>’;

// is this document read-only?

if (app.DocumentCache(idx).ReadOnly) sTable = sTable + ‘Yes’;

// close row

sTable = sTable + ‘</td></tr>’ + newline;

}

sTable = sTable + newline + ‘</table>’;

// add a new document (False = don’t create from default template - blank)

app.NewDocument(false);

// insert the table (note that the ActiveDocument will be the new document

// created above)

app.ActiveDocument.InsertText(sTable, false);

// switch to browse mode

app.CurrentView = 2;

// wait for user to re-enter edit mode

160

Using ColdFusion Studio

while (app.CurrentView != 1) {

// Wait is a home-grown routine to make up for the loss of

// DoEvents in VBScript. it will pause for a given number of

// milliseconds without locking the interface

app.Wait(100);

}

// return to the original document

app.DocumentIndex = nCurrentIdx;

alert(‘Script Completed.’);

// function call example function GetDisplayName(fname) {

if (fname == ‘’)

return ‘(untitled)’

else

return fname

}

</pre>

</body>

</html>

VBScript

<html>

<head>

<title>VBScript Example</title>

</head>

<body>

<pre>

//

//=============================================================

//ActiveScripting example (VBScript)

//=============================================================

// Displays a table containing the filenames of all open documents,

// whether or not each document has been modified, and whether each

// document is read-only.

//=============================================================

Sub Main

dim app

dim idx

dim sTable

dim newline, fname, br, tab

dim nCurrentIdx

newline = chr(13) + chr(10)

br = “<br>”

tab = chr(9)

‘ create app reference. note that the Application object is only

Chapter 10: Scripting The Visual Tools Object Model 161

‘ available from within HomeSite and Studio - to create the app object from an

‘ external script, use

CreateObject(“AllaireClientApp.TAllaireClientApp”)

set app = Application

‘ save the index of the current document so it can be returned to

nCurrentIdx = app.DocumentIndex

‘ start the table

sTable = “<b><font color=Blue>Names of all open”_

+ “ documents:</font></b>”_

+ br + newline + br + newline _

+ “<table border=1 width=460>”_

+ newline + “<tr>”_

+ “<td><b>Document</b></td>”_

+ “<td><b>Modified</b></td>”_

+ “<td><b>Read-Only</b></td>”_

+ “</tr>” + newline

‘ loop through all open documents (note that DocumentCount is 1based,

‘ whereas DocumentCache() is 0-based)

for idx = 0 to app.DocumentCount - 1

‘ get document name (uses function example)

fname = GetDisplayName(app.DocumentCache(idx).Filename)

sTable = sTable + tab + “<tr><td>” + fname

sTable = sTable + “</td><td>”

‘ is this document modified?

if app.DocumentCache(idx).Modified then sTable = sTable + “Yes”

sTable = sTable + “</td><td>”

‘ is this document read-only?

if app.DocumentCache(idx).ReadOnly then sTable = sTable + “Yes”

‘ close row

sTable = sTable + “</td></tr>” + newline

next

sTable = sTable + newline + “</table>”

‘ add a new document (False = don’t create from default template - blank)

app.NewDocument(False)

‘ insert the table (note that the ActiveDocument will be the new document

‘ created above)

app.ActiveDocument.InsertText sTable, False

‘ switch to browse mode

app.CurrentView = 2

‘ wait for user to re-enter edit mode

162

Using ColdFusion Studio

while app.CurrentView <> 1

‘ Wait is a home-grown routine to make up for the loss of

‘ DoEvents in VBScript. it will pause for a given number of

‘ milliseconds without locking the interface

app.Wait(100)

wend

‘ return to the original document

app.DocumentIndex = nCurrentIdx

MsgBox “Script Completed.”

‘ free the references

set app = nothing

End Sub

‘ function example function GetDisplayName(fname)

if fname = ““ then

GetDisplayName = “(untitled)”

else

GetDisplayName = fname

end if end function

</pre>

</body>

</html>

Chapter 10: Scripting The Visual Tools Object Model 163

Third-Party Add-Ins

At start-up, HomeSite checks the

HKEY_CURRENT_USER\Software\Allaire\HomeSite4\RunOnce

registry key and executes any scripts it finds listed. Studio checks the

HKEY_CURRENT_USER\Software\Allaire\Studio\RunOnce registry key.

If you want to distribute either program as an add-in, you can use this key to run a script that, for example, creates a toolbar for your application the next time the program starts. For example, just add a string entry whose value contains the full path to the script you want executed, like this:

[HKEY_CURRENT_USER\Software\Allaire\HomeSite4\RunOnce]

"MyAppScript”=”c:\\MyApp\\MyAppScript.bas"

Sub Main

const TB_NAME = “MyApp”

Dim app

set app = Application

’ delete toolbar if it already exists

if app.ToolbarExists(TB_NAME) then app.DeleteToolbar(TB_NAME)

end if

’ recreate toolbar app.CreateToolbar TB_NAME

’ dock it to the bottom app.SetToolbarDockPos TB_NAME, 2

’ add app toolbutton app.AddAppToolbutton TB_NAME, “c:\MyApp\MyApp.exe”, ““, “Click to run

MyApp”

’ add tag toolbutton app.AddTagToolbutton TB_NAME, “<div>”, “</div>”, “DIV Toolbutton”,

“DV”, ““

’ add script toolbutton app.AddScriptToolbutton TB_NAME, app.AppPath + “test.bas” , “Script

Toolbutton”, “SC”, ““

’ add VTM toolbutton app.AddVTMToolbutton TB_NAME, app.AppPath +

“Extensions\TagDefs\HTML\div.vtm” , “VTM Toolbutton”, “VT”, ““

End Sub

After these keys are read, the program deletes the entries so that they won’t be executed again.

Scripting support opens up numerous possibilities for third-party developers. For the latest news on third-party add-ins, check the Allaire Developer site.

Appendix

Online Help Search Tips

Studio’s help search capability has been greatly enhanced for this release. This section details the search criteria options you can use in the Help References.

This information is available online by clicking the Search Tips button in the Search

Help References dialog.

You can print this reference by opening the Search Tips PDF file in the Allaire

Support folder below the Help folder.

Contents

Search Case Sensitivity .................................................................................. 166

Multiple Word Searches ................................................................................. 166

Wildcards ........................................................................................................ 166

Operators ........................................................................................................ 167

Modifiers ......................................................................................................... 171

166

Using ColdFusion Studio

Search Case Sensitivity

If you pass a mixed case entry (mixed upper and lower case), case sensitivity is applied to the search. If you pass all upper or all lower case, case insensitivity is assumed.

Search String Matches

wddx Wddx WDDX wDDx . . .

Wddx Wddx

WDDX WDDX

Multiple Word Searches

Words separated by spaces behave as if they had a logical AND between them. Words separated by commas behave as if they had a logical OR between them.

Search String

wddx, cfas wddx cfas

Matches

documents which have either wddx OR cfas somewhere in the document documents which have both wddx AND cfas somewhere in the document

Wildcards

Wildcards "*" and "?" will match 0 to n and one characters respectively.

Search String

behav*

Matches

behaving, behave etc.

behav? behave

*site HomeSite, WebSite etc.

?ite kite, Site etc.

Note that wildcard searches appearing on the left side of a string tend to be expensive.

Chapter : 167

Operators

These operators enable you to specify sophisticated search criteria.

NEAR operator

Selects documents containing specified search terms within close proximity to each other. Document scores are calculated based on the relative number of words between search terms. For example, if the search expression includes two words, and those words occur next to each other in a document (so that the region size is two words long), then the score assigned to that document is 1.0. Thus, the document with the smallest possible region containing all search terms always receives the highest score.

Documents whose search terms are not within 1000 words of each other are not selected, since the search terms are probably too far apart to be meaningful within the context of the document.

The NEAR operator is similar to the other proximity operators in the sense that the search words you enter must be found within close proximity of one another. However, unlike other proximity operators, the NEAR operator calculates relative proximity and assigns scores based on its calculations.

To retrieve relevance-ranked documents that contain stemmed variations of the words

"war" and "peace" within close proximity to each other, you can enter the following: war <NEAR> peace

NEAR/N operator

Selects documents containing two or more words within N number of words of each other, where N is an integer. Document scores are calculated based on the relative distance of the specified words when they are separated by N words or less.

For example, if the search expression NEAR/5 is used to find two words within five words of each other, a document that has the specified words within three words of each other is scored higher than a document that has the specified words within five words of each other.

The N variable can be an integer between 1 and 1,024, where NEAR/1 searches for two words that are next to each other. If N is 1,000 or above, you must specify its value without commas, as in NEAR/1000. You can specify multiple search terms using multiple instances of NEAR/N, as long as the value of N is the same.

For example, to retrieve relevance-ranked documents that contain stemmed variations of the words "commute", "bicycle", "train", and "bus" within 10 words of each other, you can enter the following: commute <NEAR/10> bicycle <NEAR/10> train <NEAR/10> bus

You can use the NEAR/N operator with the ORDER modifier to perform ordered proximity searches. For more information about the ORDER modifier, see "ORDER

Modifier" in this appendix.

168

Using ColdFusion Studio

OR operator

Selects documents that show evidence of at least one of your search elements.

Documents selected using the OR operator are relevance-ranked.

To select documents that contain stemmed variations of the word “election” or the phrases "national elections" or "senatorial race", you can enter the following: election OR national elections OR senatorial race

Only those documents that contain at least one of the search elements, or a stemmed variation of at least one of them, are retrieved and ranked according to their scores.

PARAGRAPH operator

Selects documents that include all of the search elements you specify within a paragraph. Valid search elements are two or more words or phrases. You can specify search elements in a sequential or a random order. Documents are retrieved as long as search elements appear in the same paragraph.

To retrieve relevance-ranked documents that contain stemmed variations of the word

"drug" and the phrase "cancer treating" in the same paragraph, you can enter the following: drug <PARAGRAPH> cancer treating

To search for three or more words or phrases, you must use the PARAGRAPH operator between each word or phrase.

You can use the PARAGRAPH operator with the ORDER modifier to perform ordered proximity searches. For more information about the ORDER modifier, see "ORDER

Modifier" in this appendix.

PHRASE operator

Selects documents that include a phrase you specify. A phrase is a grouping of two or more words that occur next to each other in a specific order.

By default, two or more words separated by a space are considered to be a phrase in simple syntax. In addition, two or more words enclosed in double quotes are considered to be a phrase. To retrieve relevance-ranked documents that contain the phrase "mission oak", you can enter any of the following: mission oak

“mission oak” mission <PHRASE> oak

<PHRASE> (mission, oak)

Chapter : 169

SENTENCE operator

Selects documents that include all of the words you specify within a sentence. You can specify search elements in a sequential or a random order. Documents are retrieved as long as search elements appear in the same sentence.

To retrieve relevance -ranked documents that contain stemmed variations of the words "American", and "innovation" within the same sentence, you can enter the following: american <SENTENCE> innovation

<SENTENCE> (american, innovation)

You can use the SENTENCE operator with the ORDER modifier to perform ordered proximity searches. For more information about the ORDER modifier, see "ORDER

Modifier" in this appendix.

STARTS operator

Selects documents by matching the character string you specify with the starting characters of the values stored in a specific document field. For example, assume a document field named REPORTER has been defined. To retrieve documents written by

Jack, Jackson, and Jacks, you can enter the following:

REPORTER <STARTS> jack

SUBSTRING operator

Selects documents by matching the character string you specify with a portion of the strings of the values stored in a specific document field. The characters that comprise the string can occur at the beginning of a field value, within a field value, or at the end of a field value.

For example, assume a document field named TITLE has been defined. To retrieve documents whose titles contain words such as "solution", "resolution", "solve", and

"resolve", you can enter the following:

TITLE <SUBSTRING> sol

WILDCARD operator

Selects documents that contain matches to a wildcard character string. The

WILDCARD operator lets you define a wildcard string, which can be used to locate related word matches in documents. A wildcard string consists of special characters.

For example, to retrieve documents that contain words such as "pharmaceutical",

"pharmacology", and "pharmacodynamics", you can enter the following: pharmac*

Documents are not relevance-ranked unless the MANY modifier is used, as in:

170

Using ColdFusion Studio

<MANY> pharmac*

The wildcard characters "*" and "?" automatically enable wildcard searching. To use other constructs, use the WILDCARD operator explicitly with any of the characters below.

Character

?

-

*

[ ]

{ }

^

Function

Specifies one of any alphanumeric character, as in ?an, which locates

"ran", "pan", "can", and "ban". It is not necessary to specify the

WILDCARD operator when you use the question mark. The question mark is ignored in a set ([ ]) or in an alternative pattern ({ }).

Specifies zero or more of any alphanumeric character, as in corp*, which locates "corporate", "corporation", "corporal", and "corpulent".

It is not necessary to specify the WILDCARD operator when you use the asterisk; you should not use the asterisk to specify the first character of a wildcard string. The asterisk is ignored in a set ([ ]) or in an alternative pattern ({ }).

Specifies one of any character in a set, as in <WILDCARD> ‘c[auo]t‘, which locates "cat", "cut", and "cot". You must enclose the word that includes a set in backquotes (‘), and there can be no spaces in a set.

Specifies one of each pattern separated by a comma, as in

<WILDCARD> ‘bank{s,er,ing}‘, which locates "banks", "banker", and

"banking". You must enclose the word that includes a pattern in backquotes (‘), and there can be no spaces in a set.

Specifies one of any character not in the set, as in <WILDCARD>

‘st[^oa]ck‘, which excludes "stock" and "stack" but locates "stick" and

"stuck". The caret (^) must be the first character after the left bracket

([) that introduces a set.

Specifies a range of characters in a set, as in <WILDCARD> ‘c[a-r]t‘, which locates every three-letter word from "cat" to "crt".

WORD operator

Selects documents that include one or more instances of a word you specify. For example, to search for documents that contain the word "rhetoric", without also considering the words "rhetorical" and "rhetorician", you can enter the following:

<WORD> rhetoric

Documents are not relevance-ranked unless the MANY modifier is used, as in:

<MANY><WORD> rhetoric

Chapter : 171

Modifiers

Modifiers are used in conjunction with operators. When specified, a modifier changes the standard behavior of an operator in some way. For example, you can use the CASE modifier with an operator to specify that the case of the search word you enter be considered a search element as well. Modifiers include CASE, MANY, NOT, and

ORDER, each of which is described below.

CASE modifier

Use the CASE modifier with the WORD or WILDCARD operator to perform a casesensitive search, based on the case of the word or phrase specified. To use the CASE modifier, you simply enter the search word or phrase as you wish it to appear in retrieved documents - in all uppercase letters, in mixed uppercase and lowercase letters, or in all lowercase letters. For example, to retrieve documents that contain the word "Apple" in mixed uppercase and lowercase letters, you can enter the following:

<CASE><WORD> Apple

Only those documents that contain the word "Apple" will be selected. Occurrences of

"apple", "apples", or "APPLE" will not be selected. When mixed uppercase and lowercase characters are included in a query, the search engine finds case-sensitive matches.

MANY modifier

Counts the density of words, stemmed variations, or phrases in a document, and produces a relevance-ranked score for retrieved documents. The more occurrences of a word, stem, or phrase proportional to the amount of document text, the higher the score of that document when retrieved. Because the MANY modifier considers density in proportion to document text, a longer document that contains more occurrences of a word can score lower than a shorter document that contains fewer occurrences. You can use the MANY modifier with these operators: WORD, WILDCARD, STEM,

SOUNDEX, PHRASE, SENTENCE, PARAGRAPH. For example, to select documents based on the density of stemmed variations of the word "apple", you can enter the following:

<MANY><STEM> apple

To select documents based on the density of the phrase "mission oak", you can enter the following:

<MANY> mission oak

The MANY modifier cannot be used with AND, OR, ACCRUE, or relational operators.

172

Using ColdFusion Studio

NOT modifier

Use the NOT modifier with a word or phrase to exclude documents that show evidence of that word or phrase. For example, to select only documents that contain the words

"cat" and "mouse" but not the word "dog", you can enter the following: cat <AND> mouse <AND> <NOT> dog

You can use the NOT modifier only with the operators AND and OR.

ORDER modifier

Use the ORDER modifier to specify that search elements must occur in the same order in which they were specified in the query. If search values do not occur in the specified order in a document, the document is not selected. You can use the ORDER modifier with these operators: PARAGRAPH, SENTENCE, and NEAR/N. Always place the

ORDER modifier just before the operator. The following syntax examples show how you can use either simple syntax or explicit syntax to retrieve documents containing the word "president" followed by the word "washington" in the same paragraph:

Simple syntax: president <ORDER><PARAGRAPH> washington

Explicit syntax:

<ORDER><PARAGRAPH> ("president", "washington")

To search for documents containing the words "diver", "kills", "shark" in that order within 20 words of each other, use one of the following queries: diver <ORDER><NEAR/20> kills <ORDER><NEAR/20> shark

<ORDER><NEAR/20> (diver, kills, shark)

You can use the NEAR/N operator with the ORDER modifier to duplicate the behavior of the PHRASE operator. For example, to search for documents containing the phrase

"world wide web", you can use the following syntax: world <ORDER><NEAR/1> wide <ORDER><NEAR/1> web

Index

A

ActiveDocument object, in VTOM

152

ActiveScripting

engine, for VTOM 140

examples 157

ActiveX, in VTML 120

Adding

a background image 32

a project to source control 83

files to a project 77

HTML files to the Help

References 16

image files 32

links or images to a new file 18

media content 32

snippet shortcut keys 35

sound 33

tag help, in VTML 102

video files 33

Allaire, contacting 8

Anchoring a regular expression to

Apj extension, for projects 77

Application development features

3

ASCII special characters,

converting 28

AU files, in Studio 33

AVI files, in Studio 33

B

BACKGROUND attribute, in body

tag 32

Backreferences, in regular

expression searches 69

BGSOUND tag 34

Bookmarks

in documents 44

in online help 15

Bound controls, in VTML 124

Breakpoints

setting in Debugger 58

window in Debugger 60

Browse mode 12

Browse toolbar 13

Browser

configuring 21

copying text from 26

IE as default 21 installation options 21

printng pages 25

Building

CFML expressions 36

custom wizards 120

pages 24

tag editors, in VTML 95

C

Cascading Style Sheets 51

Cascading Style Sheets (CSS),

creating with Style Editor 51

Case

converting tag 44

matching in searches 64

sensitivity, in CodeSweeper 49

CFML coding Style Guide 4

commenting code 24

Expression Builder 36

Language Reference 22

page processing 22

running examples in Studio 22

wizards 30

Character classes, in regular

expression searches 67

Check in options, source control

84

Checking spelling 70

Client-side image map 32

Code preserving formats with

CodeSweeper 49

templates 35

validating 28

CodeSweeper 49

Coding, HTML/CFML Style Guide

4

ColdFusion

developer resources 3

documentation, about 4

page processing 22

ColdFusion Administrator

for data sources 38

source control page 83

Color

import palettes 27

setting for page elements 27

values 27

Color coding tags 24

Commenting code 24

Configuring

browsers 21

CodeSweeper 49

Tag Tree display 46

Connecting to

an FTP server 19

data sources 38

Remote Development Services

20

Constants, inserting CFML 36

Content, entering 24

Context menus 11

Converting

Microsoft Office content 26

text files 25

Copying text from a browser 26

174

Using ColdFusion Studio

Creating

a project for source control 82

projects 77

wizard definition pages 121

Cursor movement procedures, in VTOM

156

Custom Tag wizard 30

Customizing

Tag Chooser and Expression Builder,

in VTML 88

the Studio workspace 10

D

Data

registering sources 38

Data Drill-Down wizard 30

Data Entry wizard 30

Data Record Viewer wizard 30

Database

native drivers 38 tools 38

Debugger evaluating expressions and setting

watches 60

overview 54

running 58

running across multiple pages 61

shortcut keys 62

specifying server mappings 58

stepping through code 60

toolbar 14

windows 59

Default internal browser 21

Defining controls, in VTML 96

Design mode 48

Design mode, disabling 48

Developer resources, Allaire 3

DHTML wizards 29

Dialog definition files, in VTML 89

Directory

default for snippets 35

default for templates and wizards

25

FTP server-assigned 19

mapping physical 22

setting initial for FTP server 19

Document

inserting a file 25

link CSS to 52

F

testing download times 74

Favorites folders 18

Files

converting text 25

Document Type Definition (DTD), in Tag

Tree 46

Documentation conventions 7

DocumentCache Object, in VTOM 151

Domain name

Double-spaced lines, replacing 66

Download times, testing 74

Downloading Web pages 18

Dynamic expressions in tags, in VTML

124

DYNSRC, IMG attribute, for video 33

E

Edit mode 12

Editing

code in tag Inspector 47

in Design mode 48

SQL queries 42

tags 45

EMBED tag 34

Encryption, via SSL 20

Entering tags, text, and other content

24

Event handler

case-sensitivity in CodeSweeper 49

highlighting functions in tag editors

45

scripting in Tag Inspector 47

Examples

ActiveScripting 157

CFML, running in Studio 22

regular expressions, in help searches

69

Excel, converting content from 26

Exception Handling wizard 30

Executing scripts, in VTOM 141

Explorer

importing files 17

Exploring the Studio Workspace 10

Expression Builder

customizing with VTML 88

using 36

Expressions

evaluating in Debugger 60

Extended find and replace 65

Extensions, file, setting 17

image 32

importing from Windows Explorer

17

managing in a project 76

managing in source control 84

managing local 17

managing remote 19

opening Web pages 18

read-only, editing 17

save as template 29

sound 33 video 33

Filter, the file list 17

Find and replace 64

Find command 64

Folders, opening favorites 18

Form

testting submittal in Debugger 61

Formatting with Cascading Style Sheets

51

Frames wizard 29

FTP

server properties 20

FTP servers 19

Functions

CFML, inserting 36

G

GIF files

in Studio 32

load colors in color palette 27

Graphic formats, supported in Studio

17

Gutter, in Edit mode 44

H

Help

creating your own in VTML 102

in dialogs 30

online 15

tag insight 27

Hexidecimal color values, inserting 27

Host Name

Hot keys 24, 44

H-P OpenPix 33

searching 64

Index 175

HTML

commenting code 24

testting form submittal in Debugger

61

wizards 29

I

Image control, in VTML 119

Image files

OpenPix 33

Image files, inserting 32

Import

HomeSite 3.0 palettes 27

Indent

setting in CodeSweeper 50

Initial directory, FTP server 19

Inserting

a file into a document 25

database column or table names into

image files 32

SQL into a page 41

tags from the QuickBar 31

Installing browsers 21

Interface, Studio 10

Internet Explorer

as default browser 21

dragging text from 26

required for Design mode 48

ISMAP, adding image map files 33

ISP, server connection 19

J

JavaScript

ActiveScripting example in VTOM

157

preserving event handler case-

sensitivity in CodeSweeper 49

wizard 29

JPEG files, in Studio 32

K

Keyboard shortcuts

for ActiveScript 141

using 44

L

LDAP wizard 30

Line numbers, in documents 44

Link checker 71

Link to a style sheet 52 link to document 52

Link verification toolbar 14

Links

in Site View 73

verifying in a document 71

verifying in a project 78

Local files, managing 17

M

MacIntosh, saving files as 18

Mailing List wizard 30

Main toolbar 13

Managing

files in a project 76

files in source control 84

local files 17

remote files 19

Mappings

development 22

RDS 55

Microsoft

ActiveScripting 140

converting Office content 26

Visual SourceSafe, adding a project

to 83

MIDI files, in Studio 33

Multi-character regular expressions, in

search 68

N

Named color values 27

Native database drivers, in CF

Enterprise 38

Netscape Navigator as default browser 22

EMBED tag 34

Newline, inserting from CodeSweeper

50

an ODBC data source 39

local files 17

Query Builder 39

OpenPix 33

Operators, inserting CFML 36

Output, Debugger 60

P

Passive mode, server connection 20

Password

Paths

relative for links and graphics 18

PNG files, in Studio 32

Populating dialogs with tag data, in

VTML 99

POSIX character classes, in regular

expression searches 67

Preserving code formats with

CodeSweeper 49

Printing

code and browser pages 25

Product features, Studio 2

Projects

for source control 82

managing files 76

toolbar 14

verifying links in 72

Properties

Proxy server, FTP 20

Q

Query Builder

opening 39

toolbar 14

Quick Reference Guide 11

QuickBar 13

Quotes, setting in CodeSweeper 49

O

ODBC data sources 39

OLE-DB drivers in CF Pro and Enterprise

38

Online help

creating your own in VTML 102

in dialogs 30

overview 5

searching 15 using 15

Opening

a new document 25

a project 77

R

RDS

Security settings for Debugger 59

Read-only files

editing 17

skip in searches 65

RealNetworks support 34

Record Viewer wizard 30

Recordsets, in Debugger 60

Registering data sources 38

176

Using ColdFusion Studio

Regular expressions

examples 69

using in search 66

Relative paths

for links and graphics 18

Remote Development Services (RDS)

20

Remote files

Removing files from a project 77

Replacing

a color value in a tag 27

Setting

breakpoints in code 58

CodeSweeper rules 49

colors for page elements 27

editing options 44

interface options 11

server mappings 22

tag help options 27

Shortcut

keyboard 44

Synchronized Multimedia Integration

Language (SMIL) 34

Synchronizing

files in source control 86

project files 77

T

Tables

converting to JS wizard 30

wizard 29

Tabs

Resources window

tabs 11

viewing 10

Results window for search, validator, links,

thumbnails 12

using 64

Right-click menus 11

Running

queries 42

Runtime functions, in VTML 128

S

Saved searches, running 65

Saving

code blocks as snippets 34

files as template 29

files to a remote server 21

keystrokes with code templates 35

local files 18

results 64

wizard files 121

Scripting event handlers 47

Search

case-sensitive 65

using 64

Verity wizard 30

with regular expressions 66

Secure Sockets Layer (SSL), in RDS

server 20

Security, RDS settings for Debugger 59

Selecting code and text blocks 26

Server-based page processing 22

Server-side

source control, using VSS 83

menus 11

Single-character regular expressions

66

Site View 73

Slide Show wizard, DHTML 29

SMIL tags 34

Snippets

adding shortcut keys 35 sharing 35

Sound files, adding 33

Source control

editing read-only files 17

implementing 80

managing files 84

server-side 83

Spaces

setting in CodeSweeper 50

using in project folder and file names

77

Special characters

converting 28

in regular expression searches 66

replacing 65

Special variables, in VTML 101

Specifying server mappings, for

debugging 58

Spell checking 70

SQL

editing queries 42 running a query 42

SSL, RDS server 20

Stepping through code, in Debugger

60

String functions, in VTML 128

Strip tag from document, setting in

CodeSweeper 50

Style Editor, for CSS 51

Style Guide, coding HTML/CFML 4

STYLE tag 52

setting in CodeSweeper 50

Tag Chooser

customizing with VTML 88

Tag Completion 28

Tag editors, building in VTML 95

Tag Insight 27

Tag Inspector

toolbar 14

using 47

Tag tips 16

Tag Tree

toolbar 14

using 45

Tags

adding help for, in VTML 102

BACKGROUND attribute in body 32

converting case 44

editors 45

entering 24

IMG 32

setting help options 27

specific settings in CodeSweeper

50

stack, in Debugger 60

supported in Link View 73

validating code 28

viewing hierarchy 45

VTML 89

Technical support, contacting 8

Templates

code 35

Testing page download times 74

Text

copying from a browser 26

entering 24

Third-party add-ins, in VTOM 162

Thumbnails, image 32

Index

Timeout request, FTP server 20

Toolbars

in VTOM 149

Studio 13

U

UNIX, saving files as 18

Uploading a project 78

URL, start for Debugger 59

User Name

Using

find and replace 64

server-based page processing 22

shortcut keys 11 shortcut menus 11

Site View to check page links 73

SMIL tags 34

UTC time format, using 20

V

Validation tab of Settings dialog 71

Variables

CFML, inserting 36

debugging 59

special, in VTML 101

VBScript 159

Verifying links

in a document 71

in a project 78

Verity wizard 30

Video files, adding 33

Viewing

links in Site View 73

Visual editing In Design mode 48

Visual Tool Markup Language (VTML)

88

Visual Tools Object Model (VTOM) 140

VTML, importing definition file for

outline profile 46

W

Watches, setting in Debugger 60

WAV files, in Studio 33

Web development features, in Studio

2

Web site, Allaire 3

Web, downloading pages from 18

Weight, testing document 74

White space, setting in CodeSweeper

49

Windows Explorer, importing files from

17

Wizards

HTML 29

VTML tag summary 121

Word wrap 44

Word, Microsoft, converting content

from 26

Writing and Executing Scripts, in VTOM

140

X

XML, DTD support in Tag Tree 46

177

advertisement

Was this manual useful for you? Yes No
Thank you for your participation!

* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project

Related manuals

Download PDF

advertisement

Table of contents