Main Help → Writing Extensions → GEDitCOM Extensions

Writing Extensions for GEDitCOM

GEDitCOM is a separate genealogy application available on the Mac app store (hopefully coming soon). GEDitCOM has a lot of the features of GEDitCOM II, but it had to remove various advanced features due to security rules imposed on Mac App Store (MAS) apps.

The extensiblity of GEDitCOM II allowing browser styles and extensions is one power feature that has some limits in GEDitCOM. First, MAS apps are not able to launch Python scripts so any extensions written in Python cannot run in GEDitCOM. MAS apps can only use Internal Scripting or AppleScripting. When using AppleScripting, any feature that "tells" the script to use another application will also fail. Browser styles use internally interpreted commands and therefore mostly work in GEDitCOM.

This section explains how you can write browser styles and extensions that run in both GEDitCOM II and GEDitCOM:

Browser Styles in GEDitCOM

Almost all options used when writing browser styles work in both GEDitCOM and GEDitCOM II. Only a few things are needed to make styles that work in both applications:

• Any scripts included within a browser style (such as those added using ScriptLink property for a LinkButton) must use scripts that are compatible with GEDitCOM. Details on writing compatible scripts are explained below. Most importantly, the scripts cannot be in Python; they must be either Internal Scripts or AppleScripts.
• If a browser style needs to include a feature that only works in GEDitCOM II, it can still be used in GEDitCOM, but it is best to remove that feature. By checking the read-only variable #appName$, which will be "GEDitCOM II" or "GEDitCOM" depending on which application is running, you can write scripts to include the proper feature depending on application.
• The #imageType$ read-only variable will return "nopermission" in GEDitCOM if it is looking for a multimedia file, but the user does not have permission to open that file. Denial of permission is more common in MAS apps, then in non-MAS apps allowed full disk access.

Extensions in GEDitCOM

You can write scripts to package in an extension for both GEDitCOM II and GEDitCOM. Scripts that will run in GEDitCOM can only be Internal Scripts or AppleScripts. Virtually all options for Internal Scripts are allowed. If testing reveals something that does not work in GEDitCOM or you just want to change behavior of the script depending on application, you can use the following template:

if #appName$ = "GEDitCOM II"
  -- commends for GEDitCOM_II only
else
  -- commands for GEDitCOM only
endif

This template simply makes use of the #appName$ read-only variable.

If you choose to write AppleScripts that work in GEDitCOM, they are subject to the following considerations:

• AppleScripts use messaging blocks to send commands to applications such as:

  tell application "GEDitCOM II"
     (scripting commands)
  end tell

  To write scripts that work in both applications, all such blocks should "tell" only application "GEDitCOM II" and must be saved as plain-text files (with extension .applescript). When GEDitCOM runs such scripts, it replaces all "GEDitCOM II" in the text with "GEDitCOM" before compiling and running. In other words, the script will target the correct application.
      Note: You can use compiled scripts (with extension .scpt) in an extension, but would then need separate scripts for use in GEDitCOM II or GEDitCOM otherwise the "tell" blocks might target the wrong application. It is better to convert the script to a plain-text script (with extension .applescript) and work on one copy of the script.
• AppleScripts to run in GEDitCOM can only use "tell" blocks for GEDitCOM II. Any attempt to send a message to another application (even the MacOS "Finder") will fail. Denial of inter-application communication is a limitation imposed on MAS apps. AppleScripts to run in GEDitCOM II are allowed to target other applications.
• Because AppleScripts in GEDitCOM cannot use commands that target the "Finder,"" a few commands were added to GEDitCOM II scripting to replace ones that used to be done by the "Finder" (see the commands uniqueFile, makeFolder, and openURLorFile for examples). Other replacement commands are available and more may be added in the future as needed.
• Sometimes a script might like to know at run time which application is running. An AppleScripting block for this task is tricky, but this template works:

  property appName : "GEDitCOM II"
  if appName is "GEDitCOM" then
    -- commends for GEDitCOM only
  else
    -- commands for GEDitCOM_II only
  end if
  

  You create a property set to string "GEDitCOM II". When running in GEDitCOM, the step that replaces "GEDitCOM II" with "GEDitCOM" in tell blocks will also change the appName property to "GEDitCOM". The tricky part is that you cannot check using if appName is "GEDitCOM II" in your script, because that "GEDitCOM II" would also change to "GEDitCOM" causing that condition to be true in both applications. Comparing to "GEDitCOM", however, works correctly. If you only need commands for GEDitCOM II, the following template works and avoids an empty block for GEDitCOM:

  property appName : "GEDitCOM II"
  if last word of appName is "II" then
    -- commands for GEDitCOM_II only
  end if
  

• When packaging scripts in an extensions, you must list scripts that can run in GEDitCOM in the "menu choices SD" section. Any given extension can contain scripts that work in GEDitCOM and scripts that do not work. Be sure to only list scripts that work in GEDitCOM within the "menu choices SD" section. If needed, you can even package two entirely different scripts - one to run when installed in GEDitCOM II and one to run when installed in GEDitCOM.

Documentation for both GEDitCOM and GEDitCOM II

When writing browser styles and extensions that run in both GEDitCOM II and GEDitCOM, it is good practice for the documentation to be appropriate for each application. Here are the steps for application-specific documentation:

1. The <head> element of the help file should include the line

   <link rel="stylesheet" type="text/css" href="helpType.css">
   

2. The helpType.css cascading style sheet is now a required file in browser styles and extensions. It is automatically added if one is opened that does not have that file (note that automatically adding this file might trigger a warning the first time you save changes. You can ignore the warning and click "Save"). This file is just a place holder; it should not be edited and it cannot be deleted. When a user views documentation is GEDitCOM II or GEDitCOM, the helpType.css file is replaced by an application-specific version. Any changes you make to that file in GEDitCOM Editor will not be used.
3. Whenever documentation refer's to the user's application by name, replace the name with the following html code:

   <span class="appname"></span>
   

4. Any part of the documentation that applies only to GEDitCOM II users should be enclosed in the following html block:

   <span class="IIdocs">Anything inserted here before the closing element
   will be visible only when viewing documentation in "GEDitCOM II"
   </span>
   

5. Any part of the documentation that applies only to GEDitCOM users should be enclosed in the following html block:

   <span class="ASdocs">Anything inserted here before the closing element
   will be visible only when viewing documentation in "GEDitCOM"
   </span>
   

6. You can use the "Preview Help In → Browser" to test how the documentation will appear to GEDitCOM II users. Or, you can use the "Preview Help In → Browser for GEDitCOM" to see how it will appear to GEDitCOM users (if a preview triggers a warning that the file has been altered by another application, you can click either button).

Work Flow for GEDitCOM Development

GEDitCOM Editor works best when using GEDitCOM II to write browser styles and extensions. It can directly edit browser styles or extensions in the GEDitCOM II application support folders. When changes are made, they can be tested in GEDitCOM II using the "Save and Run" command (or using "Save" command and then using it in GEDitCOM II).

If you do not have GEDitCOM II, GEDitCOM Editor can also be used to write browser styles and extensions, but the work flow for the development process changes. A typical work flow when developing for GEDitCOM is:

1. Start by either creating a new browser style or extension or by downloading the one you want to change from geditcom.com and save in any convenient location. Open the new or downloaded file in GEDitCOM Editor
2. When you are ready to test some new edits, save the changes in GEDitCOM Editor. Next, switch to using GEDitCOM and choose the "Intall Extensions..." menu command. Pick the browser style or extension you just saved for the install (you can overwrite any previous version if asked).
3. In GEDitCOM, choose the newly-installed browser style or extension from the "Extensions" menu for testing. Note: you cannot test with the "Save and Run" command and you must reinstall every time you need to test changes made in GEDitCOM Editor.
4. If errors occur, return to GEDitCOM Editor, fix the mistakes, and go back to step #2.

Even if you have GEDitCOM II, the above work flow is the process needed to test that a browser style or extension also works in GEDitCOM (which means you would need to have both applications available for full testing).