It is important to understand how the page building process works so that you know what to expect when you build your pages. There are two different
types of page builds and several different ways to execute those page building functions, all of which will be covered in this document. This will also
cover some basic information about the galleries in your database and how they are handled and how the holding period works.
Overview of the Gallery Database
The gallery database stores all of the information about the galleries you have added to the database. To add galleries you can either
them or submit a single gallery
through the software control panel.
Any time that you add a new gallery to the database, either through the import or submission feature, it will be put into a pool of available
new galleries that can be selected from for display on your TGP pages. TGP Rotator keeps track of the status of all galleries in the database, and
when they are in the pool of available new galleries their status is Pending.
When a gallery from the pool of available new galleries is selected for display, it's status changes to Used. This means that the gallery has been selected
for display and is currently being used on one or more of your TGP pages. When this happens the display date is assigned to the gallery (more information on this
later) so that the software can keep track of how "old" the gallery is. The length of time that a gallery stays Used depends on the template configuration you are
using and how often your pages are being updated with new galleries. The gallery will remain Used until it is no longer displayed on at least one of your TGP pages.
Once a gallery is no longer displayed on one of your TGP pages, it's status changes to Holding. This means that the gallery is in a queue waiting to go back
into the pool of available new galleries. The holding period value (more on this below) determines when the gallery will go back into that pool. When the holding
period elapses, the gallery will be moved back into the queue of available new galleries, and it's status will be set to Pending. The click counter, build counter,
and used counter will all be reset to 0 so that the gallery will start on an even playing field with other galleries when it is once again selected for display.
This entire process will repeat itself until the gallery is deleted from the database.
The Holding Period
The holding period setting in the Edit Options interface tells the software how long a gallery should remain in the holding queue before it is rotated
back into the pool of available new galleries. This value represents the number of days since the gallery was first selected for display before it will
be rotated back into the pool of available new galleries. So, for example, if a Pending gallery is selected for display on 2005-02-01 (February 1st) and your holding
period is set to 10, the soonest the gallery will move back to the pool of available new galleries is on 2005-02-11 (February 11th).
Note that the holding period is a very important setting and some consideration needs to be taken when determining what value you should use for that setting.
For example, say you have cron setup to automatically do a "Build With New" every 20 minutes and the page that you are building selects one new gallery from the
database each time it is updated. This means that every day 72 new galleries will be used on that page alone. If you have your holding period set to 30, you will
need a bare minimum of 2160 galleries in your database to support the number of new galleries you are displaying each day. This does not take into account the other
galleries displayed on the same page, or other pages that you have that may also be selecting new galleries.
When you create or edit a TGP page you can set it's build order. This tells the software what order the pages should be built in. The page with the lowest number
will be built first and the page with the highest number will be built last. Depending on how you have decided to handle duplicate galleries (if you are allowing
them or not) and how you are sorting your galleries, the build order may be of importance. For example, say you have two pages that you want to be archive type
pages, and on those pages you are displaying the galleries chronologically. The first of the two pages that gets built will have the newer galleries, while the
second page will have the older galleries. If you did not have the build order set properly, the two might be flip-flopped and would be confusing to surfers
viewing your site who are expecting the oldest galleries to be on the second page.
There are two different types of builds that you can do. You will notice these referred to as "Build With New" and "Build" in the other sections of the
software manual. The two different build types will produce different results, so it is important to understand what each one does.
Build With New
When this type of build is done, new galleries can be selected from the database. Any GALLERIES sections where the STATUS option is set to Pending
will cause new galleries to be selected from the pool of available new galleries and displayed in those sections. For GALLERIES sections where the
STATUS option is set to Used, only galleries that have been used previously will be displayed in those sections (unless you are using filler galleries).
You can think of this as an updated that adds new galleries and also re-orders the existing galleries.
For this build type the ORDER option of the GALLERIES directive is used when sorting the galleries. You can specify both the ORDER and REORDER options,
however with this build type only the ORDER option will be used. This is the case for all GALLERIES sections, no matter if the STATUS option is Pending
Note that it is still possible for new galleries to be selected from the pool of available new galleries when the STATUS option is set to Used in one or more
of your GALLERIES directives. This is because of the filler galleries feature of the software. If you do not set the FILL option to False, the software will
attempt to fill all of the GALLERIES sections by using Pending or Holding galleries where necessary. More information on filler galleries is available in the
When this type of build is done, new galleries will not be selected from the database (unless you are using filler galleries). Any GALLERIES sections
where the STATUS option is set to Pending will automatically be converted to Used so that only previously used galleries will be displayed in that section.
For GALLERIES sections where the STATUS option is set to Used, the status is unchanged and they work as normal. You can think of this as an update that
only re-orders the existing galleries instead of adding new galleries to your pages.
For this build type the REORDER option of the GALLERIES directive is used when sorting the galleries. You can specify both the ORDER and REORDER options,
however with this build type only the REORDER option will be used. This is the case for all GALLERIES sections, no matter if the STATUS option is Pending
Note that it is still possible for new galleries to be selected from the pool of available new galleries when doing this type of build. This is because
of the filler galleries feature of the software. If you do not set the FILL option to False, the software will attempt to fill all of the GALLERIES sections
by using Pending or Holding galleries where necessary. More information on filler galleries is available in the next section.
Every time a build is done, no matter what type, the TGP pages that you are building will be updated with any HTML code you have added to or removed from
the template. Any galleries that have been deleted from the database since the last build will also no longer appear on the page(s) that are being built.
By default the software will attempt to fill all of the defined GALLERIES sections on your TGP pages. If necessary, it will use filler galleries which are
galleries that may not meet the defined requirements you have specified in the GALLERIES directive. For example, if you have a GALLERIES section that has the
AGE option set to 3, but there are no galleries in the database that meet that requirement, filler galleries will be used.
The software will use two backup database queries to pull filler galleries from the database. This gives it two opportunities to locate galleries which meet
the filler requirements. The backup queries have default values set for them, but you can override them with the PRIMARYFILL and SECONDARYFILL options of the
GALLERIES directive. The default value for PRIMARYFILL is to select from the available pool of new galleries, and the default value for SECONDARYFILL is to
select from galleries in the Holding queue. Both backup queries will allow galleries that have been displayed on other pages, but will not allow galleries
that have already been shown on the page that is being built.
If a gallery is selected from the pool of new galleries to be used as a filler gallery, it will become a Used gallery and have a display date assigned to it (more
on this later). It will then be eligible for display as a normal Used gallery when you do a "Build". However, if a gallery in the holding queue is selected as
a filler gallery, it's status does not change back to Used and it's Display Date does not change. This is done to ensure that galleries in the holding queue get
rotated back into the pool of available new galleries on the correct date. If holding galleries were changed back to used status, it is possible that some of
the galleries could permanently be displayed on your page, and thus not giving you a good rotation of your galleries.
If you would rather not have filler galleries used, set the FILL option of each of your GALLERIES directives to False. This will prevent the filler galleries
from being used, and may result in empty sections of galleries on your TGP pages.
How the Display Date is Selected
When a gallery is selected from the pool of available new galleries, a display date will be assigned to it. This display date can then be used to track how old
the gallery is, and allows you to have sections of galleries from yesterday, 2 days ago, etc. In most cases, the display date is simply set to the date when the
gallery was selected for display, however there are some special cases. These special cases only occur when filler galleries are used in conjunction with the AGE,
MAXAGE and/or MINAGE options of the GALLERIES directive. Here are a few examples:
- Filler galleries are selected from the pool of available new galleries and the AGE option is set to 1
In this case the display date will be set to yesterday's date. The AGE option restricts that section to galleries that are 1 day old, so the display date
for the selected filler gallery has to be set to yesterday's date.
- Filler galleries are selected from the pool of available new galleries and the MAXAGE option is set to 5
In this case the display date will be set to a date between today's date and the date 5 days ago. The MAXAGE option restricts that section to galleries which are
between 0 and 5 days old, so a date in that range is selected.
- Filler galleries are selected from the pool of available new galleries and the MINAGE option is set to 2
In this case the display date will be set to a date between the date 2 days ago and the date 10 days ago. The MINAGE option restricts that section to galleries which are
2 days old or older, so a random date in that range is selected. The maximum age is software limited to at most 10 days old.
- Filler galleries are selected from the pool of available new galleries, the MINAGE option is set to 2 and the MAXAGE option is set to 7
In this case the display date will be set to a date between the date 2 days ago and the date 7 days ago. Using both the MINAGE and MAXAGE options restricts the galleries
in that section to be between 2 and 7 days old, so a random date within that range is selected.
Because of these special cases you may sometimes notice that galleries have display dates in the past, which are even before the date that the gallery was
added to the database. This is completely normal, and is simply the result of how the filler galleries are selected.
Building From the Control Panel Interface
In the control panel menu there are two links for page building: Build Pages With New and Build Pages. Build Pages With New will
execute a "Build With New" type of build and Build Pages will excute a "Build" type of build. In both cases, all of your TGP pages
will be built.
If you only want to build one of your pages, you can do that through the Manage Pages interface. Each page listed in that inferface
has [Build] and [Build w/New] links that you can click to build that page. [Build w/New] will execute a "Build With New" type of build
and [Build] will excute a "Build" type of build.
Building Through Cron
By using your server's cron system, you can have TGP Rotator run page building functions automatically at the times you specify. This can be
used to have TGP Rotator update your pages automatically once per day, once every hour, or however often you want. For complete details on using
cron with TGP Rotator, please see the Cron
section of the manual.