Friend Me
 Follow Me
 Feed Me
a blog by ken pardue

Archive for the 'TreeFrog' Category

Creating a XULRunner 1.9 App on OS X

Tuesday, April 29th, 2008

I’ve just created my first simple XULRunner-based application.  In order to make creating the application work in OS X, a number of different steps have to be taken from the Windows version.  Unfortunately, there doesn’t seem to be a comprehensive guide for newbies to do so, so I created my own based on several resources.  Since much of what follows is direct quotes or slightly modified, I want to be sure to give credit where credit is due:

http://developer.mozilla.org/en/docs/Getting_started_with_XULRunner
http://groups.google.pt/group/mozilla.dev.tech.xul/browse_thread/thread/d8c0127036615492
http://rcrowley.org/2007/07/17/cross-platform-xpcom-a-howto/
http://developer.mozilla.org/en/docs/XULRunner:Deploying_XULRunner_1.8

Step 1: Install the XULRunner Framework

The first step is to download and install the XULRunner Framework.  XULRunner may be downloaded from here: http://developer.mozilla.org/en/docs/XULRunner.  On the Mac, just run the installer, which installs XULRunner as XUL.Framework in the /Library/Frameworks directory.

Step 2: Set up the Application Directory Structure

I created the root in a new /Users/{username}/Desktop/approotfolder folder, but you can create it wherever you like. Here is the subfolder structure:

../approotfolder
…./myapp
……/chrome
……../content
……….main.xul
……chrome.manifest
…./defaults
……/preferences
……..prefs.js
….application.ini

Notice that there are 4 files in the folder structure: application.ini, chrome.manifest, prefs.js, and main.xul.

Step 3: Set up the XUL Application Files

Application.ini

The application.ini file acts as the XULRunner entry point for your application. It specifies how your application intends to use the XULRunner platform as well as configure some information that XULRunner uses to run your application. Here is mine:

[App]
Vendor=Finkle
Name=Test App
Version=1.0
BuildID=20060101
Copyright=Copyright (c) 2006 Mark Finkle
ID=xulapp@starkravingfinkle.org

[Gecko]
MinVersion=1.8
MaxVersion=1.9.0.*

chrome.manifest

The chrome manifest file is used by XULRunner to define specific URIs which in turn are used to locate application resources. This will become clearer when we see how the “chrome://” URI is used. Application chrome can be in a single or a few JAR files or uncompressed as folders and files. I am using the uncompressed method for now. Here is my manifest:

content myapp file:content/

prefs.js

The prefs.js file tells XULRunner the name of the XUL file to use as the main window. Here is mine:
pref(“toolkit.defaultChromeURI”, “chrome://myapp/content/main.xul”);

XULRunner preferences include:
toolkit.defaultChromeURI
Specifies the default window to open when the application is launched.
toolkit.defaultChromeFeatures
Specifies the features passed to window.open() when the main application window is opened.
toolkit.singletonWindowType
Allows configuring the application to allow only one instance at a time.

This is described in further detail in XULRunner:Specifying Startup Chrome Window.

main.xul

Finally, we need to create a simple XUL window, which is described in the file main.xul. Nothing fancy here, just the minimum we need to make a window. No menus or anything:

<?xml version=”1.0″?>
<?xml-stylesheet href=”chrome://global/skin/” type=”text/css”?>

<window id=”main” title=”My App” width=”300″ height=”300″
xmlns=”http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul”>
<caption label=”Hello World”/>
</window>

Note: Make sure there is no extra whitespace at the beginning of the XML/XUL file

Step 4: Set up the OS X .app directory structure.

XULRunner for Mac is slightly more complicated because of strict requirements for GUI apps running in OS X. First, go download XULRunner and install the package. It will create itself deep within /Library/Frameworks (quite separate from the Windows version). In myapp, create a new directory called MacApp.app or something else ending in .app. Within this directory create one called Contents (capitalization is important), and within Contents create Frameworks and MacOS. Now create three symbolic links to complete the Mac directory structure:

ln -s /Library/Frameworks/XUL.framework MacApp.app/Contents/Frameworks/XUL.framework
ln -s ../../../myapp MacApp.app/Contents/MacOS/Resources
ln -s /Library/Frameworks/XUL.framework/Versions/Current/xulrunner MacApp.app/Contents/MacOS/xulrunner

If you would like to ship the application on a private install of XULRunner, you could always just copy the respective files into the XUL.framework and the MacOS/xulrunner directories.

Now create MacApp.app/Contents/Info.plist and dump this in, making sure to change things in ALL CAPS. I am almost certain this is not optimal as it repeats itself a lot. But it is functional.  Note: when using XULRunner 1.9, it doesn’t seem to matter what is in this file, or even that it exists.  XULRunner generates its own Info.plist file.

<?xml version=”1.0″ encoding=”UTF-8″?>
<!DOCTYPE plist PUBLIC “-//Apple Computer//DTD PLIST 1.0//EN” “http://www.apple.com/DTDs/PropertyList-1.0.dtd”>
<plist version=”1.0″>
<dict>
<key>CFBundleDevelopmentRegion</key>
<string>English</string>
<key>CFBundleExecutable</key>
<string>xulrunner</string>
<key>CFBundleGetInfoString</key>
<string>3.0</string>
<key>CFBundleIdentifier</key>
<string>YOUR_APP_ID</string>
<key>CFBundleInfoDictionaryVersion</key>
<string>YOUR_APP_VERSION</string>
<key>CFBundleName</key>
<string>YOUR_APP_NAME</string>
<key>CFBundlePackageType</key>
<string>APPL</string>
<key>CFBundleShortVersionString</key>
<string>YOUR_APP_VERSION</string>
<key>CFBundleSignature</key>
<string>YOUR_APP_ID</string>
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleURLName</key>
<string>YOUR_APP_NAME</string>
<key>CFBundleURLSchemes</key>
<array>
<string>chrome</string>
</array>
</dict>
</array>
<key>CFBundleVersion</key>
<string>YOUR_APP_VERSION</string>
</dict>
</plist>

Review Directory Structure:

As a review, here’s how our tree looks now:
/approotfolder
.. /myapp
…. /chrome
…. /content
…… main.xul
…. chrome.manifest
…. /defaults
…… /preferences
…….. prefs.js
…. application.ini
.. /MacApp.app
…. /Contents
…. /Frameworks
…… XUL.framework→/Library/Frameworks/XUL.framework
…. Info.plist
…. /MacOS
…… /xulrunner→/Library/Frameworks/XUL.framework/Versions/Current/xulrunner
…… /Resources→../../../myapp

Step 5: Run the Application

The moment of truth. We need to get XULRunner to launch the bare-bones application.  Before you can run a XULRunner application, you must install it using the –install-app xulrunner commandline flag. Installing the application creates an OS X application bundle:

/Library/Frameworks/XUL.framework/xulrunner-bin –install-app /<path>/<to>/myapp.zip

Once installed, you can run the application:

/Library/Frameworks/XUL.framework/xulrunner-bin “/Applications/Finkle/Test App.app/Contents/Resources/application.ini”

You should now see a window that looks something like this:

This application will output to Applications/Vendor Name/App Name (as specified in the application.ini).

Since XULRunner 1.9 seems to generate its own plist file (disregarding anything in the custom one), I’m not sure how to add application icons yet.  I’m sure there’s a way to specify this in the application.ini somehow, but since I’m brand new to XUL/XULRunner I can’t really speak to that.

Treefrog: User Interface, Part 2

Monday, April 28th, 2008

The Family Group Screen

The Family Group screen is, arguably, the most important screen in the entire application.  This screen is where virtually all of the data entry is done and where the user spends most of his/her time.  I’ll begin by analyzing the interfaces of some popular existing software.

Family Tree Maker is the leading (or at least the best marketed) genealogy software on Windows.  The family group screen on it is, ironically, the least intuitive.  It provides extremely basic data entry functions.  You can enter information for a husband, wife, and birth, death, and burial dates/places.  You can also enter children.

Reunion 9 is the Family Tree Maker equivalent on the Mac.  Recently it has been rewritten as a Universal Binary application and has seen many improvements.  The Family Group screen in Reunion is more feature rich, allowing the user to enter and visualize more information.

GRAMPS is the open source Linux genealogy program, and the one with the most confusing and least useful interface.  There really isn’t a “family group” screen per se, but an individual screen that brings up information related to one individual.  There are advantages to this type of layout, however.  It features a tabbed interface that allows the user to quickly navigate information for the selected individual and see which areas have content.

So, what I’ve done is create a few quick mockups of how the interface might work.  These are quick Photoshop brainstorms, so a lot of the details are left to be worked out.  My main goal was to provide an interface to make sure that the user knows where there is more information to be had on an individual.  In the process, I also want to be able to show all spouses for the selected individuals and a way visualize all children related to them.  So, if Jane Doe married three times, all of her children should be displayed with all husbands (with the option of turning this off, perhaps).  I think this can be accomplished through some sort of color coding.

The first concept builds on the Reunion idea of displaying a father on the left side, a mother on the right, and some facts and children below.  This idea would more appropriately take advantage of increasingly-popular widescreen monitors and allow more space vertically to display more information.  Spouses are displayed with color codes and may be checked on or off.  This also allows some room for things like timelines or event summaries to be displayed.  Unfortunately, this takes an individual approach than a family group approach.  Events displayed here would display only for the selected individual.  Clicking on one of the spouses names would shift the darker blue background to the spouse side and focus on his/her information.

The second concept takes a horizontal approach, displayed the husband above the wife, tabs to the right of each to get to the fathers and mothers of the individuals, and spouse information at the bottom of the person’s box.  A solid colored background behind the spouse name indicates which spouse is currently active, where the active spouse’s information is also displayed.  Checkboxes could be added to show/not show children for these individuals.  There is obviously less vertical space to play with in this model.

Perhaps the best option is a hybrid between the two, since there tends to be a lot of horizontal space left over in the second approach, but I’m not sure about how much information could be displayed for both spouses.  More ideas to come later, comments and critiques very much appreciated.

Treefrog: User Interface, Part 1

Monday, April 28th, 2008

I’m going to do generally the worst thing that developers do: I’m thinking through the user interface of Treefrog first, before necessarily planning out the data or program structure.  I’m aware of the reasons for not doing this, but there is one important reason to do it: to keep me focused.  My hope is that with a light at the end of the proverbial tunnel I’ll be able to keep a focus on what I’m doing and why I’m doing it.

Main Goals

There are two main goals of the user interface for Treefrog.  First is to take the best ideas of some popular genealogy programs and, without sacrificing function or usability, create a consistent user interface across platforms.  The second goal is to perhaps improve on the user interface to provide a better way to visualize data.  Genealogy software is generally lacking in this area, and it’s easy to see why.  Once you start factoring in complex family relationships (multiple spouses, children with reference to two different brothers as their father, adopted children, etc.), the challenges become clear.  However, I feel that the important goal first is to at least fill the gaps across platforms.

Navigating the Interface

My initial thought was to keep all of the navigation top-centric with a series of icons across the top to redraw the main window.  That is, switching between “Family Group” view, “Reports” view, “Multimedia” view, and “Tree” view, etc.  I started looking at arguably some of the best user interfaces designed, Apple’s, and found that there were very few cases where the navigation at the top of the screen actually redrew the main window.  As I looked to PC programs, I also found this to be the case.  Most of the options to redraw the main window were located in the left side of the screen, with the top of the screen being reserved for functions that enhanced or provided additional functionality to the main window.

This is consistent across all of the iLife apps.   In iTunes, the top navigation is reserved to indicate track progress and to provide different viewing options.  Down the left navigation you see different categories that are used to redraw the interface.  In iPhoto, there isn’t even a top navigation bar, instead leaving the different photo events, albums, and views to the left side, and providing a menu at the bottom of the main window that is context-sensitive to the photo/album you’re viewing.

So how does this apply to Treefrog?  Options that will redraw the main window include a Research Center/Summary page, Index (list of all individuals in the family file), Family Group, Reports, Multimedia, Maps, and Sources.  Functions that might enhance the views include an Index of individuals in the family file, a Search box, Sources, and Multimedia, all of which could be used to update the focus of the main window.  The latter two initially seem redundant, but my vision is that the left navigation will bring up a center where you can manage, tag, organize, etc. the sources and multimedia, whereas the top navigation source and multimedia links will open up drawers that you can use to drag sources and multimedia items onto persons and events.

With so little going into the top navigation, it may be a better idea to put a very small top navigation bar, or perhaps none at all and make the drawers sensitive to what’s in the main window.  That said, here is a first brainstorm in Photoshop (note: this is an extremely quickly done mockup, I know it’s quite amateurish).  Obiously this is very Mac, but there’s much room for Linux/Ubuntu and Windows native look and feel here.

Introducing Treefrog

Friday, April 25th, 2008

Treefrog, that is, the name that a friend has coined for my project “Genzilla,” a Mozilla/XUL-based, cross-platform genealogy application, is starting to take some shape.  I’m still very early in the would-be development of it and have a lot to learn about developing Real Applications (TM) before I make any progress, but at least I’m starting to define a goal.  Over the next several blog posts, I’m going to spend some time thinking through how this should work.

Desktop App or Web App?

The big question is whether or not to develop Treefrog as a standalone desktop application or as a web-application.  There are major benefits to developing it as a web application, beyond web applications being hip since everyone seems to be moving to the cloud computing/software as a service ideal these days.  And there are the obvious benefits in doing so: maintained control over upgrades and bug fixes, instantly visible by everyone on the domain; no installation or platform-specific glitches (other than browser JavaScript issues); easy ability to roll out the application to a variety of non-traditional platforms such as mobile devices (I could see an awesome iPhone app here); the ability to tap into social networking to enhance the collection and organization of data; perhaps most importantly, I already know how to develop web applications.  I’ve been doing that for a while.

We’re on the verge of ubiquitous Internet access.  Many phone carriers are shipping with unlimited data Internet plans these days, and I can foresee a day in the not-too-distant future where all laptops have carrier-independent cellular Internet connectivity built right in.  Unlike the days where you had to worry about offline access, we’ll be at a point where having a computer and having Internet access are synonyms.  Mozilla, like Google, is quick to promote the web as a platform for all things.  A Mozilla affiliate recently said (paraphrasing) that Mozilla isn’t really going to focus on XULRunner as a desktop app development platform and that it’s a much better idea to focus on promoting a healthy, open Internet with web applications. 

But on the desktop side, there are benefits as well.  First and foremost is that there really isn’t a good, quality genealogy program that works cross-platform.  Mac users have Reunion, Linux users have GRAMPS, and Windows users have Family Tree Maker, but there’s no good program intended to make a researcher’s genealogy portable across platforms.  It would be much easier to deal with privacy issues on the desktop rather than the web.  There are opportunities to take advantage of native platform look and feel, extensions to further manipulate the data, and the ability to work with large media files such as high-resolution photo and source document scans.  Let’s face it, many genealogists are older in age and may not be keen on the idea of using some Internet app to store all of their research.  Finally, a personal reason to do a desktop app is for the sheer challenge of it.  I’ve never done a desktop application and have always been interested in this arcane world.

Besides, Treefrog is such a trendy name for a Mozilla-based application!  It fits right in with Firefox, Thunderbird, Songbird, etc.  But, if the desktop truly does become obsolete in a few years as some predict I suppose that another benefit would be that, by choosing to develop on XULRunner, my application would be largely developed in the language of the web and should I decide to take it to the web or tie into the Mozilla Weave API’s in the future it wouldn’t be as difficult.

Launchpad Page: https://launchpad.net/treefrog