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.