GameDB2 User Manual - Automatic Page Generation
-
Templates and 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:
- 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.
- 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.
- 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:
Template Name
This represents the name given to this template. This is used for display purposes in the template list.
Additionally, GameDB provides several template tags which can be used to generate the URL to a page
that has been generated by a template, allowing you to link pages together. These tags can take a template name (in cases
where you have more than one template of the same type) so that they know which file you want to link to.
All templates of the same type must have a unique name.
Short Name
This special short name may be used in place of the main template name in the template tags that allow you to generate
URL's to automatically created pages. This allows you to use the Template Name field for a descriptive name
(e.g. "Main Game Details Page") while providing a shorter easier to type name for use when you want to
generate links (e.g. "gdetails").
Like the template name, every template of the same type must have a unique name.
File Extension
Generate To
Generated URL
These fields are used to determine both the filenames of files that are created, and the URL's that point to those
files, so that they can be browsed after they have been created.
Files are created as: Base Path + Template Type + DataID + Extension
In this scheme:
- Base Path is some combination of the Main Site Path specified in the system-wide configuration options
and the path specified in Generate To.
More specifically, if Generate To is an absolute path, it becomes the whole base path. Otherwise, the Base path
is a combination of the Main Site Path and the relative path provided in Generate To.
- Template Type is a string which indicates the template type used. This allows you to generate files from different
template types into the same directory without accidentally overwriting files.
- DataID is the underlying ID value of whatever data item the template represents, in the case of regular
dynamic templates, or an index type in the case of index templates.
- Extension is the extension provided in the template record, or the default from the system-wide configuration
options.
URL's are generated using a similar scheme: Base URL + Template Type + DataID + Extension
In the case of URL's the Base URL is some combination of the Generated URL field and the Main Site URL from the
system-wide configuration options:
- If no Generated URL is specified, the Main Site URL is used as the Base URL.
- If a complete URL is specified in Generated URL, that URL becomes the base URL.
- If some relative path information is specified in Generated URL, that relative path is
appended to the end of the Main Site URL to obtain the Base URL.
Because of the way that filenames and URL's are created by GameDB, it is possible to specify extra filename
parts in the file extension field, to more fully customize the filenames generated.
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:
Template Name
This represents the name given to this template. This is used for display purposes in the template list
but is otherwise unused by the system. Every static template must have a unique name.
Auto-Rebuild
This property is used to specify if this template should be automatically rebuilt or not.
When this is enabled (the default), this template will automatically be rebuilt whenever GameDB
performs an automatic page build operation for one of the dynamic templates. This
rebuild occurs even if GameDB wants to rebuild a template type for which there are no defined templates (For example,
when it wants to build a Game Information template after a Game's information changes,
but you have not defined any templates of that type.
When this is disabled, this template will only be rebuilt by a manual rebuild operation.
Generate To:
This specifies the file that this template will generate. This may be an absolute path, to specify
exactly where the file will go, or it can be a relative path. In this case, the path is relative to
the Main Site Path that is set in the system-wide configuration options.
Include Templates
Include templates are a special version of
static templates, and can be used in the following
ways:
- The contents of an include template may be used in conjunction with the <GDBInclude>
template tag to insert the contents of an include template directly into the contents of
some other template, either static or dynamic.
This is useful when you wish to include the same information (such as a site logo or copyright message)
into every page generated by GameDB. By using an Include template to do this, you can quickly change the
information on all pages by editing it in only a single place.
- The contents of an include template may be linked to an external file somewhere. In this case, any changes
that you make to the template contents in GameDB will change the contents of the linked file, and any changes
made to the linked file will automatically update the contents of the template in GameDB.
This can be used with Server Side Includes to allow you to change the contents of your web page on line from
any web browser instead of having to use FTP, for example.
Include templates have the following properties:
Template Name
This represents the name given to this template. This is used for display purposes in the template list,
and may also be used as the name in the <GDBInclude> tag to specify that this is the template which you want to include.
Every include template must have a unique name.
Short Name
This special short name may be used in place of the main template name in the <GDBInclude> tag. This allows you to
use the Template Name field for a descriptive name (e.g. "Site Wide Company Logo Banner") while providing a shorter
easier to type name for use when the template is included (e.g. "logo").
Like the template name, every include template must have a unique name.
Linked To
This specifies the name of the local file that this template is linked to, if any. When given, this may be an absolute path,
or a path relative to the Main Site Path set in the system-wide configuration options..
When an include template is linked to a file, GameDB stores a copy of the contents of the file in the database, along with
a time stamp that indicates when that data was stored. At the beginning of any automatic or manual
page generation, GameDB uses this information to synchronize the external file with the contents of the database.
In particular, if the database has been more recently changed than the local file, the contents of the file are replaced
with the contents from the database. If the file has been more recently changed, it's contents are reloaded and used to
update the database.
When a new include template is created and linked to a file, GameDB handles the situation as follows:
- If you don't enter the contents for the new template in the template add page, GameDB tries to
read the contents of the file and use that as the initial database contents.
- If you do specify contents in the Template Add Page, GameDB immediately writes that information out to
the linked file, overwriting any contents that might already exist.
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:
- At the top of the Template List, the button labeled "Rebuild Entire Site" will perform a manual rebuild across
every template type defined by the system, so that every possible page will immediately be recreated. This also
includes static templates.
- Clicking the "Rebuild All" link next to a one of the types of templates in the template list will perform a
manual rebuild of every page associated with just those template types. Static templates will not be rebuilt
unless that is the type of template that you are manually rebuilding; triggering a manual rebuild on one of the
dynamic template types does not rebuild any static templates.
- Clicking the "Rebuild" link next to a specific template will perform a manual rebuild of every page associated
with that exact template. As above, static templates are not automatically rebuilt when you perform this
action.
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:
Template Name
The full name of the template. For Dynamic and Include template types, the template
short name (if one is set) is also displayed here for quick reference.
Generated To
For Dynamic and Static templates, the list displays for you the full path that the files for
this template will be written to, along with a sample filename. In this display, the ### is replaced with the
unique identifying data for the template type. This allows you to see at a glance exactly where files are
being generated to.
For Dynamic templates, this part of the display also shows you a sample of what the URL is for items generated
by this template.
These examples allow you to verify that files are being generated to the location that you want.
Linked File
For Include templates that are linked to local file, the name of the file is displayed, allowing you to
see at a glance what templates control what files.
Auto-Build
For Static templates, GameDB tells you if the Auto-Rebuild property is turned on or off for each template
in the list.
Edit
Clicking this link allows you to edit the contents of the template.
You will not see this link unless you have Permission to edit templates.
Remove
This check box allows you to flag a template for removal from the system. To remove templates, you must first select
one or more templates by checking the check box next to their name, and then clicking on the "Remove" button that
displays at the bottom of the form. You will be asked to confirm your intention to remove the specified templates
before the removal takes place.
You will not see the check boxes or the Remove button unless you have permission to remove templates.
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.