template::list::format::create (public)

 template::list::format::create -list_name list_name \
    -format_name format_name [ -selected_format selected_format ] \
    -spec spec [ -ulevel ulevel ]

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

Adds a format 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.
• layout: The layout, can be 'table' or 'list'.
• style: The name of the template to used to render this format. Defaults to the name of the layout, and can be overridden in the ADP file.
• output: Output format, can be either 'template' or 'csv'. If 'csv'. then the output is streamed directly to the browser and not through the templating system, but you have to call template::list::write_output from your page to make this work.
• page_size: The page size for this format. Leave blank to use the list's page size.
• elements: 'table' layout: An ordered list of elements to display in this format.
• row: 'table' layout: For more complex table layout, you can specify each row individually. The value is an array-list of ( element_name spec ) pairs. You can have more than one 'row' property, in which case your output table will have more than one HTML table row per row in the data set. In the 'spec' part of each element listed in the row, you can specify properties that override the properties defined in the -elements section of template::list::create, thus changing the label, link, display_col, etc.
• template: 'list' layout: An ADP chunk to be used for display of each row of the list. Use <listelement name="element_name"> to output a list element in your template.

Switches:

-list_name (required)

Name of list.

-format_name (required)

Name of the format.

-selected_format (optional)

-spec (required)

The spec for this format. 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 formats and their order
    lappend list_properties(formats) $format_name

    # Properties are going to be stored in an array named 'list-name:format:format-name:properties'
    set format_ref "$list_name:format:$format_name:properties"

    # We also store the full format array name, so its easy to find <
    lappend list_properties(format_refs) $format_ref

    # Upvar the format properties array
    upvar #$level $format_ref format_properties

    # Setup format defaults
    array set format_properties {
        label {}
        layout table
        style {}
        output template
        page_size {}
        elements {}
        row {}
        template {}
    }

    # Let the format know its own name
    set format_properties(name) $format_name

    # Let the format know its owner's name
    set format_properties(list_name) $list_name

    # Counting the row number within one row of the dataset
    set subrownum 0
    set elementnum 0

    foreach { key value } $spec {
        switch -- $key {
            row {
                # We only care about this for the currently selected format
                if {$format_name eq $selected_format} {

                    # This is the layout specification for table layouts
                    set value [uplevel $ulevel [list subst $value]]
                    incr subrownum

                    foreach { element_name spec } $value {
                        incr elementnum

                        template::list::element::get_reference  -list_name $list_name  -element_name $element_name

                        # Set elementnum and subrownum
                        set element_properties(elementnum) $elementnum
                        set element_properties(subrownum) $subrownum

                        # Set/override additional element properties from the spec
                        template::list::element::set_properties  -list_name $list_name  -element_name $element_name  -spec $spec  -ulevel [expr {$ulevel + 1}]

                        # Remember the display order
                        lappend list_properties(display_elements) $element_name
                    }
                }
            }
            template {
                # We only care about this for the currently selected format
                if {$format_name eq $selected_format} {
                    # All other vars, do an uplevel subst on the value now
                    set value [uplevel $ulevel [list subst $value]]
                    set format_properties($key) $value
                    set list_properties(row_template) $value
                }
            }
            default {
                # We require all properties to be initialized to the empty string in the array, otherwise they're illegal.
                if { ![info exists format_properties($key)] } {
                    error "Unknown format property '$key' for element '$format_name' in list '$list_name'. Allowed properties are [join [array names format_properties] ", "]."
                }

                # All other vars, do an uplevel subst on the value now
                set format_properties($key) [uplevel $ulevel [list subst $value]]
            }
        }
    }

    # For the currently selected format, copy some things over to the list properties
    if {$format_name eq $selected_format} {
        if { $format_properties(style) eq "" } {
            set format_properties(style) $format_properties(layout)
        }

        # Move style up to the list_properties
        if { $format_properties(style) ne "" } {
            set list_properties(style) $format_properties(style)
        }

        # Move output up to the list_properties
        if { $format_properties(output) ne "" } {
            set list_properties(output) $format_properties(output)
        }

        # Move page_size up to the list_properties
        if { $format_properties(page_size) ne "" } {
            set list_properties(page_size) $format_properties(page_size)
        }

        # Move elements up to the list_properties as display_elements
        if { $format_properties(elements) ne "" } {
            set list_properties(display_elements) $format_properties(elements)
        }

    }

    return [list $format_properties(label) $format_name]

XQL Not present:

Generic, PostgreSQL, Oracle