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:
- Options:
- 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.
- -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