Getting Started Tutorial
Before starting this development tutorial, make sure that you have PhpGedView installed and running and that you have a way to edit PHP files.
This tutorial also assumes that you are familiar with PHP and are comfortable working with it.
Contents
File Structure
As a general rule, all pages which can be navigated to in a browser should be located in the root PhpGedView directory. Other directories contain function libraries or other supporting files.
Basic Example
Let's start by creating a basic example page that will give us the essential elements that are necessary for working on PhpGedView.
PhpGedView Environment
One of the first things you should do is load up the PhpGedView environment. The PhpGedView environment includes all of the functions, classes, and configuration settings for developing a page in PhpGedView. To load up the environment all you need to do is require the config.php file.
require_once('config.php');
Including the config file starts a chain reaction which loads up several other files:
- config.php loads includes/session.php
- session.php loads includes/functions.php
- session.php loads includes/functions_db.php
- session.php loads includes/functions_print.php
- session.php loads the index/gedcoms.php file which has all of the GEDCOMS defined
- session.php loads the specified GEDCOM's configuration and privacy files.
- session.php loads language files
- session.php loads the theme settings
- other files such as functions_date and functions_mediadb will also be loaded if configuration settings require the funtionality in them
With the environment loaded you can easily get the headers and footers which include the menus, favorites, and other links generally listed at the top of the page. To load the header, you use the print_header function. There is also a corresponding print_footer function. These functions are declared in the functions_print.php file and they include header and footer files from the themes to generate the basic PhpGedView page layout.
The follow code shows a basic page which loads up the environment, prints the header, does some basic HTML, and then prints the footer.
<?php
require_once('config.php');
print_header('My Page Title');
//-- do my stuff here
print_footer();
?>
Accessing Data
The simplest way to access data is through the object data model as it provides convenience when working with the data and automatically applies privacy rules. You can access information about a person through the Person object defined in the includes/person_class.php file. The constructor for the object takes a GEDCOM INDI record, but the easiest way to get a reference to a Person object is through the Person::getInstance() static singleton method. This method allows for objects to be cached and reused throughout the application. The following code shows an example of how to obtain a person object:
include_once('includes/person_class.php');
$person = Person::getInstance('I1');
The Person object has many convenience methods for working with the data. The next example shows a full page that displays a person's name and birth information:
<?php
require_once('config.php');
include_once('includes/person_class.php');
print_header('My Page Title');
$person = Person::getInstance('I1');
print '<h2>'.$person->getFullName()."</h2>\n";
print $factarray['BIRT'].': '.$person->getBirthDate()->Display().' '.$person->getBirthPlace()."<br />\n";
print_footer();
?>
GEDCOM Data
All GEDCOM data should be stored in the UTF-8 character encoding. Because data is entered by users, even though it is encoded correctly in may render incorrectly and there are times when some cleanup work needs to be done. So the general rule is that anything printed to the page from GEDCOM data should be run through the PrintReady() function. Among other things, the PrintReady() function ensures that the data is prepared to be printed for that particular language. So continuing our example again, the final code for this example would look like this:
<?php
require_once('config.php');
include_once('includes/person_class.php');
print_header($pgv_lang['individual_title']);
$person = Person::getInstance('I1');
print '<h2>'.$person->getFullName()."</h2>\n";
print $factarray['BIRT'].': '.$person->getBirthDate()->Display();
print ' '.PrintReady($person->getBirthPlace())."<br />\n";
print_footer();
?>
Walking the Tree
From the person object we can also walk the tree by referencing his/her parents and children. People are linked together through Family objects. The Family class is defined in the 'includes/family_class.php' file.
The core methods of the family class are: getHusband() getWife() getChilren()
Parents
To reference a person's parents we first need to get a reference to a Family object where that person is a child. Due to adoption and other similar circumstances a person may have more than one family where they were a child. The getChildFamilies() method of the Person object will return an array of the families where this person is a child.
Let's add the person's parents to our example code:
<?php
require_once('config.php');
include_once('includes/person_class.php');
print_header($pgv_lang['individual_title']);
$person = Person::getInstance('I1');
print '<h2>'.$person->getFullName()."</h2>\n";
print $factarray['BIRT'].': '.$person->getBirthDate()->Display();
print ' '.PrintReady($person->getBirthPlace())."<br />\n";
print '<h3>'.$pgv_lang['parents']."</h3>\n";
$fams = $person->getChildFamilies();
foreach($fams as $famid=>$family) {
$father = $family->getHusband();
if (!is_null($father)) print PrintReady($father->getFullName())." + ";
$mother = $family->getWife();
if (!is_null($mother)) print PrintReady($mother->getFullName());
}
print_footer();
?>
Children
To reference a person's children we first need to get a reference to a Family object where that person is a spouse. Due to multiple marriages and other similar circumstances a person may have more than one family where they were a spouse. The getSpouseFamilies() method of the Person object will return an array of the families where this person is a spouse.
Now let's add the person's children to our example code:
<?php
require_once('config.php');
include_once('includes/person_class.php');
print_header($pgv_lang['individual_title']);
//-- personal details
$person = Person::getInstance('I1');
print '<h2>'.$person->getFullName()."</h2>\n";
print $factarray['BIRT'].': '.$person->getBirthDate()->Display();
print ' '.PrintReady($person->getBirthPlace())."<br />\n";
//-- parents
print '<h3>'.$pgv_lang['parents']."</h3>\n";
$fams = $person->getChildFamilies();
foreach($fams as $famid=>$family) {
$father = $family->getHusband();
if (!is_null($father)) print PrintReady($father->getFullName())." + ";
$mother = $family->getWife();
if (!is_null($mother)) print PrintReady($mother->getFullName());
print "<br />\n";
}
//-- children
print '<h3>'.$pgv_lang['children']."</h3>\n";
$fams = $person->getSpouseFamilies();
foreach($fams as $famid=>$family) {
$children= $family->getChildren();
foreach($children as $childid=>$child) {
if (!is_null($child)) print PrintReady($child->getFullName())."<br />\n";
}
}
print_footer();
?>
Working with raw GEDCOM
The Person, Family, and other objects are the preferred way to work with the genealogy data. These objects provide automatic caching, privacy filters, and remote linking. But if you want you can work with the raw GEDCOM data. (You will find that many of the existing pages use the raw GEDCOM APIs because those pages were written before the object oriented API existed.)
Obtaining GEDCOM records
The GEDCOM records are stored in the DB, but you don't have to write the SQL queries yourself to obtain the records. To get a person record you can use the function find_person_record() or the more generic find_gedcom_record(). There are similar find* functions for families, sources, media, and repositories.
Once you have a raw GEDCOM record you can obtain any data from it using the get_gedcom_value() function. The following example shows how you would get the birthdate for person I1.
<?php
require_once('config.php');
$indirec = find_person_record('I1');
$birthdate = get_gedcom_value('BIRT:DATE', 1, $indirec);
print get_changed_date($birthdate);
?>
The first parameter is a colon : separated list of GEDCOM tags in the GEDCOM hierarchy. So in this example BIRT:DATE references the first DATE record under the first BIRT record. The second parameter is the level of the first GEDCOM tag, 1 in this case. The third parameter is the raw GEDCOM record you want to search in.
When working with the raw GEDCOM data, none of it will have been privatized so you must check for privacy before displaying the data. Refer to the functions in the 'includes/functions_privacy.php' file for the privacy function APIs.
