Quick Start Guide

Gigatrees5 and VGedX are a standalone applications. They do not require a separate installation program and does not modify your system registry, so you can move the installation folder at any time without affecting operation.

To Install

download the application and extract it. It will decompress itself into an installation folder ( /gigatrees ).

To Uninstall

Simply delete the installation folder. No fuss.

To Upgrade

Reinstall, but be careful. When you extract the distribution file, it will overwrite the default files located in the installation folder. To protect yourself, never edit the default files directly — always use copies.

To Build an HTML Website

Building a website is quick and easy. In order to demonstrate this, try building the sample website in HTML first. This will allow you to view it on your laptop immediately. To build the sample website in HTML, just run the sample-html.bat file. This will build the sample website and copy all of its files to the output path ( /sample ). If you have not already created the folder, Gigatrees5 will ask for permission before creating it. After the build completes, browse to the landing page ( /sample/index.html ) to view the sample website.

To Build a Database

Building a website for actual deployment, requires that you generate a database rather than individual HTML files. Before running the build file, you will need to edit the setup file ( /includes/db.xml ) and update the content of the $DOMAIN$ placeholder (located near the top of the file) with the root URL of your website. Save the file and then run sample-db.bat. This will build the sample website and copy all of its files to the output path ( /demo-gigatrees ). To view your website, you will need to deploy it to your web hosting service (GoDaddy, BlueHost, Heliohost (free), etc.). If you've never deployed a website using a web hosting service before, it's a two sip process.

take a sip of coffee
log into service
open cPanel
open File Manager
go to the public_html folder
zip your output folder
select Upload from the menu
drag and drop the zip file
select the zip file
select Uncompress from the menu
reselect the zip file
select Delete File from the menu
take another sip of coffee

If you're not ready to tackle this quite yet, you can view the Gigatrees5 Demo online.

You can also use the BlüeBox testing service to preview your family tree online. You will need to sign in to the administrative panel using the application id shown at the top of your build log. Application ids are registered the first time the Gigatrees5 runs, but only when the update check option is enabled on the command line (see below), so make sure you've done that first. Preview websites are limited in size and purged periodically. Once signed in you will be able to upload your database file. You will need to set your <PluginsURL> to https://blueboxhosting.org/plugins and your <WebsiteURL> to match your database name (e.g https://blueboxhosting.org/site/demo-gigatrees5).

If you view the batch file ( sample-db.bat ) you will see that it loads your configuration files:

gigatrees5 -v -u -c includes/plugins.xml -c includes/sample.xml -c db.xml -c lang.xml

The first file ( plugins.xml ) loads the various scripts, stylesheets and metadata (via plugins) needed to create your website's header and footer. The setup file ( sample.xml ) sets your website's title and output folder, and then creates a sample configuration for the sample GEDCOM file provided. The db file ( db.xml ) includes items that must be set for database builds; the translation file ( lang.xml ) load the default text strings.

BlüeBox supports several command line options.

Verbose
-v
Provides additional build details.
Check for updates
-u
Checks if there is a newer version available.
Config
-c config.xml
Loads an individual configuration file.
Log
-l build[-timestamp].log
Generates a log file. The timestamp is optional.

Now that you've seen how easy it is to create a family tree website specific to your ancestry, you'll no doubt want to get started with your own. I recommend a quick review of the sample configuration files if you have not already done so. You might also want to review the configuration options in the rest of the documentation. I've tried to keep the documentation concise so that it can be read through quickly. It is entirely up to you how many or few of these options you use. The configuration files used to build this documentation are included with its own build file ( docs.bat ), so that you can rebuild it any time.

The installation folder also includes a source code folder ( /src ), which contains the VGedX C++ source code ( src/vgedx.zip ), which can be used by programmers to develop their own genealogy applications based upon The Gigatrees5 GEDCOM Parser (TGP). TGP is used by both Gigatrees5 and VGedX to parse a GEDCOM files based on its GEDCOM version. Dictionary files are provided for GEDCOM versions 5.5 Rev 1, 5.5 Rev2, 5.5.1 and 5.6. The source code does NOT include Visual Studio project files, external libraries or third party source files (i.e. the Windows x64 built-in libraries, the C++ Boost libraries [https://www.boost.org], pugixml [https://pugixml.org] and UTF-8 CPP [https://sourceforge.net/projects/utfcpp/]).

Configuring Gigatrees5

The configuration pages indicate default values, when they apply, in the 2nd column. Generally, it is not important which order options are specified in a file, nor is it important in what order the properties are specified within an option (unless otherwise specified). That being said, each property is processed in the order it is loaded, so if you redefine a property, it will be overwritten (unless otherwise ... well you know). In some cases, such as redefning pages and images, you'll be notified during the build process.

All configuration files use XML tags to define data. XML file are in plain-text, so you can edit them with any text editor. All configuration files must begin and end with the <Gigatrees> tag.

<Gigatrees>

<!-- all configuration items go here -->

</Gigatrees>

XML tags are composed of opening and closing tag elements. Text falling between the opening and closing tags may include plain text, HTML, JavaScript, PHP code or additional XML tags. Since XML uses the left bracket ( < ) to deliniate the start of a tag, a special opening tag delimiter ( <![CDATA[ ) and closing tag delimiter ( ]]> ) must be used to embed HTML within an XML tag. Gigatrees5 supports embedding HTML in almost all GEDCOM record data. Given this, it should be obvious from this discussion that left brackets ( < ) unrelated to HTML tags when used in your GEDCOM record data can cause problems. Browsers will attempt to interpret these as HTML tags and the results may not be defined (nor pretty). Comments can also be embedded in both XML and HTML using a special tag structure ( <!-- and --> ). A generic example might look like this:

<Tag>

   <Tag>
     Hello World                       <!-- plain text -->
   </Tag>
   
   <Tag> 
     <![CDATA[
       <b>Hello World</b>              <!-- HTML -->
     ]]>
   </Tag>
   
</Tag>

Additionally, Gigatrees5 will automatically hotlink all standalone URLs (See <AutoHyperlinkUrls>) found in sources, notes, blog posts and most other GEDCOM data. All images will be opened using the FancyBox plugin.

The remaining documentation disscussing additional configuration options that can be used to extend the capabilities of your family tree. The documentation is divided into three sections. The Basic Configuration includes items that many users may want to review. The Advanced Configuration is for those looking to delve deeper. You will want to review these if you plan to use the DNA features, setup language translations, include origin and distribution maps, include a blog, configure source templates or setup a database. I have attempted to keep the documentation sections as short as possible. The Appendicies include serveral articles that cover some of these topics in greater detail.

In the pages that follow, default values are shown in brackets ( [ and ] ).