GEPS 013: Gramps Webapp

From Gramps
Revision as of 00:35, 15 October 2009 by Dsblank (talk | contribs) (Getting Started with Gramps in Django)
Jump to: navigation, search

Many Gramps users would like to collaborate or share their genealogy data on the web. This GEP describes a webapp, a web-based application that runs in your browser, and requires a server.


The main focus of a Gramps-based webapp is collaboration. The Gramps webapp will allow users to easily move their genealogy data to the web to be seen, and edited with proper login and permissions, in a live, collaborative environment.

Here is a small list of goals:

  1. Create a fullscale GRAMPS web framework
  2. Allow multiple users via the standard web browser
    1. Users will log in and have various levels of permissions
  3. Build on GRAMPS codebase and wealth of resources
    1. Reports
    2. Tools
    3. Visualizations
    4. Date and calendar functions
    5. Translations
    6. Manual and documentation
  4. Use standards and well-known, well-tested frameworks where possible
    1. WSGI protocol for running code
    2. Django framework
    3. Underlying powerful database engines


1. Aren't there already many fine, web-based genealogy programs? Why don't you just use one of those? Aren't you re-inventing the wheel?

There are indeed many fine, web-based genealogy programs, and some are even free software/open source. However, there are a few good reasons to develop a Gramps-based webapp:

  1. Gramps has hundreds of thousands of lines of code, some of which could be re-used directly in a webapp. For example, the reports could be run and downloaded directly from the webapp.
  2. Gramps has a very well-defined set of tables and relationships that could be re-implemented for on-line use.
  3. Users have grown to appreciate the design of Gramps, and we want to continue to build on this design.
  4. Many users want to collaborate. Currently, they would either have to move their data in and out of Gramps, or give up Gramps completely.
  5. We want to keep the developers and users that we have, and so not splinter our groups. By linking

2. Why do you need a web framework like Django? Can't you just use the same Python code, and same database that Gramps already uses?

We can't use the same database (what is called a "backend") directly. Currently Gramps uses BSDDB, and it is not configured for use in a multiuser, client/server environment. But even if we could use the same backend, we would still want some type of web development framework. Django is one of the best in any language, and it just happens to be in Python.

3. How easy will this be for me to use on my website?

We have designed it to be as easy as it can be, given that we are using Python. Many web sites allow Python programs, and Django allows many different variations in running. We picked the protocol with the most availability (WSGI). Don't worry if you haven't heard of it. Your webserver can probably run it.

4. When is this going to be available?

We are hoping to have a fully functioning webapp ready for testing December 2009.

5. How can I help?

You can start by reading the rest of this page and sending ideas and comments to the Gramps-developers mailing list, and running the code if you can.


The Gramps webapp is written in Django. Django is a sophisticated, modern web development framework. Django is written in Python, albeit in a very different style from Gramps. However, part of the motivation of using Django is that it breaks up web development into very clearly defined parts following the Model-View-Controller paradigm. Two of these parts require no special programming knowledge, and thus will allow more people to be able to possibly customize and participate in the Gramps project.

The Gramps webapp (and Django in general) is broken into three well-defined parts:

  1. models/views
  2. templates
  3. CSS (Cascading Style Sheets)

The models define the tables and relationships, but this is done in Python (not SQL). The models also define the API to read/writing/editing the data. The views are also written in Python, and are closely tied to the models. The templates are written in HTML and a template language that is very easy for non-programmers to use and understand. Finally, CSS is just Cascading Style Sheets, where all of the graphical definitions are made. The webapp uses pre-existing CSS created for the "Narrated Web" report of Gramps which was used for created static web pages. Let's take a look at specific examples of each of these parts.


Here is the model that defines the Person table from src/gen/web/grampsdb/

class Person(PrimaryObject):
    gender_type = models.ForeignKey('GenderType')
    families = models.ManyToManyField('Family', blank=True, null=True)
    parent_families = models.ManyToManyField('Family', 
                                             blank=True, null=True)
    references = generic.GenericRelation('PersonRef', related_name="refs",

Here, you can see that Person only has 4 parts: gender_type, families, parent_families, and references. There are are properties, but they are defined in the PrimaryObject class which is shared with other tables. Here is PrimaryObject:

class PrimaryObject(models.Model):
    class Meta: abstract = True
    id = models.AutoField(primary_key=True)
    handle = models.CharField(max_length=19, unique=True)
    gramps_id =  models.CharField('gramps id', max_length=25, blank=True)
    last_saved = models.DateTimeField('last changed', auto_now=True) 
    last_changed = models.DateTimeField('last changed', null=True,
                                        blank=True) # user edits
    private = models.BooleanField('private')
    marker_type = models.ForeignKey('MarkerType')

The big difference here between typical Python programming is that the Person class defines the Person table, and the interface to it. Most Python code would probably have Person be an instance of a class, but Django uses classes to represent many things.

Here are three examples using the Person class:

   >>> self.Person.objects.all()
   [<Person>, <Person>, ...]
   >>> self.Person.get(id=1)
   >>> self.Person.get(handle='gh71234dhf3746347734')

The first retrieves all of the rows for the Person table; the second retrieves just the one record that has the unique, primary key 1, and the third retrieves the single record that has the unique handle of 'gh71234dhf3746347734'.

You can also use the Person interface to select a subset of people:

   >>> self.Person.objects.filter(gender_type=1)
   [<Person>, <Person>, ...]


Templates are used to describe what to display. Here is a template from src/data/templates/main_page.html:

{% extends "gramps-base.html" %}

{% block title %}GRAMPS Connect - main page {% endblock %}
{% block heading %}GRAMPS - main page {% endblock %}

{% block content %} 

<p id="description">Welcome to GRAMPS Connect, a new web-based collaboration tool.

{% if user.is_authenticated %}
  You are now logged in
  as <a href="/user/{{user.username}}">{{user.username}}</a>.
{% endif %}

<p id="description">
Database information:
{% for view in views %}
   <li><a href="/{{view|lower}}">{{view}}</a></li>
{% endfor %}
{% endblock %}


Finally, here is a screen shot of the main_page.html (above) showing some initial testing of Gramps in Django using the Mainz CSS from the NarrWeb report:

Gramps in django.gif

Getting Started with Gramps in Django

A prototype of a GRAMPS Django webapp is in branches/geps/gep-013-server. To run it, do the following:

  1. Download Django. You'll need version 1.1
    1. On yum-based systems, try "yum install Django"
    2. Other systems: get the sources from
  2. Checkout the branches/geps/gep-013-server from SVN
    1. cd gramps
    2. svn co
    3. This will create a subdirectory here called gep-013-server
  3. cd gep-013-server/src/gen/web/
  4. Edit
    1. Edit the path to the Sqlite DB (or use another if you wish, including Oracle, MySQL, Postgresql, etc.)
  5. Create the tables, and fill with core data:
    1. make
  6. Run the test webserver:
    1. make run
  7. Point your webbrowser to:

At this point, you can now export your Gramps data to Django (and back). In another terminal window:

  1. Build this version of Gramps:
    1. cd gep-013-server/
    2. ./
  2. Start up this version of Gramps
    1. python src/
  3. Run the Django Exporter
    1. Select Family Tree -> Export
    2. Select Django

This will export your regular Gramps BSDDB data into whatever Django database you have defined in above. You now have your data in a SQL database, and can access it via the webbrowser.

To import data back from Django's SQL table back into Gramps from the website:

  1. Create a file named "import.django" somewhere (needs to end in ".django").
  2. Start up this version of Gramps
    1. python src/
  3. Run the Django Importer
    1. Select Family Tree -> Import
    2. Select the "import.django" (from above) as the file to import

For more detailed, but perhaps out of date, see:

For more on Django, try their tutorial:

Webapp Files

There are two subdirectories and two files of interest to the Gramps webapp:

  1. - HTML templates
  2. - Webapp main directory
    1. - library interface
    2. - gramps table models
    3. - gramps views model
  3. - Exporter
  4. - Importer


Phase 1: get the basic Django skeleton in place, including the core HTML templates, models, views, and templatetags. Should be able to browse and edit the 8 primary tables. This is largely independent of the current gramps codebase.

Phase 2: Be able to run all of the reports directly from the web. Be able to import/export from the web. This will largely depend on a gen/db/dbdjango library. Get translations in place.

Phase 3: Refine and polish.


Concurrent Edits

Concurrent access for write and read imply several problems when people by accident change the same objects at the same time. GRAMPS itself has an elaborate signal handling for cases when dialogs are open with no longer current information. In a web environment, this becomes more difficult however. This is not built into Django.

For discussion on this issue in Django, see:

Example GMS Web Sites

Genealogy Management Systems on the web:

Note here: the intro page is a collection of gadgets/controls, which then link into the real data.