template::list::filter::create (public)

 template::list::filter::create -list_name list_name \
    -filter_name filter_name -spec spec [ -ulevel ulevel ]

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

Adds a filter 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 of the filter.
• hide_p: Set to 1 to hide this filter from default rendering.
• type: The type of values this filter sets. Also see 'values' below. Valid options are: 'singleval', meaning that the value is a single value of a query variable with the name of the filter; 'multival', meaning the value is really a Tcl list of values, sent to a :multiple page variable; and 'multivar', meaning that the value is a list of (key value) lists, as in { { var1 value1 } { var2 value 2 } }. 'multival' is useful when you're filtering on, say, a date range, in which case you'd send two values, namely the start and end date. 'multivar' is useful when you want the selection of one filter to change the value of another filter, for example when selecting groupby, you also want to order by the grouped by column, otherwise the groupby won't work properly (you'll get a new group each time the value changes, but it's not sorted by that column, so you'll get more than one group per value over the entire list).
• add_url_eval: An expression which will be uplevel subst'ed with a magic variable __filter_value set to the value of the given filter.
• values: A list of lists of possible filter values, as in { { label1 value1 count1 } { label2 value2 count2 } ... }. The 'label' is what's displayed when showing the available filter values. 'value' is what changes filter values, and, depending on 'type' above, can either be a single value, a list of values, or a list of ( name value ) pairs. 'count' is optional, and is the number of rows that match the given filter value.
• has_default_p: If set to 1, it means that this filter has a default value, and thus cannot be cleared. If not set, the list builder will automatically provide a link to clear the currently selected value of this filter. You only need to set this if you specify a default value in your page's ad_page_contract, instead of through the 'default_value' property below.
• default_value: The default value to use when no value is selected for this filter. Automatically sets has_default_p to 1.
• where_clause: What should go in the where clause of your query when filtering on this filter. For example "l.project_id = :project_id".
• where_clause_eval: Same as where_clause, except this gets evaluated in the caller's context.
• other_label: If your values above do not carry all possible values, we can display a special 'other' value when some other value is selected for this filter. You specify here what label should be used for that element.
• form_element_properties: If you are using filter form, additional properties to override the form element declaration. Any valid form properties can be passed using the same names are template::element::create. A list of name value pairs.

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.

Switches:

-list_name (required)

Name of list.

-filter_name (required)

Name of the filter.

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

    set level [template::adp_level]

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

    # Remember the filters and their order
    lappend list_properties(filters) $filter_name

    # Properties are going to be stored in an array named 'list-name:filter:filter-name:properties'
    if {$filter_name eq ""} {
        error "Invalid filter name for list '$list_name', spec: $spec"
    }
    set filter_ref "$list_name:filter:$filter_name:properties"

    # We also store the full filter array name, so its easy to find <
    lappend list_properties(filter_refs) $filter_ref

    # Upvar the filter properties array
    upvar #$level $filter_ref filter_properties

    # Setup filter defaults
    array set filter_properties {
        label {}
        hide_p 0
        type singleval
        add_url_eval {}
        values {}
        has_default_p 0
        default_value {}
        where_clause {}
        where_clause_eval {}
        null_where_clause {}
        null_where_clause_eval {}
        from_clause {}
        from_clause_eval {}
        select_clause {}
        select_clause_eval {}
        other_label {}
        null_label {}
        form_element_properties {}
    }

    # Prepopulate some automatically generated values
    array set filter_properties {
        clear_url {}
        urls {}
        add_urls {}
        selected_p {}
    }

    # Let the filter know its own name
    set filter_properties(name) $filter_name

    # Let the filter know its owner's name
    set filter_properties(list_name) $list_name

    set_properties  -list_name $list_name  -filter_name $filter_name  -spec $spec  -ulevel [expr {$ulevel + 1}]

    # This is to be used by the export_vars function
    switch -- $filter_properties(type) {
        singleval - multivar {
            set filter_properties(var_spec) $filter_name
        }
        multival {
            set filter_properties(var_spec) "${filter_name}:multiple"
        }
    }
    lappend list_properties(filters_export) $filter_properties(var_spec)

XQL Not present:

Generic, PostgreSQL, Oracle