GameDB2 User Manual - Automatic Page Generation

Description


GameDB provides an internal system that allows you to automatically generate static pages that represent the information that GameDB is currently storing. These can be used to provide your game group's playing activity as a public website, to produce an on line store, and other things.

In order to do this, GameDB provides you with a powerful template system that allows you to fully customize the pages that are generated. Whenever information is added, removed or edited, a page generation event occurs which determines which pages need to be recreated. Those pages are then automatically generated, so that your website is always up to date.

You tell GameDB what sorts of information you're interested in generating, and then give it the skeleton of the sort of file that you want to generate. These can be html, php scripts, or any other text file that you desire.

These skeleton files, or Templates, may include any number of special GameDB HTML tags. As the file is generated, these tags are expanded out to convey some piece of information (for example, the name of a game).

There are several template types available to you that each creates files with different types of information, so that you have complete control of when and how things get generated.

How do templates work?


Behind the scenes, GameDB monitors changes that are made to it's internal data, such as changes to Games, Categories, Publishers and designers. When a change of some piece of information is detected, GameDB immediately checks the Template List to see if any templates are defined for the kind of data that has changed.

For each template that is found during this search, the following steps are carried out:
  1. The body of the template is read (using the ekthml HTML parsing library) to obtain the structure and layout of the file that is to be created.

  2. The filename of the file to be created is determined, using a combination of the internal identifying numbers that GameDB uses to organize your game data and the data specified in the template information.

  3. The contents of the template are written to the proper file. During this operation, GameDB does specially processing on the template file, to replace special HTML tags (called Template Tags) with the information for whatever type of file is being created.

The "Special Processing" done on templates is to handle Expansion Tags and Container Tags, replacing them in the template file with the underlying information that the file is being generated for. Both Expansion Tags and Container tags have the prefix "GDB" in their names, to make them distinct from regular HTML tags.

Expansion Tags


Expansion tags are special HTML tags that GameDB recognizes by name (regardless of the case used). When an HTML tag is recognized as an Expansion tag during Template processing, GameDB outputs some special text to the generated file, instead of the tag itself.

The text used depends on the Tag Name, what kind of template the tag appears in, and what special attributes have been included in the tag. At a bare minimum, any tag recognized for a particular template type will never be sent to the generated file, even if the underlying information it represents does not exist.

For example, in a Game Information Template:
Game Name: <GDBGameName> Has a GameID of <GDBGameBGGID> on BoardGameGeek
Could provide the following output:
Game Name: Carcassonne Has a GameID of 822 on BoardGameGeek
If the game that the template was being generated for does not have a BGG GameID specified in it's Game details, the output of this would be:
Game Name: UnknownGame Has a GameID of on BoardGameGeek
Some of the expansion tags that GameDB supports can be controlled by specifying one or more HTML attributes to the tags when they are entered. These attributes can change the way the tags expand out.

For example, the descriptive text for games can possibly be quite long, possibly several paragraphs or more. Using the following snippet:
Description for <GDBGameName>:<br><br>

<GDBGameDescription excerpt="paragraph>
The optional attribute excerpt tells GameDB that it should display only the first paragraph of the description.

It is also possible to include Expansion Tags inside the attribute values of regular HTML tags, so that as those tags are being written out to the generated file, the expansions can occur inside the attributes. Due to limitations of the HTML parser used, HTML tags must be written differently when they are placed inside attributes. The tag must be enclosed in ( and ) characters instead of the usual < and > characters, and any attributes must be written using single quotes instead of double quotes. For example:
<a href="(GDBGameID).html" title="(GDBGameDescription excerpt='sentence')"><GDBGameName</a>

Container Tags


Container tags are, like Expansion Tags, special HTML tags that GameDB recognizes by name. However, unlike Expansion Tags, Container tags must always appear in pairs, with an open tag and a close tag. An example of this is the <A></A> tag which creates hyperlinks in HTML.

Everything that appears between the open and close tag in a Container Tag Pair is said to be "inside the container". It is even possible for a container to contain yet another container, for example:
<B><I> </I></B>
In this example, the I container is inside the B container, and the I container is itself empty.

GameDB supports two different kinds of Container Tags, each of which operates in a different way.

Conditional Container Tags


Conditional container tags are container tags which represent some sort of boolean condition, which may possibly be modified by one or more attributes.

When a container of this type is seen in a template, the boolean condition is evaluated. When the result is true, the contents of the container are processed and written to the output file, and when the result is false, the container is completely ignored, and any content that it might have is also completely ignored.

All conditional container tags support the boolean attribute negate, which reverses the test that is being performed by the tag. This allows you to conditionally produce some output whether a condition is true or not. For example:
<GDBGameHasExpansions>
    <GDBGameName has <GDBGameExpansionCount> expansion(s)
</GDBGameHasExpansions>

<GDBGameHasExpansions negate>
    <GDBGameName does not have any expansions
</GDBGameHasExpansions>
In this snippet, only one of the two conditional containers will be processed; the other will be ignored. The result is that the output file either tells you how many expansions the game has, or it tells you that it does not have any expansions at all.

Looping Container Tags


Looping container tags are container tags which represent a set of data of some sort, for example a list of expansions for a game. Like Conditional container tags, Looping container tags may be modified by one or more attributes.

When a container of this type is seen, it's entire body is expanded out into the output file once for each piece of data in the list. It is possible for the list to be empty, in which case the body of the template is never expanded at all.

While the contents of a conditional container are being processed, an extra set of template tags is active, representing the data that is part of the conditional list. It is possible for these tags to have the same name as other tags; when this occurs, the version of the tag defined inside the conditional tag takes precedence.

For example:
<GDBGameHasExpansions negate>
    <GDBGameName does not have any expansions
</GDBGameHasExpansions>

<GDBGameHasExpansions>
    Expansions for <GDBGameName>
    <OL>
        <GDBExpansionList>
            <LI><GDBExpansionName>
        <GDBExpansionList>
    </OL>
</GDBGameHasExpansions>
In this snippet, we first check to see if there are any expansions to the game being processed. If there are none, then we say so.

When there are expansions, an ordered list is opened, and then list items are generated. Inside the <GDBExpansionList> tag, <GDBExpansionName> is defined as the name of an expansion. This container is processed once for each game that is an expansion of this game, resulting in a numbered list of all expansions.

Dynamic Templates


Dynamic templates are the type of templates that are used the most often while setting up Automatic Page Generation.

There are several different sub-types of dynamic template, one each for the different types of data that GameDB supports. For example, the Game Template type represents Game Details. GameDB provides you with a complete set of Template Tags for each type of dynamic template which represent the underlying data that the template supports.

Whenever any data changes, GameDB checks to see if there is a template type defined for that data. If there is, then all templates of that type are rebuilt, to keep local files up to date.

Regardless of their type, all Dynamic templates share the following properties:

Event Templates


Event Templates are used to generate indivual pages for each of the Events that GameDB knows about.

Internally, every event has a unique identifying EventID, which is used along with the template type "event" to create filenames for generated files and URL's. For example, if an event for Magic: The Gathering had an eventID of 50, then the filename that would be used to create this might be:
/var/www/htdocs/events/event50.html

Game Templates


Game Information Templates are used to generate pages for each of the Games that GameDB knows about.

Internally every game has a unique identifying GameID, which is used along with the template type "game" to create filenames for generated files and URL's. For example, if Carcassonne had the GameID 100, then the filename that would be used to create this might be:
/var/www/htdocs/gamepages/game100.html

Game Index Templates


Game Index Templates are used to generate information for sets of games whose names begin with a particular letter.

In total, only 28 different files are possible when using game indexes; These are identified by an uppercase letter 'A' through 'Z', the index type "num" for games whose names begin with a number, and "all" for every game in the system.

Inside templates of this type, the Template Tags will only ever refer to a specific group of games, allowing you to generate pages that allow browsing of games by letter.

As an example, the name of the file that would be created to represent all games whose names begin with the letter A might be:
/var/www/htdocs/gamepages/gameIndexA.html

Category, Publisher and Designer Templates


These templates are used to generate pages for each of the different Categories, Publishers and Designers that GameDB knows about.

Like Games, every item has a unique identifying number known as it's ItemID, which is used with the template type "category", "publisher" and "designer" to generate files and URL's. For example, the following might be the filenames used to represent the very first item of each type that was added to the system:
/var/www/htdocs/categories/category1.html
/var/www/htdocs/publishers/publisher1.html
/var/www/htdocs/designers/designer1.html

Category, Publisher and Designer Index Templates


These templates are used much like the Game Index Template is used, to generate pages for the list of Categories, Publishers and Designers whose names begin with a particular letter.

Like Game Indexes, only 28 different files are possible when using these indexes; These are identified by an uppercase letter 'A' through 'Z', the index type "num" for items whose names begin with a number, and "all" for every item in the system.

Inside templates of this type, the Template Tags will only ever refer to a specific group of items, allowing you to generate pages that allow browsing of items by letter.

As an example, the names of the files that would be created to represent all items whose names begin with the letter A might be:
/var/www/htdocs/categories/categoryIndexA.html
/var/www/htdocs/publishers/publisherIndexA.html
/var/www/htdocs/designers/designerIndexA.html

Static Templates


Static templates are primarily used to generate files which require data that doesn't fit entirely within one of the dynamic template types. For example, if you wanted to generate a file which contains all of the games which have the "Is New" flag set, you might use a static template for that, because the Game Index Template does not quite fit in with this idea.

Static templates have the following properties:

Include Templates


Include templates are a special version of static templates, and can be used in the following ways: Include templates have the following properties:

Manually rebuilding files


Although GameDB automatically detects when data has changed and starts an automatic page build, it is sometimes necessary to manually trigger the rebuild process for one or more types of templates. For example after you have made changes to a template, you may want to immediately rebuild all files that use that template.

You have several options available for template rebuilding, all of which are available from the template List: Even though not all manual rebuilds trigger a rebuild for Static templates, Include Templates are always synchronized before any template build, so that if they are included in any of the templates being rebuilt they are up to date.

A manual rebuild may only be triggered by users who have permission to edit templates.

Viewing the list of currently defined templates


The list of templates that are currently set up is available by clicking "Templates" in the main GameDB menu. Templates are listed sorted first by type, and then by alphabetically by name.

Because it can take many templates to set up a complete site, the template list may get a bit cluttered. For this reason, GameDB allows you to selectively show and hide each of the different types of templates (and in the case of dynamic templates, different kinds of dynamic templates. This is done by clicking the link next to the type of template that you would like to show or hide, with the "+" turning on the display of that type, and "-" turning it off.

In the list of templates, each template defined provides you with the following information:

Adding a new template


New templates may be added from the Template List by clicking the link labeled "Add New" next to the type of template that you would like to add. From the page that appears, you may change any of the properties of the template type that you would like to add.

You will not see the link to add new templates if you do not have Permission to add templates.

Editing templates


The body of a template and any of it's properties may be edited by clicking the "Edit" link next to the template that you would like to edit in the Template List. A page appears similar to the Add Template page, allowing you to change the properties and content of the template.

When editing templates, the type of the template may not be changed, but everything else about the template may be changed. When editing is complete, you will probably want to perform a manual rebuild so that the changes you have made take effect.

You will not see the link to edit any templates if you do not have Permission to edit templates.

Removing existing templates


Templates may be removed from the Template List by checking the check boxes next to each template that you would like to remove, and clicking the "Remove" button that appears at the bottom of the list. You will be asked to confirm your intention to remove the selected templates before the removal takes place.

When templates are removed, the files that have been generated from them remain behind; you have to manually remove such files if you no longer require them.

You will not see the check boxes or the remove button if you do not have Permission to remove templates.