Genealogy Classes: Manage genealogy trees for a family

File: README-FIRST.txt (23/06/2011)

This is what I think useful to read before using these scripts and classes.
This documentation is still in progress. So, I'm not sure that all paragraphs
are in a correct order. I hope you can understand my rough english :o(


NOTA
----
I'm not an expert in genealogy neither in PHP. But these scripts
can be used to begin your family database on the web. And you can
complete the scripts with those you need.


EXAMPLE
-------
You can see and example in use of these scripts and classes at :
http://www.fauque.fr/demogen (fictitious people data).


AVAILABLE FILES
---------------
a) PHP Classes: The PHP classes (personne and gedcom) and some files to see the
   essential fonctions of these classes : list of people, card or family of a person.
   All necessary scripts are provided to build a real database with fictitious people.
   A geographic database of french used cities in that example is provided.

b) my own website: the rest of the used files to see all people of the database and
   produce a recapitulative PDF file, in brief all files I'm using on my own website.
   All necessary scripts are provided to build a real database with fictitious people.
   The geographic database of french cities is provided.


CITIES
------
Each city (even small) have an identifier called INSEE number (INSEE is a french acronym
standing for Institut National de la Statistique et des Etudes Economiques,
i.e. National Institute for Statistics and Economic Studies).

Several small cities near from each other can have the same postal code (zipcode)
because they are served by the same post office. A set of cities make a department and
several departments are administered by a region. There are 22 regions in France + 1 (overseas).
In the database, cities are indicated by their INSEE code (bcode, dcode, icode, ucode, ecode
-see dictionary data-). Their zipcode, department and region are deduced from the INSEE code.

PHP Classes is used to share scripts, not to keep a lot of data. So, the only geographic data
provided here are those which are used by the example scripts. Il you want the complete
french cities list I have (insee, zipcode, longitude, latitude of 35330 cities),
you have to download them from my website.

Of course, you can adapt your geographic data to your country.


DIRECTORIES
-----------
The documentation supposes that your website organization is like that :

 /--+ ................. The root directory of your web site
    |                ======= for your general PDF (genealogy and others) =======
    +-- font .......... directory, sub-directory, files for making PDF files *
    +-- lib ........... library directory (with at least tfpdf.php) *
    |                -------- for your genealogy -------------------------------
    +-- gen ........... Your genealogy root directory
    |   +-- bio ....... directory for later use (biography). Empty for the moment
    |   +-- img ....... directory for icons and graphic symbols
    |   +-- photos .... directory for people's pictures (158 x 200 px)
    |   +-- src ....... directory for scanned documents (birth, death, marriage)
    |                ===========================================================
    +-- your-other-directories 
    +-- etc...

* You can find these files and scripts (and others) at http://www.fpdf.org/

If it's not your organization, you have to modify the directories.

You can modify them in :

a) init.php
   - Setup in it your root genealogy directory
   - You have not to change the sub-directories if you keep the same organization (bio,img,photos,src)

b) famille.php (not useful nor provided for the demo version on phpclasses.org).
   NB: This script is used to build a PDF file of all people stored into your database
   - (real path for font directory) :
   Once you have uploaded the font directory and his content to your root website directory,
   go to the URL http://<your.website.tld>/font/realfontdir.php where <your.website.tld> is
   the URL of your root website directory and execute the displayed indications to setup
   the real path of the font directory in the famille.php file. >>> YOU NEED THAT <<<.
   - relative path for the tFPDF class in the library directory
   You can keep this definition as it if you have the above directories tree.

NB: It can be a good idea to protect your root genealogy directory with real data by a password
    using .htaccess and .htpasswd


LANGUAGE
--------
You can change the language in the 'init.php' file ($language='en' or $language='fr').
For the moment there are only two languages : French and English ('texts-fr.php' and 'texts-en.php')
To have your own language, translate the 'texts-en.php' file into your language and save it into
'texts-xx.php' where 'xx' is your Top Level Domain (ex: it=Italy, es=Spain, pt=Portugal, etc...)
The texts which are in the database aren't translated. So, if you have imported a gedcom file in which
an approximative birthdate have been written in french such as 'vers 1938', this text will not be
translated into 'about 1938', idem for 'Rupture' or 'Mariage' instead of 'Break-up' or 'Marriage'.
If you've declared a missing language ($language='it' and 'texts-it.php' is missing), english will be
applied. If there is no language texts in the directory, the script stops.


ALLOWED DATAS
-------------
a) Personal infos.
   Each person stored in the database has a number in the 'disp' field (what to DISPlay ?).
   This number is the sum of the allowed informations such as (for the moment) :
   Picture: ..................   1
   Mobile phone number: ......   2
   Email address: ............   4
   Fixed home phone number: ..   8
   Postal address: ...........  16
   Notes: ....................  32
   Sources: ..................  64
   Biography: ................ 128  (will be used later)
   Someone who as '5' in the 'disp' field will only have his picture and his email displayed (1+4)
   even his postal address and his phone number are also stored in the database.
   The default value for the 'disp' field is 1

b) Notes.
   Several notes can be stored for someone.
   If the number stored in the 'disp' field contains 32 (2^5), the notes for this one can be displayed.
   Each note have a field 'nallow' (Note ALLOWed) with either the value 0 (not allowed) or 1 (allowed).
   So, if all the notes for someone are set to 0 (nallow=0), no note for this person will be displayed
   even the field 'disp' contains 32.

c) Biography.
   The next version will allow or not (according to the disp field : 128 in it) to display a biography
   file (format .txt .doc or .pdf)



CLASSES AND FILES
-----------------
There are only two classes in this package :
- class.gedcom.php   : to produce a GEDCOM file from the database
- class.personne.php : to get informations about a person from the database

the 'init.php' file is important because
- all definitions are in it (even the tables names)
- it contains functions to establish a connection to the database and various other functions

All other files are examples of use, including pictures. PHPCLASSES is used to share classes, not
to share applications. So the provided files are only to show three examples :
- show the nominative list of the people stored in the database
- show the card of a person
- show a mini-family tree of a person (himself, parents, grand-parents and children)

These scripts are also examples of use of these classes. All other files (such as
production of all allowed informations into a PDF file) are avalaible from my website.

if you have downloaded these files on a package from PHPCLASSES, extract all files and :
1) be sure to have the below files and the tree directories on your computer.
2) have a look into 'init.php' file to change it with your own values :
   a) language (en or fr)
   b) your root genealogy directory (URLSITE)
   c) your informations for MySQL database connection (NOM, PASS, SERVER, BASE)
   d) execute the SQL command 'create_tables-and-demo-data.sql' to build your demo database
   e) upload all files and directory to your server into your root genealogy directory
      NB: the 'doc directory is not useful on the server
3) go to : http://<your.website.tld>/<your-root-directory>/


../+  <== genealogy root directory ............ Classes and example scripts
   |
   |  class.gedcom.php ........................ Class to build a GEDCOM file
   |  class.personne.php ...................... Class to get a person informations from the database
   |
   |  content-idx_en.txt ...................... Examples files
   |  content-idx_fr.txt
   |  ged.php
   |  genprt.css
   |  genscr.css
   |  index.php
   |  init.php ................................ Setup first.
   |  showged.php
   |  showlist.php
   |  showpers.php
   |  showsheet.php
   |  texts-en.php
   |  texts-fr.php
   |
   +----/doc
   |
   |        create_tables-only.sql ............ SQL command to create tables 
   |        create_tables-and-demo-data.sql ... SQL command to create tables and insert demo data
   |        data-dictionnary.txt .............. no comment.
   |        desc-tables.txt ................... Description of tables
   |        drop_tables.sql ................... SQL command to delete all tables
   |
   +----/img
   |
   |        addr.jpg .......................... Postal address symbol 
   |        doc.jpg ........................... Document symbol (certificates: birth, marriage, death)
   |        f.jpg ............................. Female symbol
   |        iall.png .......................... Menu icon: display all people
   |        iged.png .......................... Menu icon: send the database in a PDF file
   |        ihelp.png ......................... Menu icon: help
   |        ilist.png ......................... Menu icon: go to the nominative list
   |        imail.png ......................... Menu icon: send a mail about the displayed person
   |        ipdf.png .......................... Menu icon: send all information into a ¨DF file
   |        iphotos.png ....................... Menu icon: display all collected photographies
   |        iprint.png ........................ Menu icon: print the current page
   |        isheet.png ........................ Menu icon: display the family tree (parents, grand-parentd, children)
   |        m.jpg ............................. Male symbol
   |        mail.jpg .......................... Email symbol
   |        mob.jpg ........................... Mobile phone symbol
   |        nopic.jpg ......................... No picture symbol
   |        pic.jpg ........................... Picture symbol
   |        tel.jpg ........................... Fixed phone symbol
   |        u.jpg ............................. Unknown sex symbol
   |
   +----/photos
   |
   |        kermarec_paa.jpg .................. Picture of 'KERMAREC Paul Adrien Alan'
   |        kermarec_rle.jpg
   |        kermarec_yml.jpg
   |
   +----/src
   |
   |        B1.jpg ............................ Birth certificate of the person number 1 (scan)
   |        B6.jpg
   |        U3.jpg ............................ Union certificate of the person number 3 (scan)
   |        U7.jpg
   |
   `----/tools

           ll_conv.php ........................ Longitude/latitude conversions

NB: The files into the tools sub-directory isn't used by the scripts or the classes.
    It's only a tool for you to insert longitudes and latitudes in décimal system into your database.


DATABASE
--------
The database is described in the 'desc-tables.txt' file.
The database can be created by the SQL commands 'create_tables-*.sql'


DEPENDANCES
-----------
The example which is on my website use a class previously uploaded on PHP classes, easy to use
and mamed "class liste" (PHP Classes package n° 2625). Download it to place a combo list allowing
to select another person to see.


QR_CODE
-------
Not used by the scripts uploaded to PHPCLASSES.
This 2D barcode on the last PDF page contains the URL of your genealogy website.
It's a picture 236 x 236 px (2,00 x 2,00 cm)
You can get your own QR code with two ways
a) go to the URL http://www.keremerkan.net/qr-code-and-2d-code-generator/
   and generate the code you want with your own data (URL and/or phone number)
b) download the free and portable application Zint Barcode Studio Portable which
   can be downloaded from http://portableapps.com/apps/utilities


To continue...


06/07/2011.