What's New

Older History

Introduction

The External Editor Protocol described in this page is a client/server protocol based on Apple events. The server application is usually a text editor, and the client application is usually an ftp client, but nothing prevents the protocol from being used in other scenarios as well.

This protocol is currently implemented by BBEdit, Style, Tex-Edit Plus and PageSpinner on the server side, and by Interarchy, NetFinder, Transmit and Fetch on the client side.

The clients of this protocol have an "Edit with <External Editor>" menu command. When you select a file in a remote directory and choose that command, the file is downloaded to a temporary location (the invisible "Cleanup At Startup" folder) and opened in the external editor. When the user saves the document from the external editor, the file is automagically uploaded back to the remote machine by the ftp client. Very handy.

How Does It Work?

It's pretty simple. The ftp client sends the editor an 'odoc' event with some additional parameters:

The augmented 'odoc' event.
Parameter Type Required? Description
---- typeAEList The usual list of file aliases to open.
FSnd typeType The creator code of the client application.
FTok typeAEList   A list of arbitrary tokens to be associated with the opened documents.
Burl typeAEList   A list of document URLs.
RdEV typeUInt32   Text encoding hint (overrides the document-specified encoding, if any)
RdFB typeUInt32   Text encoding hint (fallback used only if the document doesn't provide any encoding information)

The 'FTok' and 'Burl' parameters are lists because the direct parameter of the 'odoc' event is itself a list of aliases, one for each document to open, although in most cases the direct parameter is a list of only one alias.

The tokens in the 'FTok' list are arbitrary descriptors. Interarchy uses strings (typeChar), NetFinder uses numbers (typeLongInteger) and Trasmit uses yet another type, but the server application shouldn't care about the type: it should just make a copy of the token descriptor and associate it internally with the open document. When the document is saved or closed, the editor should hand the token back to the ftp client in one of the notification events described below.

The 'Burl' parameter is a list of URLs (typeChar) associated with the documents to open. It is purely informational. BBEdit and Style display the URLs in the window headers, so it's clear the documents come from a remote machine, but other implementations can safely ignore this parameter.

window header displaying the URL

The 'RdEV' optional parameter, first introduced by BBEdit in 2005, and the 'RdFB' optional parameter, first introduced with BBEdit 9.0 and TextWrangler 3.0, specify the text encoding of files to open. They can be any encoding (any value of type TextEncoding) listed in <CarbonCore/TextCommon.h>. You can also use any value of type CFStringEncoding here, as defined in <CoreFoundation/CFString.h>, since CFStringEncoding is really a subset of TextEncoding. If the 'RdEV' parameter is present, it overrides any encoding information that may be present in the file itself (such as a UTF-8 BOM in a plain text file, or a meta tag in an HTML file). On the other hand, the 'RdFB' parameter serves as a fallback in case there is no reliable means to figure out the correct encoding by inspecting the file.

Thanks to Ben Artin for providing details about the 'RdEV' and 'RdFB' parameters.

The File Modified Event

This is a notification event sent by the editor to the ftp client (whose creator was previously specified in the 'FSnd' parameter) when the user saves the file. When it gets this event, the ftp client should upload the modified file back to the remote machine (probably making a temporary copy first, because the original file remains open and may be modified again before the upload is completed).

The 'file modified' event (class = 'R*ch', ID = 'FMod').
Parameter Type Required? Description
---- typeFSS The FSSpec of the original file.
Tokn any   The token associated with the open document, if any.
New? typeFSS   This optional parameter is used when the file is 'Saved As' to a new location.
It contains the new FSSpec.

The File Closed Event

This is a notification event sent by the editor to the ftp client when the user closes the file. The purpose of this event is to release the file/URL association maintained internally by the ftp client.

The 'file closed' event (class = 'R*ch', ID = 'FCls').
Parameter Type Required? Description
---- typeFSS The FSSpec of the original file.
Tokn any   The token associated with the open document, if any.

Choosing an External Editor

Ftp clients have traditionally hard-coded their choice of external editor to BBEdit, because BBEdit was the editor that first introduced and implemented this protocol. But now that several other editors support the same protocol, ftp clients should let their users pick the one they like best.

Whether or not the ftp client provides a user interface for choosing the external editor, this preference should be synchronized with the value of the helper•ftp-editor key in the Internet Config database. When this key is missing, client applications may default to the application specified by helper•editor, if it's known to support this protocol, else fall back to BBEdit.

This is an extension to the original Bare Bones specification, supported by Interarchy 4.1 and Fetch 4.0.

Editor-Initiated Editing Sessions

External editor sessions are usually initiated by the ftp client. There are cases, though, when it can be handy to start the session from the editor. For instance, the editor may have a Recent Documents menu. When the user chooses a remote file from that menu, the editor should ask the ftp client to initiate an external editing session.

The editor does this by sending the ftp client the following ftpedit event:

The 'ftpedit' event (class = 'FTP!', ID = 'Edit').
Parameter Type Required? Description
---- typeAEList A list of URLs.
FSnd typeType The creator code of the external editor.

This event is a request by the external editor for the ftp client to download the specified remote files. When the download is complete, the ftp client should initiate an external editing session by sending the augmented 'odoc' event described before.

When starting a session for just one URL (by far the most common case), editors should be able to specify either a typeAEList parameter containing one item, or a typeChar parameter, and ftp clients should be ready to accept both variations. In most cases, no special effort is required, since the Apple Event Manager can automatically coerce a string to a list of one string.

This is an extension to the original Bare Bones specification supported by Interarchy 4.1.