template::list::element::create (public)

 template::list::element::create -list_name list_name \
    -element_name element_name -spec spec [ -ulevel ulevel ]

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

Adds an element to a list builder list.

This proc shouldn't be called directly, only through template::list::create.

These are the available properties in the spec:

• label: The label to use in the header.
• hide_p: 1 to hide the element from the default display, 0 (default) to show it.
• aggregate: Aggregate function to use on this column. Can be 'sum', 'average', or 'count'. The aggregate will be displayed at the bottom of the table. If groupby is used, aggregates for each group will also be displayed.
• aggregate_label: The label to use for the aggregate, e.g. "Total".
• aggregate_group_label: The label to use for the group aggregate, e.g. "Subtotal".
• html: HTML attributes to be output for the table element, e.g. { align right style "background-color: yellow;" }. Value should be a Tcl list with { name value name value }
• display_col: The column to display for this element, if not the column with the same name as the element.
• display_template: An ADP chunk used to display the element. This overrides all other display options. You can use @multirow_name.column_name@ to get values of the multirow, and you can directly use the variables specified in the 'pass_properties' argument to the template::list::create.
• display_template_name: theme-able template. If a display_template_name is specified, and a file with this name is available from the resource directory in the display_templates section, then take its countent as display_template. The resource directory is taken from the ResourceDir of the theme (parameter of acs-sub-site) or from the "resources" directory in acs-templating. The display_template_name acts similar to the query names in the database interface: When display_template_name is specified and the file is available, it overrules display_template, which acts as a default.
• link_url_col: Name of column in the multirow which contains the URL to which the cell contents should point. If either link_url_col or link_url_eval is specified, the cell's contents will be made a link to the specified URL, if that URL is nonempty.
• link_url_eval: A chunk of Tcl code which will be evaluated in the context of a template::multirow foreach looping over the dataset multirow, to return the URL to link this cell to. This means that it will have all the columns of the multirow available as local variables. Example: link_url_eval {[acs_community_member_url -user_id $creation_user]}.
• link_html: Attributes to be set on the <a> tag of the link generated as a result of link_url_col or link_url_eval. For example link_html { title "View this user" style "background-color: yellow;" }. Value should be a Tcl list with { name value name value }
• csv_col: The column to return in CSV output.
• sub_class: The second half of the CSS class name. Will be combined with the list's 'main_class' property to form the full CSS class name with a dash in-between, as in 'main-sub'.
• class: Alternatively, you can specify full class here, in which case this will override the sub_class property.
• orderby: The column to use in the order by clause of the query, when sorting by this column. Specifying either this, or 'orderby_asc' and 'orderby_desc' will cause the table's header to become a hyperlink to sort by that column.
• orderby_asc: If you want to be able to sort by this column, but sorting ascending and descending is not just a matter of appending 'asc' or 'desc', you can specify the asc and desc orderby clauses directly. This is useful when you're actually sorting by two database columns.
• orderby_desc: The reverse ordering from 'orderby_asc'.
• default_direction: The default order direction when ordering by this column, 'asc' or 'desc'.

Switches:

-list_name (required)

Name of list.

-element_name (required)

Name of the element.

-spec (required)

The spec for this filter. This is an array list of property/value pairs, where the right hand side is 'subst'ed in the caller's namespace, except for *_eval properties, which are 'subst'ed inside the multirow.

-ulevel (optional, defaults to "1")

Where we should uplevel to when doing the subst's. Defaults to '1', meaning the caller's scope.

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

Testcases:

No testcase defined.

Source code:

    # Get an upvar'd reference to list_properties
    template::list::get_reference -name $list_name

    # Get the list properties
    lappend list_properties(elements) $element_name

    # We store the full element ref name, so its easy to find later
    lappend list_properties(element_refs) [get_refname -list_name $list_name -element_name $element_name]

    # Create the element properties array
    get_reference -create -list_name $list_name -element_name $element_name

    # Setup element defaults
    array set element_properties {
        label {}
        hide_p 0
        aggregate {}
        aggregate_label {}
        aggregate_group_label {}
        html {}
        display_col {}
        display_template {}
        display_template_name {}
        link_url_col {}
        link_url_eval {}
        link_html {}
        csv_col {}
        sub_class {}
        class {}
        orderby {}
        orderby_asc {}
        orderby_desc {}
        default_direction {}
        select_clause {}
        select_clause_eval {}
        from_clause {}
        from_clause_eval {}
        where_clause {}
        where_clause_eval {}
    }

    # These attributes are internal listbuilder attributes
    array set element_properties {
        subrownum 0
        aggregate_col {}
        aggregate_group_col {}
        cell_attributes {}
        orderby_asc {}
        orderby_desc {}
        default_direction {}
        orderby_url {}
        orderby_direction {}
        orderby_html_title {}
        ordering_p "f"
        class {}
    }

    # Let the element know its own name
    set element_properties(name) $element_name

    # Let the element know its owner's name
    set element_properties(list_name) $list_name

    incr ulevel

    set_properties  -list_name $list_name  -element_name $element_name  -spec $spec  -ulevel $ulevel

    # Default display_col to element name
    if { $element_properties(display_col) eq "" } {
        set element_properties(display_col) $element_properties(name)
    }

    # Default csv_col to display_col
    if { $element_properties(csv_col) eq "" } {
        set element_properties(csv_col) $element_properties(display_col)
    }

    # Default sub_class to list:sub_class
    if { $element_properties(sub_class) eq "" } {
        set element_properties(sub_class) $list_properties(sub_class)
    }

    # Default class to (list:main_class)-(element:sub_class)
    if { $element_properties(class) eq "" } {
        set element_properties(class) [join [concat $list_properties(main_class) $element_properties(sub_class)] "-"]
    }

    # Create the orderby filter, if specified
    if { $element_properties(orderby) ne "" || $element_properties(orderby_asc) ne "" || $element_properties(orderby_desc) ne "" } {
        set orderby_spec [list]
        foreach elm { orderby orderby_asc orderby_desc default_direction label } {
            if { $element_properties($elm) ne "" } {
                lappend orderby_spec $elm $element_properties($elm)
            }
        }

        template::list::orderby::create  -list_name $list_name  -orderby_name $element_properties(name)  -ulevel [expr {$ulevel + 1}]  -spec $orderby_spec
    }

XQL Not present:

Generic, PostgreSQL, Oracle