Parts of a GEDitCOM II Extension

GEDitCOM II is a scriptable application. By writing or using Internal scripts or scripts in AppleScript or Python, you can manipulate the genealogy data in your files, calculate and export results about the files, create web sites, import data from arbitrarily-formatted text files, control the user interface, and much more.

The recommended method for installing scripts is to package them in an extension. A GEDitCOM II extension is a package of one or more scripts along with a manifest file, documentation files, and possibly other associated files. This topic explains these parts. You should refer to other help on writing extensions to learn how to create and edit extensions and to program scripts for GEDitCOM II.

Scripts
The Main Script Choice
Manifest Tags
Documentation Files
Associated Files

Scripts in Extensions

A GEDitCOM II extension can contain any number of Internal Scripts, AppleScripts, or Python scripts. Internal Scripts and Python ccripts will be listed in the "Scripts" section and can be fully edited in GEDitCOM Editor. AppleScripts will be listed in the "other files" item of the "properties" section. They are edited using Apple's Script Editor.

The Main Script Choices

The "main choices" and "main choices SD" items in the "Properties" section give the names of the scripts to run when the extension is selected in GEDitCOM II. If an extension has only a single script, then these options should list just that one script. If an extension has more than one script, the user will be given a list when the extension is run and can pick which one to run from a list of descriptions. Thus for multiple scripts, add each script name in the "Key" section and write a short description of the script in the "Value" section. These descriptions are what the user will see when deciding which one to run.

You can edit these choices by double clicking the "Key" or "Value" entries. You can add or delete choices with "Add Property" or "Delete Property" menu commands (or tool bar icons).

You can add an edit the special "Key" named "prompt" key to create a prompt string (in its "Value") that will appear above the list of scripts when the user is asked to select an option. If the "prompt" key is not used, a generic prompt will appear instead.

Note the AppleScripts can be compiled scripts (with file extension .scpt) or plain text scripts (with file extension .applescript). If you enter a script name in these choices with file extension .scpt and that script is not found, GEDitCOM II will look for a script with the same name but having extension .applescript instead. If found, it will be compiled and run. This switch does not work in reverse, If your choice has extension .applescript, only a script with that name will be run.

The "main choices" list is for running scripts in GEDitCOM II. The "main choices SD" list is for running scripts GEDitCOM and it should list only Internal Scripts and AppleScripts that are compatible with GEDitCOM (for more details, see help on writing extensions for GEDitCOM).

Manifest Tags

The manifest tags describe certain properties of the extension and are used by GEDitCOM II to support various extension features.

category: All installed extensions appear in the "Extensions" menu and can optionally appear in submenus in that menu. If this tag is empty, the extension will appear at the root level of the "Extensions" menu. If a category is entered (e.g., "Editing Tools"), it will appear in a submenu. It can appear in nested submenus by separating the submenu titles with slashes (e.g., "Editing Tools/Family Records"). GEDitCOM II uses the category tag when installing extensions to automatically place them in the correct folder in the application support folders.
menu command: The text to appear in the "Extensions" menu of GEDitCOM II for this extension.
description: A short description of the feature created by this extension.
minimum version: The minimum version of GEDitCOM II required to run this extension. GEDitCOM II will verify a proper version is running before running the extension. Note that for extensions that package several scripts, this version should be the minimum version for all scripts. Any script in the same extension that needs a newer version should include a separate check in its scripting code.
minimum version SD: The minimum version of GEDitCOM required to run the extensions GEDitCOM will verify a proper version is running before running the extension (for more details, see help on writing extensions for GEDitCOM). Note that for extensions that package several scripts, this version should be the minimum version for all scripts. Any script in the same extension that needs a newer version should include a separate check in its scripting code.
help: The name of the main documentation file in this extension.

You can edit these tags by doubling clicking the "Key" or "Value" fields.

Documentation Files

You can (and should) fully document extensions. To provide documentation, you can add any number of documentation files (files with extension .html, .htm, or .css). They will appear in the "Documentation" section. If the documentation needs other files (e.g., images), they can be imported and will appear in the "other files" item in the "Properties" section.

Associated Files

Besides scripts and documentation, an extension can include any number of associated files. The types of associated files are:

Plain Text Files: You can add any number of plain text files, which are files with extension .txt or .tex. These files will appear in the "Text" section. These files can be added using the "New Text File..." menu command. They can be edited on the right side of the window by selecting them in the "Text Files" section.
Other Files: You can import any other files you want to store in the extension by using the "Import Files..." menu command. They will appear in the "other files" item in the "Properties" section, but these files cannot be edited in GEDitCOM Editor.