template::list::create (public)

 template::list::create -name name [ -multirow multirow ] [ -key key ] \
    [ -pass_properties pass_properties ] [ -actions actions ] \
    [ -bulk_actions bulk_actions ] \
    [ -bulk_action_method bulk_action_method ] \
    [ -bulk_action_export_vars bulk_action_export_vars ] \
    [ -selected_format selected_format ] [ -has_checkboxes ] \
    [ -checkbox_name checkbox_name ] [ -orderby_name orderby_name ] \
    [ -row_pretty_plural row_pretty_plural ] [ -no_data no_data ] \
    [ -main_class main_class ] [ -sub_class sub_class ] \
    [ -class class ] [ -html html ] [ -caption caption ] \
    [ -page_size page_size ] \
    [ -page_size_variable_p page_size_variable_p ] \
    [ -page_groupsize page_groupsize ] [ -page_query page_query ] \
    [ -page_query_name page_query_name ] \
    [ -page_flush_p page_flush_p ] [ -ulevel ulevel ] \
    -elements elements [ -filters filters ] [ -groupby groupby ] \
    [ -orderby orderby ] [ -formats formats ] \
    [ -filter_form filter_form ] \
    [ -bulk_action_click_function bulk_action_click_function ] \
    [ -aggregation_format aggregation_format ]

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

Defines a list to be displayed in a template. The list works in conjunction with a multirow, which contains the data for the list. The list is output using the <listtemplate> and <listfilters> templating tags, with the help of <listelement> and <listrow>.

Here's an example of a fairly simple standard list.

    template::list::create  -name order_lines  -multirow order_lines  -key item_id  -actions [list "Add item" [export_vars -base item-add {order_id}] "Add item to this order"]  -bulk_actions {
            "Remove" "item-remove" "Remove checked items"
            "Copy" "item-copy" "Copy checked items to clipboard"
        }  -bulk_action_method post  -bulk_action_export_vars {
            order_id
        }  -row_pretty_plural "order items"  -elements {
            quantity {
                label "Quantity"
            }
            item_id {
                label "Item"
                display_col item_name
                link_url_col item_url
                link_html { title "View this item" }
            }
            item_price {
                label "Price"
                display_eval {[lc_sepfmt $item_price]}
            }
            extended_price {
                label "Extended Price"
                display_eval {[lc_sepfmt [expr {$quantity $item_price}]]}
            }
        }

    db_multirow -extend { item_url } order_lines select_order_lines {
        select l.item_id,
        l.quantity,
        i.name as item_name,
        i.price as item_price
        from   order_lines l,
        items i
        where  l.order_id = :order_id
        and    i.item_id = l.item_id
    } {
        set item_url [export_vars -base "item" { item_id }]
    }
    

And the ADP template would include this:

    <listtemplate name="order_lines"></listtemplate>
    

Switches:

-name (required)

The name of the list you want to build.

-multirow (optional)

The name of the multirow which you want to loop over. Defaults to name of the list.

-key (optional)

The name of the column holding the primary key/unique identifier for each row. Must be a single column, which must be present in the multirow. This switch is required to have bulk actions.

-pass_properties (optional)

A list of variables in the caller's namespace, which should be available to the display_template of elements.

-actions (optional)

A list of action buttons to display at the top of the list in the form (label1 url1 title1 label2 url2 title2 ...). The action button will be a simple link to the url.

-bulk_actions (optional)

A list of bulk action buttons, operating on the checked rows, to display at the bottom of the list. The format is (label1 url1 title1 label2 url2 title2 ...). A form will be submitted to the url, containing a list of the key values of the checked rows. For example, if 'key' is 'message_id', and rows with message_id 2 4 and 9 are checked, the page will get variables message_id=2&message_id=4&message_id=9. The receiving page should declare message_id:naturalnum,multiple in its ad_page_contract. Note that the 'message_id' local variable will the be a Tcl list.

-bulk_action_method (optional, defaults to "get")

should a bulk action be a "get" or "post"

-bulk_action_export_vars (optional)

A list of additional variables to pass to the receiving page, along with the other variables for the selected keys. This is typically useful if the rows in this list are all hanging off of one row in a parent table. For example, if this list contains the order lines of one particular order, and the primary key of the order lines table is 'order_id, item_id', the key would be 'item_id', and bulk_action_export_vars would be 'order_id', so together they constitute the primary key.

-selected_format (optional)

The currently selected display format. See the 'formats' option.

-has_checkboxes (optional, boolean)

Set this flag if your table already includes the checkboxes for the bulk actions. If not, and your list has bulk actions, we will add a checkbox column for you as the first column.

-checkbox_name (optional, defaults to "checkbox")

You can explicitly name the checkbox column here, so you can refer to it and place it where you want it when you specify display formats. Defaults to 'checkbox'. See the 'formats' option.

-orderby_name (optional, defaults to "orderby")

The page query variable name for the selected orderby is normally named 'orderby', but if you want to, you can override it here.

-row_pretty_plural (optional, defaults to "#acs-templating.data#")

The pretty name of the rows in plural. For example 'items' or 'forum postings'. This is used to auto-generate the 'no_data' message to say "No (row_pretty_plural)." Defaults to 'data'. See 'no_data' below.

-no_data (optional)

The message to display when the multirow has no rows. Defaults to 'No data.'.

-main_class (optional, defaults to "list-table")

The main CSS class to be used in the output. The CSS class is constructed by combining the main_class and the sub_class with a dash in between. E.g., main_class could be 'list', and sub_class could be 'narrow', in which case the resulting CSS class used would be 'list-narrow'.

-sub_class (optional)

The sub-part of the CSS class to use. See 'main_class' option.

-class (optional)

Alternatively, you can specify the CSS class directly. If specified, this overrides main_class/sub_class.

-html (optional)

HTML attributes to be output for the table tag, e.g. { align right style "background-color: yellow;" }. Value should be a Tcl list with { name value name value }

-caption (optional)

Caption tag that appears right below the table tag. Required for AA. Added 2/27/2007

-page_size (optional)

The number of rows to display on each page. If specified, the list will be paginated.

-page_size_variable_p (optional, defaults to "0")

Displays a selectbox to let the user change the number of rows to display on each page. If specified, the list will be paginated.

-page_groupsize (optional, defaults to "10")

The page group size for the paginator. See template::paginator::create for more details.

-page_query (optional)

The query to get the row IDs and contexts for the entire result set. See template::paginator::create for details.

-page_query_name (optional)

Alternatively, you can specify a query name. See template::paginator::create for details.

-page_flush_p (optional, defaults to "0")

-ulevel (optional, defaults to "1")

The number of levels to uplevel when doing subst on values for elements, filters, groupbys, orderbys and formats below. Defaults to one level up, which means the caller of template::list::create's scope.

-elements (required)

The list elements (columns). The value should be an array-list of (element-name, spec) pairs, like in the example above. Each spec, in turn, is an array-list of property-name/value pairs, where the value is 'subst'ed in the caller's environment, except for the *_eval properties, which are 'subst'ed in the multirow context. See template::list::element::create for details.

-filters (optional)

Filters for the list. Typically used to slice the data, for example to see only rows by a particular user. Array-list of (filter-name, spec) pairs, like elements. Each spec, in turn, is an array-list of property-name/value pairs, where the value is 'subst'ed in the caller's environment, except for the *_eval properties, which are 'subst'ed in the multirow context. In order for filters to work, you have to specify them in your page's ad_page_contract, typically as filter_name:optional. The list builder will find them from there, by grabbing them from your page's local variables. See template::list::filter::create for details. filters are also the mechanism to export state variables which need to be preserved. If for example you needed user_id to be maintained for the filter and sorting links you would add -filters {user_id {}}

-groupby (optional)

Things you can group by, e.g. day, week, user, etc. Automatically creates a filter called 'groupby'. Single array-list of property-name/value pairs, where the value is 'subst'ed in the caller's environment. Groupby is really just a filter with a fixed name, so see above for more details. See template::list::filter::create for details.

-orderby (optional)

Things you can order by. You can also specify ordering directly in the elements. Automatically creates a filter called 'orderby'. Array-list of (orderby-name, spec) pairs, like elements. Each spec, in turn, is an array-list of property-name/value pairs, where the value is 'subst'ed in the caller's environment, except for the *_eval properties, which are 'subst'ed in the multirow context. If the name of your orderby is the same as the name of an element, that element's header will be made a link to sort by that column. See template::list::orderby::create for details.

-formats (optional)

If no formats are specified, a default format is created. Automatically creates a filter called 'format'. Array-list of (format-name, spec) pairs, like elements. Each spec, in turn, is an array-list of property-name/value pairs, where the value is 'subst'ed in the caller's environment. See template::list::format::create for details.

-filter_form (optional, defaults to "0")

Whether or not we create the form data structure for the listfilters-form tag to dynamically generate a form to specify filter criteria. Default 0 will not generate form. Set to 1 to generate form to use listfilters-form tag.

-bulk_action_click_function (optional, defaults to "acs_ListBulkActionClick")

JavaScript function name to call when bulk action buttons are clicked.

-aggregation_format (optional)

An option to format the result (number) of an aggregation operation. Default is empty string (result is not formatted). See the Tcl built-in command format for details on the different formatting options.

See Also:

• template::list::element::create
• template::list::filter::create
• template::list::orderby::create
• template::list::format::create

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

Testcases:

No testcase defined.