advertisement
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
Chapter 1: Setting Up Studio...........................................................................9
iv
Using ColdFusion Studio
Chapter 2: Creating Pages .............................................................................25
Contents
Chapter 3: Accessing ColdFusion Data Sources...........................................39
Chapter 4: Editing Pages ...............................................................................45
Using the Style Editor..............................................................................................................52
Chapter 5: Debugging CFML Applications from Studio..............................55
Chapter 6: Testing and Maintaining Web Sites ...........................................65
v
vi
Using ColdFusion Studio
Chapter 7: Creating Projects for Site Management.....................................77
Chapter 8: Adding Source Control for Development Projects ...................81
Chapter 9: Customizing the Development Environment............................89
Contents
Chapter 10: Scripting The Visual Tools Object Model ...............................141
vii
viii
Using ColdFusion Studio
Appendix: Online Help Search Tips ........................................................... 165
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
•
•
•
About ColdFusion Documentation .................................................................. 4
•
Printing ColdFusion Documentation............................................................... 5
•
•
•
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
•
•
Getting the Most from Studio’s Online Help System ..................................... 14
•
•
•
•
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.
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
.
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
•
•
•
•
Getting Started with Templates and Wizards................................................. 30
•
•
•
•
•
Saving Keystrokes with Code Templates ........................................................ 37
•
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
•
•
•
•
•
•
•
•
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
•
•
•
•
•
•
•
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
.
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
•
•
Configuring RDS from the Debugger ............................................................. 56
•
•
•
•
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
•
•
•
•
•
•
•
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
•
•
•
•
•
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
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
•
•
Implementing a Source Control System......................................................... 82
•
Choosing a Source Control Provider............................................................... 83
•
Creating a Studio Project for Source Control ................................................. 83
•
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
•
•
•
•
•
VTML Container/Control Reference ............................................................ 105
•
•
•
Creating Wizard Output Templates .............................................................. 129
•
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
•
•
•
•
•
•
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>”, “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
•
•
•
•
•
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
ActiveScripting
Adding
a project to source control 83
HTML files to the Help
links or images to a new file 18
Anchoring a regular expression to
Apj extension, for projects 77
Application development features
ASCII special characters,
B
BACKGROUND attribute, in body
Backreferences, in regular
Bookmarks
Breakpoints
Browser
IE as default 21 installation options 21
Building
C
Cascading Style Sheets (CSS),
Case
sensitivity, in CodeSweeper 49
CFML coding Style Guide 4
Character classes, in regular
Check in options, source control
Code preserving formats with
Coding, HTML/CFML Style Guide
4
ColdFusion
ColdFusion Administrator
Color
Configuring
Connecting to
Remote Development Services
Converting
Copying text from a browser 26
174
Using ColdFusion Studio
Creating
a project for source control 82
Cursor movement procedures, in VTOM
Customizing
Tag Chooser and Expression Builder,
D
Data
Database
Debugger evaluating expressions and setting
running across multiple pages 61
Developer resources, Allaire 3
Dialog definition files, in VTML 89
Directory
default for templates and wizards
setting initial for FTP server 19
Document
F
Files
Document Type Definition (DTD), in Tag
DocumentCache Object, in VTOM 151
Domain name
Double-spaced lines, replacing 66
Dynamic expressions in tags, in VTML
DYNSRC, IMG attribute, for video 33
E
Editing
Entering tags, text, and other content
Event handler
case-sensitivity in CodeSweeper 49
highlighting functions in tag editors
Examples
regular expressions, in help searches
Excel, converting content from 26
Executing scripts, in VTOM 141
Explorer
Exploring the Studio Workspace 10
Expression Builder
Expressions
importing from Windows Explorer
Form
testting submittal in Debugger 61
Formatting with Cascading Style Sheets
FTP
Functions
G
GIF files
load colors in color palette 27
Graphic formats, supported in Studio
H
Help
Hexidecimal color values, inserting 27
Host Name
Index 175
HTML
testting form submittal in Debugger
I
Image files
Import
Indent
Initial directory, FTP server 19
Inserting
database column or table names into
Internet Explorer
ISMAP, adding image map files 33
J
JavaScript
ActiveScripting example in VTOM
preserving event handler case-
K
Keyboard shortcuts
L
Link to a style sheet 52 link to document 52
Links
M
Managing
Mappings
Microsoft
Visual SourceSafe, adding a project
Multi-character regular expressions, in
N
Native database drivers, in CF
Netscape Navigator as default browser 22
Newline, inserting from CodeSweeper
P
Passive mode, server connection 20
Password
Paths
relative for links and graphics 18
Populating dialogs with tag data, in
POSIX character classes, in regular
Preserving code formats with
Printing
Projects
Properties
Q
Query Builder
Quotes, setting in CodeSweeper 49
O
OLE-DB drivers in CF Pro and Enterprise
Online help
Opening
R
RDS
Security settings for Debugger 59
Read-only files
176
Using ColdFusion Studio
Regular expressions
Relative paths
Remote Development Services (RDS)
Remote files
Removing files from a project 77
Replacing
Setting
Shortcut
Synchronized Multimedia Integration
Synchronizing
T
Tables
Tabs
Resources window
Results window for search, validator, links,
Running
Runtime functions, in VTML 128
S
Saving
keystrokes with code templates 35
Search
Secure Sockets Layer (SSL), in RDS
Security, RDS settings for Debugger 59
Selecting code and text blocks 26
Server-based page processing 22
Server-side
Single-character regular expressions
Snippets
adding shortcut keys 35 sharing 35
Source control
Spaces
using in project folder and file names
Special characters
in regular expression searches 66
Special variables, in VTML 101
Specifying server mappings, for
SQL
editing queries 42 running a query 42
Stepping through code, in Debugger
Strip tag from document, setting in
Style Guide, coding HTML/CFML 4
Tag Chooser
Tag editors, building in VTML 95
Tag Inspector
Tag tips 16
Tag Tree
Tags
BACKGROUND attribute in body 32
specific settings in CodeSweeper
Technical support, contacting 8
Templates
Testing page download times 74
Text
Third-party add-ins, in VTOM 162
Index
Timeout request, FTP server 20
Toolbars
U
User Name
Using
server-based page processing 22
shortcut keys 11 shortcut menus 11
Site View to check page links 73
V
Validation tab of Settings dialog 71
Variables
Verifying links
Viewing
Visual editing In Design mode 48
Visual Tool Markup Language (VTML)
Visual Tools Object Model (VTOM) 140
VTML, importing definition file for
W
Watches, setting in Debugger 60
Web development features, in Studio
Web, downloading pages from 18
White space, setting in CodeSweeper
Windows Explorer, importing files from
Wizards
Word, Microsoft, converting content
Writing and Executing Scripts, in VTOM
X
XML, DTD support in Tag Tree 46
177
advertisement
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
Related manuals
advertisement
Table of contents
- 9 Contents
- 10 Product Features
- 10 Web Development Features
- 10 Application Development Features
- 11 Developer Resources
- 12 About ColdFusion Documentation
- 12 ColdFusion Studio
- 12 Printed documentation
- 12 Online documentation
- 13 ColdFusion manuals
- 13 Printing ColdFusion Documentation
- 13 ColdFusion Server Acrobat files
- 14 ColdFusion Studio Acrobat files
- 14 Documentation Conventions
- 14 Getting Answers
- 15 Contacting Allaire
- 15 Corporate headquarters
- 15 Technical support
- 15 Sales
- 16 Setting Up Studio
- 16 Contents
- 17 Exploring the Studio Workspace
- 17 Customizing the workspace
- 18 Using shortcut menus
- 18 Using shortcut keys
- 18 The Resources window
- 19 Working in Edit, Browse, and Design modes
- 19 The Results window
- 19 Toolbars
- 19 Positioning toolbars
- 19 To dock a toolbar:
- 20 Main (D)
- 20 QuickBar (D)
- 20 Edit
- 20 Browse
- 20 Design
- 20 Debugger (D)
- 20 Link Verification (D)
- 20 Projects (D)
- 21 Help (D)
- 21 Tag Inspector (D)
- 21 Tag Tree (D)
- 21 Query builder
- 21 Getting the Most from Studio’s Online Help System
- 21 To use bookmarks:
- 21 To search online references:
- 22 Extending the help system
- 22 To add HTML files to the Help References:
- 22 Creating help files for custom tag editors
- 23 Tag help options
- 23 Using tag help
- 23 Using dialog help
- 23 Using F1 help
- 23 Using tag editor help
- 24 Managing Local Files
- 24 Opening files
- 24 To open local files:
- 24 To filter the file list:
- 24 Importing files from Windows Explorer
- 25 Playing favorites
- 25 Saving files
- 25 Downloading Web pages
- 25 To open a page from a Web site:
- 26 Managing Remote Files
- 26 Connecting to an FTP server
- 26 To add an FTP server:
- 27 Connecting to Remote Development Services
- 27 To add an RDS server:
- 28 Working with remote files
- 28 To open files on a remote server:
- 28 To save a file to a remote server:
- 29 Configuring Browsers
- 29 Browser installation options
- 29 Using server-based page processing
- 30 Setting server mappings
- 30 To define a server mapping:
- 31 Creating Pages
- 31 Contents
- 32 Building Pages
- 32 Entering tags, text, and other content
- 32 Commenting code
- 32 Color-coding tags
- 33 Printing code and browser pages
- 33 Document Basics
- 33 Opening a new document
- 33 Inserting a file into a document
- 33 To insert a file:
- 33 Converting a text file
- 34 Copying text from a browser
- 34 Converting Microsoft Office content
- 34 To convert Microsoft Word and Excel content:
- 34 Selecting code and text blocks
- 34 Setting colors for page elements
- 35 To replace a color value in a tag:
- 35 To import Studio 3.0 palettes:
- 35 Setting Tag Help Options
- 35 Tag Insight
- 35 To enable Tag Insight:
- 35 To use Tag Insight:
- 36 Tag Completion
- 36 Tag validation
- 36 Special characters
- 36 Getting Started with Templates and Wizards
- 37 Templates
- 37 HTML wizards
- 37 DHTML wizards
- 37 CFML Wizards
- 38 Working in Tag Chooser
- 38 Inserting Tags from the QuickBar
- 39 To move a QuickBar tab:
- 39 To organize QuickBar tabs:
- 39 To customize QuickBar tabs:
- 39 To add a toolbar:
- 39 To add a custom toolbutton:
- 40 Adding Media Content
- 40 Image files
- 40 Viewing image thumbnails
- 40 Image maps
- 40 To add a client-side image map:
- 41 OpenPix
- 41 Video
- 41 To add a video file to your Web page:
- 41 Sound
- 41 To add a sound file to your Web page:
- 42 RealNetworks support
- 42 Using SMIL tags
- 42 Saving Code Blocks as Snippets
- 42 To create a code snippet:
- 43 Sharing snippets
- 43 To create a shared snippets folder:
- 43 Adding snippet shortcut keys
- 43 Saving Keystrokes with Code Templates
- 44 Building CFML Expressions
- 44 To build expressions:
- 45 Accessing ColdFusion Data Sources
- 45 Contents
- 46 Introduction to Database Tools
- 46 Registering Data Sources
- 46 To register a data source:
- 46 Connecting to Data Sources
- 47 Opening an ODBC Data Source
- 47 To open a data source:
- 47 Using Query Builder
- 47 To open the Query Builder:
- 48 Building a SELECT Query
- 48 To create a SELECT statement:
- 48 To use a CFML variable in a SQL WHERE clause:
- 48 To save a query:
- 49 Inserting SQL into a Page
- 49 To insert a saved query:
- 50 Running and Editing Queries
- 50 Running a query
- 50 To run a query in the Query Builder:
- 50 Editing Queries
- 50 To edit a query:
- 51 Editing Pages
- 51 Contents
- 52 Setting Editing Options
- 52 Keyboard Shortcuts
- 52 Editing Tools
- 53 Tag Editors
- 53 Tag Tree and Tag Inspector
- 53 Tag Tree
- 53 To use the Tag Tree:
- 54 To configure the Tag Tree display:
- 54 To import an Outline Profile:
- 54 Tag Inspector
- 54 To use the Tag Inspector:
- 54 To change a tag definition file:
- 55 Scripting Event Handlers
- 55 Visual Editing in Design Mode
- 55 To edit a page in Design view:
- 55 To convert Microsoft Word and Excel content:
- 56 Preserving Code Formats with CodeSweeper
- 56 Configuring CodeSweeper
- 56 CodeSweeper settings
- 57 Tag-specific settings
- 57 To set rules for a tag:
- 57 To add a tag to a CodeSweeper:
- 57 Adding a new CodeSweeper
- 58 To add a new CodeSweeper:
- 58 Formatting Pages with Cascading Style Sheets
- 58 Using the Style Editor
- 58 To create a new style sheet:
- 58 To link a style sheet to documents:
- 59 To edit existing styles:
- 60 Debugging CFML Applications from Studio
- 60 Contents
- 61 Interactive Debugger Overview
- 61 Configuring RDS from the Debugger
- 61 To configure a remote development server:
- 62 Creating RDS Mappings
- 62 File mapping examples
- 62 Using local paths
- 63 Using drive mappings
- 63 Using UNC paths/Network Neighborhood
- 64 Using Remote Development Services
- 64 Specifying Server Mappings
- 65 To specify server and file mappings for debugging:
- 65 Running the Interactive Debugger
- 65 To run the interactive debugger:
- 66 Debug windows
- 67 Stepping through code
- 67 Evaluating expressions and setting watches
- 67 To set watches:
- 68 Debugging across multiple pages
- 69 Debugger Shortcut Keys
- 70 Testing and Maintaining Web Sites
- 70 Contents
- 71 Working in the Results Window
- 71 Saving results
- 71 Using Find and Replace
- 71 Search commands
- 71 To search the current document:
- 72 To replace text in the current document:
- 72 Using extended search and replace features
- 72 Replacing special characters
- 73 Replacing double-spaced lines
- 73 Searching with Regular Expressions
- 73 Special characters
- 73 Single-character regular expressions
- 74 Character classes
- 75 Multi-character regular expressions
- 76 Backreferences
- 76 Anchoring a regular expression to a string
- 76 Expression examples
- 77 Resources
- 77 Checking Spelling
- 77 To run the spell checker:
- 78 Validating Code
- 78 To run the validator:
- 78 Verifying Page Links
- 78 To verify links in the current document:
- 79 Link verification options:
- 79 Verifying links in a project:
- 80 Using Site View to Check Page Links
- 80 Testing Page Download Times
- 80 To test the current document’s download time:
- 81 To set the root URL for an FTP server:
- 82 Creating Projects for Site Management
- 82 Contents
- 83 Why Use Projects?
- 83 The Projects Tab
- 83 Managing Files in a Project
- 84 To create a project:
- 84 To open a project:
- 84 To add a file to a project:
- 84 To remove a file from a project:
- 85 Verifying Links in a Project
- 85 To check the links in project files:
- 85 Uploading a Project
- 85 To upload a project:
- 86 Adding Source Control for Development Projects
- 86 Contents
- 87 Why Use Source Control?
- 87 Implementing a Source Control System
- 88 Local and remote source control
- 88 Standard source control commands
- 88 Choosing a Source Control Provider
- 88 Creating a Studio Project for Source Control
- 89 Establishing a working directory
- 89 Adding a Studio project to source control
- 89 To add a Studio project to Visual SourceSafe:
- 90 Setting up server-side source control
- 90 Server installation:
- 90 Client installation:
- 91 Managing Files in Source Control
- 91 Check-in options
- 91 Command options
- 92 Adding files and subdirectories
- 92 To add a new file to source control:
- 92 To create a new subdirectory:
- 92 Synchronizing files
- 92 To synchronize project files with source control:
- 92 To add files from source control to your working directory:
- 92 To remove local files:
- 94 Customizing the Development Environment
- 94 Contents
- 95 The Visual Tools Markup Language (VTML)
- 95 Customizing Tag Chooser and Expression Builder
- 95 Customization objective
- 96 Dialog Definition Files
- 97 Category tag
- 97 Element tag
- 98 Creating Tag Definitions
- 99 Creating a tag definition file
- 99 Defining attributes
- 100 Defining attribute value types
- 100 Defining enumerated values
- 102 Defining attribute categories
- 102 Building Tag Editors
- 103 Defining controls
- 106 Populating dialogs with tag data
- 107 Special $$TAGBODY attribute name
- 107 Generating a tag
- 107 Variables passed to the layout template
- 108 Special variables
- 108 Using OPTIONLowerCaseTags
- 108 Using OPTIONLinearLayout
- 109 Using TAGDATAUnknownAttributes
- 109 Adding Tag Help
- 110 Providing help from an external file
- 110 VTML Container/Control Reference
- 110 TabDialog container
- 111 TabDialog example:
- 111 TabPage container
- 112 TabPage example:
- 112 Panel container
- 112 Panel example:
- 114 Label control
- 114 Label example:
- 115 TextBox control
- 115 TextBox example
- 116 DropDown control
- 116 DropDown example
- 117 FontPicker control
- 117 FontPicker example
- 118 ColorPicker control
- 118 ColorPicker example
- 119 CheckBox control
- 119 Checkbox example
- 120 RadioGroup control
- 120 RadioGroup example
- 121 TextArea control
- 121 TextArea example
- 122 SQLTextArea control
- 122 SQLTextArea example
- 124 FileBrowser control
- 125 FileBrowser example
- 126 Image control
- 126 Image example
- 127 ActiveX control
- 127 ActiveX example
- 127 Building Custom Wizards
- 127 To create a wizard:
- 128 Saving wizard files
- 128 Creating Wizard Definition Pages
- 128 VTML for Wizards tag summary
- 128 VTML for Wizards tag reference
- 129 WIZARD
- 129 PARAM (for WIZARD tag)
- 129 TEMPLATE
- 130 PAGE
- 130 PARAM (for PAGE tag)
- 130 INPUT
- 131 NEXTPAGE
- 131 Dynamic expressions in tags
- 131 Bound controls
- 132 Wizard definition page example
- 134 Creating Wizard Output Templates
- 134 Using WIZML
- 134 Parameters
- 134 Expressions and functions
- 135 String functions
- 135 Runtime functions
- 136 WIZ Tags
- 136 Supported tags
- 136 Special considerations
- 136 WIZML reference
- 136 WIZSET
- 137 WIZINCLUDE
- 137 WIZLOOP, WIZBREAK, and WIZCONTINUE
- 138 WIZIF, WIZELSEIF, and WIZELSE
- 138 Wizard Definition Page Library
- 138 SelectNameAndLocation
- 138 Description
- 139 Exposes controls
- 139 Example
- 139 SelectDataSource
- 139 Description
- 139 Uses controls
- 139 Reads parameters
- 140 Example
- 140 SelectTables
- 140 Description
- 140 Exposes controls
- 140 Reads parameters
- 141 Example
- 141 SelectTable
- 141 Description
- 141 Exposes controls
- 141 Reads parameters
- 142 Example
- 142 SelectTableJoins
- 142 Description
- 142 Exposes controls
- 142 Reads parameters
- 142 Example
- 143 SelectFields
- 143 Description
- 143 Exposes controls
- 143 Reads parameters
- 143 Example
- 144 SelectField
- 144 Description
- 144 Exposes controls
- 144 Reads parameters
- 144 Example
- 145 Scripting The Visual Tools Object Model
- 145 Contents
- 146 Writing and Executing Scripts
- 146 Writing Scripts
- 147 Executing Scripts
- 147 Application Object
- 147 Application (TAllaireClientApp) Object
- 147 Properties
- 149 Methods
- 154 Projects
- 155 Toolbars
- 157 DocumentCache Object
- 157 Properties
- 158 ActiveDocument Object
- 158 Properties
- 159 Methods
- 162 Cursor Movement Procedures
- 162 ActiveScripting examples
- 162 JavaScript
- 164 VBScript
- 167 Third-Party Add-Ins
- 168 Contents
- 169 Search Case Sensitivity
- 169 Multiple Word Searches
- 169 Wildcards
- 170 Operators
- 170 NEAR operator
- 170 NEAR/N operator
- 171 OR operator
- 171 PARAGRAPH operator
- 171 PHRASE operator
- 172 SENTENCE operator
- 172 STARTS operator
- 172 SUBSTRING operator
- 172 WILDCARD operator
- 173 WORD operator
- 174 Modifiers
- 174 CASE modifier
- 174 MANY modifier
- 175 NOT modifier
- 175 ORDER modifier