Frontier Install File Creator

UserLand Software, Inc.

UserLand Software is located at 400 Seaport Court, Redwood City, CA 94063. 415-369-6600, 415-369-6618 (fax). UserLand and Frontier are trademarks of UserLand Software, Inc. Other product names may be trademarks or registered trademarks of their owners.

Email: userland.dts@applelink.apple.com. If youÕre an AppleLink user, check out the UserLand Discussion Board under the Third Parties icon. CompuServe users enter GO USERLAND at any ! prompt.

Comments, questions and suggestions are welcome!

Background

If youÕve added Apple Event support to your application and installed the Menu Sharing Toolkit, youÕre almost ready to ship.

How are script writers going to learn about and benefit from your Apple Event support?


An Example

Check out ÒMinimal AppletÓ in the Sample Code folder. In addition to being an example of programming with UserLand's Applet Toolkit, it also has a Read Me file, a Frontier install file, and a DocServer text file included in the ÒMinApp & FrontierÓ sub-folder.

 

 

MinApp.Frontier is a Frontier install file. It contains an embedded script that teaches Frontier how to talk to MinApp.

DocServer Source Text is a text file that contains documentation for the Apple Events that MinApp implements.

Read Me is a text file that contains installation instructions for script writers, and other important information.

The goal of this document is to walk you thru the steps needed to produce an install file and DocServer text for your application.


Getting Started

Make a list

YouÕll need the following information before configuring Frontier for your application:

1.  Your applicationÕs name. It should be short, but not so short as to be cryptic. It must be a language identifier, and therefore should contain no spaces, and it must start with an alphabetic character. Underscores are allowed but not recommended. By convention, application names are MixedCase: like BarChart, QuickMail, PageMaker.
2.  Does your application support menu sharing? For more information, see the Menu Sharing Toolkit folder.
3.  The application file. You may have several copies of your program on your system, Frontier needs to know which copy to launch when communicating with your application.

Set up Frontier

First, launch Frontier.

A new version of the Commercial Developers Suite is included in this folder. Double-click on its icon to install.

Select Commercial Developers from the Suites menu. The Glue menu appears in Frontier's menu bar. 

Select ÒEnter Your AppÕs NameÓ from the Glue menu. A series of dialogs guide you thru the process of setting up Frontier to work with your application.


Your Glue Table

Open your glue table

From the Glue menu, choose the Open Table & Menu command. It opens your app's table and shared menu. Bring the table to the front.

Write your first glue script

LetÕs write a Òglue scriptÓ to connect to one of the Apple Events implemented in your program. WeÕll start with a very simple one that simply tells your program to quit.

Bring your glue script table to the front. ItÕs the one named system.verbs.MyApp.

From the Table menu in Frontier, select the New ScriptÉ command. Enter the name for your script:

 

 

A window opens with an empty script. Enter the following into the new window (use the tab key to indent the second line):

 

 

Launch your application. Then bring up FrontierÕs Quick Script window (press cmd-semicolon) and type:

 

Then click on the Run button. Frontier runs the MyApp.quit script; in turn, it sends an Apple Event to your application telling it to quit. If youÕve correctly implemented the required event suite (fingers crossed!) your application should no longer be running.

 

LetÕs do another experiment. Bring the Quick Script window to the front and click on the Run button again. You should see an error message:

 

 

If you click on the Go To button, Frontier takes you to the place that the error occurred, the call to the appleEvent built-in.

 


The second glue script

Now letÕs write a script that connects to the required 'odoc' Apple Event.

In Frontier, bring system.verbs.MyApp to the front, select New ScriptÉ from the Table menu and name the script openDocument. Then enter the following script into the new window:

 

It's important to coerce the file path to the correct type. This allows script writers to call MyApp.openDocument with a string, or a filespec, or any type that can be coerced to an alias. As a general rule, your glue scripts should coerce the type of every parameter to the type that your program expects.

Launch your program, then enter the following into the Quick Script window and click on the Run button:

          MyApp.openDocument ("System:Test Document")

Inside the quotes, enter the full path to a document created by your application. Switch into your application. You should see a window displaying the contents of the document.


The remaining glue scripts

The rest of your glue scripts follow the same pattern. Write one script to connect to each of the Apple Events supported by your application.

To see an example of a complete glue scripts table, double-click on MinApp.Frontier in the Minimal Applet folder, and jump to system.verbs.apps.MinApp.

MyApp.examples

You should include some example scripts to show script writers how to work with your application in a sub-table of your glue script table. Call it examples.

See MinApp.examples for some ideas. They donÕt have to be profound, actually the simpler the better. Give us ideas on how to access the power of your program.

MyApp.appInfo

An ÒappInfoÓ table was created when you entered the name of your application. It has several bits of information that help Frontier work with your application:

1.  app1Supported is a boolean, indicating whether or not the application supports the app1 verb set. It's default value is false.
2.  sharedMenus is a boolean, it indicates whether or not the application implements FrontierÕs menu sharing protocol.
3.  name is a string, itÕs used in Frontier messages that mention your application by name. Enter the full name of your product here. For example, the name in the appInfo table for Think C 6.0 is "Think Project Manager," and its verbs are in the Think table.
4.  path is a string, set automatically and maintained by the app.start Frontier verb.
5.  id is a 4-character string, the creator id of your application.

MyApp.id

This is the target of all the Apple Events sent to your application. Usually it is just the creator id of your application. However, if Frontier is talking to your application over a network, it contains the network address of your application.

You should never assign to MyApp.id, it's handled automatically, but all your glue scripts should refer to it.

innerCasing

By convention, the names of glue scripts are innerCase. The first character is lower case. Each new word in the script name begins with an uppercase letter.

Sample code

If youÕre looking for examples showing how to implement the other side of these glue scripts, have a look at the ÒMenu SharerÓ sub-folder in the Sample Code folder. It implements a single, very simple Apple Event.


'aete' Resources

Jump-starting your glue table

Terminology or 'aete' resources are the equivalent of Frontier install files for AppleScript. If you already have such a resource for your application, you can use the Commercial suiteÕs ÒImport 'aete' InfoÓ command to jump-start your glue table. The command scans your applicationÕs terminology resource and creates a set of glue scripts for the events you support. It also adds values to your table corresponding to any classes, properties, and enumerators youÕve defined.

All of the items are named according to the terminology in the resource, with multiple-word names mapped to innerCase identifiers. Classes and properties are represented as string4Type values.

If you fully support the Core or Miscellaneous Standards suites, a set of scripts is created that call FrontierÕs corresponding core or misc verbs. So in cases where Frontier defines more than one verb for an event, such as core.get and core.getAs, your table will include matching entries. For individual suite events and custom events, a glue script is created directly from the 'aete' data.

Hand-tuning the result

The resulting glue table will be almost ready for prime time. But it should be reviewed carefully, and fine tuned as necessary. In particular, the 'aete' resource doesnÕt provide a name for an eventÕs ÒdirectÓ parameter. Frontier makes a best-guess at a name based on the parameterÕs datatype, but itÕs likely that you can come up with something more meaningful.

As you go through the hand-tuning process, you may want to take notes about the changes you make. If you end up wanting to re-import from the resource later, youÕll need to apply the changes again.

Once you have the glue scripts tuned to your satisfaction, you should think about providing higher-level verbs that build on this basic set. Consider the types of tasks that script writers might want to accomplish with your application; does it make sense to bundle several common steps into a single verb? For object model applications, there may be events that are likely to be called with a specific set of parameters. For example, a charting application might add a ÒcreateNewChartÓ verb that simplifies the use of the core ÒcreateÓ event. The time you spend smoothing out the scripting interface here will make a lot of difference to script writers.


Your Shared Menu

Where your shared menu lives

If your applicationÕs creator id is 'MYAP', the shared menu for your application is at system.menubars.MYAP. Use FrontierÕs Jump To command (cmd-J) to open your menubar.

Its Purpose

When you add menu sharing to your application youÕre allowing script writers to add commands to your program. When preparing a sample menu bar to ship with your application, youÕre providing examples that will show script writers what they can do.

ItÕs created automatically

When you entered your applicationÕs name using the Glue menu, a new shared menu is created automatically. Initially this menu has three real commands and three placeholders for demo scripts.

Conventions

The art of developing shared menus has progressed substantially. This section details some of what weÕve learned. ItÕs a style guide, not hard and fast rules. But a bit of consistency between shared menus will make it easier for people to learn how to write scripts for new apps.

1.  Use hierarchies sparingly.
If you have ten commands to share as sample scripts, donÕt use any hierarchies. Keep a balanced appearance, put the same care into organizing the structure of your shared menu as you would with a Òhard wiredÓ menu.
2.  One menu, not five.
Leave lots of room for script writers to be creative. The more menus you write, the less inviting for the script writer. Choose your examples carefully.
3.  Call it the Scripts menu.
Give it a name to set it off from the rest of your menus. The script writer can change this later.

4.  Include an About command.
It should be the first item in the menu. Use Frontier's built-in dialog.notify verb to display a short message.
5.  Cmd-M opens the shared menu.
This should be the second-to-last item in your shared menu. It opens the shared menubar for the script writer to edit it. If cmd-M is already in use in your program, leave the cmd-key blank in the menu bar editor.
6.  Cmd-T opens the scripts table.
This should be the last item in your shared menu. It opens your applicationÕs scripts table. If cmd-T is already in use in your program, leave the cmd-key blank in the menu bar editor.

When your menu bar is created initially it is set up automatically to follow these conventions. Of course you can and should edit it.

Exporting your Install File

When to do it

In the process of releasing Apple Event support for your application, you will export your install file many times. Basically, any time you want to give a copy of your program to a script writer, you should export a current install file and include it with your application.

How to do it

Select Commercial Developers from the Suites menu to add the Glue menu to the menu bar. Be sure that youÕve entered the name of your application. Then choose Export Install FileÉ from the Glue menu.


DocServer Docs

DocServer

UserLand includes a copy of DocServer with Frontier, and it is available for downloading on the AppleLink and CompuServe on-line services. The purpose of DocServer is to provide a quick and simple way for script writers to access documentation for your glue scripts.

commercial.sampleDocs

Preparing your DocServer docs is done in Frontier, using the built-in outliner.

Open the outline at commercial.sampleDocs. As you browse thru it youÕll see that thereÕs a common structure. Each verb has information about its syntax, parameters, action and returned values. Also included are example script fragments and often notes and pointers to other relevent verbs.

To prepare documentation for your verbs, edit this outline. Then select the Compile DocServer Text command to export the outline into a format that can be read by DocServer. To see what your docs look like, launch DocServer and doube-click on the file.

Include this file in your ÒMyApp & FrontierÓ folder.


MyApp & Frontier

The Folder

You should prepare a folder called ÒMyApp & Frontier.Ó You may choose to include it on your shipping disk or upload it to UserLandÕs CompuServe forum (Library 3, Scriptable Apps). It should contain three files:

Read Me

You should include a Read Me file in TeachText format. Tell the reader how to install support for your application in Frontier. Keep it direct and simple. YouÕre talking to script writers, theyÕre more technical than the average end user. People will tune out if the installation instructions are too complicated.

MyApp.Frontier

This is your Frontier install file. This file is created by the Export Install FileÉ command in the Commercial Developer Suite, included in this folder. Details are provided in a separate section.

DocServer Source Text

This is a text file, produced by the Compile DocServer Text command in the Commercial Developers Suite. ItÕs file type is TEXT, the creator is DOCS. When the script writer double-clicks on this file, UserLandÕs DocServer app launches and loads the text into its database.


Scriptability Checklist

Launching in the background

Many apps assume that the only way they can be launched is by the user double-clicking on something in the Finder, or selecting their application from the Apple menu. In other words, they assume that when they are launched they will be the frontmost application.

However, when a script launches your application it will not be the frontmost application until the script brings you to front. If you are performing a server function for the script, you may never be brought to front.

Therefore, techniques like splash screens work only if they do not require interaction from the user. In fact, it would be more polite to only show a splash screen if you are the frontmost app.

Some early System 7 apps break this rule, and as a result are much less useful to script writers.