timed-build

Allows you to build CPU-intensive regions of Interchange tags on a timed basis.

Summary

[timed-build file] ... [/timed-build]

Parameter	Description	Default
file	The name of the cache file.	None
minutes	Number of minutes after which the timed build should be repeated.	60
period	Alternative way of expressing time.	None
auto	Turn on automatic region processing.	None
if	Conditional display of the cached region.	None
scan
login	Use the (or create) cache even if the user is logged in.	No
force	Always use (or create) the cache.	No
new		No
umask		None
hide	Suppress any output text that would ordinarily be returned from this tag. (This universal parameter was introduced with Interchange version 5.5.2.)	No
interpolate	Parse Interchange tags, included in the body text, before this container tag executes.	No
reparse	Process any Interchange tags found in the text output from this tag.	Yes

Examples

Tag expansion example

Assuming the time is 6:03am when first viewed by a user

[timed-build]
Built at [time]%k:%M%p[/time].
[/timed-build]

Built at 6:03am

When viewed at 6:04am

Built at 6:03am

When viewed at 6:45am

Built at 6:03am

When viewed at 7:02am

Built at 6:03am

Assuming that first visit to page, after 7:03am, was at 7:06am

Built at 7:06am

When viewed at 7:15am

Built at 7:06am

Perl example

$Tag->timed_build({
file => $file,
body => $body,
});

or similarly with positional parameters:

$Tag->timed_build($file, $attribute_hash_reference, $body);

Description

Allows you to build CPU-intensive regions of Interchange tags on a timed basis. In the simplest case, you can just surround a region of Interchange tags with [timed-build] and [/timed-build], as follows:

[timed-build]
Built at [time]%c[/time].
[/timed-build]

If a file parameter is not passed then [timed-build] will save to the timed directory in the website's home directory (CatRoot), with the file name of the current page. If the minutes parameter, specifying how often the page should be rebuilt, is not passed then no rebuilding will occur until the output file is removed.

Parameters

file

Name of the file in which to to save the results. Relative to the website home directory (CatRoot). If a directory is specified then it must exist.

minutes

The number of minutes after which the timed build should be repeated. If set to 0 then it will be built once and then not rebuilt until the output file is removed. If no number of minutes is specified then 60 will be assumed.

period

An alternative way of expressing time. You can pass a string describing the rebuild time period as follows:

[timed-build period="4 hours"]
Interchange tags....
[/timed-build]

period="4 hours" and minutes="240" are equivalent

The following region would be rebuilt every 5 seconds:

[timed-build period="5 seconds"]
ITL tags....
[/timed-build]

Performance Tip

Using minutes=".08" instead of period="5 seconds" will avoid having to parse the "period" string, thus saving a couple of CPU cycles.

auto

Turns on automatic region processing. The text of the timed-build region is processed to determine a unique checksum, or MD5 digest. The checksum/digest is then used as a file name in the "tmp/auto-timed" directory (assuming ScratchDir is set to "tmp"). This is designed to automatically build regions of commonly used areas without having to manage the file name yourself.

This implies login=1, but will still abort if no session ID cookie has been received. Use force=1 to ignore the cookie status.

if

Allows you to to only display the cached region when this parameter is true. For example, you can do this:

[timed-build if="[value timed]"]
Interchange tags....
[/timed-build]

If the [value timed] tag returns a non-zero, non-blank value then the cached region will be displayed. Otherwise, this tag's body text will be interpolated.

scan

login

Normally [timed-build] will abort if the user is logged in, resulting in the region not being cached and the cached copy not being displayed. If this parameter is set true then the region will be cached even if the user is logged in.

You should use this parameter when the logged-in status of the user should not affect the displayed data.

This parameter is implied by the auto=1 parameter.

Note

A bug in Interchange versions prior to 5.5.0 prevented this option from working.

force

Normally [timed-build] will abort if the user is not using a session cookie, resulting in the region not being cached and the cached copy not being displayed. If this parameter is true then the region will be cached even if the user does not have a session cookie.

You should use this parameter only when there are no internal links to any Interchange pages in the cached region, otherwise usage can cause users without cookies to loose their session.

This parameter overrides the login parameter.