User Guide

Manuals Brands Macromedia Manuals Other COLDFUSION STUDIO 5-USING COLDFUSION 5 STUDIO

CFS_MANCVRPG_live.fh9 10/1/01 12:37 PM Page 1

Composite

C M Y CM MY CY CMY K

macromedia

Using ColdFusion 5 Studio

COLDFUSION

STUDIO

macromedia

Summary of content (328 pages)

PAGE 1

CFS_MANCVRPG_live.
PAGE 2

Copyright Notice Copyright 2001 Macromedia, Inc. All rights reserved. Macromedia, the Macromedia logo, ColdFusion, Dreamweaver, Dreamweaver UltraDev, Flash, HomeSite, JRun, Quick Tag Editor, Roundtrip, and what the web can be are trademarks or registered trademarks of Macromedia, Inc. which may be registered in the United States and internationally. Java and Solaris are trademarks of Sun Microsystems, Inc.
PAGE 3

Contents About This Book ................................ xi Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii Developer Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Macromedia Web site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ColdFusion Web resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 4

iv Contents Connecting to servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling Secure FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding server mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Understanding RDS Mappings . . . . . . . . . . . .
PAGE 5

Contents v Chapter 5 Writing Code and Web Content ......... 53 Inserting Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Inserting tags from the QuickBar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Selecting tags from the Tag Chooser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Completing tags with Tag Editors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 6

vi Contents Editing code in the Tag Inspector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Setting the display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Creating and editing event handler script blocks . . . . . . . . . . . . . . . . . . . . . 80 Formatting Pages with Cascading Style Sheets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 About the Style Editor . . . . . . . . . . . . . . . . . . . .
PAGE 7

Contents vii Chapter 8 Accessing Data Sources .............. 109 Introduction to Database Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 Working with Data Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring data sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Connecting to data sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 8

viii Contents Displaying the Source Control toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 Sharing project files in Visual SourceSafe . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Administering multiuser projects in VSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Chapter 11 Deploying Files ..................... 139 Setting Default Deployment Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 9

Contents ix Defining attribute categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 Building Tag Editors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Populating dialog boxes with tag data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Generating a tag . . . . . . . . . . . . . . . . .
PAGE 10

x Contents Application Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Toolbar and toolbutton methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 11

About This Book Using ColdFusion Studio is designed to familiarize you with the product’s user interface and productivity tools that you can use to quickly develop high-quality applications and Web content. Contents • Intended Audience.................................................................................................... xii • Developer Resources................................................................................................. xii • About the Documentation......................
PAGE 12

xii About This Book Intended Audience This book is intended for professional Web developers who have a working knowledge of HTML and Web server environments. It introduces you to the ColdFusion Studio user interface and development tools, and provides instructions for installing, configuring, and using the product. Developer Resources Macromedia Corporation is committed to setting the standard for customer support in developer education, technical support, and professional services.
PAGE 13

Developer Resources xiii Resource Description URL Developer Exchange Open repository where you can view, http://www.macromedia.com/go/ contribute, and download multiple types of fp_cfstudio_exchange content that benefit software developers, for example custom tags, scripts, Web content, visual tools, and third-party applications Browser testing sites Browser compatibility is still an important issue for Web site developers and these sites provide online testing services. http://builder.cnet.
PAGE 14

xiv About This Book About the Documentation The documentation is designed to provide support for the complete spectrum of participants. The print and online versions are organized to allow you to quickly locate the information that you need. The online documentation is provided in HTML and Adobe Acrobat formats. You can also access release notes, product support information, and several developer resources from the Help menu.
PAGE 15

About the Documentation xv Book Description CFML Reference Provides descriptions, syntax, usage, and code examples for all ColdFusion tags, functions, and variables CFML Quick Reference A brief guide that shows the syntax of ColdFusion tags, functions, and variables Viewing online documentation You can view Help for a specific tag, Help topics in HTML format, or online documentation in Adobe Acrobat (PDF) format. To view Help for a tag: • Position the cursor in a tag and press F1.
PAGE 16

xvi About This Book Printing online documentation You can print one Help topic at a time in the HTML Help, or print as many pages of the Help as you need from the Adobe Acrobat (PDF) format of the Help. To print a single Help topic in the HTML Help: 1 Display the Help topic you need to print. For instructions, see “Viewing online documentation” on page xv. 2 Right-click the topic in the Document window and select your browser’s command to print.
PAGE 17

Getting Answers xvii Getting Answers One of the best ways to solve particular programming problems is to tap into the vast expertise of the ColdFusion Studio developer communities on the ColdFusion Forum. on the Macromedia Web site. Other developers on the forum can help you figure out how to do just about anything with ColdFusion Studio. The search facility can also help you search messages from the previous 12 months, allowing you to learn how others have solved a problem that you might be facing.
PAGE 18

xviii About This Book
PAGE 19

Chapter 1 Setting Up the Product This chapter contains instructions for installing or upgrading ColdFusion Studio and configuring it. Contents • System Requirements ................................................................................................. 2 • Installing or Upgrading............................................................................................... 2 • Completing Setup ......................................................................................................
PAGE 20

2 Chapter 1 Setting Up the Product System Requirements Following are the minimum installation requirements: • Pentium-compatible processor (Pentium II or higher recommended) • • • • • Windows® 98, ME, NT 4, 2000, XP Internet Explorer 4.
PAGE 21

Completing Setup 3 5 Follow the instructions in the Installation Wizard. 6 Once the program files are copied to your system, select the option to restart your machine and click Finish to complete the installation. The upgrade is completed. Completing Setup This section explains how to initially set up ColdFusion Studio if you have installed it for the first time, and how to set up ColdFusion Studio based on the options that were set in a previous version.
PAGE 22

4 Chapter 1 Setting Up the Product Setting up for the first time This section explains how to complete the Initial Configuration Wizard (ICW) if you installed ColdFusion Studio for the first time, or if you uninstalled and installed it. To complete the ICW after a first-time installation: 1 The ICW automatically starts when you run ColdFusion Studio for the first time. 2 In the initial welcome dialog box of the wizard, click Next.
PAGE 23

Completing Setup 5 • 4 If the previous version contained customizations such as shortcuts, snippets, code templates, and modifications to Tag Completion and Tag Insight, then the Upgrade Feature Customizations dialog box appears. Select every customization that you want to carry over to the current version and click Next. In the Preserve Editor Settings dialog box, select the options to carry over to the current version. Click Next.
PAGE 24

6 Chapter 1 Setting Up the Product Monitoring System Resources ColdFusion Studio’s extensive use of GDI and User resources under Windows 98/ME has consistently caused problems for users on these platforms. This section describes the problem and how to mitigate it. For more information, also see Knowledge Base article 21011 on the Macromedia Web site.
PAGE 25

Monitoring System Resources 7 Using the Resource Level Monitor This section explains how to respond to warnings and how to configure the monitor. Responding to warnings The following graphic is an example of the warning dialog box that appears if you have the default warning threshold for GDI resources set at 15% and your available GDI resources drop below this level. For best results, at least save your work, even if you choose to continue.
PAGE 26

8 Chapter 1 Setting Up the Product
PAGE 27

Chapter 2 Configuring Browsers and Servers This chapter contains instructions for setting up browsers and servers. Contents • Configuring the Internal Browser ............................................................................ 10 • Configuring External Browsers ................................................................................ 11 • Working with Files on Remote Servers ....................................................................
PAGE 28

10 Chapter 2 Configuring Browsers and Servers Configuring the Internal Browser The following sections describe the choices available for browsing documents and application pages from within Studio. Setting the internal browser options You can use the internal browser to view documents in a Web browser within the program. To set options, select Options > Settings and click Browse.
PAGE 29

Configuring External Browsers 11 Configuring External Browsers As part of the installation process, the program compiles a list of the Web browsers it detects on your system. You can view, add, edit, and delete browsers; you can change the default browser; and you can set the browsers’ file saving behavior. To view the list of browsers: • Select Options > Configure External Browsers.
PAGE 30

12 Chapter 2 Configuring Browsers and Servers To delete a browser from the list: 1 Select Options > Configure External Browsers to open the External Browsers dialog box, if it is not already open. 2 Click the browser to remove from the list and click Delete. 3 Click Yes in the message that appears to confirm that you want to delete it. 4 Click OK to save your changes and close the External Browsers dialog box.
PAGE 31

Working with Files on Remote Servers 13 Working with Files on Remote Servers Working with directories and files on remote servers is virtually identical to working with them on local or network drives. For example, when you save files, changes are saved to the remote server. The primary difference is that you must establish a connection to a remote server before you can work with its files. You can work on remote servers from the Files tabs and from Windows Explorer via Explorer shell integration.
PAGE 32

14 Chapter 2 Configuring Browsers and Servers 2 Select the appropriate compatibility option: • • 3 Allaire HomeSite/Studio 4.5.2 Enables the remote server functionality in both this version and in previous versions and changes the name of the SNE node to “Allaire FTP & RDS.” Macromedia HomeSite/Studio 5.0+ Enables the remote server functionality only in this version. Click Switch to apply the change, and click Close.
PAGE 33

Working with Files on Remote Servers 15 To connect to an FTP server: 1 Open the drive list at the top of the Files tab and select Macromedia FTP & RDS. You can also access this feature from Windows Explorer. 2 Right-click Macromedia FTP & RDS and select Add FTP Server to open the Configure FTP Server dialog box. 3 Enter the following information for the server that you want to connect to: Field Description Comment Description Descriptive name to display in the Files tab and in Windows Explorer.
PAGE 34

16 Chapter 2 Configuring Browsers and Servers Field Description Comment Disable passive mode Option to select if the server does not use passive connections. File time offset The number of hours ahead or If you set this value, you behind the current local time to cannot select the Assume UTC use in the date/time file times option. information for files on the FTP server.
PAGE 35

Working with Files on Remote Servers 17 To enable SSL for an FTP connection: 1 Open the Properties dialog box and select the Secure (SSL) option. 2 Click the Configure SSL button and make the appropriate certificate entries. Click the Help button for information on these settings. 3 Click OK. This table summarizes the error messages you could receive: Error message Cause Unable to connect to the FTP server.Success Remote Server Operation Failure: Winsock Error: Connection aborted.
PAGE 36

18 Chapter 2 Configuring Browsers and Servers Connecting to an RDS server Complete the following configuration procedure for each ColdFusion server that you want to access. To connect to an RDS server: 1 In ColdFusion Studio, click the Files tab at the bottom of the Resources window. 2. Open the Drive list at the top of the Files pane and select Macromedia FTP & RDS. 3 Right-click Macromedia FTP & RDS in the Directory list and select Add RDS Server. 4.
PAGE 37

Working with Files on Remote Servers 19 Adding server mappings A development mapping is essential for working with files via Remote Development Services (RDS).
PAGE 38

20 Chapter 2 Configuring Browsers and Servers Anwer these questions in the RDS dialog box: • Studio Path How does ColdFusion Studio see the directory? • ColdFusion Path How does the Web server/ColdFusion server see the directory? • Browser Path How does the browser see the directory? Note An error will occur if you try to browse a file when there is a mismatch between the Studio Path in a mapping defined in the Remote Development Settings and the path of the active file.
PAGE 39

Working with Files on Remote Servers 21 For example, a user might 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 might be viewed by the server as C:\webprojects\App1\index.cfm and the browser might view it using the URL path http://215.180.21.1/App1/index.
PAGE 40

22 Chapter 2 Configuring Browsers and Servers Using Remote Development Services When developing outside local area networks, you access files on a ColdFusion server across the Internet using Remote Development Services (RDS). In such a scenario, a file that appears to Studio as RDS://MY_RDS_SERVER/C:/webprojects/App1/index.cfm might be viewed by the server as C:\webprojects\App1\index.cfm and the browser might view it using the URL path http://215.180.21.1/App1/index.
PAGE 41

Working with Files on Remote Servers To edit a mapping: 1 Select a mapping from the list. 2 Make changes as necessary and click Update. To change to a different mapping: • Select the mapping to switch to in mappings list. To set a mapping as the default: 1 Select Options > Settings and click Browse. 2 Select the entry that you want to move in mappings list. 3 Click the up arrow button to move the entry to the top of the list. 4 Click OK.
PAGE 42

24 Chapter 2 Configuring Browsers and Servers
PAGE 43

Chapter 3 Exploring the Workspace This chapter acquaints you with the main areas of the interface. It also gives you some pointers on customizing the workspace to make all of your development work as productive as possible. Contents • The Workspace Areas ................................................................................................ 26 • Working in the Resources Window ..........................................................................
PAGE 44

26 Chapter 3 Exploring the Workspace The Workspace Areas The term workspace describes the user interface that you see when you first load the program. The workspace has four principal areas: • Command area At the top of the workspace is the title bar, which displays the file path of the current document. Below that is the menu bar, which contains standard Windows commands plus development menus. Below the menus are toolbars that provide one-click access to commands and application tools.
PAGE 45

Working in the Resources Window 27 Setting workspace options Selecting Options > Settings (F8) opens the control center for user preferences. By navigating the feature tree in the left pane, you can view and change options for file management, coding, and testing applications and Web content. Working in the Resources Window The Resources window is a tabbed user interface that gives you quick access to file management, development, and Help resources.
PAGE 46

28 Chapter 3 Exploring the Workspace • Snippets tab Provides a convenient place to store code blocks and content for reuse. Snippets can also be shared with other users. • Help tab Contains product documentation and other online resources. You can customize the help by adding help files and editing existing help files. For more information, see “Extending the Help system” on page 39. • Tag Inspector tab Lets you edit in an interactive property sheet user interface.
PAGE 47

Creating and Browsing Files in the Document Window 29 Creating and Browsing Files in the Document Window The Document window is the center for code and content development. It has tabs for working in Edit and Browse mode, and to view Help. You can press F12 to switch from the Help to Edit tab, and press F12 again to switch from the Edit to Browse tab. The rest of this section describes each tab in detail. Tip To edit your page visually, you can open it in UltraDev from ColdFusion Studio.
PAGE 48

30 Chapter 3 Exploring the Workspace Help tab This tab displays tag-specific Help and pages from the Help References. This tab becomes visible in the workspace when you first open it.
PAGE 49

Customizing the Workspace 31 Customizing the Workspace There are many ways to customize the look and functionality of your workspace, including setting the display and positioning of toolbars and Resource window tabs; assigning shortcut keys for commands, code snippets, and scripts; and creating custom toolbuttons. This section provides instructions for using these basic customizations.
PAGE 50

32 Chapter 3 Exploring the Workspace To hide or show a toolbar: 1 In the Customize dialog box, in the Visible Toolbars box, clear the checkbox next to the toolbar you want to hide. 2 To show a toolbar, select the checkbox next to the toolbar in this same list. Tip To reset the default settings for which toolbars are shown or hidden, click Reset to Defaults in the Customize dialog. This also moves every toolbar back to its default position.
PAGE 51

Customizing the Workspace 33 3 In the Toolbuttons box, click the vertical scrollbar and drag it down until you see the button you want to add. 4 Click the button in the Toolbutton box and drag it to a free space in the toolbar shown under Toolbar View. The button is added to the toolbar. 5 Click Close to return to working in the product. To add a custom button to a toolbar: 1 Select Options > Customize from the menu to open the Customize dialog box.
PAGE 52

34 Chapter 3 Exploring the Workspace 3 On the toolbar shown under Toolbar View, drag each button you want to move to its new location. The buttons are rearranged in your toolbar as you make changes. 4 Click Close to return to working in the product. To remove a button from a toolbar: 1 Select Options > Customize from the menu to open the Customize dialog box. 2 In the Visible Toolbars box, select the toolbar from which you want to remove a button.
PAGE 53

Getting the Most from the Help System 35 Getting the Most from the Help System The online Help system encompasses a variety of features: • Pop-up Help for basic tag syntax (F2) • Comprehensive context-sensitive tag Help (F1) • Embedded Help in tag editors, Tag Chooser, and Expression Builder (F1 and Ctrl+F1) • An extensive collection of searchable references in the Help tab Opening Help in tag editors and Tag Chooser Help text in tag editors and in the Tag Chooser provides context-sensitive syntax and us
PAGE 54

36 Chapter 3 Exploring the Workspace Bookmarking Help topics You can quickly access your favorite Help documents by bookmarking them. You can assign bookmarks to documents in the Help tree, the file system, or the Internet. To bookmark a document in the Help Tree: • If the Help document is closed, right-click the document title and click Add bookmark. • If the Help document is open, it automatically displays in the Bookmarks list. If the document is not open, right-click again and select Refresh.
PAGE 55

Getting the Most from the Help System 37 Searching Help References You can access a book’s online index in the Help reference tree, or you can search the entire set of Help References using simple to complex search criteria. Using an online index With the exception of language references, each book in the Help reference tree on the Help Resources tab has an online index. To search a book using an index: 1 Decide on the term or terms you want to find in the index.
PAGE 56

38 Chapter 3 Exploring the Workspace 5 Click the Search button to display the search results in the Help References pane. 6 Double-click a document in the results list to open it. The results list is saved until a new search is run, so you can return to the document list by clicking the Search results button on the Help toolbar. Tip To redo a recent search, click the down arrow next to the Enter the word(s) to find box and select the search keywords you previously used from the drop-down list.
PAGE 57

Getting the Most from the Help System 39 Members of the Macromedia documentation group then attempt to correct errors and clarify points directly on the Comments page. Larger documentation issues are targeted to the next product release. And, in general, they use your feedback to assess the effectiveness of their user guides and to improve them. Note LiveDocs is not technical support. For technical issues, you should go to the Technical Support page on the Macromedia site to view support options.
PAGE 58

40 Chapter 3 Exploring the Workspace To add documents to the Help tree, do one of the following: • Write an HTML Help file and save it to a folder in the Help directory • Use standard Windows commands to paste a file into a Help folder • Display the document to add in a Web browser and then choose the Save As command to save it to a folder in the Help directory Changing the order of items in the Help tree If you add a folder to the Help directory, the folder appears at the bottom of the Help reference tr
PAGE 59

Getting the Most from the Help System 41 Adding media content You have considerable flexibility in adding supporting files (such as graphics, animations, video, and sound) to Help documents. There are two ways to do this: • Create a file structure in the Help tree that conforms to the media file references in your documents. For example you might copy an Images folder into your custom help folder.
PAGE 60

42 Chapter 3 Exploring the Workspace
PAGE 61

Chapter 4 Managing Files This chapter describes how to perform file management tasks such as opening, closing, saving, and automatically backing up files. This chapter also describes how to work with Unicode and DBCS (Double-Byte Character Support) files. The tasks described in this chapter do not replace the need for creating a project to organize the files in a Web site or Web application. For instructions on how to use projects, see “Managing a Web Site with Projects” on page 125.
PAGE 62

44 Chapter 4 Managing Files About the Files Tabs The Files tabs in the Resources Window give you access to servers, drives, directories, and files without having to go to Windows Explorer. Having two Files tabs reduces the amount of file system navigation needed to work across multiple directories and drives.
PAGE 63

About File Encoding 45 The Files tabs use these rules to determine which directory is the current directory: • When browsing to a file in a tag editor, the current directory is the folder that the current document is in. Options > Settings > General > Display current folder in file dialogs must be set. • Otherwise: − If only one File tab is visible, the current directory is the one displayed in the visible File tab.
PAGE 64

46 Chapter 4 Managing Files Working with Files You can use the following procedures to work with files, regardless of their location (local drive, network drive, or remote server). Opening and saving files refer to the current directory. For information about how ColdFusion Studio determines the current directory with two Files tabs, see “About the Files Tabs” on page 44.
PAGE 65

Working with Files 47 To open an encoded file: • Before opening the file, make sure you have Unicode formatting enabled. If you do not, enable it. For instructions, see “About File Encoding” on page 45. If you attempt to open a Unicode file without having selected the Enable non-ANSI file encoding option, the encoding format of the file cannot be detected or handled properly. The file is loaded as an ANSI string of the same type as is specified in your system language settings.
PAGE 66

48 Chapter 4 Managing Files Use the Save commands from the File menu or the Standard toolbar icons to save and close files. Open the Settings dialog box (F8) and use the File Settings pane 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 a link or image to a new file, you are prompted to save the file.
PAGE 67

Working with Files 49 How Auto-Backup works Following are the steps that the product takes in order to back up your files: 1 A default AutoBackup folder is created below the product directory during installation. You can change the location to a different local or network directory as needed. 2 A control file named AutoBackup.ini is automatically created to track files in the selected backup location. If you change the backup location, a new .ini file is created there.
PAGE 68

50 Chapter 4 Managing Files To recover unsaved files after the application closes abnormally: 1 Open ColdFusion Studio again. 2 If you have set options for Timed Auto-Backup, the Timed Auto-Backup Recover dialog box automatically appears. Recover each lost file by selecting it and clicking OK. 3 Otherwise, select Options > Auto-Backup File Maintenance and, in the Auto-Backup File Maintenance dialog box, check the files that you need to recover and select File > Open Selected Files for Edit.
PAGE 69

Working with Files 51 Building a favorite folders list You can build a list of favorite folders to make accessing their files easier. To add a folder to the favorites list: 1 Select the folder in the Directory List. 2 In the file list, right-click and select Favorite Folders > Add Current Folder to Favorites. The folder is added to your favorites list for easy selection. To view a favorite folder: 1 Right-click in the file list and select Favorite Folders from the menu.
PAGE 70

52 Chapter 4 Managing Files To copy Web page content do one of the following: • To select a block of text on a Web page and insert it into a document, use Windows copy and paste commands. Note that page formatting is not preserved. • To copy the code behind a Web page, use the browser’s command to view the page source code, and then copy and paste the content you want. Note Please adhere to any copyright and other restrictions on Web document content.
PAGE 71

Chapter 5 Writing Code and Web Content ColdFusion Studio manages many different Web development tasks, from writing simple HTML pages to designing, testing, and deploying complex, dynamic sites. This chapter describes basic techniques for creating Web content and application code. Contents • Inserting Code ........................................................................................................... 54 • Using Inline Tools to Enter Code .......................................................
PAGE 72

54 Chapter 5 Writing Code and Web Content Inserting Code ColdFusion Studio coding tools support a range of writing styles, from typing to point-and-click, and you can set the level of support you want: for repetitive tasks, you can use its productivity tools to enter repeated code blocks and required text; when coding tags that you are not familiar with, you can display pop-up tips and lists of language elements.
PAGE 73

Inserting Code 55 To do this Do this Add custom toolbutton Click Add Custom Button. Custom Toolbutton dialog box displays. Select an action;complete entries for action; click OK. Add separator In Customize dialog box, Visible Toolbars list, click a toolbar. Click Add Separator. Separator is added. Drag separator. Remove toolbutton In Customize dialog box, Visible Toolbars list, click a toolbar. or separator Drag item from toolbar to outside of toolbar.
PAGE 74

56 Chapter 5 Writing Code and Web Content Completing tags with Tag Editors You can use a Tag Editor to add a lot of content within an existing tag, for example in the body tag. To complete the details for a tag: 1 In the Editor, position the cursor in the tag to complete. 2 Right-click, and select Edit Current Tag from the popup menu. 3 Complete the Tag Editor dialog box. For help, click the Embedded Help button or see the Tag Definitions documentation, located in the Help References pane.
PAGE 75

Using Inline Tools to Enter Code 57 Using Inline Tools to Enter Code You have a number of tools to help you easily insert new code and to edit existing code as you type. Each of these tools supports a distinct language element, such as tags, objects, and functions. You can set the options for these inline tools in the Settings dialog box (F8). Tag Insight Tag Insight lets you insert tag names, attributes, and values as you type, after typing a start bracket (<) for a tag.
PAGE 76

58 Chapter 5 Writing Code and Web Content • To change an attribute: Delete the attribute and add a new attribute. • To add a value: Press the spacebar after the attribute to display a drop-down list of known values for the attribute. Select a value and press Enter. • To change a value: Delete the value and add a new value. Function Insight Function Insight lets you insert function argument syntax as you type.
PAGE 77

Using Inline Tools to Enter Code 59 Auto Completion Auto Completion completes a code block by inserting the appropriate code when you type the opening code fragment (trigger string). You can set options for this feature in the Options > Settings > Editor > Auto Completion pane. Only a few strings are listed by default; for example, to insert --> after you type PAGE 206
188 Chapter 13 Customizing the Development Environment PAGE 207
Creating Wizard Output Templates 189 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 with a single attribute FILEPATH, the template could look as simple as this: This example will create a file with a single tag.
PAGE 208

190 Chapter 13 Customizing the Development Environment For syntax and usage information, see Expressions and Functions in the VTML Reference. 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.
PAGE 209

Wizard Definition Page Library 191 Wizard Definition Page Library A set of seven page definition files is available in ColdFusion Studio and JRun Studio. The library can be used to quickly build data access capabilities into wizards. This section is included for HomeSite users who may want to upgrade to use these additional features. Examples Following are examples of each of the seven wizard definition pages available in the library.
PAGE 210

192 Chapter 13 Customizing the Development Environment SelectTables PAGE 211
Wizard Definition Page Library 193 SelectFields PAGE 212
194 Chapter 13 Customizing the Development Environment
PAGE 213

Chapter 14 Scripting the Visual Tools Object Model The term Visual Tools refers to the Macromedia products HomeSite, ColdFusion Studio, and JRun Studio. Using the Visual Tools Object Model, developers can extend their work in two broad categories: • Power users can script recurring tasks. • Application developers can call Visual Tools functionality for use in their applications. This chapter describes how to write and execute scripts in Visual Tools.
PAGE 214

196 Chapter 14 Scripting the Visual Tools Object Model Writing and Executing Scripts in Visual Tools The Visual Tools expose an Object Model, enabling developers to manipulate program functionality from external applications. In addition, power users can create scripts to automate tasks using JScript or VBScript and run the scripts from the Visual Tools environments. The Visual Tools internal scripting feature requires the Microsoft ActiveScripting engine version 3.
PAGE 215

Writing and Executing Scripts in Visual Tools 197 To automate Visual Tools tasks, you must familiarize yourself with the Visual Tools Object Model (VTOM). The main object is the Application object. The Application object contains two important child objects, the ActiveDocument object and the DocumentCache object. You can use these objects to write scripts for common tasks. In addition, the Application object contains a number of toolbar-related functions, which enable you to create toolbars dynamically.
PAGE 216

198 Chapter 14 Scripting the Visual Tools Object Model Creating a custom toolbutton and toolbar After you write a script, you can create a custom toolbutton to execute the script from within the program. If you intend to write multiple scripts, you can create a toolbar for them. You can rearrange the buttons and add separators in the toolbar. To create a custom toolbutton: 1 On the Toolbars tab, select your custom script toolbar from the Toolbars list. The toolbar displays at the top of the tab.
PAGE 217

Application Object 199 Application Object You can script the Application object’s child objects to perform common tasks and to create toolbars dynamically. Properties ActiveDocument Syntax Description ActiveDocument: object (read-only) The active document. For details, see “ActiveDocument Object” on page 230. ApplicationType Syntax Description ApplicationType: integer (read-only) The current application type. Sample ApplicationType script //**********************************// // Tests Application.
PAGE 218

200 Chapter 14 Scripting the Visual Tools Object Model } default: { sMessage = ’an unknown application type’; } }MessageBox(’You are enjoying ’ + sMessage + ’.’, ’Application Type’, 0); } AppPath Syntax Description Example AppPath: OleString (read-only) Path to application executable. function Main() { var sPath; with (Application) { sPath = AppPath; // Store the path in a variable } } CurrentFolder Syntax Description Example CurrentFolder: OleString Path currently displayed in the local file list.
PAGE 219

Application Object 201 Sample CurrentView script //**********************************************************// // This script switches the views inside the application //*********************************************************// function Main () { var sMessage; with (Application) { CurrentView = 1; sMessage = "You are now in Edit View of your " + VersionText; MessageBox (sMessage, VersionText, 0); CurrentView = 2; sMessage = "You are now in Browse View of your " + VersionText; MessageBox (sMessage, Vers
PAGE 220

202 Chapter 14 Scripting the Visual Tools Object Model DocumentCount Syntax Description Example DocumentCount: integer (read-only) Number of open documents. function Main() { Var sMessage; with (Application){ sMessage = "There are "; sMessage = sMessage + sDocumentCount + " open.\n"; // Get the number of open documents. sMessage = sMessage + sDocumentIndex + ".\n"; // Get the index of the current document.
PAGE 221

Application Object 203 Height Syntax Description Example Height: integer Height in pixels of main window.
PAGE 222

204 Chapter 14 Scripting the Visual Tools Object Model Left Syntax Description Example Left: integer Left (x-coordinate) of main window.
PAGE 223

Application Object Top Syntax Description Example Top: integer Top (y-coordinate) of main window.
PAGE 224

206 Chapter 14 Scripting the Visual Tools Object Model Width Syntax Description Width: integer Width in pixels of the main application window. Use this property with the Height property to return the size of the main window as well as to resize the window. WindowState Syntax Description WindowState: integer Set and get window state.
PAGE 225

Application Object 207 BrowseText Syntax Description Example BrowseText(sText, BaseHREF: OleVariant); Displays the passed text in the internal browser. Use the BaseHREF parameter to interpret relative paths. For local files, BaseHREF is the folder that contains the file.
PAGE 226

208 Chapter 14 Scripting the Visual Tools Object Model ExtractFileName Syntax Description Example ExtractFileName(const wsFile: WideString): WideString; Returns only the file portion of the passed file name. function Main() { Var sFullFilePath; Var sFileName; sFullFilePath = "C:/Temp/MyScript.js" with (Application){ sFileName = ExtractFileName(sFullFilePath); // Returns ’MySript.
PAGE 227

Application Object 209 ActiveDocument.InsertText(’
’, false); } } } GetImageHeight Syntax Description GetImageHeight(const wsImageName: WideString): Integer; Returns the height in pixels of the passed image. Returns 0 on error. Example /* Tests GetImageHeight, GetImageWidth Looks for first GIF image in current directory */ function Main(){ with (Application) { aFileObj= new ActiveXObject("Scripting.FileSystemObject"); aFolder= aFileObj.GetFolder(CurrentFolder); aFiles= new Enumerator(aFolder.
PAGE 228

210 Chapter 14 Scripting the Visual Tools Object Model GetImageSize Syntax Description Example GetImageSize(const wsImageFile: WideString; var nHeight, nWidth: Integer): WordBool; Boolean. Retrieves the size of the passed image. Returns False on error. function Main() { Var sFullImagePath; Var Height; Var Width; sFullImagePath = "C:/Temp/photos/MyPic.
PAGE 229

Application Object 211 GetRelativePath Syntax Description GetRelativePath(const wsBaseURL, wsFolderURL: WideString): WideString; Returns the relative path of a folder given a base URL. For example, GetRelativePath ("http://www.macromedia.com/", "http:// www.macromedia.com/software/") returns "products/". Example function Main() { Var sFullPath1; Var sRelativePath; Var sFullPath2; sFullPath1 = "http://www.macromedia.com/"; sFullPath2 = "http://www.macromedia.
PAGE 230

212 Chapter 14 Scripting the Visual Tools Object Model GetURL Syntax Description Example GetURL(const wsURL: WideString): WideString; Retrieves a URL and returns its contents. function Main() { Var sURL; Var sContents; sURL = "http://www.macromedia.com/"; with (Application){ sContents = GetURL(sURL); // Storing HTML code of the URL in sContents } } GetURLResponse Syntax Description Example GetURLResponse(const wsURL: WideString): WideString; Retrieves a URL and returns its contents.
PAGE 231

Application Object 213 GetURLStatus Syntax Description 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. GetURLStatusCode Syntax Description Example GetURLStatusCode(const wsURL: WideString): Integer; Returns the status code for the passed URL. See the GetURLResponse example. HideProgress Syntax Description Example HideProgress(); Hides the progress bar.
PAGE 232

214 Chapter 14 Scripting the Visual Tools Object Model } } } HTMLGetAttribute Syntax Description 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.
PAGE 233

Application Object 215 with (Application) { sInput = InputBox(VersionText, "What is your name?", "Alex"); sOutput = "I know you, your name is " + sInput + "."; MessageBox (sOutput, VersionText, 0); } } IsFileOpen Syntax Description Example IsFileOpen(sFile: OleVariant): WordBool; Boolean. Returns True if the passed file is open in the Document tab. function Main(){ sFile = ’D:\\Test\\index.
PAGE 234

216 Chapter 14 Scripting the Visual Tools Object Model Example function Main(){ with (Application){ InstallParserScript(’D:\\Download\\XHTML_2.scc’, ’xhtml’); } } LogMemoryStatus Syntax Description Example LogMemoryStatus(const wsLogFile, wsDescrip: WideString); Writes the current memory status to a log file, wsLogFile: logfilename. Creates the file if it does not exist, otherwise appends status to the file. The description text for the entry is entered in wsDescrip: text .
PAGE 235

Application Object Example 217 function Main() { Var sInput; Var sOutput; with (Application) { sInput = InputBox(VersionText, "What is your name?", "Alex"); sOutput = "I know you, your name is " + sInput + "."; MessageBox (sOutput, VersionText, 0); } } NewDocument Syntax Description Example NewDocument(wbUseDefaultTemplate: WordBool); Boolean. Creates a new document, optionally from the default template.
PAGE 236

218 Chapter 14 Scripting the Visual Tools Object Model NextDoc Syntax Description Example NextDoc(); Moves to the next document in the Document tab. If the last document is showing, wraps to the first. function Main() { Var sMessage; sMessage = "Hello world!"; with (Application) { NewDocument(false); NextDoc(); ActiveDocument.InsertText(sMessage); newly-created document } } // Moving to the PreviousDoc Syntax Description Example PreviousDoc(); Moves to the previous document in the Document tab.
PAGE 237

Application Object 219 } } RunCodeSweeper Syntax Description Example RunCodeSweeper(); Runs the CodeSweeper on the active document using the active CodeSweeper. To change the active CodeSweeper, use SetActiveCodeSweeper. function Main() { with (Application) { RunCodeSweeper (); } } SaveAll Syntax Description Example SaveAll(): WordBool; Boolean. Saves all open documents. Returns True if successful.
PAGE 238

220 Chapter 14 Scripting the Visual Tools Object Model SetActiveCodeSweeper Syntax Description Example SetActiveCodeSweeper(const wsFileName: WideString): WordBool; Changes the active CodeSweeper format file. function Main(){ var sCS_File = ’C:\\Program Files\\Macromedia\\ColdFusion Studio 5\\Extensions\\CodeSweepers\\WebXML.vtm’; with (Application){ SetActiveCodeSweeper(sCS_File); } } SetActiveResults Syntax Description SetActiveResults(resType: TCurrentResultsType); Boolean.
PAGE 239

Application Object Example 221 function Main(){ var sFolder1 var sFolder2 = ’C:\\Program Files\\Bradbury\TopStyle2’; = ’C:\\InetPub\\wwwroot’; with (Application) { SetFileTabFolder(1, sFolder1); SetFileTabFolder(2, sFolder2); } } SetProgress Syntax Description SetProgress(nProgress: Integer); Sets the position of the progress bar in the status area. The following values are allowed: 1-100.
PAGE 240

222 Chapter 14 Scripting the Visual Tools Object Model ShellToAppAndWait Syntax Description Example ShellToAppAndWait(const wsAppFileName: WideString); Boolean. Same as ShellToApp but waits for the external program to close before returning. The application is locked until ShellToAppAndWait returns, so use this method with caution. function Main(){ with (Application){ // Edit current document in notepad and then reload it ShellToAppAndWait(’notepad.exe ’ + ActiveDocument.Filename); ActiveDocument.
PAGE 241

Application Object Example 223 function Main(){ with (Application){ if (ActiveDocument.Modified){ StatusError(’Current document is modified’); } } } StatusWarning Syntax Description Example StatusWarning(const wsMsg: WideString); Displays a warning message in the status bar. Message appears on a blue background and displays for at least 5 seconds. function Main(){ with (Application){ if (ActiveDocument.
PAGE 242

224 Chapter 14 Scripting the Visual Tools Object Model Wait Syntax Description Example Wait(nMilliseconds: Integer); Pauses for given number of milliseconds. Use Wait to enable scripts to execute loops yet still allow access to the UI. Without the call to Wait in the loop, the application appears locked and the user cannot change views. The following JScript sample waits for the user to return to edit source view: var app = Application; while (app.CurrentView != 1) { app.
PAGE 243

Application Object 225 AddScriptToolbutton Syntax Description Example AddScriptToolbutton(wsToolbarName, wsScriptFile, wsImageFile: WideString): WordBool; wsHint, wsCaption, Boolean. Adds a script toolbutton (executes passed JScript or VBScript file when clicked) to the passed toolbar. Fails if toolbar does not exist. Returns True if a toolbutton already exists, but does not add a duplicate button.
PAGE 244

226 Chapter 14 Scripting the Visual Tools Object Model with (Application){ AddVTMToolbutton(’Common’, sVTM_File, ’Block quote’, ’BQ’, ’’); } } CreateToolbar Syntax Description Example CreateToolbar(wsToolbarName: WideString): WordBool; Boolean. Creates a new, undocked toolbar of the passed name. Fails if the toolbar of the same name already exists.
PAGE 245

Application Object 227 SetToolbarDockPos Syntax Description SetToolbarDockPos(wsToolbarName: WideString; nDockPos: Integer): WordBool; Boolean. Sets the docking position of the toolbar. Fails if the toolbar does not exist. The following values for nDockPos are allowed : 1 2 3 4 Example = = = = Top Bottom Left Right function Main(){ with (Application){ SetToolbarDockPos(’Standard’, 2); } } ShowToolbar Syntax Description Example ShowToolbar(wsToolbarName: WideString): WordBool; Boolean.
PAGE 246

228 Chapter 14 Scripting the Visual Tools Object Model Sample toolbar script 1 //******************************************************// // This script creates a toolbar named Apps if one does not exist, // then adds two custom toolbuttons to it. The first toolbutton // launches Windows Explorer, the second one opens Windows Explorer // at the current folder in the editor. //****************************************************// function Main() { var TB_NAME = ‘Apps’; var app = Application; if (!app.
PAGE 247

Application Object 229 Sample toolbar script 2 //*************************************************************// // This script creates a toolbar which is capable of executing // all of the scripts contained in the Document Cache //*************************************************************// function Main () { var var var var var sToolBarName; Result; count; fname; fnamepath; with (Application) {fnamepath sToolBarName = InputBox (VersionText, "Enter the Toolbar name.
PAGE 248

230 Chapter 14 Scripting the Visual Tools Object Model ActiveDocument Object Use the ActiveDocument object to refer to the document currently displayed in the editor. To access an open document that is not active, use the Application.DocumentCache object. Properties CanRedo Syntax Description Example CanRedo: WordBool (read-only) Boolean. Returns True if changes can be re-done. function Main() { var sMessage; sMessage = "CanRedo : "; with (Application) { If(ActiveDocument.
PAGE 249

ActiveDocument Object 231 CaretPosX Syntax Description Example CaretPosX: integer (read-only) The X-axis caret position. function Main(){ with (Application){ if (ActiveDocument.CaretPosX > 1){ ActiveDocument.CursorLineStart(false); } } } CaretPosY Syntax Description Example CaretPosY: integer (read-only) The Y-axis caret position. function Main(){ with (Application){ if (ActiveDocument.CaretPosY > 1){ ActiveDocument.
PAGE 250

232 Chapter 14 Scripting the Visual Tools Object Model LineCount Syntax Description Example LineCount: integer (read-only Number of lines in the active document. function Main() { var sMessage; sMessage = "Your file line count is: "; with (Application) { sMessage = sMessage + ActiveDocument.LineCount; MessageBox(sMessage, VersionText, 0); } } Lines Syntax Description Example Lines(Index: integer) OleString Gets and sets the text of the line at the passed index.
PAGE 251

ActiveDocument Object 233 MessageBox(sMessage, VersionText, 0); } } ReadOnly Syntax Description Example ReadOnly: WordBool (read-only) Boolean. Returns True if the active document is read-only. function Main(){ with (Application){ if (ActiveDocument.ReadOnly){ MessageBox(’Current document is Read-Only’, ’Information’, 0); } } } SelStart Syntax Description Example SelStart: integer Gets and sets the start of the current selection.
PAGE 252

234 Chapter 14 Scripting the Visual Tools Object Model SelText Syntax Description Example SelText: OleString Gets and sets the text in the current selection. function Main() { var sMessage; sMessage = "The length of the selected text of your document is "; with (Application) { sMessage = sMessage + ActiveDocument.SelText; MessageBox(sMessage, VersionText, 0); } } TabIndex Syntax Description Example TabIndex Gets and sets the tab index of the document tab.
PAGE 253

ActiveDocument Object 235 Clear Syntax Description Clear(); Clears all text from the active document. Close Syntax Description Close(wbPromptToSave: WordBool): WordBool; Boolean. 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). Cursor Syntax Description Cursor_ (wbSelect: WordBool); Boolean. Positions the cursor.
PAGE 254

236 Chapter 14 Scripting the Visual Tools Object Model } finally{ ActiveDocument.EndUpdate(); } MessageBox(’Total tags: ’ + iTags, ’Tag Count’, 0); } } GetCaretPos Syntax Description GetCaretPos(var x, y: integer); Returns the caret pos (x=column, y=line). GetCurrentChar Syntax Description GetCurrentChar(): OleVariant; Returns the current character. GetNextChar Syntax Description GetNextChar(): OleVariant; Returns the next character.
PAGE 255

ActiveDocument Object 237 GotoNextEndTag Syntax Description GotoNextEndTag(wbSelect: WordBool): WordBool; Boolean. Moves the next end tag, and selects it if wbSelect is True. Returns False if no tag found. GotoNextStartTag Syntax Description GotoNextStartTag(wbSelect: WordBool): WordBool; Boolean. Moves the next starting tag and selects it if wbSelect is True. Returns False if no tag is found. GotoPreviousEndTag Syntax Description Example GotoPreviousEndTag(wbSelect: WordBool): WordBool; Boolean.
PAGE 256

238 Chapter 14 Scripting the Visual Tools Object Model InsertTag Syntax InsertTag(sStartTag, sEndTag: OleVariant; wbOverwriteSelection: WordBool); Description Boolean. Inserts the passed tag pair at the current cursor position, overwriting the selection if wbOverwriteSelection is True. The cursor is positioned between the start and end tags after this operation. If wbOverwriteSelection is False, the tags surround the current selection. Example function Main(){ with (Application){ ActiveDocument.
PAGE 257

ActiveDocument Object 239 Reload Syntax Description Reload(wbPromptToSave: WordBool); Boolean. Reloads the active document. If wbPromptToSave is True, prompts the user to save changes. ReplaceAll Syntax Description ReplaceAll(strSearch, strReplace: OleVariant; bMatchCase: WordBool): Integer; Boolean. Replaces all occurrences of strSearch with strReplace, matching case if bMatchCase is True. Returns the number of replacements made. Save Syntax Description Save: WordBool(); Boolean.
PAGE 258

240 Chapter 14 Scripting the Visual Tools Object Model SelectAll Syntax Description SelectAll(); Selects all the text in the active document. SelectCurrentLine Syntax Description SelectCurrentLine(); Highlights the current line. SelectLine Syntax Description SelectLine(Index: Integer); Highlights the passed line. SetCaretPos Syntax Description SetCaretPos(x, y: Integer); Sets the current column/line.
PAGE 259

DocumentCache Object 241 DocumentCache Object It is very important to understand the DocumentCache object when using the VTOM. Although the Visual Tools enable you to open dozens of files at once, only the active document stays in memory. When a document becomes inactive, that is, when the user switches to a different document in the Document window, the previously active document is cached to conserve resources. Every open document has an element in the Application.DocumentCache array.
PAGE 260

242 Chapter 14 Scripting the Visual Tools Object Model Example function Main() { var sMessage; sMessage = "Your file name is: "; with (Application) { sMessage = sMessage + DocumentCache (0).Filename; } } Modified Syntax Description Example Modified: WordBool (read-only) Boolean. Returns True if the cached document changed since it was last saved. function Main() { var sMessage; sMessage = "Modified: "; with (Application) { If(DocumentCache (0).
PAGE 261

DocumentCache Object Text Syntax Description Example Text: OleString (read-only) File contents of the cached document. function Main() { var sMessage; sMessage = "Your document contains the following text: \n"; with (Application) { sMessage = sMessage + DocumentCache (0).
PAGE 262

244 Chapter 14 Scripting the Visual Tools Object Model Project Object The Project object provides a basic set of propeties and methods for scripting project maintenance tasks. The ProjectManager and DeploymentManager objects extend the capabilities of the Project object. For more information, see “ProjectManager Object” on page 246 and “DeploymentManager Object” on page 252.
PAGE 263

Project Object 245 ShowLastProjectError Syntax Description ShowLastProjectError(); Displays an error message for the last project-related error. UploadProjectDlg Syntax Description UploadProjectDlg(): WordBool; Boolean. Displays the upload project dialog box for the active project. UploadProject Syntax Description UploadProject(const wsTargetDir: WideString; const wbForceLCase, wbUploadOnlyNewer, wbEncryptCFML: WordBool): WordBool; Boolean. Uploads a project based on the passed criteria.
PAGE 264

246 Chapter 14 Scripting the Visual Tools Object Model ProjectManager Object The ProjectManager object provides extensive and granular scripting capabilities. This section groups the PropertyManager methods by function. FileCount Syntax Description FileCount: Integer (read-only) The number of files in the project. IsDirty Syntax Description IsDirty: WordBool (read-only) Boolean. Differences exist between the project as viewed in the Visual Tools and the underlying disk structure.
PAGE 265

ProjectManager Object 247 AddFolder Syntax Description AddFolder(Folder: OleVariant; FolderType: TFolderType; FolderPath: OleVariant; Parent: OleVariant); Adds a new folder to the project root. To add a subfolder to an existing folder, use a folder-level method. CheckedIn Syntax Description CheckedIn: WordBool; Boolean. Checks a project into source control. CreateProject Syntax Description CreateProject(ProjectName: OleVariant; ProjectPath: OleVariant); Creates a new project.
PAGE 266

248 Chapter 14 Scripting the Visual Tools Object Model RemoveFolder Syntax Description RemoveFolder(FolderName: OleVariant); Removes a folder from the project. Save Syntax Description Save; Saves the current project to disk in WDDX format. SelectFile Syntax Description SelectFile(Filename: OleVariant); Selects a file for source control operations. Folder methods FolderAddFile Syntax Description FolderAddFile(Folder: OleVariant; Filename: OleVariant); Add a file to the specified folder.
PAGE 267

ProjectManager Object 249 FolderDeployTarget Syntax Description FolderDeployTarget(Folder: FolderTarget: OleVariant); OleVariant; out FolderType: Integer; out Gets the folder deployment target and type. FolderFileCount Syntax Description FolderFileCount(Folder: OleVariant): Integer; Counts the number of files in the project folder. FolderRemoveFile Syntax Description FolderRemoveFile(Folder: OleVariant; Filename: OleVariant); Removes file from specified folder.
PAGE 268

250 Chapter 14 Scripting the Visual Tools Object Model Deployment methods DeploymentScriptAdd Syntax Description DeploymentScriptName: OleVariant; Adds a deployment script to the project. DeploymentScriptCount Syntax Description DeploymentScriptCount: Integer; Returns the number of scripts. DeploymentScriptList Syntax Description DeploymentScriptList: OleVariant; Lists all project deployment scripts.
PAGE 269

ProjectManager Object DeploymentServerRemove Syntax Description DeploymentServerRemove(ServerName: OleVariant); Removes a deployment server from a project.
PAGE 270

252 Chapter 14 Scripting the Visual Tools Object Model DeploymentManager Object The DeploymentManager object is a scriptable interface to the Project Deployment engine. The DeploymentManager object provides a collection of methods and properties that enable you to write highly customized scripts to control the deployment process. For examples of DeploymentManager Object syntax, see the “Sample deployment script” on page 257.
PAGE 271

DeploymentManager Object 253 ServerCount Syntax Description ServerCount: Integer (read-only) Counts the deployment servers associated with the current open project, including any new servers that were added temporarily using the AddServer method. UploadOnlyIfNewer Syntax Description UploadOnlyIfNewer: WordBool (read-write) Boolean. Determines whether the deployment engine only uploads a file if it has a newer date/time stamp than the target file.
PAGE 272

254 Chapter 14 Scripting the Visual Tools Object Model CopyFile Syntax Description CopyFile(const SourceFile: WideString; const TargetFile: WideString): Integer; Copies the source file to the target file location. CopyFileExtended Syntax Description CopyFileExtended(const SourceFile: WideString; const TargetFile: WideString; CreateFolder: WordBool; UploadOnlyIfNewer: WordBool; EncryptCFML: WordBool): Integer; Boolean.
PAGE 273

DeploymentManager Object 255 such as "Rds://localhost/D:/main/images/TestImage.jpg" which you can pass as the second argument to the UploadFile method. GetFolderDeployPath Syntax Description GetFolderDeployPath(const wsFolderName:String): WideString; Returns the deployment path of the passed folder name. Use this path in conjunction with the GetDeployServer and GetFolderName methods.
PAGE 274

256 Chapter 14 Scripting the Visual Tools Object Model GetLastErrorMessage Syntax Description GetLastErrorMessage(): WideString; Tests the result of an UploadFile call by returning last associated RDS error message. IsFolderDeployable Syntax Description IsFolderDeployable(const wsFolderName:WideString): WordBool; Boolean. Returns the deployment status of the passed folder name. Use this method to skip folders that are designated as Do Not Deploy folders.
PAGE 275

DeploymentManager Object 257 UploadFile Syntax Description UploadFile(const wsFile:Widestring, sTargetFile: WideString); Uploads an individual file to the server. The first OleString represents the fully qualified path of an individual file to upload. The second OleString represents the fully qualified target name, such as rds://localhost/main/index.html.
PAGE 276

258 Chapter 14 Scripting the Visual Tools Object Model // // // // // =================================================================== Server List: Local Deployment =================================================================== function Main() { var app = Application; var DeploymentManager = Application.
PAGE 277

DeploymentManager Object 259 // =========================================================== // Iterate through Project Folders //=========================================================== for (j=0; j <= DeploymentManager.FolderCount-1; j++) { sFolderName = DeploymentManager.GetFolderName(j); sDeployPath = DeploymentManager.
PAGE 278

260 Chapter 14 Scripting the Visual Tools Object Model HTTPProvider Object The HTTPProvider object is a general purpose HTTP protocol object. You can use it in VTOM scripts for low-level HTTP operations. The HTTPProvider object is an alternative to simplified HTTP-related methods, such as the GetURL method of the main Application object, which has a limited number of customizable HTTP parameters.
PAGE 279

HTTPProvider Object 261 Cookie Syntax Description Example Cookie: OleVariant Sets and gets the Cookie header element. Use this property to send a set of client cookies to the server along the HTTP request. Sample cookie script function Main () { var app = Application; var httpPro = app.HTTPProvider; httpPro.URL = "http://127.0.0.1/GetCustomerRegistration.cfm"; httpPro.Cookie = ‘Customer="John_Doe"; $Path="/myapp";Cust_ID="4567"; $Path="/myapp"’; httpPro.
PAGE 280

262 Chapter 14 Scripting the Visual Tools Object Model MultiThreaded Syntax Description MultiThreaded: WordBool Boolean. Sets and gets whether the HTTPProvider uses multithreading when executing HTTP requests. NoCache Syntax Description NoCache: WordBool Boolean. Sets and gets the NoCache request-header field. Password Syntax Description Password: OleVariant Sets and gets the Web server access password. Proxy Syntax Description Proxy: OleVariant Sets and gets the proxy server.
PAGE 281

HTTPProvider Object 263 RcvdCount Syntax Description RcvdCount: Integer (read-only) The size of the content stream received from the server. Use this property to display progress during asynchronous GET operations. Use the ContentLength property value extracted from the document header to get the total length of the incoming content stream. ReasonPhrase Syntax Description ReasonPhrase: OleVariant (read-only) The Reason-Phrase element provides a short textual description of the Status-Code.
PAGE 282

264 Chapter 14 Scripting the Visual Tools Object Model Reference Syntax Description Reference: OleVariant Sets and gets the Referer request-header field. This field allows the client to specify, for the server’s benefit, the address (URI) of the resource from which the Request-URI was obtained. This allows a server to generate lists of back-links to resources for interest, logging, optimized caching, and so on. It also allows obsolete or mistyped links to be traced for maintenance.
PAGE 283

HTTPProvider Object 265 StatusCode Syntax Description StatusCode: Integer (read-only) The HTTP request Status-Code element. This is a 3-digit integer result code of the attempt to understand and satisfy the request. URL Syntax Description URL: OleVariant Sets and getss the URL location of the resource on which an HTTP method is to be applied. Username Syntax Description Username: OleVariant Sets and gets the Web server access username.
PAGE 284

266 Chapter 14 Scripting the Visual Tools Object Model httpPro.URL = "http://www.macromedia.com"; httpPro.Get(); app.MessageBox( httpPro.ReceivedHeaderAsString ,"Received HTTP Header", hsOKInfo); app.MessageBox( "URL=’ "+ httpPro.URL + "‘\n" + "ProxyUsername=’" + httpPro.Username + "‘\n" + "ProxyPassword=’" + httpPro.Password + "‘\n" + "Proxy=’" + httpPro.Proxy + "‘\n" + "ProxyPort=’" + httpPro.Proxyport + "‘\n" + "ProxyUsername=’" + httpPro.ProxyUsername + "‘\n" + "ProxyPassword=’" + httpPro.
PAGE 285

HTTPProvider Object 267 HeadAsync Syntax Description HeadAsync(); Performs an HTTP HEAD method request asynchronously. Post Syntax Description Example Post(); Performs an HTTP POST method request. Sample POST script //*******************************************// // This script illustrates a POST method by which // three FORM variables are submitted to a ColdFusion page. //***********************************************// function Main () { var app = Application; var httpPro = app.
PAGE 286

268 Chapter 14 Scripting the Visual Tools Object Model The following error messages are predefined. Check for the error strings to detect these error cases: • File already exits—Returned when file specified in FilePath exists and bOverwrite is set to False. • Path does not exist—Returned when the path specified in FilePath does not exist.
PAGE 287

HTTPProvider Object 269 Sample HTTPProvider script //**********************************************// // ActiveScripting example (JScript) //**********************************************// // This script contacts the site specified by the user URL, // copies its source code and displays the page in the internal // browser of the application //**********************************************// function Main (){ var sDocName; var sSource; var sMessage; with (Application){ if (HTTPProvider.
PAGE 288

270 Chapter 14 Scripting the Visual Tools Object Model ZIPProvider Object The ZIPProvider object is the general purpose PKZIP services object used by the Visual Tools for ZIP file composition and extraction. You can use this object in your VTOM scripts for low-level PKZIP operations from within the Visual Tools. Because Macromedia uses a licensed control for its ZIP operations, you cannot use ZIPProvider outside of the Visual Tools.
PAGE 289

ZIPProvider Object 271 ZIPComment Syntax Description ZIPComment: OleVariant Sets and gets the comment for the archive file. Use this property to read a comment of an existing archive file, or set the comment for a new archive file that you created. ZIPFile Syntax Description Example ZIPFile: OleVariant Sets and gets the archive file path against which the operation is to be applied.
PAGE 290

272 Chapter 14 Scripting the Visual Tools Object Model breaks. The function returns a status code that can be investigated to determine the success of the operation. Example Sample Add script function Main () { var hsOKInfo = 64; var app = Application; var ZIPPro = app.ZIPProvider; //Identify the files to be compressed var ZIPFiles = ‘d:\\projects\\hs4\\scripts\\test.htm’; ZIPFiles = ZIPFiles + ‘\n’ + ‘d:\\projects\\hs4\\scripts\\test.zip’; ZIPFiles = ZIPFiles + ‘\n’ + ‘d:\\projects\\hs4\\scripts\\*.
PAGE 291

ZIPProvider Object 273 else if (nStatusCode == 410){sMessage else if (nStatusCode == 420){sMessage else if (nStatusCode == 430){sMessage else if (nStatusCode == 440){sMessage else if (nStatusCode == 450){sMessage "ErrorCantOpenSfxConfig";} else if (nStatusCode == 460){sMessage "ErrorInvalidEventParam";} else if (nStatusCode == 470){sMessage else if (nStatusCode == 490){sMessage else if (nStatusCode == 500){sMessage else if (nStatusCode == 510){sMessage = = = = = "ErrorMultidisk";} "ErrorWrongDisk";} "Er
PAGE 292

274 Chapter 14 Scripting the Visual Tools Object Model FileIsReadOnly Syntax Description FileIsReadOnly(nIndex: Integer): WordBool; Boolean. Use this function to determine whether a specific element in an archive is read-only. The index value can be from 0 to FileCount-1. FileIsHidden Syntax Description FileIsHidden(nIndex: Integer): WordBool; Boolean. Use this function to determine whether a specific element in an archive is a hidden file. The index value can be from 0 to FileCount-1.
PAGE 293

ZIPProvider Object 275 // Loop through the contents of the ZIP file for ( x = 0; x < ZIPPro.FileCount; x++ ) { if ( ZIPPro.FileName(x) == ’cfabort.vtm’ ) { app.MessageBox( "File found in the archive.","ZIPProvider", hsOKInfo); } } } FileSize Syntax Description FileSize(nIndex: Integer): Double; Returns the size of an existing archive file element (file/directory/volume) by index. The index value can be from 0 to FileCount-1.

PAGE 294

276 Chapter 14 Scripting the Visual Tools Object Model ActiveScripting Examples JScript JScript Example

//*****************************************************// // ActiveScripting example (JScript) //*****************************************************// // Generates a table of the filenames of all open documents, // listing their modified status and read-only property.

PAGE 295

ActiveScripting Examples 277 //Is this document Modified? if (DocumentCache (count).Modified) sTable = sTable + ’
Yes’+’’; else sTable = sTable + ’ No’ + ’’; //Is this document Read-Only? if (DocumentCache (count).ReadOnly) sTable = sTable + ’Yes’+ ’ ’; else sTable = sTable + ’No’ + ’ ’; // close row. sTable = sTable + ’’ + newline; count ++; // increment count by 1.

PAGE 296

278 Chapter 14 Scripting the Visual Tools Object Model VBScript VBScript Example

 //********************************************************// // Displays a table containing file information //********************************************************// Sub Main dim app dim idx dim sTable dim newline, fname, br, tab dim nCurrentIdx newline = chr(13) + chr(10) br = "
" tab = chr(9) ‘ create app reference.

PAGE 297

ActiveScripting Examples 279 ‘ is this document modified? if app.DocumentCache(idx).Modified then sTable = sTable + "Yes" sTable = sTable + "" ‘ is this document read-only? if app.DocumentCache(idx).ReadOnly then sTable = sTable + "Yes" ‘ close row sTable = sTable + "" + newline next sTable = sTable + newline + "" ‘ add a new document (False = don’t create from default template blank) app.
PAGE 298

280 Chapter 14 Scripting the Visual Tools Object Model Third-Party Add-Ins Scripting support offers many possibilities for third-party developers. For the latest news on third-party add-ins, visit the VTOM Scripts section of the Macromedia Developer Exchange at http://www.macromedia.com/go/fp_cfstudio_exchange. Running a script at startup If you want to distribute an add-in, you can register it to run the script.
PAGE 299

Third-Party Add-Ins 281 ’ 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.
PAGE 300

282 Chapter 14 Scripting the Visual Tools Object Model Table of CommandID Values The following table lists the set of currently exposed commands. For backward compatibility, these values will not change, but some value might become obsolete and be removed from the set.
PAGE 301

Table of CommandID Values Command ID 283 Value CMDID_cmdCursorDocStart 32 CMDID_cmdCursorDocEnd 33 CMDID_cmdCursorLineStart 34 CMDID_cmdCursorLineEnd 35 CMDID_cmdEditBackspace 36 CMDID_cmdEditCut 37 CMDID_cmdEditCopy 38 CMDID_cmdEditPaste 39 CMDID_cmdEditUndo 40 CMDID_cmdEditRedo 41 CMDID_cmdEditRepeatLastTag 42 CMDID_cmdEditCodeFormat // CodeSweeper 43 CMDID_cmdEditToggleInsertMode 44 CMDID_cmdEditDelete 45 CMDID_cmdEditDeleteLine 46 CMDID_cmdEditDeleteToEOL 47 CMDID_cmd
PAGE 302

284 Chapter 14 Scripting the Visual Tools Object Model Command ID Value CMDID_cmdSelectionAddBR 67 CMDID_cmdSelectionStripTags 68 CMDID_cmdSelectionUCase 69 CMDID_cmdSelectionLCase 70 CMDID_cmdSearchFind 71 CMDID_cmdSearchReplace 72 CMDID_cmdSearchAgain 73 CMDID_cmdSearchFindEx 74 CMDID_cmdSearchReplaceEx 75 CMDID_cmdSearchFindMatchingTag 76 CMDID_cmdSearchReplaceDoubleSpacing 77 CMDID_cmdSearchReplaceExtChars 78 CMDID_cmdToolsTagChooser 79 CMDID_cmdToolsSpellCheck 80 CMDID_c
PAGE 303

Table of CommandID Values Command ID 285 Value CMDID_cmdViewEditSource 102 CMDID_cmdViewToggleEditPreview 103 CMDID_cmdViewToggleEditDesign 104 CMDID_cmdViewToggleTagInspectorFocus 105 CMDID_cmdViewToggleSpecialChar 106 CMDID_cmdViewTagInsight 107 CMDID_cmdViewTagTip 108 CMDID_cmdViewEditorToolbar 109 CMDID_cmdViewEditorTab 110 CMDID_cmdViewToggleQuickBar 111 CMDID_cmdViewResults 112 CMDID_cmdOptionsSettings 113 CMDID_cmdOptionsCustomize 114 CMDID_cmdOptionsOrganizeQuickBar 11
PAGE 304

286 Chapter 14 Scripting the Visual Tools Object Model Table of SettingID Values The following table lists currently exposed setting IDs. For backward compatibility, these values will not change, but some might become obsolete and be removed from the set.
PAGE 305

Table of SettingID Values 287 Setting ID Value Description SET_MSIE_AUTO_REFRESH 19 Automatically refresh MSIE after navigating (needed for IE3.
PAGE 306

288 Chapter 14 Scripting the Visual Tools Object Model Setting ID Value Description SET_USE_CSE_VALIDATOR 41 Use CSE validator for full-page validation.
PAGE 307

Table of SettingID Values 289 Setting ID Value Description SET_SHOW_SKIPPED_FILES _IN_SEARCH 66 See dxSearchResults.AddSkipItem SET_LOWERCASE_LINKS 67 Lowercase IMG, A, and other dropped links SET_ALLOW_MULTIPLE_INSTANCES 79 Only for debugging.
PAGE 308

290 Chapter 14 Scripting the Visual Tools Object Model Setting ID Value Description SET_USE_VTM_IMAGE_DIALOG 107 Use vtml image dialog SET_USE_VTM_ANCHOR_DIALOG 108 Use vtml anchor dialog SET_USE_VTM_BODY_DIALOG 109 Use vtml body dialog SET_TEMPFILE_PREFIX 110 Prefix to use for tempfiles SET_FILELIST_COLS_ACTIVE 120 Set local columns as active SET_FILELIST_COL_SIZES 121 Local FileList Column Size Settings SET_REMOTE_FILELIST_COLS_ACTIVE 122 Set remote columns as active SET_REMOTE_FI
PAGE 309

Table of SettingID Values 291 Setting ID Value Description SET_DIR_WIZARDS 159 Set location of wizard root directory SET_DIR_CUSTOM_TEMPLATES 160 Set location of custom templates directory SET_DIR_OLD_TEMPLATES 161 Set location of old templates directory SET_DIR_OLD_TAGEDITORS 162 Set location of old tag editors directory SET_DIR_EXTENSIONS 163 Set location of extensions directory SET_DIR_TAGDEFS 164 Set location of tag definitions directory SET_DIR_CUSTOM_TAGDEFS 165 Set location of
PAGE 310

292 Chapter 14 Scripting the Visual Tools Object Model Setting ID Value Description SET_QUICKBAR_DATA_FILE 207 Set location of file containing data about what toolbars are in the QuickBar SET_INSIGHT_TAGLIST_FILE 208 Set location of tag insight file SET_STYLE_EDIT_EXE 209 Set location of styleedit executable SET_CODETEMPLATE_FILE 210 Set location of code template file SET_AUTOREPLACE_FILE 211 Set location of code template replace file SET_TAGCOMPLETION_FILE 212 Set location of tag compl
PAGE 311

Table of SettingID Values Setting ID 293 Value Description SET_EDITOR_AUTOCLOSE_ASP 314 Add %> when <% entered SET_EDITOR_AUTOCOMMENT 315 Add --> when