Adobe CS2 User Manual

cs2

GoLive

Adobe

SDK Programmer’s Guide

bbc

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.

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

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 <mytag>, 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,” i n th e GoLive CS2 SDK Programmer’s

Reference.

You use ExtendScript to create extension

s 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.

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, “

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.

Using External Libraries.”

● 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

Italics Variables or placeholders in code. For example, in name="myName", the text

Blue underlined text

Sans-serif bold font

Note: Notes like this one highlight issues that deserve extra attention, key requirements, and common

errors.

A hyperlink you can click to go to a related section, in this book or the

Literal values and code, such as JavaScript code, HTML code, filenames, and pathnames.

myName represents a value you are expected to supply, such as name="Fred". Also indicates the first occurrence of a new term.

companion volume.

The names of GoLive UI elements (menus, menu items, and buttons).

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.

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

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

name properties explicitly.

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

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 with the SDK are in the

Samples and Tools folders.

Adobe GoLive SDK 8.0r1. The extensions provided

Each sub-folder in the 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.

Samples and Tools folders holds a different example of an extension. It is

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

➤ 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

Adobe GoLive 8.0/Modules/Extend Scripts folder:

● Custom Box

● KeyMap

● Markup Tree

● Menus and Dialogs

● Palettes

Main.html file or in the Release Notes.

GoLiveSDK_dir/Samples folder to the

3. Copy the contents of the GoLiveSDK_dir/Samples/Common folder to the

Adobe GoLive 8.0/Modules/Extend Scripts/Common folder.

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

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:

JavaScript Debugger without restarting GoLive.

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

Preferences

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

If you are not sure whether you need to enable a particular module, you can get a description of it in the Preferences dialog

dialog to display Modules, as shown in the figure above. In the list of modules, uncheck the

any extensions.

Extend Scripts folder, use the Edit >

➤ 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 (the default), the GoLive JavaScript Debugger is active. You can use the Debugger’s console to set the value to

● The GoLive JavaScript Debugger is described in Chapter 13, “Debugging Scripts.”

● The ExtendScript Toolkit is described in Chapter 5, “ExtendScript Tools and Features,” of t h e GoLive CS2

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 E 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.

false, making the ExtendScript Toolkit active.

SDK Programmer’s Reference.

NTER to evaluate the expression. If you get a response in the output view, the command

property of the settingsSDK Object. When it is true

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.

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 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

selection event, you define and register a handler function for that event inside a <script> element in

the

Main.html file that defines the extension.

The GoLive DOM supports not just HTML, but XML (Extensible Markup Language). This ability enables GoLive to recognize other markup languages, such as those which define server-side tags, as well as the

markup object. You can edit HTML files just as a browser or other HTML editor

Adobe GoLive CS2

SDK Programmer’s Guide How to Create an Extension 19

special <jsx… > tags the SDK provides. As a result, you can edit an extension’s Main.html file (or any of the other file types noted) in a GoLive document window, just like any other markup document.

GoLive CS2 SDK provides enhanced support for site-level operations, including notification of changes in the content or organization of the Site window, and programmatic selection of site assets according to criteria you specify. For example, an extension can select all files in the site that would take longer than a minute to download at 56kbps. You might then process each selected file in some way. For example, you might compress it, downsample it, or reformat it in some way that would reduce the time required to download it.

In addition to its extended DOM and event model, the GoLive object model provides access to the GoLive application itself, which in turn makes available a host of other services and content.

The GoLive application provides access to:

● The GoLive user interface (Menus, Dialogs, Palettes, Inspectors, Site window, Document windows, Site

reports, built-in localization).

● User settings, global stylesheets, preferences, shared data, other extensions.

● Custom/server tag support and special parsing behavior.

● You can create extensions that provide your own customized tags and content as icons in the Objects

palette. You can also preprocess documents before the GoLive parser reads them, to deal with encoding issues or to mimic the effects of server-side code in Layout view, which is the graphical editing view in GoLive.

● Automation and macros: apply automated edits to every file in a site, or generate entire sites

programmatically.

● Dynamic Content database content.

● Resources on network and WebDAV servers.

The typical extension can and does, of course, define things for itself in its own code, such as its own user interface items, custom functions, custom tags, SDK-provided tags, HTML tags, localization, source translation, and more. To accomplish this, you’ll just add tags and functions to an extension’s file as you might add them to a web page: tags go in the file’s JavaScript functions go in the file’s

XML support enables even further extensibility, allowing GoLive to grow rapidly and conform easily to new standards that may emerge in the future.

Anatomy of an Extension

At its most basic, an extension consists of a Main.html file in a subfolder of the Extend Scripts folder, called the extension folder. The extension folder can contain other files the extension requires, such as images. These additional files can be kept in subfolders. For example, the contains the extension’s image files.

The extension’s

Main.html file contains markup tags and JavaScript that define the extension. At startup

time, GoLive interprets these tags and scripts to load an extension in the GoLive environment. The

Main.html file should be an xHTML UTF-8 encoded markup document.

Main.html file, and also an Images subfolder that holds external .gif and .jpg

Main.html

<head> and <body> elements, and

<script> elements.

Custom Box extension’s folder

The extension defines objects using the GoLive SDK xHTML tags, and also defines the behavior for those objects using JavaScript code.

Adobe GoLive CS2

SDK Programmer’s Guide How to Create an Extension 20

● The Main.html file defines the extension’s menus, controls, inspectors, palettes, and custom tags. You

can combine the special SDK tags with standard HTML tags as necessary.

● The <jsxmodule> tag defines the extension’s name and some basic behavioral features.

● Various SDK-defined tags such as <jsxdialog> and <jsxmenu> define the extension’s objects, such as

windows, menus, and UI controls.

● JavaScript code contained in a <script> element in the Main.html file defines your own functions

and your implementations of GoLive event-handling functions. When an event is triggered in one of your extension’s objects (for example, when the user interacts with an extension’s custom menu, dialog, or palette), GoLive calls your extension’s handler for that event.

Extension-building tools

The GoLive CS2 SDK includes powerful tools that make extension building easy. These tools are found in

GoLiveSDK_dir

the

Scripts

● Extension Builder

folder, as described in Installing the core set of tools and sample extensions.

This tool creates the skeleton code for an extension, together with the extension folder in the proper location. It opens the skeleton specific objects and behavior.

/Tools folder. To use them, copy them into the

Main.html file in GoLive’s Layout view, so that you can edit it to define

GoLive_dir

/Modules/Extend

The skeleton provides the file framework, including basic HTML (such as enclosing tags), and basic elements needed for an extension, such as the

<jsxmodule> and <script> tags. It

provides for easy automatic insertion of common objects, such as menus and windows, and provides a JavaScript script with placeholder function definitions (without body code) of the callback functions

initializeModule, startModule, and terminateModule.

When this tool is installed correctly, you can invoke it by choosing

● Edit Extension

This tool complements the

Extension Builder, allowing you to open and edit an extension’s

Extensions > New Extension.

Main.html file after you first create it. Invoke it by choosing Extensions > Edit Extension. Together, you

can use these tools to iteratively modify and test your extension, restarting GoLive as needed to load new objects.

● Dialog Editor

This tool helps you design dialogs and add them to your extension. It adds a dialog-building tab to the Objects palette, with UI controls that you can easily drag into GoLive’s Layout view of your extension’s

Main.html file.

For a step-by-step walkthrough of how to use these tools to build an extension quickly and easily, see GoLive CS2 SDK:Getting Started, in the

The step-by-step tutorial in this chapter (Creating An Extension Module extension from scratch, to help you understand the framework and requirements that the

Builder

tool takes care of for you.

GoLive_dir

/Adobe GoLive SDK folder.

) walks you through creating an

Extension

Adobe GoLive CS2

SDK Programmer’s Guide How to Create an Extension 21

Example Main.html File

This incomplete example shows the basic structure of the Main.html file for an extension with some typical components, such as a menu item, dialog box with UI controls, a custom element with an Inspector, and event-handling functions:

<html>

<body>

// define JavaScript event-handling functions

function initializeModule (){

if confirm ("Modify...?"){

fileGetDialog(...);}

...}

function menuSignal (menuItem){

if (menuItem.name == "myItem") {

//do something } ...}

... </script> // add a menu item to a GoLive menu

</jsxmenu>

</jsxmenubar>

// define a dialog with UI controls

... </jsxdialog> // define a custom element and add it to the Objects palette

// define an Inspector for the custom element

...

</jsxinspector

</body>

</html>

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

<body>.

and

2. Switch to Source view and add a

<body>

</body>

<jsxmodule> tag in the <body> element before the <p> start tag:

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

3. Add a

<body>

</body>

Typically, the <script> element is placed inside the <body> element, but you can put it inside the

<head> element.

4. Inside the

<head>

function initializeModule() {

menubar["Test"].items["Item1"].addEventListener("menuSignal",

'function(e){Window.alert(e.target.name + " was selected!");}')

}

</script>

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 </script> end tag, add special SDK tags for a menu and menu item:

</script>

</jsxmenu>

</jsxmenubar>

The file should now look like this:

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html>

<head>

content="text/html;charset=iso-8859-1"> <meta name="generator" content="Adobe GoLive 7"> <title>Welcome to Adobe GoLive 7</title>

</head>

function initializeModule() {

menubar["Test"].items["Item1"].addEventListener(

"menuSignal", 'function(e){

Window.alert(e.target.name + " was selected!");}')

} </script> <jsxmenubar>

</jsxmenu> </jsxmenubar> <p> </p>

</body>

</html>

6. Save the document as Main.html in a new folder named My First Extension in the Extend

Scripts

7. To test your extension, restart GoLive. Select

was selected.

folder.

Test menu>Item 1. This should display an alert “Item 1

”

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 provides a

// Main.html file for Hello example <html>

</html>

name property:

<body>

// functions that provide your extension’s behavior go here

</script>

// Tags that define your extension go here.

</body>

Main.html file a <jsxmodule> tag that

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 commercial versions of your extension.

The

<jsxmodule> 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 represent your extension. However, it is recommended that you explicitly define your own

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 <script> tags. Many of these functions are event handlers, which you register for particular event target objects. GoLive calls these functions in response to specific events, such as the GoLive user clicking on something or entering text. Your extension can provide a handler to respond to a specific event in a specific object, such as the selection of a menu item or the opening of a document. When the event occurs in a target object, GoLive looks for all registered handlers for that event in that object, and if it finds one, executes it.

The GoLive CS2 SDK Programmer’s Reference provides the names and syntax of all the event and event target objects, and describes the handlers that you can define. Most of them are optional; you only need to supply handlers for the events you need to respond to.

Module startup and termination events are handled by functions with predefined names. For example, on startup, GoLive checks all loaded modules for implementations of the

startModule functions. If your module needs to perform any initialization, it can do it in these functions.

initializeModule function is called as soon as the module is loaded, and can perform any

The initialization that does not depend on other modules, and the modules are loaded. Similarly, your implementation of the housekeeping tasks before GoLive unloads your extension.

debug attribute from

name property of the module object it creates to

<jsxmodule>’s

initializeModule and

startModule function is called after all

terminateModule function can perform

Adobe GoLive CS2

SDK Programmer’s Guide How to Create an Extension 25

The following example shows very simple implementations of the initializeModule, startModule, and

terminateModule functions.

// Main.html file for Hello example <html>

<body>

// functions that provide your extension’s behavior go here

function initializeModule() {

writeln ("Loading the " + module.name + " extension."); } function startModule() {

writeln ("Starting the " + module.name + " extension."); } function terminateModule() { Window.alert ("Unloading the " + module.name + "extension.") }

</script>

// Tags that define your extension’s data go here.

</body>

</html>

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 statement that uses the

name property of the module object to identify the currently executing extension.

writeln

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 objects, and the 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

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.

● Implement and register event-handling functions for events of interest to your extension.

initializeModule function registers the event handlers that provide behavior for your

terminateModule function unregisters the handlers. An extension generally provides

, and Providing Behavior for Controls.

● 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, “

● For a complete list and description of all tags that the SDK defines, see Chapter 2, “Tags,” i n the

Objects,” in the GoLive CS2 SDK Programmer’s Reference.

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, “

● Use the JavaScript Debugger window to examine your extension’s data and evaluate expressions

Events and Event Handlers,” i n the GoLive CS2 SDK Programmer’s Reference.

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.

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 objects

s. 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 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 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 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

CDATA

<jsxdialog> element in your extension definition results in

for the page (document.documentElement), and that object’s

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

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 been explicitly set, that property has a value of (rather than its value) is

undefined to indicate a null state. When a property exists, but no value has

undefined. If a property has never been defined, its state

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 attribute object, rather than accessing the attribute directly by name, as a property of the

element object’s getAttributeNode and setAttributeNode functions to access 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

<jsxmenubar> // opens definition of all menus

<jsxmenu name="Hello" title="Hello, GoLive!"> // Hello menu

</jsxmenu> // closes definition of Hello menu

</jsxmenubar> // 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

var myMenu = menubar["ADBEHello"];

name attribute with the letters ADBE.

<jsxitem name="This" title="Do Something"> // menu item <jsxitem name="That" title="Do Something Else” > menu item

menus collection. You can use the name to retrieve this menu from the collection:

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 Object

s. 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 JavaScript Access Contents

boxCollection

boxes global property Read-only array of all boxes in the

current document.

controlCollection

controls

global property

Controls.

windowObj.controls property

dialogCollection

dialogs global variable The current document’s windows and

dialogs that have run at least once. Read-only.

documentCollection

history

htmlStyleSetCollection

LinkCollection

documents global property Documents open in GoLive.

document.history property Undo actions for the document.

app.htmlStyles

property Every HTMLStyleSet Object in the

Window > Styles palette.

boxObj.links property Links to all files that reference this box

(in links) and all files this box references (out links).

MarkupCollection

markupObj.subElements Immediate subelements of the

markup object.

MenuCollection

menus

global variable All menus currently available in

GoLive.

MenuItemCollection

PictureCollection

ServerInfoCollecton

WebsiteCollection

menubar[value].items property

menuObj.items.propName

pictures

app.server

website.server property

websites

global property All pictures accessible to this module.

property

global property All web sites currently open in GoLive.

All the menu items belonging to a menu.

All servers known to GoLive.

All web servers for a site.

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:

</jsxmenu>

The following retrieves the Sample menu from the menuCollection object in the menubar global variable, and stores the retrieved

var sampleMenu = menubar["sample"]

menu object in the sampleMenu variable:

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.item1

sample menu.

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 Most of the time, an object’s unique

name property provides the most reliable way to retrieve it.

controls collection, do not support numeric access at all.

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, “

Documents Programmatically.”

Editing

+ 167 hidden pages