User manual ADOBE CS2

SDK Programmer's Guide bc Adobe GoLive cs2 ® ® © 2005 Adobe Systems Incorporated. All rights reserved. AdobeÆ Creative Suite 2 GoLive® CS2 SDK Programmer's Guide for Windows® and Macintosh®. NOTICE: All information contained herein is the property of Adobe Systems Incorporated. No part of this publication (whether in hardcopy or electronic form) may be reproduced or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written consent of Adobe Systems Incorporated. The software described in this document is furnished under license and may only be used or copied in accordance with the terms of such license. This publication and the information herein is furnished AS IS, is subject to change without notice, and should not be construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies, makes no warranty of any kind (express, implied, or statutory) with respect to this publication, and expressly disclaims any and all warranties of merchantability, fitness for particular purposes, and noninfringement of third party rights. Any references to company names in sample templates are for demonstration purposes only and are not intended to refer to any actual organization. Adobe, the Adobe logo, Acrobat, and GoLive are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. Apple, Mac, Macintosh, and Mac OS are trademarks of Apple Computer, Inc., registered in the United States and other countries. Microsoft and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and other countries. JavaScript and all Java-related marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. UNIX is a registered trademark of The Open Group. All other trademarks are the property of their respective owners. If this guide is distributed with software that includes an end user agreement, this guide, 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. Except as permitted by any such license, no part of this guide 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 Adobe Systems Incorporated. Please note that the content in this guide is protected under copyright law even if it is not distributed with software that includes an end user license agreement. The content of this guide is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies that may appear in the informational content contained in this guide. Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA. Contents Preface ........................................................................................................................................ 10 About Adobe GoLive CS2 SDK ................................................................................................................................................10 About This Book............................................................................................................................................................................11 Who should read this book ................................................................................................................................................11 What is in this book ...............................................................................................................................................................11 Document conventions .......................................................................................................................................................12 Typographical conventions .........................................................................................................................................12 JavaScript common properties...................................................................................................................................12 Where to Go for More Information ........................................................................................................................................13 1 Installing and Configuring the GoLive SDK............................................................................. 14 Installing the GoLive CS2 SDK..................................................................................................................................................14 Installing the core set of tools and sample extensions ............................................................................................14 Installing the core extensions .....................................................................................................................................14 Uninstalling an extension .............................................................................................................................................15 Configuring GoLive for Extension Development..............................................................................................................15 Enabling the Extend Script module ................................................................................................................................15 Enabling and disabling modules......................................................................................................................................16 Debugging Your Scripts.............................................................................................................................................................17 Error logs ...................................................................................................................................................................................17 2 How to Create an Extension...................................................................................................... 18 About Adobe GoLive CS2 Extensions ...................................................................................................................................18 What can extensions do? ....................................................................................................................................................18 Anatomy of an Extension ..........................................................................................................................................................19 Extension-building tools .....................................................................................................................................................20 Example Main.html File..............................................................................................................................................................21 Creating An Extension Module................................................................................................................................................21 Creating the Main.html file.................................................................................................................................................22 Adding SDK Tags and JavaScript Functions to the Module..........................................................................................23 Adding the module tag .......................................................................................................................................................24 Adding event-handling functions ...................................................................................................................................24 Summary ...................................................................................................................................................................................26 3 The JavaScript Environment..................................................................................................... 27 JavaScript Objects in the GoLive Environment .................................................................................................................27 Objects, elements, and properties...................................................................................................................................27 Accessing attribute values..................................................................................................................................................27 Naming objects and attributes .........................................................................................................................................28 JavaScript object collections..............................................................................................................................................29 Using the global object arrays ....................................................................................................................................29 Comparing objects..........................................................................................................................................................30 Updating references to objects ........................................................................................................................................30 Scope of Variables and Functions ..........................................................................................................................................31 Releasing Memory .................................................................................................................................................................32 Handling Events............................................................................................................................................................................32 Defining and Registering Event Handlers.....................................................................................................................33 3 Adobe GoLive CS2 SDK SDK Programmer's Guide Contents 4 Nesting Event Handlers .......................................................................................................................................................34 Sharing Data...................................................................................................................................................................................34 Persistent shared data..........................................................................................................................................................35 Non-persistent shared data................................................................................................................................................35 Communicating with other extensions .........................................................................................................................35 Sending messages to other extension modules ..................................................................................................36 Responding to a broadcast ..........................................................................................................................................36 Delays and Timeouts...................................................................................................................................................................36 Timed tasks...............................................................................................................................................................................37 Setting the JavaScript timeout..........................................................................................................................................37 Progress bars ...........................................................................................................................................................................37 Starting a progress or busy bar...................................................................................................................................38 Updating a progress or busy bar................................................................................................................................38 Progress bar example.....................................................................................................................................................39 4 Menus and Toolbars .................................................................................................................. 40 Creating Custom Menus ............................................................................................................................................................40 Basic example..........................................................................................................................................................................40 Adding the menu bar tag....................................................................................................................................................41 Defining the Menu.................................................................................................................................................................41 Defining menu items ............................................................................................................................................................42 Creating submenus ...............................................................................................................................................................43 Defining menu behavior .....................................................................................................................................................43 Using one handler to react to multiple items .......................................................................................................44 Capturing events in the menu object ......................................................................................................................44 Complete simple menu example .....................................................................................................................................45 Assigning Keyboard Shortcuts to Menu Items ..................................................................................................................45 Setting a Menu Item's State Programmatically .................................................................................................................46 Setting a menu item's checked state..............................................................................................................................46 Setting a menu item's enabled state .............................................................................................................................46 Initializing menu items.........................................................................................................................................................47 Adding Items to GoLive Menus...............................................................................................................................................48 Extending Context Menus.........................................................................................................................................................50 Registering context menu handlers................................................................................................................................51 Defining context menu handlers .....................................................................................................................................51 Creating Toolbars .........................................................................................................................................................................52 5 Windows and Controls .............................................................................................................. 54 Types of Windows ........................................................................................................................................................................54 Dialog windows......................................................................................................................................................................54 Positioning windows ............................................................................................................................................................54 Using the Dialog Editor tool...............................................................................................................................................55 Modal Dialog Windows ..............................................................................................................................................................58 Defining the modal dialog window ................................................................................................................................58 Opening and closing modal dialogs...............................................................................................................................58 Displaying a modal dialog............................................................................................................................................58 Closing a modal dialog ..................................................................................................................................................60 Palette Windows...........................................................................................................................................................................60 Showing and hiding palettes .....................................................................................................................................61 The Inspector window ...................................................................................................................................................62 Control Containers.......................................................................................................................................................................63 Creating panels.......................................................................................................................................................................63 Adobe GoLive CS2 SDK SDK Programmer's Guide 5 Creating tab panels ...............................................................................................................................................................63 Creating split panels .............................................................................................................................................................64 Autolayout of Localized Controls ...........................................................................................................................................65 Adding Controls to Windows...................................................................................................................................................66 Creating different types of controls ................................................................................................................................67 Creating radio button groups .....................................................................................................................................68 Creating text input fields ..............................................................................................................................................68 Creating source and preview controls .....................................................................................................................69 Creating controls with parameters ...........................................................................................................................69 List controls........................................................................................................................................................................70 Adding controls to a window dynamically...................................................................................................................72 Providing Behavior for Controls..............................................................................................................................................73 Handling events for a target control...............................................................................................................................73 Handling simple clicks ...................................................................................................................................................73 Handling different actions............................................................................................................................................73 Handling editing actions...............................................................................................................................................74 Handling events in a control's parent window ...........................................................................................................74 Creating Custom Controls.........................................................................................................................................................76 Defining user interactions with custom controls .......................................................................................................76 Drawing custom controls....................................................................................................................................................76 Updating a control's appearance immediately ....................................................................................................77 Defining drag-and-drop for custom controls ..............................................................................................................77 Control as Sender of a Drag Event.............................................................................................................................77 Receiving a drop event..................................................................................................................................................77 6 Custom Elements ....................................................................................................................... 78 Overview..........................................................................................................................................................................................78 Tags for creating custom elements .................................................................................................................................78 Defining A Custom Element.....................................................................................................................................................79 Defining the tag for a custom element..........................................................................................................................79 Redefining Tags Locally.................................................................................................................................................79 Defining the custom tag's palette icon and HTML content ...................................................................................80 Creating a Palette Entry in the Objects Palette .................................................................................................................81 Adding Palette Entries to a Built-in Tab ...............................................................................................................................81 Adding palette entries to a customized tab.................................................................................................................82 Defining the appearance of a custom element....................................................................................................82 Initializing a custom element box....................................................................................................................................83 Displaying a custom element box ...................................................................................................................................84 Drawing into container boxes ....................................................................................................................................84 drawBox Examples ..........................................................................................................................................................84 Resizing a custom element box........................................................................................................................................86 Built-in undo support ...........................................................................................................................................................86 Inspecting a Custom Element..................................................................................................................................................86 Initializing the Inspector window ....................................................................................................................................87 Responding to changes in the Inspector ......................................................................................................................87 Multiple Inspectors................................................................................................................................................................88 Supporting the Undo and Redo Commands .....................................................................................................................88 Undo support and document parsing ...........................................................................................................................88 The document's undo history ...........................................................................................................................................89 Creating the undo object....................................................................................................................................................89 Initializing the undo object ................................................................................................................................................89 Adobe GoLive CS2 SDK SDK Programmer's Guide 6 Implementing the undoSignal Function.......................................................................................................................90 Updating Images Dynamically ................................................................................................................................................91 Creating pictures....................................................................................................................................................................92 Drawing the image................................................................................................................................................................92 Deleting pictures....................................................................................................................................................................93 7 Editing Documents Programmatically..................................................................................... 94 The GoLive Document Object Model ..................................................................................................................................94 The Markup Tree...........................................................................................................................................................................94 Reparsing and object references .....................................................................................................................................95 Markup editing options.................................................................................................................................................95 Automatic and explicit reparsing .............................................................................................................................96 Working With Documents.........................................................................................................................................................97 Opening documents.............................................................................................................................................................97 Open a document in a document window ............................................................................................................97 Display layout view .........................................................................................................................................................98 Open a document without displaying it .................................................................................................................98 Manipulating open documents........................................................................................................................................98 Make an open document window frontmost .......................................................................................................98 Count open documents ................................................................................................................................................98 Validate document objects ..........................................................................................................................................99 Working with style sheets...................................................................................................................................................99 Creating a new HTML page ................................................................................................................................................99 Saving documents.............................................................................................................................................................. 100 Closing documents ............................................................................................................................................................ 100 Working with Selections in Document Windows .......................................................................................................... 100 Retrieving the current selection .................................................................................................................................... 101 Setting the current selection .......................................................................................................................................... 102 Using the range object...................................................................................................................................................... 102 Accessing selections through the document source............................................................................................. 104 Retrieving Objects from the Markup Tree........................................................................................................................ 104 Retrieving individual markup objects ......................................................................................................................... 105 Retrieving multiple markup objects............................................................................................................................. 106 Editing Source Code Through Markup Objects ............................................................................................................. 106 Using Markup Objects to Edit HTML Directly............................................................................................................ 106 Overriding document encoding for elements ......................................................................................................... 107 8 Editing with Layout .................................................................................................................108 Layout View and the Layout Objects ................................................................................................................................. 108 Editing displayed elements through layout objects.............................................................................................. 109 Getting the layout objects for tables, cells, and layout grids........................................................................ 109 Editing Attributes of Managed Objects................................................................................................................ 109 Example: Using layout objects................................................................................................................................. 110 Editing displayed elements through markup objects ........................................................................................... 111 Editing Text in Layout View ................................................................................................................................................... 112 Manipulating text elements............................................................................................................................................ 113 Adding text ..................................................................................................................................................................... 113 Setting the cursor position........................................................................................................................................ 113 Finding and replacing text ........................................................................................................................................ 114 Selecting and deselecting text ................................................................................................................................ 114 Manipulating Text Styles ........................................................................................................................................................ 115 Applying styles to selected text..................................................................................................................................... 116 Adobe GoLive CS2 SDK SDK Programmer's Guide 7 Editing existing styles and stylesets............................................................................................................................. 117 Inserting Elements in Layout View...................................................................................................................................... 117 Inserting raw HTML ............................................................................................................................................................ 118 Working with Tables in Layout View .................................................................................................................................. 118 Table styles ............................................................................................................................................................................ 118 Applying a table style within a table ..................................................................................................................... 119 Table cells............................................................................................................................................................................... 119 Cell styles................................................................................................................................................................................ 120 Working with Layout Grids .................................................................................................................................................... 121 Adjusting the grid............................................................................................................................................................... 121 Sizing and positioning elements on the grid............................................................................................................ 121 9 Managing Files and Folders ....................................................................................................123 Overview....................................................................................................................................................................................... 123 Using File Objects...................................................................................................................................................................... 123 Acquiring file objects ........................................................................................................................................................ 124 Determining the location of a file or folder......................................................................................................... 124 Validating file objects.................................................................................................................................................. 124 Accessing folders ............................................................................................................................................................... 125 Getting a file object from the user................................................................................................................................ 126 Creating a new file object ................................................................................................................................................ 126 Moving, Copying, and Deleting Files and Folders......................................................................................................... 127 Moving and copying files................................................................................................................................................. 127 Moving and copying folders........................................................................................................................................... 128 Deleting files or folders..................................................................................................................................................... 128 Working With Document Files ............................................................................................................................................. 128 Creating a document file.................................................................................................................................................. 128 Reading the contents of an existing file ..................................................................................................................... 129 Opening a markup document file .......................................................................................................................... 129 Opening other files ...................................................................................................................................................... 129 Changing encoding in a file...................................................................................................................................... 129 Working With Folders .............................................................................................................................................................. 130 Creating folders ................................................................................................................................................................... 130 Retrieving the contents of a folder .............................................................................................................................. 130 Getting files from a file object.................................................................................................................................. 130 Getting files from a siteReference object............................................................................................................. 131 Retrieving the contents of subfolders................................................................................................................... 132 Working with Remote Files ................................................................................................................................................... 133 Using HTTP protocol .......................................................................................................................................................... 133 Using FTP and DAV protocol........................................................................................................................................... 133 Exchanging Data with Remote Hosts ............................................................................................................................... 134 Establishing a simple HTTP connection...................................................................................................................... 134 Establishing an internet server....................................................................................................................................... 135 Example: A chat server ...................................................................................................................................................... 135 10 Managing Web Sites................................................................................................................137 Creating Files and Folders in GoLive Web Sites ............................................................................................................ 137 Adding files and folders.................................................................................................................................................... 137 Using templates................................................................................................................................................................... 138 Deleting files and folders ................................................................................................................................................. 139 Managing the Site Window ................................................................................................................................................... 139 Selecting site files programmatically........................................................................................................................... 139 Adobe GoLive CS2 SDK SDK Programmer's Guide 8 Creating custom columns in the Site window ......................................................................................................... 139 Using event handlers to display custom column content............................................................................. 140 Using named properties to display custom column content....................................................................... 140 Removing a custom column at runtime............................................................................................................... 141 Working With Site Documents ............................................................................................................................................. 142 Making a document's Site window frontmost ......................................................................................................... 142 Copying files ......................................................................................................................................................................... 143 Working with Version Control Systems............................................................................................................................. 145 11 Localization and Translation ..................................................................................................149 Dynamic UI Localization ......................................................................................................................................................... 149 Creating the localization table ....................................................................................................................................... 149 Creating a localization table in GoLive ................................................................................................................. 150 Creating an external localization table ................................................................................................................. 151 Using the localization table............................................................................................................................................. 151 Translating attribute value strings ......................................................................................................................... 151 Translating JavaScript strings................................................................................................................................... 152 Localization test features ................................................................................................................................................. 152 Document Source Translation.............................................................................................................................................. 153 Defining a translator .......................................................................................................................................................... 153 Inspecting translated elements ..................................................................................................................................... 154 12 Extending GoLive Actions.......................................................................................................156 GoLive Action Types................................................................................................................................................................. 156 Adding actions to a page ................................................................................................................................................. 156 Creating Your Own Actions ................................................................................................................................................... 157 Changing action icons ...................................................................................................................................................... 158 Anatomy of an Action File...................................................................................................................................................... 158 Action Tags .................................................................................................................................................................................. 160 csactionclass ......................................................................................................................................................................... 160 csactionparam...................................................................................................................................................................... 161 JavaScript Source for Actions................................................................................................................................................ 163 Layout Grid .................................................................................................................................................................................. 163 Action Tutorials .......................................................................................................................................................................... 165 Tutorial 1: Customizing the Actions Inspector ......................................................................................................... 165 Tutorial 2: Go to previous page action ........................................................................................................................ 166 Tutorial 3: Resize window action................................................................................................................................... 167 13 Debugging Scripts ...................................................................................................................170 Enabling Debug Services........................................................................................................................................................ 170 Using the JavaScript Command Shell................................................................................................................................ 171 Executing JavaScript commands .................................................................................................................................. 172 The Internal JavaScript Source Debugger........................................................................................................................ 173 Controlling code execution in the script Debugger window ............................................................................. 174 Customizing the Debugger Window ................................................................................................................................ 175 Troubleshooting Tips............................................................................................................................................................... 177 Null and undefined values............................................................................................................................................... 177 Case sensitivity..................................................................................................................................................................... 177 Line breaks in palette entries and string literals ...................................................................................................... 177 A Using External Libraries ..........................................................................................................178 About External Libraries.......................................................................................................................................................... 178 Installing external libraries .............................................................................................................................................. 179 Adobe GoLive CS2 SDK SDK Programmer's Guide 9 Installing an external JavaScript library................................................................................................................ 179 Installing Binary Libraries........................................................................................................................................... 179 External JavaScript Libraries ................................................................................................................................................. 179 Including an external JavaScript file ............................................................................................................................ 180 Calling JavaScript library functions .............................................................................................................................. 180 External Binary Libraries ......................................................................................................................................................... 181 Implementing external binary libraries ...................................................................................................................... 181 Including C header files.............................................................................................................................................. 181 Bit Alignment ................................................................................................................................................................. 181 Initializing the JavaScript engine............................................................................................................................ 182 Defining external library functions ........................................................................................................................ 182 Registering external functions................................................................................................................................. 184 Implementing optional termination code .......................................................................................................... 184 Calling C library functions from JavaScript................................................................................................................ 184 Evaluating JavaScript expressions in C functions ................................................................................................... 185 Performance Issues................................................................................................................................................................... 186 Glossary ....................................................................................................................................188 Index .........................................................................................................................................192 Preface Welcome to the Adobe® GoLive CS2 SDK Programmer's Guide. This book and its companion volume, the GoLive CS2 SDK Programmer's Reference, describe how to extend the Adobe GoLive® CS2 Web-site development environment. About Adobe GoLive CS2 SDK The Adobe GoLive CS2 SDK (Software Development Kit) enables you to extend the behavior and user interface of GoLive CS2. Using the GoLive CS2 SDK, you can create tools tailored to your specific GoLive tasks. The SDK can create, customize, and extend most aspects of the GoLive user interface, such as: Menus and menu items Floating palettes and task-specific dialogs that include text, graphics, and controls Custom HTML elements, such as , that can be edited in an Inspector palette Custom controls, that you can add as drag-and-drop items in the Objects palette Custom columns in the Site window In addition, the SDK give you programmatic options for working with GoLive CS2: Programmatic file and Web-site resource manipulation, both local and remote Programmatic manipulation of the content of HTML and other markup documents Document parsing options for encoding, translation, localization, and non-HTML tags Adobe GoLive CS2 SDK uses ExtendScript, Adobe's extended implementation of JavaScript, which is used by all Adobe Creative Suite 2 applications that provide a scripting interface. (The GoLive documents refer to JavaScript and ExtendScript interchangeably.) In addition to implementing the JavaScript language according to the W3C specification, ExtendScript provides certain additional features and utilities, which are described in Chapter 5, "ExtendScript Tools and Features," in the GoLive CS2 SDK Programmer's Reference. You use ExtendScript to create extensions to GoLive CS2. Creating an extension is similar to creating a Web page or a Web application -- to design the appearance of your extension you use the GoLive user interface to add SDK-provided tags to an HTML document. See Chapter 2, "How to Create an Extension" for more information. When the user interacts with one of your extension's user interface items, the SDK calls one or more JavaScript functions that you have created to provide the extension item's behavior. However, you don't need to be a JavaScript expert to use this SDK. If you've used HTML to create Web page content, and perhaps added some interactivity to that page with JavaScript, you're already familiar with the concepts behind ExtendScript extensions. The SDK enables even inexperienced JavaScript users to create simple extensions with custom menus and dialogs easily. Yet it is comprehensive and powerful: The SDK provides numerous JavaScript objects and methods to perform tasks on a document, on a site, in the GoLive environment, on local and remote file systems including HTTP, FTP, and DAV servers. Virtually all of the user commands in GoLive are made available in JavaScript. Using JavaScript to automate repetitive tasks, you can, for example, edit all the documents on your site programmatically. 10 Adobe GoLive CS2 SDK SDK Programmer's Guide Preface 11 Because the files that define extensions use HTML syntax, you can use GoLive itself -- including your own custom extensions -- to create additional extensions to the GoLive design environment. In the same way that you can create JavaScript scripts to generate and manipulate HTML files, you can write JavaScript scripts to generate and manipulate GoLive extensions. Using this technique you could, for example, use JavaScript scripts to customize menu items in GoLive according to the contents of a database. Optionally, extensions can call custom libraries written in the C and JavaScript programming languages. You can even use XML to define entirely new structured markup languages and documents to GoLive, providing practically unlimited extensibility. About This Book This book, GoLive CS2 SDK Programmer's Guide, describes methodologies and techniques for using the GoLive CS2 SDK to extend and customize Adobe GoLive CS2. This book is a companion to the GoLive CS2 SDK Programmer's Reference, which provides reference descriptions of SDK tags, objects, and methods. Open both documents in Adobe Acrobat® to use the live cross-reference links between the two books. This book does not document the JavaScript language or how to use the Adobe GoLive CS2 application. For a listing of some helpful publications, see Where to Go for More Information. Who should read this book This book is for anyone who wants to extend the capabilities of Adobe GoLive using JavaScript and the special markup tags that the GoLive CS2 SDK provides. This book assumes that: You know how to create pages and Web sites in Adobe GoLive, as described in the Adobe GoLive CS2 User Guide. You are a programmer with a working understanding of the HTML and JavaScript languages, and have written some of your own JavaScript scripts. Most GoLive extensions do not use shared libraries. However, if you are familiar with shared libraries in Microsoft® Windows® and Mac OS®, you can use them to extend GoLive even further. For more information, see Appendix A, "Using External Libraries." What is in this book This book contains the following chapters: Chapter 1, "Installing and Configuring the GoLive SDK," describes how to install the GoLive CS2 SDK and enable the appropriate modules. Chapter 2, "How to Create an Extension," describes what an extension is and what extensions can do. It provides a tutorial that creates a simple "Hello, World" extension. Chapter 3, "The JavaScript Environment," describes how GoLive makes JavaScript objects available to extensions and discusses other application-level considerations such as variable scoping, data sharing and communication among extensions, and timing issues. Chapter 4, "Menus and Toolbars," describes how to add custom menus, submenus, and menu items to GoLive. Chapter 5, "Windows and Controls," describes how to create modal dialogs and floating palettes, and add the user-interface controls that allow users to interact with your extension. Adobe GoLive CS2 SDK SDK Programmer's Guide Preface 12 Chapter 6, "Custom Elements," describes how to define a custom element, with an icon the user can drag from the Objects palette into a GoLive document in a document window. Chapter 7, "Editing Documents Programmatically," describes how extensions can use JavaScript code to manipulate document content. Chapter 8, "Editing with Layout," describes how you can manipulate document content while GoLive's Layout view is open, with a minimum of reparsing and redisplay flicker. Chapter 9, "Managing Files and Folders," describes how to manipulate files and folders on disk. Chapter 10, "Managing Web Sites," describes how to work with a Web site's file resources and how to work with and customize the GoLive Site window. Chapter 11, "Localization and Translation," describes dynamic language localization and source code transformation. Chapter 12, "Extending GoLive Actions," describes how to create and edit GoLive actions, JavaScript scripts you can add to a page and edit with an Inspector. Chapter 13, "Debugging Scripts," describes how to use the internal JavaScript Debugger. Appendix A, "Using External Libraries," describes how to create external C or JavaScript libraries your extension can call from JavaScript. "Glossary," lists and defines many of the specialized terms uses in these books. Document conventions This book uses the following typographic and terminology conventions. Typographical conventions Monospaced font Literal values and code, such as JavaScript code, HTML code, filenames, and pathnames. Variables or placeholders in code. For example, in name="myName", the text myName represents a value you are expected to supply, such as name="Fred". Also indicates the first occurrence of a new term. A hyperlink you can click to go to a related section, in this book or the companion volume. The names of GoLive UI elements (menus, menu items, and buttons). Italics Blue underlined text Sans-serif bold font The > symbol is used as shorthand notation for navigating to menu items. For example, Edit > Cut refers to the Cut item in the Edit menu. Note: Notes like this one highlight issues that deserve extra attention, key requirements, and common errors. JavaScript common properties Because most objects provided by the SDK provide a name property, the Objects chapter in the GoLive CS2 SDK Programmer's Reference (companion volume to this guide), does not list name properties explicitly. Similarly, the Reference does not list properties and methods provided by the JavaScript language itself. For example, it is common for JavaScript objects to provide a toString method, and many of the objects Adobe GoLive CS2 SDK SDK Programmer's Guide Preface 13 the SDK supplies implement this method. However, the Reference does not describe such methods unless they differ from the standard JavaScript implementation. Where to Go for More Information This book documents the Adobe GoLive CS2 SDK only. It does not describe the JavaScript language or how to use the GoLive CS2 application. For documentation of the JavaScript language or descriptions of how to use it, see any of numerous works on this subject, including the following: JavaScript: The Definitive Guide, 4th Edition; Flanagan, D.; O'Reilly 2001; ISBN 0-596-00048-0 JavaScript Programmer's Reference; Wootton, C.; Wrox 2001; ISBN 1-861004-59-1 JavaScript Bible. 5th Edition; Goodman, D. and Morrison, M.; John Wiley and Sons1998; ISBN 0-7645-57432 1 Installing and Configuring the GoLive SDK The first part of this chapter describes how to install the GoLive CS2 SDK and introduces the JavaScript environment that GoLive provides for extensions. The next part specifies the file and folder structure you must use to create an extension. This chapter concludes with an example of a simple extension that writes messages in the JavaScript Debugger window. Installing the GoLive CS2 SDK The GoLive CS2 SDK requires version 8.0 of Adobe GoLive CS2 and is included in the default installation. Updates to the SDK and to this documentation set are available at http://partners.adobe.com/asn. Installing the core set of tools and sample extensions This section describes how to install an extension in GoLive. GoLive CS2 SDK files are initially installed in a subfolder of the Adobe application folder called Adobe GoLive SDK 8.0r1. The extensions provided with the SDK are in the Samples and Tools folders. Each sub-folder in the Samples and Tools folders holds a different example of an extension. It is recommended that you install the core set of sample extensions and tools, and use them to help learn about and create your own extensions. Once you have become familiar with the use of the tags, scripts, and objects these samples illustrate, you can remove any or all of them, as you prefer. Installing the core extensions To install an existing extension, in most cases you simply copy or move the folder to the GoLive_dir/Modules/Extend Scripts folder. See the Release Notes for a list of samples whose installation requires more than this; in these cases, the installation instructions are included in the extension's Main.html file or in the Release Notes. The following steps make the core extensions available to GoLive: 1. Quit GoLive if it is running. 2. Copy at least the following extension folders from the GoLiveSDK_dir/Samples folder to the Adobe GoLive 8.0/Modules/Extend Scripts folder: Custom Box KeyMap Markup Tree Menus and Dialogs Palettes 3. Copy the contents of the GoLiveSDK_dir/Samples/Common folder to the Adobe GoLive 8.0/Modules/Extend Scripts/Common folder. 14 Adobe GoLive CS2 SDK SDK Programmer's Guide Installing and Configuring the GoLive SDK 15 4. Copy the following folders from the GoLiveSDK_dir/Tools folder to the GoLive_dir/Modules/Extend Scripts folder: Dialog Editor Edit Extension Extension Builder 5. Start GoLive. When GoLive starts, it loads all of the extensions present in the Extend Scripts folder. Uninstalling an extension To remove an extension from GoLive, remove its folder from the Extend Scripts folder and restart GoLive. You can deactivate an extension without removing it; see Enabling and disabling modules. Configuring GoLive for Extension Development Developing GoLive extensions is an iterative process that generally requires you to restart GoLive whenever you need to load a new version of the extension you are developing. JavaScript-only changes can be reloaded from the JavaScript Debugger without restarting GoLive. Enabling the Extend Script module The built-in Extend Script module must be enabled before you can load or run any extensions. The module is enabled by default. Disabling this module disables all GoLive extension capabilities, which you normally do not want to do. If this module has become disabled, you can re-enable it as follows: 1. Select Edit > Preferences. 2. In left panel of the Preference dialog, select Modules. Modules are listed on the right by folder name. Adobe GoLive CS2 SDK SDK Programmer's Guide Installing and Configuring the GoLive SDK 16 3. In the list of modules, check the Extend Script module. ExtendScript module checked Show description of selected module 4. Click OK to confirm your changes and dismiss the Preferences panel. 5. Quit GoLive and restart it. Enabling and disabling modules GoLive packages much of its functionality in units known as modules. An extension that you develop using the SDK is simply another kind of module that GoLive can use. To add some particular new functionality to GoLive, you can install and enable the module that provides it. You can also disable or remove a module to remove its associated features and behaviors. To turn off an extension but leave the extension in the Extend Scripts folder, use the Edit > Preferences dialog to display Modules, as shown in the figure above. In the list of modules, uncheck the modules any extensions you want to turn off. The change takes effect when you restart GoLive. The precise set of modules you can disable successfully depends on the features your extension or site uses--you cannot disable a module your site or your extension requires for its functionality. Note: Do not disable the Extend Script module. If this module is not enabled, GoLive cannot load or run any extensions. If you are not sure whether you need to enable a particular module, you can get a description of it in the Preferences dialog Getting descriptions of modules 1. Select Edit > Preferences, and in the left panel of the Preferences dialog, select Modules. 2. In the right pane, click to select the module to be described. 3. If Show Item Information appears at the bottom of the modules list, as shown in the figure above, click it to reveal the item information pane. Adobe GoLive CS2 SDK SDK Programmer's Guide Installing and Configuring the GoLive SDK 17 A description of the selected module appears in the item information pane: ExtendScript module selected Description of selected module Debugging Your Scripts You can use either the internal GoLive JavaScript Debugger window to develop and debug your scripts, or the ExtendScript Toolkit, which is available to all Creative Suite 2 applications. To choose one or the other debugging environment, set the internalDebugger property of the settingsSDK Object. When it is true (the default), the GoLive JavaScript Debugger is active. You can use the Debugger's console to set the value to false, making the ExtendScript Toolkit active. The GoLive JavaScript Debugger is described in Chapter 13, "Debugging Scripts." The ExtendScript Toolkit is described in Chapter 5, "ExtendScript Tools and Features," of the GoLive CS2 SDK Programmer's Reference. These tools are complete development environments that allow you do more than just test your code-- you can use them, for example, to edit documents interactively. To become familiar with the JavaScript environment in GoLive, try entering some JavaScript expressions into the Command field of a Debugger window; press ENTER to evaluate the expression. If you get a response in the output view, the command shell is ready for use; if not, see Enabling Debug Services. Error logs All script errors are written to a log that is displayed in the Log window, which you can access through the File >Log command. Double click a script error entry in the log window to opens the script file in the debugger and go to the error line. If an extension file contains a script tag that refers to an non-existing file, a warning is written to the log. When a run-time error occurs in an extension script, an alert window displays the error message before the error is written to the log. Run-time errors in other scripts, such as startup scripts, are written to the log without an alert message. 2 How to Create an Extension Like a plug-in, an extension provides new capabilities to its host environment. With the GoLive CS2 SDK, you can use ExtendScript (Adobe's ECMAScript-compliant version of JavaScript) and HTML to create extensions that extend and customize the Adobe GoLive web-design environment. About Adobe GoLive CS2 Extensions An extension that you create for Adobe GoLive CS2 using the SDK is actually an HTML file that GoLive uses in a special way. Creating an extension is similar to creating a web page: you add tags and scripts to this file to define content. Instead of defining content for a web page, however, you use tags that define menus, dialogs, palettes, inspectors, and additional objects in the GoLive design environment. You can also create custom tags to define objects of your own. When GoLive loads an extension, it makes the object defined in that extension available to GoLive users through the GoLive UI and through UI elements that you define. You can add to the GoLive menus, and create your own menus. You can add to GoLive windows--for example, add custom components to the Objects palette--or create your own dialogs and palettes. You can create custom elements, to extend the kind of markup a user can add to a page with GoLive's simple drag-and-drop technique, and customize the GoLive Inspector to make it display and modify your component's attributes. You can extend GoLive to integrate with other applications, web services, and more. What can extensions do? One of the most popular uses of an extension is the programmatic editing of files written in HTML, XML, ASP, JSP, and other markup languages. To ease your learning curve, GoLive allows you to use familiar tools for this task. The JavaScript DOM in GoLive works just like the one in a web browser, providing programmatic access to the markup elements in an HTML file through the markup object. You can edit HTML files just as a browser or other HTML editor would. The SDK can operate directly on documents in Layout view, allowing you to create extensions that automate the creation or modification of HTML pages. The SDK can also operate on documents without displaying them, enabling extensions to process batches of files rapidly. In addition to supporting standard JavaScript DOM events, GoLive provides additional events that support the programmatic modification of documents and sites in the GoLive design environment. Responding to an event in your extension is similar to responding to one in a web page: you define an appropriately named JavaScript function within the HTML file's // add a menu item to a GoLive menu // define a dialog with UI controls ... // define a custom element and add it to the Objects palette // define an Inspector for the custom element ... Creating An Extension Module Every extension takes the form of a Main.html file that resides in its own uniquely named folder in the Extend Scripts folder. This section describes how to create the file and folder structure GoLive expects extensions to have. To begin creating an extension, first create the extension folder. Create a folder with a unique name and place it in the Adobe GoLive CS_Lang/Modules/Extend Scripts/ folder. Adobe GoLive CS2 SDK Programmer's Guide How to Create an Extension 22 In this folder, create a new file named Main.html. You can use any text or HTML editor to edit this file, including Adobe GoLive CS2 itself. Creating the Main.html file The Main.html file contains the markup tags and JavaScript that define an extension. To create a Main.html file: 1. In GoLive, create a new page, using File > New Document. In the dialog, select Favorites and HTML Page, then click OK. This automatically creates and displays an HTML document with basic page elements such as and . 2. Switch to Source view and add a tag in the element before the

start tag:

For more information on this tag, see Adding the module tag below. 3. Add a

Typically, the For more information on defining and using JavaScript functions in an extension, see Adding event-handling functions below. Adobe GoLive CS2 SDK Programmer's Guide How to Create an Extension 23 5. After the end tag, add special SDK tags for a menu and menu item:

The file should now look like this:

6. Save the document as Main.html in a new folder named My First Extension in the Extend Scripts folder. 7. To test your extension, restart GoLive. Select Test menu>Item 1. This should display an alert "Item 1 was selected." Congratulations! You have just created your first extension to GoLive. That is really all there is to creating a basic extension using the GoLive CS2 SDK. Adding SDK Tags and JavaScript Functions to the Module This section illustrates some development techniques by walking you through a simple extension that writes a message in the JavaScript Debugger window and displays a user alert. In this exercise, you add tags and scripts to the body of a Main.html file such as the one you created above. Adobe GoLive CS2 SDK Programmer's Guide How to Create an Extension 24 Adding the module tag GoLive packages much of its functionality in units known as modules. To add some particular new functionality to GoLive, a user can install and enable the module that provides it. A GoLive user can also disable or remove a module to remove its associated features and behaviors. An extension that you develop using the SDK is simply another kind of module that GoLive can use. Like the built-in modules, extensions can be enabled and disabled in the Preferences dialog. Each module must have a unique name that represents it in the global JavaScript namespace. To define the name of your extension's module, add to your extension's Main.html file a tag that provides a name property: // Main.html file for Hello example // Tags that define your extension go here. When GoLive loads this Main.html file, it creates a module object to represent this extension and sets the value of the object's name property to the HelloModule string. The presence of the debug attribute enables debugging services in the JavaScript Debugger window. Always remove the debug attribute from commercial versions of your extension. The tag and all of its attributes are optional. If you do not supply this tag, or if this tag's name attribute is missing, GoLive assigns a default value to the name property of the module object it creates to represent your extension. However, it is recommended that you explicitly define your own 's name attribute so you can use it for debugging purposes. Adding event-handling functions The JavaScript functions that provide an extension's behavior reside within its // Tags that define your extension's data go here. In this example, the initializeModule and startModule functions simply display messages in the JavaScript Debugger window before the extension runs. The body of these functions consist of a writeln statement that uses the name property of the module object to identify the currently executing extension. When you start GoLive and it loads this extension (along with all other extensions), the text is displayed in the Output panel in the GoLive JavaScript Debugger or in the ExtendScript Toolkit: For the terminateModule function, you might not see such a display before GoLive quits. To make sure you see this message, the example function displays the text in a user alert like this one: To do this, the function uses a globally available static function of the Window class: function terminateModule() { Window.alert ("Unloading the " + module.name + "extension.") } GoLive does not unload this extension and complete the exit process until you click OK in the user alert dialog. Adobe GoLive CS2 SDK Programmer's Guide How to Create an Extension 26 If you place this Main.html file in a HelloModule folder in the Modules/Extend Scripts folder and restart GoLive, you should see the loading and starting messages in the JavaScript Debugger window when GoLive restarts. When you quit GoLive, you see the alert before the application exits. Typically, your initializeModule function registers the event handlers that provide behavior for your objects, and the terminateModule function unregisters the handlers. An extension generally provides event handlers to, for example, respond to clicks on menu items it has added, or to text entry in controls it has defined. For more examples, see Defining menu behavior, and Providing Behavior for Controls. Summary This short example introduces most of the concepts required to understand start using the SDK to define your own extensions. You have now seen how to: Create the Main.html file that defines an extension module. Add SDK tags to that file to define extension data. The next several chapters of this book describe how to add tags that create menus, dialogs, and custom markup elements in the GoLive environment. For a complete list and description of the GoLive CS2 SDK objects, functions, and properties, see Chapter 1, "Objects," in the GoLive CS2 SDK Programmer's Reference. For a complete list and description of all tags that the SDK defines, see Chapter 2, "Tags," in the GoLive CS2 SDK Programmer's Reference. See "Handling Events" on page 32 for an introduction to the event-handling mechanism. Further chapters show event-handling for different functional areas. For example, Chapter 4, "Menus and Toolbars," describes how your extension can respond to the selection of a menu item it defines. For a complete list and description of all event and event target objects the SDK defines, see Chapter 3, "Events and Event Handlers," in the GoLive CS2 SDK Programmer's Reference. Implement and register event-handling functions for events of interest to your extension. Use the JavaScript Debugger window to examine your extension's data and evaluate expressions within your extension's execution scope. Before beginning a serious extension development project, be sure to become more acquainted with the GoLive JavaScript Debugger, a fully featured, internal source debugger. Chapter 13, "Debugging Scripts," describes this useful tool in detail. 3 The JavaScript Environment This chapter discusses JavaScript and ECMAScript/ExtendScript concepts and usage in GoLive, including: JavaScript Objects in the GoLive Environment Scope of Variables and Functions Handling Events Sharing Data Delays and Timeouts JavaScript Objects in the GoLive Environment GoLive provides access to data and objects in a way that JavaScript programmers will find familiar. Those new to JavaScript will discover that the GoLive environment usually provides multiple ways to access data and objects. This section describes various ways an extension's JavaScript code can access data and objects in the GoLive environment. Objects, elements, and properties GoLive JavaScript objects can represent parts of a document, or GoLive components: When GoLive loads a markup document, it generates objects to represent the markup tree of a document. Collectively, the objects that represent portions of the markup document are known as markup objectss. Markup objects can represent HTML markup elements (as defined by a tag and its attributes), and also comments, text blocks, and other types of markup such as entities or CDATA sections. When GoLive loads an extension definition file (that is, the Main.html file for your extension), it creates JavaScript objects to represent the GoLive components you define, such as windows, UI controls, and menu items. For example, a element in your extension definition results in a window Object. There are various ways to obtain a reference to a JavaScript object, depending on the object's type. You can retrieve most component objects by name from global properties, such as the menus and dialogs collections. Objects that represent HTML page content are available from the markup tree; you get the root object from the document Object for the page (document.documentElement), and that object's properties and methods allow you to navigate the tree. GoLive passes relevant objects as event-object property values to event-handling functions. For information on retrieving a particular object, see that object's description in the GoLive CS2 SDK Programmer's Reference. Accessing attribute values The attributes of an element (whether it is a document markup element or an element in your extension definition) appear as the properties of the corresponding JavaScript object. For example, the name 27 Adobe GoLive CS2 SDK SDK Programmer's Guide The JavaScript Environment 28 attribute of the element becomes the name property of the object. Access to JavaScript properties is case-sensitive; that is, the Thing attribute creates the Thing property, not the thing property. When writing JavaScript code, observe case accordingly. JavaScript uses the symbol undefined to indicate a null state. When a property exists, but no value has been explicitly set, that property has a value of undefined. If a property has never been defined, its state (rather than its value) is undefined. To test whether a property exists in JavaScript, you must test the state (not the value), by checking whether the name has a defined type; for example: // correct test if (typeof (myProperty) != undefined) // do something Do not use the following test. This tests the property's value, rather than its state, and results in a run-time error if the property does not exist: // incorrect test if (myProperty != undefined) // if myProperty does not exist, an error occurs When you must test a property's value with a case-sensitive comparison, you can use the toLowerCase method of the JavaScript String object. For example, this tests an element object's tagName property, disregarding the value's case: if (currElt.tagName.toLowerCase()) == (tagToGet.toLowerCase()) For element Objects, attributes are also represented by objects, which are themselves nodes in the markup tree. Use an element object's getAttributeNode and setAttributeNode functions to access the attribute object, rather than accessing the attribute directly by name, as a property of the element object. By using these methods, you avoid potential problems with referencing names that contain special characters, such as hyphens. Naming objects and attributes The value of an element's name attribute must follow JavaScript naming conventions. If more than one element or object uses the same name, the results of name-based object retrieval are unpredictable, so you must take care to ensure that your names are unique. One way to do this is to use a unique prefix or postfix in all of your extension's names. For example, the following element definitions begin the value of each element's name attribute with the letters ADBE. // opens definition of all menus // Hello menu // menu item menu item // closes definition of Hello menu // closes definition of all menus When the SDK loads an extension containing these elements, it creates a menu object that appears in the JavaScript global menus collection. You can use the name to retrieve this menu from the collection: var myMenu = menubar["ADBEHello"]; Adobe GoLive CS2 SDK SDK Programmer's Guide The JavaScript Environment 29 JavaScript object collections The SDK makes commonly used objects available as the elements of array-like structures that all extensions can access. GoLive updates the contents of these structures dynamically as these objects are created and deleted. The SDK implements many of these structures as collection Objects. This is like an array that provides access to its elements by name or index; however, collections are not actually arrays; not every collection provides numeric access to its elements, as an array object does. Each of these global properties contains a collection object that GoLive updates dynamically: Object boxCollection JavaScript Access boxes global property Contents Read-only array of all boxes in the current document. Controls. The current document's windows and dialogs that have run at least once. Read-only. Documents open in GoLive. Undo actions for the document. Every HTMLStyleSet Object in the Window > Styles palette. Links to all files that reference this box (in links) and all files this box references (out links). Immediate subelements of the markup object. All menus currently available in GoLive. All the menu items belonging to a menu. All pictures accessible to this module. All servers known to GoLive. All web servers for a site. All web sites currently open in GoLive. controlCollection controls global property windowObj.controls property dialogCollection dialogs global variable documentCollection history htmlStyleSetCollection documents global property document.history property app.htmlStyles property LinkCollection boxObj.links property MarkupCollection markupObj.subElements menus global variable MenuCollection MenuItemCollection menubar[value].items property menuObj.items.propName PictureCollection ServerInfoCollecton pictures global property app.server property website.server property WebsiteCollection websites global property Using the global object arrays These examples use the menus array to illustrate how you retrieve objects from global arrays. This array provides access to all of the menus and menu items added to GoLive by extensions. Most of the arrays work the same way; exceptions are noted in the GoLive CS2 SDK Programmer's Reference. Adobe GoLive CS2 SDK SDK Programmer's Guide The JavaScript Environment 30 The following JavaScript defines a menu Sample, with one item, MyItem. The SDK creates a menu object named sample and a menuitem object named item1: The following retrieves the Sample menu from the menuCollection object in the menubar global variable, and stores the retrieved menu object in the sampleMenu variable: var sampleMenu = menubar["sample"] In this case, "Sample" is the title of the menu, as displayed to the user, while "sample" is the name of the menu object, which you use to access it programmatically. The following retrieves the menu item by name from the collection in the items property the sample menu: menubar["sample"].items["item1"] Alternatively, you can retrieve the menu item directly, using its name as a property name of the sample menu: menubar["sample"].item1 GoLive also makes each menu available as a JavaScript object in the global namespace. Thus, the following simple line of JavaScript retrieves the menu item from the sample menu. sample.item1 Many collections can be accessed by numeric index as well as by name. For example, if item1 is the first menu item: menubar["sample"].items[0] // 0-based index of first item This is only reliable for the items, not for menus; because other extensions can also add menus, you cannot rely on the order. Some collections, like the controls collection, do not support numeric access at all. Most of the time, an object's unique name property provides the most reliable way to retrieve it. Comparing objects To ascertain an object's identity, you can compare the value of its name property to a known string, or you can compare object references directly. For example, you could test the name of a menu item in any of the following ways: if (item.name == "item1") // compare object name to known string value if (item == menubar["sample"].items["item1"]) // compare objects if (item == sample.item1) // another object comparison example Updating references to objects GoLive generates objects to represent the markup tree of a document when it loads that document. It regenerates these objects if the documents changes; this is know as reparsing the document. If you save a reference to an object that GoLive generated as the result of interpreting a markup tag, you must update that reference any time the document containing the tag changes. For details, see Chapter 7, "Editing Documents Programmatically." Adobe GoLive CS2 SDK SDK Programmer's Guide The JavaScript Environment 31 Scope of Variables and Functions You use standard JavaScript syntax to define your extension's variables and functions. When a Main.html file defines a "global" variable or function, GoLive actually creates the variable or function within the scope of the extension module the file defines, not in the JavaScript global namespace. It is available within the execution scope of that module. It is not available to other extensions. The only truly global values in the GoLive JavaScript environment are those provided by system-defined global variables such as the app variable and the document variable. These properties are available to every extension. For a complete listing and description, see Appendix E, "Scoping in JavaScript in the GoLive CS2 SDK Programmer's Reference. To demonstrate variable scope in the JavaScript Debugger window, add the following highlighted lines to the Main.html file that you created in Chapter 2, "How to Create an Extension," and restart GoLive. // Main.html file for Hello example The new code just adds another writeln statement, but packages it as an extension-specific function. From within the body of this function, the myGlobal variable is accessible as a global variable. However, it is not accessible to any other modules. The JavaScript Debugger shows the current scope in its module list. To set the execution scope to the HelloModule extension, choose its module name from the pulldown menu, as shown here. Adobe GoLive CS2 SDK SDK Programmer's Guide The JavaScript Environment 32 To set the global variable, type the following into the command line: myGlobal = "Hartford, Hereford, and Hampshire." Then run the function from the command line: fabFour(); The function prints the changed string to the output window, using the new value of the global variable. You might think you could access another module's variable by evaluating module.var or some similar JavaScript expression, but it is not that simple. You can use the common Object to share data among extensions if necessary, although most extensions do not need to do so; see Sharing Data. Releasing Memory For optimum performance, you should release unused memory as soon as possible. You can set unneeded JavaScript variables to null to make them available for garbage collection. Before it unloads your extension, GoLive calls the terminateModule function. If you allocate any resources outside the JavaScript environment, your implementation of this function can be used to release them. Handling Events GoLive 8 implements a WC3-compliant event-handling mechanism, which defines event objects of various types which encapsulate information about events, and event targets, GoLive objects in which events can occur. The following GoLive objects act as event targets: app module document box menu menuItem window control Each of these objects inherits the addEventListener function, which allows you to register a handler for a type of event that can occur in that object. When the event occurs in that object, your handler is passed a single argument, one of the Event Object Types, which encapsulates information about the event, such as where and when it occurred. For example, a menuSignal event can occur in a menuItem object, and you can register a handler for that event that responds to the selection of a menu item that your extension added. Your handler is passed a menuEvent object. Your handlers for the menuSignal and control events such as onClick will implement much of the UI functionality. See Chapter 4, "Menus and Toolbars" and Chapter 5, "Windows and Controls," for examples. Register handlers with the document Object for document events such as selection and save. Register handlers with the app Object for the opened and new events, which occur when the user opens or creates a new document. Terminating the GoLive application generates the appterm event in the app Object. You can register a handler for this event to do any cleanup that your extension requires. Adobe GoLive CS2 SDK SDK Programmer's Guide The JavaScript Environment 33 Other events allow more specialized responses, such as defining the appearance of a custom control when it needs to be redrawn (see Chapter 6, "Custom Elements"). For a complete list of events and the circumstances that generate them, see Chapter 3, "Events and Event Handlers" in the GoLive CS2 SDK Programmer's Reference. Note: Event handling has changed significantly in this release. See Compatibility with Previous Event Handlers in the GoLive CS2 SDK Programmer's Reference. Defining and Registering Event Handlers You must register a handler for a specific event in each event target object that should respond to that event. For example, if your extension defines two menu items, you could register a handler to respond to the menuSignal in each of the menuItem Objects. Use the event target object's addEventListener function to register for a specific event in that object. An event handler takes a single argument, the event object. You can define an event handler as a separate named function, or you can define it inline during registration. Inline code can be a locally defined function that takes the event-object argument, or a simple statement. For example, supposing that your extension adds a menu item with the name doThisItem to the Hello menu, you can register an event handler for the item in any of the following ways: To define the handler as a separate function: //define the handler function function doThisHandler (menuEvt) { Window.alert ("You chose" + menuEvt.name); } //register the handler for a target function initializeModule() { menubar['Hello'].items['doThisItem'].addEventListener( 'menuSignal', doThisHandler) } To define the handler inline during registration: // register a locally-defined function function initializeModule() { menubar['Hello'].items['doThisItem'].addEventListener( 'menuSignal', function (e) {'Window.alert ("You chose" + e.name);'}) } --or-- // register inline source code function initializeModule() { menubar['Hello'].items['doThisItem'].addEventListener( 'menuSignal', 'Window.alert ("You chose the Do This menu item")') } It is possible to register an event handler at any time. You can, for convenience, use your extension's initialization function to register your handlers: // Register event handler function initializeModule() { menubar['Hello'].items['doThisItem'].addEventListener( 'menuEvent', Adobe GoLive CS2 SDK SDK Programmer's Guide The JavaScript Environment 34 doThisHandler) } It is not necessary to unregister handlers on termination; the shutdown process does so automatically. To unregister a handler before termination, use the target object's removeEventListener function. Nesting Event Handlers When an event is generated for a child object in a hierarchy (such as a control in a tab panel in a window), GoLive goes through an event capture phase before executing the handler registered with the event trigger object, and then goes through a "bubbling" phase after executing that handler. During the capture phase, GoLive looks for handlers for the event that are registered with ancestor objects of the target. It starts at the topmost level and runs the first handler it finds. It then runs any handler that is registered with the target object itself. After executing the target's handler, it "bubbles" back out through the ancestor objects, running the first registered handler that it finds on the way out. For example, suppose a dialog window contains a panel which contains a button. A script registers an event handler function for the mouseEvent at the window object, another handler at the panel object, and a third handler at the button object (the actual target). In this case, when the user clicks the button, the handler for the topmost parent (the window object) is called first, during the capture phase, then the target button object's local handler. Finally, during the bubbling phase, GoLive calls the handler registered with the immediate parent, the panel object. This allows you to execute multiple handlers for the same event occurrence, or to handle events at a higher level. For example, you could register a mouseEvent handler with a parent window object, instead of or in addition to handlers registered with the individual controls in the window. If you define multiple handlers for the same event in nested objects, or use the same handler at different levels: Check the eventPhase property of the event object to see whether the handler has been invoked in the capture, at-target, or bubbling phase. Check the currentTarget property of the event object for the object where the currently executing handler was registered. In the capture and bubbling phase, this is an ancestor of the target object. Sharing Data You can get GoLive user preferences programmatically, and also create your own extension preferences. You can set values that persist across user sessions, or that are available to other extension only during a single session. You can also communicate with other running extensions and share data with them. Extension modules can use a prefs Object to store persistent user preference data that is available to all extensions. The attribute Object provides read-only access to a subset of GoLive's global preferences. The common Object provides a place to share non-persistent data with other extensions. The app Object's broadcast method allows one extension to send a message to another, and optionally receive a reply from that extension's broadcast event handler. You cannot share or save objects, which are ephemeral. The broadcast method can only exchange strings with other extensions. Adobe GoLive CS2 SDK SDK Programmer's Guide The JavaScript Environment 35 Persistent shared data Extensions can create their own preference data which persists across between user sessions and is available to all extension modules. This feature enables all extensions to share a common set of preferences and to store persistent data. The prefs Object in the prefs global variable makes preference data available to all extensions. Preferences are stored as properties of this object. Create a new preference value simply by writing to a prefs property. For example, this creates a myModule preference that holds "Version 1.0" as its value: prefs.myModule = "Version 1.0"; All other modules can check for the presence of this module: if (prefs.myModule == "Version 1.0")... When GoLive quits, it saves the prefs values along with all other preference data. The next time GoLive starts, it makes this data available to all modules again. Note: You cannot save Javascript objects as pref values. Non-persistent shared data The common Object provides a means of sharing non-persistent string and primitive data among all currently running extensions. You cannot store objects in the common object. The common object provides no predefined properties. Your extension can call the common object's create method to create a new namespace for shared properties in the common object; the namespace is then available to all extensions as a property of the common object. For example, the following creates a namespace to hold properties of a particular extension, then adds a property with an assigned value: common.create("myExt"); common.myExt.myProperty = myValue; Communicating with other extensions The broadcasting mechanism enables an extension to send a message to another extension requesting that it perform a task. Optionally, the called extension can return a result string. When one extension module needs to communicate with another extension module, it calls the app Object's broadcast method. This method generates a broadcastEvent, containing the message argument. An extension that responds to messages from other extensions defines a handler for the broadcastEvent and registers it in the module Object. Your handler for the broadcastEvent checks the message property, performs any tasks necessary to respond to the broadcast message, and optionally returns a result string in the answer property of the event object. Use of the broadcast mechanism is entirely optional. If your extension does not need to communicate with other extensions, it need not implement a broadcastEvent handler. Adobe GoLive CS2 SDK SDK Programmer's Guide The JavaScript Environment 36 Sending messages to other extension modules The broadcast method sends its argument to the broadcastSignal method of any or all running extension modules. broadcast(argument [, targets]); This method converts the argument value to a string, stores the name of the calling module and the argument string to a broadcastEvent object, and generates this event in the target module or modules. The optional targets value is a list of modules to call, in calling order. By default, the broadcast method generates the event in every extension module. Each called module's registered broadcastEvent handler must return a string value or undefined. Broadcasting terminates as soon as any extension's handler returns a value. (The handler can also store a response in the answer property of the event object.) This method's result is the return value supplied by the last handler. If none of the called modules supply a return value, the broadcast method's return value is undefined. Responding to a broadcast To receive and respond to messages from other extensions, your extension must define a handler for the broadcast event and register it with the app object. A called module's handler determines its actions according to the message and sender values in the passed broadcastEvent object. The value the handler sets in the object's answer property is returned as the broadcast method's return value. For example: function handleBroadcast(bcastEvt) { switch (bcastEvt.message) { case thisValue: bcastEvt.answer=5; case thatValue: bcastEvt.answer="Yes"; case anotherValue: { var myResult = myFunction(); if (myResult) bcastEvt.answer=myResult.toString() else bcastEvt.answer="undefined"; } default: bcastEvt.answer="undefined"; } } //register handler function initializeModule(){ app.addEventListener( 'broadcastSignal', handleBroadcast) } Delays and Timeouts GoLive has a global timer that you can use to schedule execution of your own scriptlets. You can set a JavaScript timeout value to avoid an infinite loop or other failure in an extension's JavaScript code that could otherwise halt GoLive indefinitely. Adobe GoLive CS2 SDK SDK Programmer's Guide The JavaScript Environment 37 You can display a progress bar or busy bar to the user while your extension performs lengthy processing tasks. Timed tasks You can evaluate a JavaScript expression after a specified delay. The startTimer global function accepts a scriptlet and a timeout. The scriptlet is stored internally and executed as soon as the timeout has elapsed. Optionally, the scriptlet can be scheduled for repeated execution. For example, you might schedule a script to run once per second. The following code prints a counter in the JavaScript Output window every second: counter = 0; myTimer = startTimer ("writeln (++counter)", 1000, true); Note that the startTimer method's return value is required to stop this code's execution. To do so, pass this value to the stopTimer method, as the following statement does. stopTimer (myTimer); Setting the JavaScript timeout You can specify the amount of time GoLive waits for JavaScript code to return control before it exits the current script unconditionally. Without this feature, an infinite loop or other failure in an extension's JavaScript code could halt GoLive indefinitely. By default, GoLive waits forever for a JavaScript function call to complete. If you are not confident that a JavaScript function can complete its task in a reasonable amount of time, you may prefer to specify the amount of time GoLive waits for a response. Each extension can specify its own timeout that GoLive uses to execute that extension's scripts. To set the script execution timeout, your extension's Main.html file must include a tag that provides a timeout attribute. The value of this attribute is the number of seconds GoLive waits for a script to return control before it exits the script. Values of 0 or false restore the default behavior of never timing out. // give scripts ten seconds to complete before unconditional exit // scripts and SDK tags go here Note: An external library that calls an extension can specify a separate temporary script execution timeout for each JavaScript call. For more information, see the description of the JSAEval function in Appendix A, "Using External Libraries. Progress bars To provide user feedback during lengthy operations, your extension can display a progress bar dialog or busy bar dialog. You can specify the title and the text to be shown while processing. For example: app.startProgress( 'Please wait', 'Progress: 0%', false); //show bar app.setProgress(0,6, 'Progress: 60%');//update periodically Adobe GoLive CS2 SDK SDK Programmer's Guide The JavaScript Environment 38 A busy bar does not display a progress value; instead, it rotates the spiral indicator about once a second. For example: app.startProgress( 'Please wait', 'Processing', true); //busy bar These are the same dialogs GoLive displays as part of its own user interface. Three methods of the app Object make these dialogs available to extensions: The startProgress method initializes and displays the progress dialog. The setProgress method updates the status bar or busy bar display. The stopProgress method hides the progress dialog. As an alternative to these globally-available predefined dialogs, you can define a progress-bar control in your own window; see Creating controls with parameters. Starting a progress or busy bar The startProgress method has this syntax: app.startProgress(title [, message, doBusy, seconds]) You must specify the string that appears in the progress window's title bar, such as "Please wait" in the examples. The optional message argument provides the initial status message displayed when the dialog opens. The method opens a progress bar, unless you pass true for the optional doBusy argument. The optional seconds argument is a number of seconds to delay before Golive displays the dialog. For example, a value of 2 means that GoLive displays the dialog only for operations that take more than 2 seconds to complete. Updating a progress or busy bar While the progress window is displayed, your code must update the position of the progress bar. It can optionally update the message text as well. Your code must also determine whether the user clicked the Stop button and act accordingly to abort the operation in progress. To perform these tasks, call the setProgress method periodically: setProgress( value, [message]) The value argument is a value between 0 and 1 that specifies the portion of the progress bar to be drawn. For example, the value .50 specifies that 50 per cent of the progress bar is drawn to indicate a task half completed. Adobe GoLive CS2 SDK SDK Programmer's Guide The JavaScript Environment 39 The optional message argument is the string to display as the new status message. You can update a busy bar with a new status message; it ignores the value argument. The setProgress method returns false when the user clicks Stop in the dialog. Your code should respond to this condition by aborting the operation that is in progress and closing the dialog. During lengthy operations, it is especially important to call the setProgress method regularly, so that your extension can respond quickly if the user clicks Stop. When the lengthy operation is completed (or the user clicks Stop), call the stopProgress method to close the dialog. Progress bar example This example displays a progress bar. The doSomeWork function is your own code that performs the task on which you are reporting progress. function progressDemo() { var percentDone = 0; var continue = true; app.startProgress("Progress Demo", "Starting, please wait.", busy); while (continue && percentDone < 100) { doSomeWork(); // your own code percentDone += 1; // simply 1 to 100 for sample continue = app.setProgress(percentDone/100, 'Progress: ' + percentDone + '%';) } if (!continue) writeln ("User clicked Stop."); app.stopProgress(); } 4 Menus and Toolbars This chapter describes how you can use the GoLive CS2 SDK to add menus and menu items to the GoLive menu bar and context menus, and add toolbars to the GoLive main toolbar. Note: This chapter does not describe pop-up menus, which are controls that appear in dialog windows. For information on popup menus, see "Adding Controls to Windows" on page 66. To create a custom menu in the GoLive menu bar, your extension defines the menu and menu items, and defines and registers event handlers which GoLive calls when the user chooses a menu item. You can add submenus, enable and disable a menu programmatically, and check and uncheck menu items. You can also add menu items to the predefined menus in the GoLive menu bar. The GoLive CS2 SDK provides limited access to some of GoLive's context menus. Your extension can define an event handler for a context menu that extends that menu by adding submenus or menu items. See Extending Context Menus below. Similarly, to create a toolbar, your extension defines the toolbar and its controls (typically buttons with icons), and defines and registers event handlers for the controls. See Creating Toolbars below. Creating Custom Menus You can add a custom menu to the GoLive menu bar in your extension definition (the Main.html file) using the three menu SDK tags. To create a custom menu or menu item when your extension is loaded, place these tags in an extension's Main.html file: One binary tag per Main.html file surrounds all the other tags that add menus to the GoLive menu bar. The tag defines a custom menu that appears to the left of the Window menu in the GoLive menu bar. The tag defines a custom menu item that appears in a custom menu. GoLive adds custom menus to the menu bar at the left of the Window menu. You cannot specify the order in which GoLive loads multiple custom menus. However, the items in a menu always appear in the order the Main.html file defines them. Your script can also add menu items and submenus to existing menus at run time, using a menu Object's addItem or addChild function. The addChild function can add either an item or a submenu; it creates and returns the menu or menuItem object as well as modifying the existing menu. For an example that creates both a submenu and its menu items, see "Context menu example" on page 51. When the user chooses a menu item, GoLive generates a menuSignal with that menuItem Object as its target. Your extension must define a menuSignal handler to implement the behavior of your menu item, and register it for with the menuItem object. GoLive calls this function whenever the user chooses the item for which it is registered. Basic example This example defines the custom menu shown below: // opens definition of all menus 40 Adobe GoLive CS2 SDK SDK Programmer's Guide Menus and Toolbars 41 // custom menu // menu item 1 //menu item 2 // closes definition of Hello menu // closes definition of all menus When GoLive runs this extension, the custom menu appears in the GoLive menu bar. When the user chooses one of these custom menu items, GoLive calls the menuItem's registered menuSignal handler function. The Adding the menu bar tag The opening tag must precede all of the tags that define custom menus and custom menu items. Its companion closing tag must close all the HTML that defines custom menus and custom menu items. The Main.html file must contain only one tag set. // Main.html file // opens definition of all menus and menu items // Tags that define your menu & menu items go here. // closes definition of all menus and menu items Defining the Menu Inside the tags, the tag defines the name of your custom menu. Its syntax looks like this: Adobe GoLive CS2 SDK SDK Programmer's Guide Menus and Toolbars 42 The name attribute specifies the name used to access the menu in the JavaScript namespace, while the title attribute specifies the text that appears as the menu's title in the GoLive menu bar. In this example, this defines the top level of the menu: // Main.html file for Hello example // opens definition of all menus and menu items // Tags that define your menu items will go here. // closes definition of all menus & menu items You use the name, rather than the title, to access the menu when this extension is running: myMenu = menubar["Hello"]; If you omit the name property or supply no value for it, GoLive uses the value of the title property as the default value of name. To retrieve the menu reliably, the name must be unique in the JavaScript namespace. Unlike most of the objects in an extension, menus are a resource shared by all extension modules. The menus global array makes all menus defined by all extensions available to all extensions. If a element's name attribute duplicates the name property of an existing menu object defined by any module the SDK has already loaded, GoLive appends the element's menu items to that existing menu. Defining menu items The tags that define a custom menu enclose one or more tags. Each tag defines a menu item that appears in the custom menu. The syntax for this tag is: As for the menu itself, the name attribute specifies the name used to access the menu item in the JavaScript namespace, while the title attribute specifies the text that appears in the menu in the GoLive UI. The optional dynamic attribute specifies that this item needs to be initialized on startup. For details, see Initializing menu items. In the example, this defines the two custom menu items. // Main.html file for Hello example // opens definition of all menus and menu items // closes definition of all menus & menu items Adobe GoLive CS2 SDK SDK Programmer's Guide Menus and Toolbars 43