Adobe GoLive CS2 Programmer's Manual

bbc

Adobe

®

GoLive

®

cs2

SDK Programmer’s Guide

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.

3

Contents

Preface........................................................................................................................................10

About Adobe GoLive CS2 SDK ................................................................................................................................................10

About This Book............................................................................................................................................................................11

Who should read this book ................................................................................................................................................11

What is in this book ...............................................................................................................................................................11

Document conventions .......................................................................................................................................................12

Typographical conventions .........................................................................................................................................12

JavaScript common properties...................................................................................................................................12

Where to Go for More Information ........................................................................................................................................13

1 Installing and Configuring the GoLive SDK............................................................................. 14

Installing the GoLive CS2 SDK..................................................................................................................................................14

Installing the core set of tools and sample extensions ............................................................................................14

Installing the core extensions .....................................................................................................................................14

Uninstalling an extension.............................................................................................................................................15

Configuring GoLive for Extension Development..............................................................................................................15

Enabling the Extend Script module ................................................................................................................................15

Enabling and disabling modules......................................................................................................................................16

Debugging Your Scripts.............................................................................................................................................................17

Error logs ...................................................................................................................................................................................17

2 How to Create an Extension......................................................................................................18

About Adobe GoLive CS2 Extensions ...................................................................................................................................18

What can extensions do? ....................................................................................................................................................18

Anatomy of an Extension ..........................................................................................................................................................19

Extension-building tools .....................................................................................................................................................20

Example Main.html File..............................................................................................................................................................21

Creating An Extension Module................................................................................................................................................21

Creating the Main.html file.................................................................................................................................................22

Adding SDK Tags and JavaScript Functions to the Module..........................................................................................23

Adding the module tag .......................................................................................................................................................24

Adding event-handling functions ...................................................................................................................................24

Summary ...................................................................................................................................................................................26

3 The JavaScript Environment.....................................................................................................27

JavaScript Objects in the GoLive Environment .................................................................................................................27

Objects, elements, and properties...................................................................................................................................27

Accessing attribute values..................................................................................................................................................27

Naming objects and attributes .........................................................................................................................................28

JavaScript object collections..............................................................................................................................................29

Using the global object arrays ....................................................................................................................................29

Comparing objects..........................................................................................................................................................30

Updating references to objects ........................................................................................................................................30

Scope of Variables and Functions ..........................................................................................................................................31

Releasing Memory .................................................................................................................................................................32

Handling Events............................................................................................................................................................................32

Defining and Registering Event Handlers.....................................................................................................................33

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

10

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

Using External Libraries.”

What is in this book

This book contains the following chapters:

● Chapter 1, “Installing and Configuring the GoLive SDK,” describes how to install the GoLive CS2 SDK

and enable the appropriate modules.

● Chapter 2, “How to Create an Extension,” describes what an extension is and what extensions can do. It

provides a tutorial that creates a simple “Hello, World” extension.

● Chapter 3, “The JavaScript Environment,” describes how GoLive makes JavaScript objects available to

extensions and discusses other application-level considerations such as variable scoping, data sharing

and communication among extensions, and timing issues.

● Chapter 4, “Menus and Toolbars,” describes how to add custom menus, submenus, and menu items to

GoLive.

● Chapter 5, “Windows and Controls,” describes how to create modal dialogs and floating palettes, and

add the user-interface controls that allow users to interact with your extension.

Adobe GoLive CS2 SDK

SDK Programmer’s Guide Preface 12

● Chapter 6, “Custom Elements,” describes how to define a custom element, with an icon the user can

drag from the Objects palette into a GoLive document in a document window.

● Chapter 7, “Editing Documents Programmatically,” describes how extensions can use JavaScript code

to manipulate document content.

● Chapter 8, “Editing with Layout,” describes how you can manipulate document content while GoLive’s

Layout view is open, with a minimum of reparsing and redisplay flicker.

● Chapter 9, “Managing Files and Folders,” describes how to manipulate files and folders on disk.

● Chapter 10, “Managing Web Sites,” describes how to work with a Web site’s file resources and how to

work with and customize the GoLive Site window.

● Chapter 11, “Localization and Translation,” describes dynamic language localization and source code

transformation.

● Chapter 12, “Extending GoLive Actions,” describes how to create and edit GoLive actions, JavaScript

scripts you can add to a page and edit with an Inspector.

● Chapter 13, “Debugging Scripts,” describes how to use the internal JavaScript Debugger.

● Appendix A, “Using External Libraries,” describes how to create external C or JavaScript libraries your

extension can call from JavaScript.

● “Glossary,” lists and defines many of the specialized terms uses in these books.

Document conventions

This book uses the following typographic and terminology conventions.

Typographical conventions

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

errors.

JavaScript common properties

Because most objects provided by the SDK provide a name property, the Objects chapter in the GoLive CS2

SDK Programmer’s Reference (companion volume to this guide), does not list

name properties explicitly.

Similarly, the Reference does not list properties and methods provided by the JavaScript language itself.

For example, it is common for JavaScript objects to provide a

toString method, and many of the objects

Monospaced font

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

pathnames.

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

myName represents a value you are expected to supply, such as name="Fred".

Also indicates the first occurrence of a new term.

Blue underlined text

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

companion volume.

Sans-serif bold font

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.

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

14

1

Installing and Configuring the GoLive SDK

The first part of this chapter describes how to install the GoLive CS2 SDK and introduces the JavaScript

environment that GoLive provides for extensions. The next part specifies the file and folder structure you

must use to create an extension. This chapter concludes with an example of a simple extension that writes

messages in the JavaScript Debugger window.

Installing the GoLive CS2 SDK

The GoLive CS2 SDK requires version 8.0 of Adobe GoLive CS2 and is included in the default installation.

Updates to the SDK and to this documentation set are available at http://partners.adobe.com/asn

.

Installing the core set of tools and sample extensions

This section describes how to install an extension in GoLive. GoLive CS2 SDK files are initially installed in a

subfolder of the Adobe application folder called

Adobe GoLive SDK 8.0r1. The extensions provided

with the SDK are in the

Samples and Tools folders.

Each sub-folder in the

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

recommended that you install the core set of sample extensions and tools, and use them to help learn

about and create your own extensions.

Once you have become familiar with the use of the tags, scripts, and objects these samples illustrate, you

can remove any or all of them, as you prefer.

Installing the core extensions

To install an existing extension, in most cases you simply copy or move the folder to the

GoLive_dir/Modules/Extend Scripts folder. See the Release Notes for a list of samples whose

installation requires more than this; in these cases, the installation instructions are included in the

extension's

Main.html file or in the Release Notes.

➤ The following steps make the core extensions available to GoLive:

1. Quit GoLive if it is running.

2. Copy at least the following extension folders from the

GoLiveSDK_dir/Samples folder to the

Adobe GoLive 8.0/Modules/Extend Scripts folder:

● Custom Box

● KeyMap

● Markup Tree

● Menus and Dialogs

● Palettes

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

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

Adobe GoLive CS2 SDK

SDK Programmer’s Guide Installing and Configuring the GoLive SDK 15

4. Copy the following folders from the GoLiveSDK_dir/Tools folder to the

GoLive_dir/Modules/Extend Scripts folder:

● Dialog Editor

● Edit Extension

● Extension Builder

5. Start GoLive.

When GoLive starts, it loads all of the extensions present in the

Extend Scripts folder.

Uninstalling an extension

To remove an extension from GoLive, remove its folder from the Extend Scripts folder and restart

GoLive.

You can deactivate an extension without removing it; see Enabling and disabling modules

.

Configuring GoLive for Extension Development

Developing GoLive extensions is an iterative process that generally requires you to restart GoLive

whenever you need to load a new version of the extension you are developing. JavaScript-only changes

can be reloaded from the

JavaScript Debugger without restarting GoLive.

Enabling the Extend Script module

The built-in Extend Script module must be enabled before you can load or run any extensions. The module

is enabled by default. Disabling this module disables all GoLive extension capabilities, which you normally

do not want to do.

➤ If this module has become disabled, you can re-enable it as follows:

1. Select Edit > Preferences.

2. In left panel of the

Preference dialog, select Modules.

Modules are listed on the right by folder name.

Adobe GoLive CS2 SDK

SDK Programmer’s Guide Installing and Configuring the GoLive SDK 16

3. In the list of modules, check the Extend Script module.

4. Click OK to confirm your changes and dismiss the Preferences panel.

5. Quit GoLive and restart it.

Enabling and disabling modules

GoLive packages much of its functionality in units known as modules. An extension that you develop

using the SDK is simply another kind of module that GoLive can use. To add some particular new

functionality to GoLive, you can install and enable the module that provides it. You can also disable or

remove a module to remove its associated features and behaviors.

To turn off an extension but leave the extension in the

Extend Scripts folder, use the Edit >

Preferences

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

modules any extensions you want to turn off. The change takes effect when you restart GoLive.

The precise set of modules you can disable successfully depends on the features your extension or site

uses—you cannot disable a module your site or your extension requires for its functionality.

Note: Do not disable the Extend Script module. If this module is not enabled, GoLive cannot load or run

any extensions.

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

Preferences dialog

➤ Getting descriptions of modules

1. Select Edit > Preferences, and in the left panel of the Preferences dialog, select Modules.

2. In the right pane, click to select the module to be described.

3. If

Show Item Information appears at the bottom of the modules list, as shown in the figure above, click it

to reveal the item information pane.

ExtendScript module checked

Show description of selected module

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:

Debugging Your Scripts

You can use either the internal GoLive JavaScript Debugger window to develop and debug your scripts, or

the ExtendScript Toolkit, which is available to all Creative Suite 2 applications. To choose one or the other

debugging environment, set the internalDebugger

property of the settingsSDK Object. When it is true

(the default), the GoLive JavaScript Debugger is active. You can use the Debugger’s console to set the

value to

false, making the ExtendScript Toolkit active.

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

● The ExtendScript Toolkit is described in Chapter 5, “ExtendScript Tools and Features,” o f th e GoLive CS2

SDK Programmer’s Reference.

These tools are complete development environments that allow you do more than just test your code—

you can use them, for example, to edit documents interactively. To become familiar with the JavaScript

environment in GoLive, try entering some JavaScript expressions into the Command field of a Debugger

window; press E

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

shell is ready for use; if not, see Enabling Debug Services

.

Error logs

All script errors are written to a log that is displayed in the Log window, which you can access through the

File >Log command. Double click a script error entry in the log window to opens the script file in the

debugger and go to the error line. If an extension file contains a script tag that refers to an non-existing

file, a warning is written to the log.

When a run-time error occurs in an extension script, an alert window displays the error message before the

error is written to the log. Run-time errors in other scripts, such as startup scripts, are written to the log

without an alert message.

Description of selected module

ExtendScript module selected

18

2

How to Create an Extension

Like a plug-in, an extension provides new capabilities to its host environment. With the GoLive CS2 SDK,

you can use ExtendScript (Adobe’s ECMAScript-compliant version of JavaScript) and HTML to create

extensions that extend and customize the Adobe GoLive web-design environment.

About Adobe GoLive CS2 Extensions

An extension that you create for Adobe GoLive CS2 using the SDK is actually an HTML file that GoLive uses

in a special way. Creating an extension is similar to creating a web page: you add tags and scripts to this

file to define content. Instead of defining content for a web page, however, you use tags that define

menus, dialogs, palettes, inspectors, and additional objects in the GoLive design environment. You can

also create custom tags to define objects of your own.

When GoLive loads an extension, it makes the object defined in that extension available to GoLive users

through the GoLive UI and through UI elements that you define.

● You can add to the GoLive menus, and create your own menus.

● You can add to GoLive windows—for example, add custom components to the Objects palette—or

create your own dialogs and palettes.

● You can create custom elements, to extend the kind of markup a user can add to a page with GoLive’s

simple drag-and-drop technique, and customize the GoLive Inspector to make it display and modify

your component’s attributes.

● You can extend GoLive to integrate with other applications, web services, and more.

What can extensions do?

One of the most popular uses of an extension is the programmatic editing of files written in HTML, XML,

ASP, JSP, and other markup languages.

To ease your learning curve, GoLive allows you to use familiar tools for this task. The JavaScript DOM in

GoLive works just like the one in a web browser, providing programmatic access to the markup elements

in an HTML file through the

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

would.

The SDK can operate directly on documents in Layout view, allowing you to create extensions that

automate the creation or modification of HTML pages. The SDK can also operate on documents without

displaying them, enabling extensions to process batches of files rapidly.

In addition to supporting standard JavaScript DOM events, GoLive provides additional events that support

the programmatic modification of documents and sites in the GoLive design environment. Responding to

an event in your extension is similar to responding to one in a web page: you define an appropriately

named JavaScript function within the HTML file’s

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

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

Main.html

file as you might add them to a web page: tags go in the file’s

<head> and <body> elements, and

JavaScript functions go in the file’s

<script> elements.

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

Custom Box extension’s folder

contains the extension’s

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

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.

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

the

GoLiveSDK_dir

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

GoLive_dir

/Modules/Extend

Scripts

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

● Extension Builder

This tool creates the skeleton code for an extension, together with the extension folder in the proper

location. It opens the skeleton

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

specific objects and behavior.

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

Extensions > New Extension.

● Edit Extension

This tool complements the

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

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

GoLive_dir

/Adobe GoLive SDK folder.

The step-by-step tutorial in this chapter (Creating An Extension Module

) walks you through creating an

extension from scratch, to help you understand the framework and requirements that the

Extension

Builder

tool takes care of for you.

Page is loading ...

Adobe GoLive CS2 Programmer's Manual

Adobe GoLive CS2 Programmer's Manual

Related papers

Other documents