template::paginator::create (public)

 template::paginator::create statement_name name query [ args... ]

Defined in packages/acs-templating/tcl/paginator-procs.tcl

Creates a paginator object. Performs an initial query to get the complete list of rows in the query result and caches the result for subsequent queries.

Parameters:

statement_name (required)

A query name. This is overwritten by the contents of the "query" parameter if it is not the empty string.

name (required)

A unique name corresponding to the query being paginated, including specific values in the where clause and sorting specified in the order by clause.

query (required)

The actual query that returns the IDs of all rows in the results. Bind variables may be used.

Options:

-timeout

The lifetime of a query result in seconds, after which the query must be refreshed (if not reset).

-pagesize

The number of rows to display on a single page.

-groupsize

The number of pages in a group, for UI purposes. This is useful for result sets which span several pages. For example, if you have 1000 results at 10 results per page, that will leave you with 100 pages and you may not want to display 1-100 in the UI. In this case, setting a groupsize of 10 will allow you to display pages 1-10, then 11-20, and so on. The default groupsize is 10.

-contextual

Boolean indicating whether the pagination interface presented to the user will provide some other contextual clue in addition or instead of page number, such as the first few letters of a title or date. By default, the second column in the result set returned by query will be used as the context.

-page_offset

The first page in a set of page groups to be created by this paginator. This can be used to slice very large sets of page groups into paginators, cached separately (be sure to name each page group's paginator uniquely if you're caching pagination query results). Very useful since filling the cache for an entire set of page groups can be very costly, and since often only the first few pages of items (for instance, forum threads) are visited through the pagination interface. The list builder provides an example of how to do this.

Partial Call Graph (max 5 caller/called nodes):

Testcases:

No testcase defined.

Source code:

    set level [template::adp_level]
    variable parse_level
    set parse_level $level

    # maintain paginator properties in stack frame of current template
    upvar #$level pq:$name:properties opts

    variable defaults
    array set opts $defaults
    template::util::get_opts $args

    set cache_key    $name:$query
    set row_ids [template::cache get $cache_key:row_ids]

    # full number of rows returned by original paginator query
    set full_row_count [template::cache get $cache_key:full_row_count]

    #
    # GN: In the following line, we had instead of [::cache exists
    # $cache_key] the commdand [nsv_exists __template_cache_timeout
    # $cache_key] It is not clear, what the intended semantic was, and
    # why not the API working on the nsv was used. See as well
    # below. In general, using a test for a cache entry and a code
    # depending on the cached entry is NOT AN GOOD idea, since the
    # operations are not atomic. Between the check and the later code,
    # the cache entry might be deleted.  refactoring of this code is
    # recommended. Unfortunately, several places in OpenACS have this
    # problem.
    #
    if { ($row_ids eq {} && ![template::cache exists $cache_key])
         || ([info exists opts(flush_p)] && $opts(flush_p) == "t")
    } {
        if { [info exists opts(printing_prefs)] && $opts(printing_prefs) ne "" } {
            lassign $opts(printing_prefs) title stylesheet background header_file footer_file return_url
            if { $stylesheet ne "" } {
                set css_link [subst {<link rel="stylesheet" href="[ns_quotehtml $stylesheet]" type="text/css">}]
            } else {
                set css_link ""
            }
            if { $background ne "" } {
                set bg "background=\"$background\""
            } else {
                set bg ""
            }

            ad_return_top_of_page [subst {
                <html>
                <head>
                <title>$title</title>
                <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
                $css_link
                </head>
                <body $bg>
            }]
            if { $header_file ne "" } {
                ns_write [ns_adp_parse -file $header_file]
            }
            ns_write [lindex $opts(printing_prefs) 6]
            init $statement_name $name $query 1
            ns_write [lindex $opts(printing_prefs) 7]
            if { $footer_file ne "" } {
                ns_write [ns_adp_parse -file $footer_file]
            }
            if { $return_url ne "" } {
                # Not sure, what the intended semantics of this command was...
                #if { [llength $opts(row_ids)]==0 } {
                #   nsv_set __template_cache_timeout $cache_key $opts(timeout)
                #}
                ns_write [subst {
                    <script type="text/javascript" nonce="[security::csp::nonce]">
                    document.location.href="[ns_quotehtml $return_url]";
                    </script>
                    <noscript><a href="[ns_quotehtml $return_url]">Click here to continue.</a></noscript>
                }]
            }
            ad_script_abort
        } else {
            init $statement_name $name $query
        }
    } else {
        set opts(row_ids) $row_ids
        set opts(full_row_count) $full_row_count
        set opts(context_ids) [template::cache get $cache_key:context_ids]
    }

    set opts(row_count) [llength $opts(row_ids)]
    set opts(page_count) [expr {[get_page $name $opts(row_count)] + $opts(page_offset)}]
    set opts(group_count) [get_group $name $opts(page_count)]

XQL Not present:

PostgreSQL, Oracle

Generic XQL file:

packages/acs-templating/tcl/paginator-procs.xql