29

Menus

A menubar object can be exported as an ordinary packed object, but frequently what is desired is to export a particular menu item (along with its script, and any menu items hierarchically dependent upon it). This is done by selecting the menu item in a menubar edit window, and choosing Export SubMenu from the Menubars menu.

Folders

You can export a table and its entries as individual packed objects, rather than exporting the whole table as one packed object. To do this, select the table as an entry in its parent table, and choose Export from the Main menu; when the Export dialog appears, set the first popup to Folder.

The table will be represented on disk by a folder (despite the Save dialog, which asks for a "file" name). All entries in the table are exported as individual packed objects, except for tables, which are represented as folders. Thus the end product is a hierarchy of folders and packed object files, mirroring the structure of the original table.

One advantage of this format is that the exported objects, though many, are relatively small; Frontier has an easier time importing and exporting smaller objects. On the other hand, a single packed object file is far more space-efficient than its contents broken out into individual packed object files.

Importing Packed Objects

A packed object may be opened from the Finder like any other file - by double-clicking it, or by selecting it and choosing Open from the File menu, and so on. It is also possible to open a packed object from within Frontier, using Open from the File menu; or the packed object's icon may be dropped onto Frontier's icon.

When a packed object is opened, Frontier comes to the front and presents a dialog offering a chance to cancel importing, or to determine the imported object's destination (its object reference) in the database. The default is the object's path from before it was exported. You can change this destination if you wish: you must supply a complete path (except for "root"), and it must be a valid object reference. If an object of the same name already exists, a second dialog asks whether you wish to overwrite it with the imported object; if you decline, the first dialog appears again.

if typeOf (adr^) == tableType «see if it has an importSuite script

    if defined (adr^.importSuite)

        « adr^.importSuite (adr)

        « previous line removed, and next one added, for safety

        dialog.notify (string(adr) + " has an importSuite routine")

        return (true)

Script Editor Format

If you're using OSA Menu, you can have it run an exported script for you. The chief advantage of this is that the script runs in the context of the frontmost application. Also, such scripts are not imported into Frontier (though of course Frontier must be running). The whole operation works just like choosing a shared menu item (see Chapter 26).

Here's an example. Suppose we are in Microsoft Word. From OSA Menu's special script menu towards the far right of the menubar, choose Open "Microsoft Word Scripts" Folder. In Frontier, make a script; as a test, it might say simply:

dialog.notify("Hello there.")

Export the script into the Microsoft Word Scripts folder (it's in a folder called Scripts in the System folder), choosing Script Editor format from the first popup menu in the Export dialog. Suppose we call the exported file Hello. Now go back into Microsoft Word. OSA Menu's script menu now contains an item Hello; choosing it brings up our dialog within Microsoft Word, just as if we had called the same script from a shared menu.

Script-Based Approach

In the script-based approach, you begin by deleting the card entry in the droplet table. You then edit the script entry called script.

The script will be treated rather like the proc of a visit verb: it will be called multiple times. On the first call only, system.droplet.startup will be true, to give the script a chance to perform any initializations; in that same call, the first file to be processed will be in system.droplet.path . Then in subsequent calls, successive files to be processed will be in system.droplet.path. After all files have been provided, there is one last call, where system.droplet.closedown will be true. To maintain globals between calls to your script, just store them in system.droplet.

When you create a droplet table, it contains a script object called script that provides an illustrative minimum framework:

if system.droplet.startup

    msg ("starting up")

if system.droplet.closedown

    msg ("closing down")

local (f = system.droplet.path)

Suppose we modify this to read as follows.

if system.droplet.startup

    frontier.bringtofront()

    dialog.notify ("starting up")

if system.droplet.closedown

    dialog.notify ("closing down")

else

    local (f = system.droplet.path)

    dialog.notify(f)

The resulting droplet, when icons are dropped onto it, brings Frontier to the front and presents a succession of dialogs: the first dialog says starting up, then dialogs give the pathnames of the icons dropped onto the droplet, and finally, there is a dialog reading closing down. The script explicitly brings Frontier to the front first, because that's where the dialogs will appear.

An entry in the droplet table is named faceless . If its value is false when the application is built, then when icons are dropped onto the application, a "splash screen" dialog will appear in the Finder, displaying the text from the helpText entry of the droplet table and offering a choice of running the droplet, editing it, or quitting it. You are expected to modify helpText to make the splash screen informative about what the droplet does.

A non-faceless droplet also has its own menus at the top of the screen. By default, these consist of just a File menu with a Quit item. To add further menus, create a menubar called menubar in the droplet table; its menus will appear at the top of the screen in addition to the File menu. While the splash screen is showing, the user might choose from your menu items in order to initialize settings affecting how the droplet will behave.

Dialog-Based Approach

In the dialog-based approach, the card entry is not deleted, but is modified to be a MacBird dialog (see Chapter 25, Dialogs) that will appear within Frontier. The script entry is ignored. All of the pathnames of files and folders dropped on the droplet are available in a list of fileSpecs, system.droplet.fileList .

As an example, we'll make a dialog-based droplet which lists in a popup menu the files and folders dropped. The dialog might look like Figure 29-1 in MacBird.

The popup menu is called theMenu, and an initial phrase has been entered into it just to space the layout nicely. The OK button has an action script, card.close(); and the card table contains a startCard script, as follows:

local (s, f)

for f in system.droplet.filelist

    s = s + string(f) + ";"

s = string.delete(s, sizeof(f), 1)

card.popup.setMenu("theMenu",s)

When files and folders are dropped onto the droplet, Frontier comes to the front automatically, unlike with script-based droplets.

Backing Up

You can create a backup copy of the database by choosing Backup from the Main menu. This calls suites.backups.backuproot() , which simply makes a Finder copy of the database. The new copy goes into a folder called backups in the same folder as Frontier; backups get consecutively numbered names, and old backups are not deleted, so it is up to you clean out the backups folder occasionally.

Afterwards, the pathname of the file just created is deposited at backups.lastfile . Then, your people.[user.initials] table is consulted to see if it contains a script called customBackup; if so, it is called with no parameters. How you use this mechanism (a pseudo-hook) is up to you; see Chapter 27, Agents and Hooks.

Saving a Copy

Frontier provides a mechanism for saving a compacted version of the database. There are two reasons why this is useful.

First, although making frequent backups provides a measure of security, it is not a panacea. To be sure, the backup preserves entries in case they are overwritten or deleted in the working copy of the database. But if the database has become structurally corrupted in some way, backing up does not eliminate the corruption: whatever problems lurk in the database will lurk in a copy.

On the other hand, saving a compacted copy does help assure the database's integrity, because it causes Frontier to "rethink" the whole structure of the database. This affords a considerably greater measure of security.

Some sense of the database's structural status can be gained by calling table.validate() ; this checks the internal consistency of a table and all its subtables to infinite depth. However, I'm told that it is possible for certain kinds of lurking problem to pass this test undetected. I'm also told that you can get a false positive if a table contains an entry whose value has not yet been set.

Second, as the database is used, free space opens up in it, and pointers to the free blocks are added to a list called the "avail list," which must be traversed each time Frontier searches the database. This strategy makes saving and accessing the database rapid and robust in the short term, but over time its accumulated effects reduce the database's efficiency.

To examine this aspect of the database, call window.dbStats() ; the third line of the windoid that appears tells the number of nodes in the avail list, and the fourth line shows the amount of free (meaning wasted) space in the database.

To compact the database, choose Save a Copy from the File menu. (You can drive this command programmatically with filemenu.saveCopy() .) The process may take considerable time, but afterwards both the third and fourth lines of the dbStats window will be 0. Frontier never performs this operation automatically; it is incumbent upon the user to do it from time to time, and it is important to do it, as a way of keeping the database in good condition.

The dialog that appears when you choose Save a Copy will offer to overwrite the existing database with the new copy, but this is probably not a good idea; instead, back up the database just in case, save a copy under a different name, such as Frontier.rootNew, and then quit Frontier, throw away the old Frontier.root, and rename the compacted copy Frontier.root.

Batch Export

The most reliable way to assure the integrity of your database material is to export it as a number of packed objects, thus altogether isolating it both from the database and from its structure. This is called a batch export. A batch export is also a very good way to transport data between roots, or to migrate into a clean root (discussed later in this chapter).

For this purpose, the batchExporter suite is provided. To access it, choose Batch Exporter from the Suites menu. You then choose Export from the Batch menu that appears. This causes suites.batchExporter.batchExport() to generate packed object files.

The process works like this. A single-level outline at suites.batchExporter.list says what tables should be exported. Frontier tries to export the items of each of these tables as a single packed object; if any of the items proves to be a table too large to permit this, Frontier instead performs a folder-style export, representing the table as a folder and trying to export each of its entries as a single packed object - and so on. The result is sort of limited folder-style export. The results of the operation are logged at user.batchExporter.log, which you can check afterwards to determine that all went well.

suites.batchExporter.list is of interest because it tells you what parts of the database UserLand thinks a user might have modified - implying, mutatis mutandis, that the rest of the database should be considered off limits.

people

You might have put anything at all into people.[user.initials], and you might have imported third-party scripts into other tables.

suites

You might have written your own suite, or imported a third-party suite.

user

Any suites and commands maintain important data here, and some suites expect you to store your own customized settings, scripts, and other objects here.

system.agents

You might have written an agent, or a suite might have installed one.

system.extensions

You might have written a UCMD, installed a third-party UCMD, or imported an XCMD.

system.menubars

You might have customized or created a shared menu.

system.misc

In system.misc.menubars, you might have customized your =user.initials menu, added bookmarks, installed suites that changed the suites menu, and so forth; I'm not sure there's any other part of system.misc that you would really be free to personalize.

system.startup, system.suspend, system.resume, system.shutdown

You or a suite might have added a hook script.

system.verbs.apps

You might have built or imported glue for driving an application.

system.verbs.traps

You might have added a trap so that Frontier can be driven from outside.

workspace

You might have put anything at all here.

Notice that scratchpad is not exported, because by definition its contents are expendable.

It is possible that, outside these areas of the database, you might "illegally" have reached deeper into Frontier's functionality to customize it. For example, I don't like the way the Find & Replace dialog "forgets" where I put it, so I have modified search.dialog() to remember the dialog's location between calls. But, being a built-in verb, search.dialog() belongs to UserLand, not to me, and is not included in a batch export. In cases like this, I maintain a copy of the customized script in my people.[user.initials] table. That way, my customized version is preserved during a batch export.

Import from Batch Export

To import material exported with batch export, you have a choice of two strategies:

• You could perform a batch import of a whole folder. This is done by choosing Batch Import from the Batch menu, which asks what folder to import and then calls suites.batchExporter.batchImport() . This routine performs a much better folder import than suites.export.importFolder(): it doesn't empty out the table into which it imports, and it creates subtables intelligently. It will, however, replace database entries without notifying the user.
• You could import packed objects individually, by opening them in the Finder. This lets you pick and choose what objects to import, and gives you a chance to think twice before deleting an object already present in the database. However, your importing of packed objects can only be as "individual" as the export was; the batch export might have exported as a single packed object a table of which you want to import only one particular entry. What I like to do, therefore, is this: if an object exists already, I import the packed object into the workspace table temporarily, where I can inspect its contents. Then I can copy and paste just the desired entries into their proper place in the database.

Importing from a batch export, no matter how you do it, can be a little tricky. Experience has suggested the following cautions:

• If you do a batch import of the Suites folder, when Frontier comes to the packed object file for suites.batchExporter, it will use the imported object to overwrite the currently running script. That's very bad. Move that file so it won't be batch-imported.
• Don't open a packed object representing suites.export and replace the existing suites.export: that, too, overwrites the currently running script.
• Don't do a batch import that includes system.misc.paths. In fact, don't ever touch system.misc.paths.
• Don't do a batch import that includes system.misc.menubar. You can, however, import system.misc.menubar by opening it in the Finder and then replacing the existing object.

How to Migrate

The usual first step in migrating to a clean root is to do a batch export from your present database. Then you throw out your present database, make the clean root your Frontier.root, and import into it your customized material from the batch-exported files.

This import process can be a little tricky. The clean root may contain improvements from UserLand, so you don't want to replace an object if the imported version would be less up to date than what's already there. For example, you wouldn't want to import your exported suites.Eudora if the new clean root comes with better Eudora "glue" than the old one did. On the other hand, perhaps you customized the old Eudora glue somehow, so you'd like to use the new glue but keep your customization.

The problem, in my view, is one of organization. You can use the usual techniques to import carefully and conservatively; but if you don't remember what changes you've made to the database, you're afraid of losing those changes if you import too conservatively.

The solution is to have good work habits. Don't make changes to parts of the database that won't be exported in a batch export; if you do, make copies in your people table. Try to keep running documentation, in the people table, of changes that you make to the database. As you change or create a script, mark it using Insert Timestamp in the Scripts menu; later, before doing a batch export, you can search the database for your initials to find all such places.

A Different Approach

If you're extremely organized, and have kept track of every database entry you've customized, then instead of using batch export and subsequent import, you could take advantage of the fact that it is possible to have two databases open at once, to have a script copy your customized material from the old database to the new one. See Chapter 30, Multiple Databases.