4.78. timed-build

4.78.1. Summary

Parameters: file

Positional parameters in same order.

The attribute hash reference is passed after the parameters but before the container text argument. This may mean that there are parameters not shown here.

Must pass named parameter interpolate=1 to cause interpolation.

This is a container tag, i.e. [timed-build] FOO [/timed-build]. Nesting: NO

Invalidates cache: no

Called Routine:

ASP-like Perl call:

    $Tag->timed_build(
        {
         file => VALUE,
        },
        BODY
    )

 OR

    $Tag->timed_build($file, $ATTRHASH, $BODY);
    [timed-build file other_named_attributes]
Parameters Description Default
auto Turn on automatic region processing. none
file Name of the cache file. none
if Conditional display of the cached region. none
minutes Number of minutes after which the timed build should be repeated. 60
period Alternative way of expressing time. none
Attributes Default
interpolate No
reparse Yes
Other_Characteristics  
Invalidates cache no
Container tag Yes
Has Subtags No
Nests No

Tag expansion example:

    [timed-build file]
---
    TODO: (tag result)

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.78.2. Description

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

In the simplest case, surround a region of ITL with [timed-build] and [/timed-build]:

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

If a file parameter is not passed, saves to the directory timed in catalog root, with the file name of the current page. If the minutes parameter is not passed specifying how often the page should be rebuilt, then it will not be rebuilt until the output file is removed.

Accepts the following parameters:

4.78.2.1. auto

Turns on automatic region processing. The text of the timed-build region is processed to determine a unique checksum or digest (using MD5), and that file name is checked in the directory tmp/auto-timed (assuming ScratchDir is set to tmp). If no number of minutes is supplied, 60 is assumed.

This is designed to automatically build regions of commonly used areas without having to manage the file name yourself.

Implies login=1, but will still abort if no session ID cookie has been sent. Use force=1 to ignore cookie status.

4.78.2.2. file

Name of the file to save the results in. Relative to catalog root. The directory must exist.

4.78.2.3. if

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

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

The cached region will only be displayed if the variable timed is set to a non-zero, non-blank value. Otherwise, the ITL tags will be re-interpreted every time.

4.78.2.4. minutes

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

4.78.2.5. period

Alternative way of expressing time. You can pass a string describing the rebuild time period:

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

This is really the same as minutes=240. Useful for passing seconds:

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

The region will be rebuilt every 5 seconds.

Performance Tip: use minutes of .08 instead; avoids having to parse the period string.

If you have the StaticDir catalog.cfg parameter set to a writable path, you can build a cached static version of your catalog over time. Simply place a [timed-build] tag at the top of pages you wish to build statically. Assuming the catalog is not busy and write lock can be obtained, the StaticDBM database will be updated to mark the page as static and the next time a link is made for that page the static version will be presented.