Difference between revisions of "GEPS 013: Gramps Webapp"

From Gramps
Jump to: navigation, search
(Getting Started with Gramps in Django)
Line 82: Line 82:
 
A prototype of a GRAMPS Django webapp is in branches/geps/gep-013-server. To run it, do the following:
 
A prototype of a GRAMPS Django webapp is in branches/geps/gep-013-server. To run it, do the following:
  
# Download Django. I'm running version 1.0.3
+
# Download Django. You'll need version 1.1
 +
## On yum-based systems, try "yum install Django"
 
# Checkout the branches/geps/gep-013-server from SVN
 
# Checkout the branches/geps/gep-013-server from SVN
 +
## cd gramps
 +
## svn co https://gramps.svn.sourceforge.net/svnroot/gramps/branches/geps/gep-013-server
 +
## This will create a subdirectory here called ''gep-013-server''
 
# cd gep-013-server/src/gen/web/
 
# cd gep-013-server/src/gen/web/
 
# Edit settings.py
 
# Edit settings.py

Revision as of 12:13, 14 October 2009

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.

Motivation

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 possibly edited, in a 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. Visualization
  4. Use standards and well-known, well-tested frameworks where possible
    1. WSGI protocol for running code
    2. Django framework

Overview

The Gramps webapp is written in Django. Django is a sophisticated, modern web development framework. It is written in Python, albeit in a very different style from Gramps. However, part of the motivation of Django is that it breaks up web development into very clearly defined parts following the Model-View-Controller paradigm.

The webapp uses pre-existing CSS created for the "Narrated Web" report.

The Gramps webapp (and Django in general) is broken into three well-defined parts: models/views, templates, and CSS. 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.

Let's take a look at specific examples of each of these.

Here is the model that defines Person from src/gen/web/grampsdb/models.py:

class Person(PrimaryObject):
    """
    The model for the person object
    """
    gender_type = models.ForeignKey('GenderType')
    families = models.ManyToManyField('Family', blank=True, null=True)
    parent_families = models.ManyToManyField('Family', 
                                             related_name="parent_families",
                                             blank=True, null=True)
    references = generic.GenericRelation('PersonRef', related_name="refs",
                                         content_type_field="object_type",
                                         object_id_field="object_id")

Here, you can see that Person only has 4 parts: gender_type, families, parent_families, and references. There are are properties, but they are shared with other PrimaryObjects.

The big difference here 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 is a template from src/data/templates/person_list.html:

{% load my_tags %}
<table cellspacing="0">
<thead>
  <tr>
{% table_header headers %}
  </tr>
</thead>
<tbody>
  {% for person in persons.object_list %}<tr class="{% cycle odd,even %}">
    <td>{{ person.gender|escape }}</td>
    <td>{{ person.first_name|escape }}</td>
    <td>{{ person.last_name|escape }}</td>
    <td>{{ person.email|escape }}</td>
  </tr>
  {% endfor %}
</tbody>
</table>
{% paginator %}

Templates define what to display.

Finally, here is a screen shot from the main page of Gramps in Django using the 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. Checkout the branches/geps/gep-013-server from SVN
    1. cd gramps
    2. svn co https://gramps.svn.sourceforge.net/svnroot/gramps/branches/geps/gep-013-server
    3. This will create a subdirectory here called gep-013-server
  3. cd gep-013-server/src/gen/web/
  4. Edit settings.py
    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:
    1. http://127.0.0.1:8000/

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. ./autogen.sh
  2. Start up this version of Gramps
    1. python src/gramps.py
  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 settings.py 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/gramps.py
  3. Run the Django Importer
    1. Select Family Tree -> Import
    2. Select the "import.django" (from above) as the file to import

For more on Django, try their tutorial:

Issues

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.