Scripting Tutorials

Any user familiar with GEDitCOM II's Internal Scripting language, AppleScript, or Python can write their own scripts, package them in an "Extension," and thereby add new features to GEDitCOM II and GEDitCOM. Besides writing your own extensions, you can check the Extensions page for ready-made extensions you can download and use immediately in both GEDitCOM II and GEDitCOM.

Getting Started

Writing scripts is a computer programming task that requires an ability to program in GEDitCOM II's Internal Scripting language, AppleScript, or Python. If you have programmed before, but not with these languages, it should not be hard to get started. The basic structures of these languages are simple. It takes a little more effort, however, to understand the finer points of each one.

The recommended language is GEDitCOM II's Internal Scripting language. Internal Scripts run about 20 times faster than other languages and do not have to rely on Apple continuing to support use of other languages. If you want your extension to work in both GEDitCOM II and in GEDitCOM, you must use either Internal Scripting or AppleScripting. If you only need to use GEDitCOM II, Python is a third option. To simplify some scripting tasks, GEDitCOM II and GEDitCOM comes with both Internal Scripting and Python modules that can be called by scripts. These modules are documented in the GEDitCOM Editor help.

Here are some references for using Internal Scripting, AppleScript, or Python:

• All documentation for learning and writing internal scripts can be found in the GEDitCOM Editor Documentation. The key sections of the help for using Internal Scripts are:
  1. GENerel Reference: definition of Internal Scriptin language.
  2. Writing Internal Scripts Using GENerel: example of writing Internal Scripts.
  3. Writing Extensions for GEDitCOM: how to wrtie scripts that work in both GEDitCOM II and GEDitCOM.
• Python Language Documentation - the official Python web site's documentation page with tutorials and more.
• AppleScript Language Guide - Apple's developer documentation on the AppleScript language. It is a good reference but is not very good for learning AppleScript.
• "AppleScript: The Comprehensive Guide to Scripting and Automation on Mac OS X," Hanaan Rosenthal, Apress; 2nd Rev edition (September 25, 2006). (See it on Amazon.com).
• "AppleScript: The Definitive Guide: Scripting and Automating Your Mac," Matt Neuberg, O'Reilly Media, Inc.; 2 edition (January 1, 2006). This book explains many of the complexities of AppleScript that are not described elsewhere (See it on Amazon.com).

Finally, these tutorials are written for GEDitCOM II users because that application provides the easiest path to developing extensions. GEDitCOM users can still edit extensions or write their own extensions with the following steps:

1. Download GEditCOM Editor
2. See revised work flow in GEDitCOM Editor help to learn how to edit and test extensions or browser styles while using GEDitCOM. The revised methods are needed for any steps listed in these tutorials that only work in GEDitCOM II.

Working on Extensions and Scripts

An "Extension" contains one or more Internal Scripts, AppleScripts, and Python scripts, some key "Properties," and documentation files. Extensions are created and edited using the GEDitCOM Editor application. Internal Scripts and Python scripts will be in the "Scripts" section and can be edited in GEDitCOM Editor. AppleScripts in the extension will be listed in the "other files" section in the extension "Properties." Double click any AppleScript to open it for editing in Apple's "Script Editor" that comes in MacOS.

When an extension is ready, it can be installed in GEDitCOM II using the "Install Extensions..." menu command. To modify an installed extension, reopen it in GEDitCOM Editor. While using GEDitCOM II, you can reopen an extension in GEDitCOM Editor by selecting select it from the Extensions menu while holding down the option key. Note that GEDitCOM users need a revised work flow for testing extensions.

Scripting Dictionary

All scriptable applications include a "Dictionary" that defines the scriptable objects in the application and available scripting commands.

• AppleScript and Python: These languages both use the dictionary you can view in Apple's "Script Editor" by choosing its "Open Dictionary..."" menu command and selecting GEDitCOM II from the list of dictionaries. These standard dictionaries are notoriously too brief. To get more information, you should also refer to the "Writing Extensions" section of the GEDitCOM Editor help information. That help gives more detail, especially on supported commands and on how to translate AppleScript terms for Python scripts.
• Internal Scripts: The dictionary for this language (which is similar for the one for AppleScripts and Python) is in the Dictionary of Internal Scripting Objects topic in The GEDitCOM Editor help information. The GEDitCOM Editor help on supported commands also explains how to translate AppleScripting commands into Internal Scripting commands and defines many new commands only available for Internal Scripts.

Tutorials Index

The following are the scripting tutorials. These tutorials assume you a familiar with the chosen scripting language and are familiar with scripting "Dictionaries".

Creating a Custom Report

One great use of extensions is to design your own custom genealogy reports. This tutorial shows how to create the same simple report using Internal Scripting, AppleScripting, or Python scripting.

Customizing the "Create Web Site" Script (Internal Scripting)

GEDitCOM II and GEDitCOM are provided with an extension for creating a web site from your genealogy file. This tutorial explains some options you have for editing that etension to customize the type of web site that gets created.

Running Lifelines Programs

This tutorial explains how to get started converted Lifelines programs into scripts for GEDitCOM II and GEDitCOM.

GEDitCOM II Scripting Module (Internal Scripting)

GEDitCOM II and GEDitCOM come with two (or more) Internal Scripting modules to make it easier to write scripts. The documentation for all the methods in these module can be found in the GEDitCOM Editor help.

GEDitCOM II Scripting Module (Python)

GEDitCOM II comes with a GEDitCOMII.py module to make it easier to script GEDitCOM II using Python. The documentation for all the methods in this module can be found in the GEDitCOM Editor help.

Scripting Utility Subroutines (AppleScript)

This section describe a series of utility subroutines for AppleScripts. When writing your own scripts, you can copy and paste them to add common utility functions to your scripts..