Index: openacs-4/packages/acs-templating/tcl/0-procs.tcl =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/tcl/Attic/0-procs.tcl,v diff -u -r1.5 -r1.6 --- openacs-4/packages/acs-templating/tcl/0-procs.tcl 19 Jul 2002 23:17:15 -0000 1.5 +++ openacs-4/packages/acs-templating/tcl/0-procs.tcl 31 Aug 2002 02:01:41 -0000 1.6 @@ -101,9 +101,9 @@ namespace export form element request } -# Generic wrapper for registered tag handlers. - ad_proc -public template_tag { name arglist body } { + Generic wrapper for registered tag handlers. +} { switch [llength $arglist] { Index: openacs-4/packages/acs-templating/tcl/acs-integration-procs.tcl =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/tcl/acs-integration-procs.tcl,v diff -u -r1.4 -r1.5 --- openacs-4/packages/acs-templating/tcl/acs-integration-procs.tcl 21 Aug 2002 18:15:37 -0000 1.4 +++ openacs-4/packages/acs-templating/tcl/acs-integration-procs.tcl 31 Aug 2002 02:01:41 -0000 1.5 @@ -32,6 +32,8 @@ ad_proc -public ad_template_return {{file_stub ""}} { + Alias proc (wrapper) for ad_return_template +} { uplevel 1 "ad_return_template $file_stub" } Index: openacs-4/packages/acs-templating/tcl/doc-tcl-procs.tcl =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/tcl/doc-tcl-procs.tcl,v diff -u -r1.4 -r1.5 --- openacs-4/packages/acs-templating/tcl/doc-tcl-procs.tcl 21 Aug 2002 18:15:37 -0000 1.4 +++ openacs-4/packages/acs-templating/tcl/doc-tcl-procs.tcl 31 Aug 2002 02:01:41 -0000 1.5 @@ -67,22 +67,6 @@ } -# @private find_marker_indices -# given a body of text and a text marker, returns a list of position indices -# for each occurrence of the text marker - -# @param text body of text to be searched through -# @param marker the text-divider mark - -# @return list of indices of the position immediately preceding each -# occurrence of the text marker; if there are no occurrences -# of the text marker, returns a zero-element list - -# @see namespace doc -# @see proc doc::parse_file -# @see proc doc::parse_namespace doc.html#doc::parse_namespace -# @see proc doc::util::text_divider - ad_proc -private doc::util::find_marker_indices { text marker } { given a body of text and a text marker, returns a list of position indices for each occurrence of the text marker @@ -193,7 +177,6 @@ ad_proc -private template::util::proper_noun { string_ref } { - @private proper_noun capitalizes the first letter of a string @return returns formatted string (UNFINISHED. FIXME.) } { @@ -294,10 +277,6 @@ } -# @private set_proc_name_source_txt -# called by parse_comment_text -# @param comment_text this should include the source text - ad_proc -private doc::set_proc_name_source_text_comment_text { proc_block } { called by parse_comment_text @param comment_text this should include the source text @@ -543,34 +522,39 @@ ad_proc -private doc::parse_file { path } { Parse API documentation from a Tcl page API documentation is parsed as follows: - Document is scanned until a @namespace directive is encountered. + Valid directives in a procedure doc include: - - @author - - @param (for hard parameters) - - @see (should have the form namespace::procedure. A reference to an + - +

Reads the text for a file and scans for a namespace directive. When one is encountered, reads until the next namespace or EOF and calls doc::parse_namespace on the accumulated lines to get procedure documentation. - +

creates a multirow variable in the variable name designated by result_ref with columns namespace_name, proc_name, public_private, author, param, option, see, return and source_text - +

Note that this format is suitable for passing to array set for creating a lookup on namespace name. } { Index: openacs-4/packages/acs-templating/tcl/element-procs.tcl =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/tcl/element-procs.tcl,v diff -u -r1.4 -r1.5 --- openacs-4/packages/acs-templating/tcl/element-procs.tcl 12 May 2002 20:57:02 -0000 1.4 +++ openacs-4/packages/acs-templating/tcl/element-procs.tcl 31 Aug 2002 02:01:41 -0000 1.5 @@ -15,49 +15,61 @@ eval template::element::$command $form_id $element_id $args } -# @public create +ad_proc -public template::element::create { form_id element_id args } { + Append an element to a form object. If a submission is in progress, + values for the element are prepared and validated. -# Append an element to a form object. If a submission is in progress, -# values for the element are prepared and validated. + @param form_id The identifier of the form to which the element is to + be added. The form must have been previously created + with a form create statement. -# @param form_id The identifier of the form to which the element is to -# be added. The form must have been previously created -# with a form create statement. -# @param element_id A keyword identifier for the element that is unique -# in the context of the form. -# @option widget The name of an input widget for the element. Valid -# widgets must have a rendering procedure defined in -# the template::widget namespace. -# @option datatype The name of a datatype for the element values. Valid -# datatypes must have a validation procedure defined in -# the template::data::validate namespace. -# @option html A list of name-value attribute pairs to include in -# the HTML tag for widget. Typically used for additional -# formatting options, such as cols or rows, -# or for JavaScript handlers. + @param element_id A keyword identifier for the element that is unique + in the context of the form. -# @option options A list of options for select lists and button groups -# (check boxes or radio buttons). The list contains -# two-element lists in the form -# { {label value} {label value} {label value} ...} -# @option value The default value of the element -# @option values The default values of the element, where multiple values -# are allowed (checkbox groups and multiselect widgets) -# @option validate A list of custom validation blocks in the form -# { name { expression } { message } \ -# name { expression } { message } ...} -# where name is a unique identifier for the validation step, -# expression is a block to Tcl code that evaluates to -# 1 or 0, and message is to be displayed to the user when -# the validation step fails. -# @option optional A flag indicating that no value is required for this -# element. If a default value is specified, the default -# is used instead. + @option widget The name of an input widget for the element. Valid + widgets must have a rendering procedure defined in + the template::widget namespace. -ad_proc -public template::element::create { form_id element_id args } { + @option datatype The name of a datatype for the element values. Valid + datatypes must have a validation procedure defined in + the template::data::validate namespace. + + + @option html A list of name-value attribute pairs to include in + the HTML tag for widget. Typically used for additional + formatting options, such as cols or + rows, or for JavaScript handlers. + + + @option options A list of options for select lists and button groups + (check boxes or radio buttons). The list contains + two-element lists in the form + { {label value} {label value} {label value} ...} + + + @option value The default value of the element + + + @option values The default values of the element, where multiple values + are allowed (checkbox groups and multiselect widgets) + + + @option validate A list of custom validation blocks in the form + { name { expression } { message } \ + name { expression } { message } ...} + where name is a unique identifier for the validation + step, expression is a block to Tcl code that evaluates to + 1 or 0, and message is to be displayed to the user when + the validation step fails. + + + @option optional A flag indicating that no value is required for this + element. If a default value is specified, the default + is used instead. +} { set level [template::adp_level] # add the element to the element list @@ -116,18 +128,16 @@ } -# @public set_properties +ad_proc -public template::element::set_properties { form_id element_id args } { + Modify properties of an existing element. The same options may be + used as with the create command. Most commonly used to set the + default value for an element when a form page is initially requested. -# Modify properties of an existing element. The same options may be -# used as with the create command. Most commonly used to set the -# default value for an element when a form page is initially requested. + @param form_id The identifier of the form containing the element. + @param element_id The unique identifier of the element. -# @param form_id The identifier of the form containing the element. -# @param element_id The unique identifier of the element. - -# @see create - -ad_proc -public template::element::set_properties { form_id element_id args } { + @see create +} { get_reference # create a reference to opts as expected by get_opts @@ -138,35 +148,30 @@ copy_value_to_values_if_defined } -# @public set_value - -# Sets the value of an element - -# @param form_id The identifier of the form containing the element. -# @param element_id The unique identifier of the element. -# @param value The value to apply - ad_proc -public template::element::set_value { form_id element_id value } { + Sets the value of an element + @param form_id The identifier of the form containing the element. + @param element_id The unique identifier of the element. + @param value The value to apply +} { + get_reference set element(value) $value set element(values) [list $value] } -# @public get_value - -# Retrieves the current value of an element. Typically used following -# a valid form submission to retrieve the submitted value. - -# @param form_id The identifier of the form containing the element. -# @param element_id The unique identifier of the element. - -# @return The current value of the element. -# @see get_values - ad_proc -public template::element::get_value { form_id element_id } { + Retrieves the current value of an element. Typically used following + a valid form submission to retrieve the submitted value. + @param form_id The identifier of the form containing the element. + @param element_id The unique identifier of the element. + + @return The current value of the element. + @see get_values +} { get_reference if { [info exists element(value)] } { @@ -176,40 +181,34 @@ } } -# @public get_values - -# Retrieves the list current values for an element. Typically used -# following a valid form submission where multiple values may have -# been submitted for a single element (i.e. for a checkbox group or -# multiple select box). - -# @param form_id The identifier of the form containing the element. -# @param element_id The unique identifier of the element. - -# @return A list of current values for the element. -# @see get_value - ad_proc -public template::element::get_values { form_id element_id } { + Retrieves the list current values for an element. Typically used + following a valid form submission where multiple values may have + been submitted for a single element (i.e. for a checkbox group or + multiple select box). + @param form_id The identifier of the form containing the element. + @param element_id The unique identifier of the element. + + @return A list of current values for the element. + @see get_value +} { get_reference return $element(values) } -# @public get_property - -# Retrieves the specified property of the element, such as value, -# datatype, widget, etc. - -# @param form_id The identifier of the form containing the element. -# @param element_id The unique identifier of the element. -# @param property The property to be retreived - -# @return The value of the property, or "" if the property does not exist -# @see set_properties - ad_proc -public template::element::get_property { form_id element_id property } { + Retrieves the specified property of the element, such as value, + datatype, widget, etc. + @param form_id The identifier of the form containing the element. + @param element_id The unique identifier of the element. + @param property The property to be retreived + + @return The value of the property, or "" if the property does not exist + @see set_properties +} { get_reference if { ![info exists element($property)] } { @@ -219,22 +218,23 @@ } } -# @private validate +ad_proc -private template::element::validate { form_id element_id } { + Validates element values according to 3 criteria: +

    +
  1. required elements must have a not-null value; +
  2. values must match the element's declared datatype; +
  3. values must pass all special validation filters specified with + the -validate option when the element was created. +
+

+ If validation fails for any reason, + one or more messages are added to the error list for the form, + causing the submission to be invalidated and returned to the user + for correction. -# Validates element values according to 3 criteria: (1) required -# elements must have a not-null value; (2) values must -# match the element's declared datatype; (3) values must pass -# all special validation filters specified with the -validate option -# when the element was created. If validation fails for any reason, -# one or more messages is added to the error list for the form, -# causing the submission to be invalidated and returned to the user -# for correction. - -# @param form_id The identifier of the form containing the element. -# @param element_id The unique identifier of the element. - -ad_proc -public template::element::validate { form_id element_id } { - + @param form_id The identifier of the form containing the element. + @param element_id The unique identifier of the element. +} { set level [template::adp_level] # use an array to hold error messages for this form @@ -352,21 +352,18 @@ } } -# @public set_error - -# Manually set an error message for an element. This may be used to -# implement validation filters that involve more than one form element -# ("Sorry, blue is not available for the model you selected, please -# choose another color.") - -# @param form_id The identifier of the form containing the element. -# @param element_id The unique identifier of the element with which -# the error message should be associated in the form -# template. -# @param message The text of the error message. - ad_proc -public template::element::set_error { form_id element_id message } { + Manually set an error message for an element. This may be used to + implement validation filters that involve more than one form element + ("Sorry, blue is not available for the model you selected, please + choose another color.") + @param form_id The identifier of the form containing the element. + @param element_id The unique identifier of the element with which + the error message should be associated in the form + template. + @param message The text of the error message. +} { set level [template::adp_level] upvar #$level $form_id:error formerror @@ -375,18 +372,15 @@ set formerror($element_id) $message } -# @public error_p - -# Return true if the named element has an error set. Helpful for client code -# that wants to avoid overwriting an initial error message. - -# @param form_id The identifier of the form containing the element. -# @param element_id The unique identifier of the element with which -# the error message should be associated in the form -# template. - ad_proc -public template::element::error_p { form_id element_id } { + Return true if the named element has an error set. Helpful for client code + that wants to avoid overwriting an initial error message. + @param form_id The identifier of the form containing the element. + @param element_id The unique identifier of the element with which + the error message should be associated in the form + template. +} { set level [template::adp_level] upvar #$level $form_id:error formerror @@ -395,11 +389,10 @@ return [info exists formerror($element_id)] } -# Get all values for an element, performing any transformation defined -# for the datatype. - ad_proc -public template::element::querygetall { element_ref } { - + Get all values for an element, performing any transformation defined + for the datatype. +} { upvar $element_ref element set datatype $element(datatype) @@ -420,17 +413,14 @@ return $values } -# @public exists - -# Determine if an element exists in a specified form - -# @param form_id The identifier of the form containing the element. -# @param element_id The unique identifier of the element within the form. - -# @return 1 if the element exists in the form, or 0 otherwise - ad_proc -public template::element::exists { form_id element_id } { + Determine if an element exists in a specified form + @param form_id The identifier of the form containing the element. + @param element_id The unique identifier of the element within the form. + + @return 1 if the element exists in the form, or 0 otherwise +} { set level [template::adp_level] upvar #$level $form_id:$element_id element_properties @@ -440,12 +430,12 @@ # @private get_reference -# Gets a reference to the array containing the properties of an -# element, and throws and error if the element does not exist. Called -# at the beginning of several of the element commands. ad_proc -public template::element::get_reference {} { - + Gets a reference to the array containing the properties of an + element, and throws and error if the element does not exist. Called + at the beginning of several of the element commands. +} { uplevel { set level [template::adp_level] @@ -457,22 +447,19 @@ } } -# @private render +ad_proc -private template::element::render { form_id element_id tag_attributes } { + Generate the HTML for a particular form widget. -# Generate the HTML for a particular form widget. + @param form_id The identifier of the form containing the element. + @param element_id The unique identifier of the element within the form. + @param tag_attributes A name-value list of addditional HTML + attributes to include in the tag, such as JavaScript + handlers or special formatting (i.e. ROWS and COLS + for a TEXTAREA). -# @param form_id The identifier of the form containing the element. -# @param element_id The unique identifier of the element within the form. -# @param tag_attributes A name-value list of addditional HTML -# attributes to include in the tag, such as JavaScript -# handlers or special formatting (i.e. ROWS and COLS -# for a TEXTAREA). - -# @return A string containing the HTML for an INPUT, SELECT or TEXTAREA -# form element. - -ad_proc -public template::element::render { form_id element_id tag_attributes } { - + @return A string containing the HTML for an INPUT, SELECT or TEXTAREA + form element. +} { get_reference # Remember that the element has been rendered already @@ -481,34 +468,28 @@ return [template::widget::$element(widget) element $tag_attributes] } -# @private render_help +ad_proc -private template::element::render_help { form_id element_id tag_attributes } { + Render the -help_text text -# Render the -help_text text - -# @param form_id The identifier of the form containing the element. -# @param element_id The unique identifier of the element within the form. -# @param tag_attributes Reserved for future use. - -ad_proc -public template::element::render_help { form_id element_id tag_attributes } { - + @param form_id The identifier of the form containing the element. + @param element_id The unique identifier of the element within the form. + @param tag_attributes Reserved for future use. +} { get_reference return $element(help_text) } -# @private options +ad_proc -private template::element::options { form_id element_id tag_attributes } { + Prepares a multirow data source for use within a formgroup -# Prepares a multirow data source for use within a formgroup - -# @param form_id The identifier of the form containing the element. -# @param element_id The unique identifier of the element within the form. -# @param tag_attributes A name-value list of addditional HTML -# attributes to include in the INPUT tags for each -# radio button or checkbox, such as JavaScript -# handlers or special formatting. - -ad_proc -public template::element::options { form_id element_id tag_attributes } { - + @param form_id The identifier of the form containing the element. + @param element_id The unique identifier of the element within the form. + @param tag_attributes A name-value list of addditional HTML + attributes to include in the INPUT tags for each + radio button or checkbox, such as JavaScript + handlers or special formatting. +} { get_reference if { ! [info exists element(options)] } { @@ -555,13 +536,9 @@ } } - - -# @private copy_value_to_values_if_defined - -# define values from value, if the latter is more defined - -ad_proc -public template::element::copy_value_to_values_if_defined {} { +ad_proc -private template::element::copy_value_to_values_if_defined {} { + define values from value, if the latter is more defined +} { upvar opts opts # values is always defined, init to "" from template::element::defaults if { [info exists opts(value)] && [llength $opts(values)] == 0 } { Index: openacs-4/packages/acs-templating/tcl/file-procs.tcl =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/tcl/file-procs.tcl,v diff -u -r1.1 -r1.2 --- openacs-4/packages/acs-templating/tcl/file-procs.tcl 19 Jul 2002 23:17:15 -0000 1.1 +++ openacs-4/packages/acs-templating/tcl/file-procs.tcl 31 Aug 2002 02:01:41 -0000 1.2 @@ -1,7 +1,8 @@ -# The new file type returns the list { file_name temp_file_name content_mime_type }. -ad_proc -public template::data::transform::file { element_ref } { +ad_proc -public template::data::transform::file { element_ref } { + @return the list { file_name temp_file_name content_mime_type }. +} { upvar $element_ref element set element_id $element(id) @@ -19,9 +20,11 @@ } -# Our file widget can't fail - ad_proc -public template::data::validate::file { value_ref message_ref } { + Our file widget can't fail + + @return true +} { return 1 } Index: openacs-4/packages/acs-templating/tcl/filter-procs.tcl =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/tcl/filter-procs.tcl,v diff -u -r1.5 -r1.6 --- openacs-4/packages/acs-templating/tcl/filter-procs.tcl 9 Mar 2002 02:00:02 -0000 1.5 +++ openacs-4/packages/acs-templating/tcl/filter-procs.tcl 31 Aug 2002 02:01:41 -0000 1.6 @@ -9,10 +9,9 @@ # License. Full text of the license is available from the GNU Project: # http://www.fsf.org/copyleft/gpl.html -# Redirect and abort processing - ad_proc -public template::forward { url } { - + Redirect and abort processing +} { # DRB: The code that was here before didn't preserve the protocol, always # using HTTP even if HTTPS was used to establish the connection. Besides # which ad_returnredirect has funky checks for even funkier browsers, and @@ -23,13 +22,12 @@ ad_script_abort } -# Run any filter procedures that have been registered with the -# templating system. The signature of a filter procedure is -# a reference (not the value) to a variable containing the URL of -# the template to parse. The filter procedure may modify this. - ad_proc -public template::filter { command args } { - + Run any filter procedures that have been registered with the + templating system. The signature of a filter procedure is + a reference (not the value) to a variable containing the URL of + the template to parse. The filter procedure may modify this. +} { variable filter_list set arg1 [lindex $args 0] @@ -55,10 +53,9 @@ # "/foo"-style URLs would require fixing it, too. Also ACS 4.2 had these # debugging filters enabled by default. I've turned them off by default. -# Show the compiled template (for debugging) - ad_proc -public cmp_page_filter { why } { - + Show the compiled template (for debugging) +} { if { [catch { set url [ns_conn url] regsub {.cmp} $url {} url_stub @@ -83,10 +80,9 @@ return filter_return } -# Show the comments for the template (for designer) - ad_proc -public dat_page_filter { why } { - + Show the comments for the template (for designer) +} { if { [catch { set url [ns_conn url] regsub {.dat} $url {} url_stub Index: openacs-4/packages/acs-templating/tcl/form-procs.tcl =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/tcl/form-procs.tcl,v diff -u -r1.4 -r1.5 --- openacs-4/packages/acs-templating/tcl/form-procs.tcl 19 Jan 2002 22:10:14 -0000 1.4 +++ openacs-4/packages/acs-templating/tcl/form-procs.tcl 31 Aug 2002 02:01:41 -0000 1.5 @@ -19,26 +19,24 @@ eval template::form::$command $args } -# @public create +ad_proc -public template::form::create { id args } { + Initialize the data structures for a form. -# Initialize the data structures for a form. + @param id A keyword identifier for the form, such as "add_user" or + "edit_item". The ID must be unique in the context of a + single page. -# @param id A keyword identifier for the form, such as "add_user" or -# "edit_item". The ID must be unique in the context of a single page. + @option method The standard METHOD attribute to specify in the HTML FORM + tag at the beginning of the rendered form. Defaults to POST. -# @option method The standard METHOD attribute to specify in the HTML FORM -# tag at the beginning of the rendered form. Defaults to POST. + @option html A list of additional name-value attribute pairs to + include in the HTML FORM tag at the beginning of the + rendered form. Common attributes include JavaScript + event handlers and multipart form encoding. For example, + "-html { enctype multipart/form-data onSubmit validate() }" -# @option html A list of additional name-value attribute pairs to -# include in the HTML FORM tag at the beginning of the rendered form. -# Common attributes include JavaScript event handlers and multipart -# form encoding. For example, "-html { enctype multipart/form-data -# onSubmit validate() }" - -# @option elements A block of element specifications. - -ad_proc -public template::form::create { id args } { - + @option elements A block of element specifications. +} { set level [template::adp_level] # keep form properties and a list of the element items @@ -80,36 +78,30 @@ } } } - -# @public exists - -# Determine whether a form exists by checking for its data structures. - -# @param id The ID of an ATS form object. - -# @return 1 if a form with the specified ID exists. 0 if it does not. ad_proc -public template::form::exists { id } { + Determine whether a form exists by checking for its data structures. + @param id The ID of an ATS form object. + + @return 1 if a form with the specified ID exists. 0 if it does not. +} { set level [template::adp_level] upvar #$level $id:elements elements return [info exists elements] } -# @private template +ad_proc -private template::form::template { id { style "" } } { + Auto-generate the template for a form -# Auto-generate the template for a form + @param id The form identifier + @param style The style template to use when generating the form. + Form style templates must be placed in the forms + subdirectory of the ATS resources directory. -# @param id The form identifier -# @param style The style template to use when generating the form. -# Form style templates must be placed in the forms -# subdirectory of the ATS resources directory. - -# @return A string containing a template for the body of the form. - -ad_proc -public template::form::template { id { style "" } } { - + @return A string containing a template for the body of the form. +} { get_reference set elements:rowcount 0 @@ -147,19 +139,16 @@ return $__adp_output } -# @private generate +ad_proc -private template::form::generate { id { style "" } } { + Render the finished HTML output for a dynamic form. -# Render the finished HTML output for a dynamic form. + @param id The form identifier + @param style The style template to use when generating the form. + Form style templates must be placed in the forms + subdirectory of the ATS resources directory. -# @param id The form identifier -# @param style The style template to use when generating the form. -# Form style templates must be placed in the forms -# subdirectory of the ATS resources directory. - -# @return A string containing the HTML for the body of the form. - -ad_proc -public template::form::generate { id { style "" } } { - + @return A string containing the HTML for the body of the form. +} { set __adp_output [template $id $style] set level [template::adp_level] @@ -182,37 +171,31 @@ return [template::adp_eval code] } -# @public section - -# Set the name of the current section of the form. A form may be -# divided into any number of sections for layout purposes. Elements -# are tagged with the current section name as they are added to the -# form. A form style template may insert a divider in the form -# whenever the section name changes. - -# @param id The form identifier. -# @param section The name of the current section. - ad_proc -public template::form::section { id section } { + Set the name of the current section of the form. A form may be + divided into any number of sections for layout purposes. Elements + are tagged with the current section name as they are added to the + form. A form style template may insert a divider in the form + whenever the section name changes. + @param id The form identifier. + @param section The name of the current section. +} { get_reference set properties(section) $section } -# @private render +ad_proc -private template::form::render { id tag_attributes } { + Render the HTML FORM tag along with a hidden element that identifies + the form object. -# Render the HTML FORM tag along with a hidden element that identifies -# the form object. + @param id The form identifier + @param tag_attributes A name-value list of special attributes to add + to the FORM tag, such as JavaScript event handlers. -# @param id The form identifier -# @param tag_attributes A name-value list of special attributes to add -# to the FORM tag, such as JavaScript event handlers. - -# @return A string containing the rendered tags. - -ad_proc -public template::form::render { id tag_attributes } { - + @return A string containing the rendered tags. +} { get_reference # make a reference to the formerror array with any validation messages @@ -262,16 +245,13 @@ return $output } -# @private check_elements +ad_proc -private template::form::check_elements { id } { + Iterates over all declared elements, checking for hidden widgets and + rendering those that have not been rendered yet. Called after rendering + a custom form template as a debugging aid. -# Iterates over all declared elements, checking for hidden widgets and -# rendering those that have not been rendered yet. Called after rendering -# a custom form template as a debugging aid. - -# @param id The form identifier - -ad_proc -public template::form::check_elements { id } { - + @param id The form identifier +} { get_reference set output "" @@ -302,55 +282,46 @@ return $output } -# @public is_request - -# Return true if preparing a form for an initial request (as opposed -# to repreparing a form that is returned to the user due to validation -# problems). This command is used to conditionally set default values -# for form elements. - -# @param id The form identifier - -# @return 1 if true or 0 if false - ad_proc -public template::form::is_request { id } { + Return true if preparing a form for an initial request (as opposed + to repreparing a form that is returned to the user due to validation + problems). This command is used to conditionally set default values + for form elements. + @param id The form identifier + + @return 1 if preparing a form for an initial request; or 0 if + repreparing a form that is returned to the user due to + validation problems +} { return [expr ! [is_submission $id]] } -# Return true if submission in progress - -# @public is_submission - -# Return true if a submission in progress. The submission may or may not -# be valid. - -# @param id The form identifier - -# @return 1 if true or 0 if false - ad_proc -public template::form::is_submission { id } { + Return true if a submission in progress. The submission may or may not + be valid. + @param id The form identifier + + @return 1 if true or 0 if false +} { set level [template::adp_level] upvar #$level $id:submission submission return $submission } -# @public is_valid - -# Return true if submission in progress and submission was valid. -# Typically used to conditionally execute DML and redirect to the next -# page, as opposed to returning the form back to the user to report -# validation errors. - -# @param id The form identifier - -# @return 1 if true or 0 if false - ad_proc -public template::form::is_valid { id } { + Return true if submission in progress and submission was valid. + Typically used to conditionally execute DML and redirect to the next + page, as opposed to returning the form back to the user to report + validation errors. + @param id The form identifier + + @return 1 if id is the form identifier of a valid submission or 0 otherwise +} { set level [template::adp_level] upvar #$level $id:submission submission @@ -370,18 +341,15 @@ } } -# @public get_values - -# Set local variables for form variables (assume they are all single values). -# Typically used when processing the form submission to prepare for DML -# or other type of transaction. - -# @param id The form identifier -# @param args A list of element identifiers. If the list is empty, -# retreive all form elements - ad_proc -public template::form::get_values { id args } { + Set local variables for form variables (assume they are all single values). + Typically used when processing the form submission to prepare for DML + or other type of transaction. + @param id The form identifier + @param args A list of element identifiers. If the list is empty, + retrieve all form elements +} { if { [llength $args] > 0 } { set elements $args } else { @@ -397,20 +365,19 @@ } } -# @public get_combined_values - -# Return a list which represents the result of getting combined values -# from multiple form elements - -# @param id The form identifier -# @param args A list of element identifiers. Each identifier may be -# a regexp. For example, form get_combined_values "foo.*" -# will combine the values of all elements starting with -# "foo" -# @param return The combined list of values -# ad_proc -public template::form::get_combined_values { id args } { + Return a list which represents the result of getting combined values + from multiple form elements + @param id The form identifier + @param args A list of element identifiers. Each identifier may be + a regexp. For example, + form get_combined_values "foo.*" + will combine the values of all elements starting with + "foo" + + @return The combined list of values +} { get_reference set exp [join $args "|"] @@ -426,19 +393,16 @@ return $values } -# @public set_values - -# Convenience procedure to set individual values of a form (useful for -# simple update forms). Typical usage is to query a onerow data -# source from database and pass the resulting array reference to -# set_values for setting default values in an update form. - -# @param id The form identifier -# @param array_ref The name of a local array variable whose -# keys correspond to element identifiers in the form - ad_proc -public template::form::set_values { id array_ref } { + Convenience procedure to set individual values of a form (useful for + simple update forms). Typical usage is to query a onerow data + source from database and pass the resulting array reference to + set_values for setting default values in an update form. + @param id The form identifier + @param array_ref The name of a local array variable whose + keys correspond to element identifiers in the form +} { upvar 2 $array_ref values foreach name [array names values] { @@ -449,17 +413,14 @@ } } -# @public export - -# Generates hidden input tags for all values in a form submission. -# Typically used to create a confirmation page following an initial -# submission. - -# @return A string containing hidden input tags for inclusion in a -# form. - ad_proc -public template::form::export {} { + Generates hidden input tags for all values in a form submission. + Typically used to create a confirmation page following an initial + submission. + @return A string containing hidden input tags for inclusion in a + form. +} { set form [ns_getform] if { $form == "" } { return "" } @@ -478,25 +439,18 @@ return $export_data } - -# @public size - -# Return the number of elements in a form - -# @param id The form identifier - ad_proc -public template::form::size { id } { + @param id The form identifier + @return the number of elements in the form identified by id +} { template::form::get_reference return [llength $elements] } -# @private get_reference - -# Helper procedure used to access the basic data structures of a form object. -# Called by several of the form commands. - -ad_proc -public template::form::get_reference {} { - +ad_proc -private template::form::get_reference {} { + Helper procedure used to access the basic data structures of a form object. + Called by several of the form commands. +} { uplevel { set level [template::adp_level] Index: openacs-4/packages/acs-templating/tcl/paginator-procs.tcl =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/tcl/paginator-procs.tcl,v diff -u -r1.5 -r1.6 --- openacs-4/packages/acs-templating/tcl/paginator-procs.tcl 13 Aug 2002 16:45:49 -0000 1.5 +++ openacs-4/packages/acs-templating/tcl/paginator-procs.tcl 31 Aug 2002 02:01:41 -0000 1.6 @@ -14,29 +14,31 @@ eval paginator::$command $args } -# @public create +ad_proc -public template::paginator::create { statement_name name query args } { + 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. -# 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. + @param name A unique name corresponding to the query being + paginated, including specific values in the where + clause and sorting specified in the order by clause. -# @param name A unique name corresponding to the query being paginated, -# including specific values in the where clause and sorting -# specified in the order by clause. -# @param query The actual query that returns the IDs of all rows in the -# results. Bind variables may be used. -# @option timeout The lifetime of a query result in seconds, after which -# the query must be refreshed. -# @option pagesize The number of rows to display on a single page. -# @option groupsize The number of pages in a group, for UI purposes. -# @option 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. + @param query The actual query that returns the IDs of all rows in + the results. Bind variables may be used. -ad_proc -public template::paginator::create { statement_name name query args } { + @option timeout The lifetime of a query result in seconds, after which + the query must be refreshed. + @option pagesize The number of rows to display on a single page. + + @option groupsize The number of pages in a group, for UI purposes. + + @option 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. +} { set level [template::adp_level] variable parse_level set parse_level $level @@ -63,12 +65,9 @@ set opts(group_count) [get_group $name $opts(page_count)] } -# @private init - -# Initialize a paginated query. Only called by create. - -ad_proc -public template::paginator::init { statement_name name query } { - +ad_proc -private template::paginator::init { statement_name name query } { + Initialize a paginated query. Only called by create. +} { get_reference # query for an ordered list of all row identifiers to cache @@ -117,76 +116,71 @@ } } -# @public get_page - -# Calculates the page on which the specified row is located. - -# @param name The reference to the paginator object. -# @param rownum A number ranging from one to the number of rows in the -# query result. - -# @return A number ranging from one to the number of pages in the query result. - ad_proc -public template::paginator::get_page { name rownum } { + Calculates the page on which the specified row is located. + @param name The reference to the paginator object. + @param rownum A number ranging from one to the number of rows in the + query result, representing the number of a row therein. + + @return A number ranging from one to the number of pages in + the query result, representing the number of the page + the specified row is located in. +} { get_reference set pagesize $properties(pagesize) return [expr ($rownum - 1 - (($rownum - 1) % $pagesize)) / $pagesize + 1] } -# @public get_row - -# Calculates the first row displayed on a page. - -# @param name The reference to the paginator object. -# @param pagenum A number ranging from one to the number of pages in -# the query result. - -# @return A number ranging from one to the number of rows in the query result. - ad_proc -public template::paginator::get_row { name pagenum } { + Calculates the first row displayed on a page. + @param name The reference to the paginator object. + @param pagenum A number ranging from one to the number of pages in + the query result, representing the number of a page + therein. + + @return A number ranging from one to the number of rows in + the query result, representing the number of the first + row on the specified page. +} { get_reference return [expr ($pagenum - 1) * $properties(pagesize) + 1] } -# @public get_group - -# Calculates the page group in which the specified page is located. - -# @param name The reference to the paginator object. -# @param pagenum A number ranging from one to the number of pages in -# the query result. - -# @return A number ranging from one to the number of groups in the query -# result, as determined by both the page size and the group size. - ad_proc -public template::paginator::get_group { name pagenum } { + Calculates the page group in which the specified page is located. + @param name The reference to the paginator object. + @param pagenum A number ranging from one to the number of pages in + the query result. + + @return A number ranging from one to the number of groups in the query + result, as determined by both the page size and the group size. + This number represents the page group number that the specified + page lies in. +} { get_reference set groupsize $properties(groupsize) return [expr ($pagenum - 1 - (($pagenum - 1) % $groupsize)) / $groupsize + 1] } -# @public get_row_ids - -# Gets a list of IDs in a page, selected from the master ID list -# generated by the initial query submitted for pagination. IDs are -# typically primary key values. - -# @param name The reference to the paginator object. -# @param pagenum A number ranging from one to the number of pages in -# the query result. - -# @return A Tcl list of row identifiers. - ad_proc -public template::paginator::get_row_ids { name pagenum } { + Gets a list of IDs in a page, selected from the master ID list + generated by the initial query submitted for pagination. IDs are + typically primary key values. + @param name The reference to the paginator object. + @param pagenum A number ranging from one to the number of pages in + the query result. + + @return A Tcl list of row identifiers. +} { get_reference set pagesize $properties(pagesize) @@ -199,18 +193,15 @@ return $ids } -# @public get_pages - -# Gets a list of pages in a group, truncating if appropriate at the end. - -# @param name The reference to the paginator object. -# @param group A number ranging from one to the number of page groups in -# the query result. - -# @return A Tcl list of page numbers. - ad_proc -public template::paginator::get_pages { name group } { + Gets a list of pages in a group, truncating if appropriate at the end. + @param name The reference to the paginator object. + @param group A number ranging from one to the number of page groups in + the query result. + + @return A Tcl list of page numbers. +} { get_reference set group_count $properties(group_count) @@ -238,20 +229,17 @@ return $pages } -# @public get_groups - -# Determines the set of groups to which a group belongs, and calculates the -# starting page of each group in that set. - -# @param name The reference to the paginator object. -# @param group A number ranging from one to the number of page groups in -# the query result. -# @param count The desired size of the group set. - -# @return A Tcl list of page numbers. - ad_proc -public template::paginator::get_groups { name group count } { + Determines the set of groups to which a group belongs, and calculates the + starting page of each group in that set. + @param name The reference to the paginator object. + @param group A number ranging from one to the number of page groups in + the query result. + @param count The desired size of the group set. + + @return A Tcl list of page numbers. +} { get_reference set group_count $properties(group_count) @@ -282,22 +270,19 @@ return $pages } -# @public get_context - -# Gets the context cues for a set of pages in the form of a multirow -# data source with 3 columns: rownum (starting with 1); page (number -# of the page); and context (a short string such as the first few -# letters of a name or title). The context cues may be used in the -# paging interface along with or instead of page numbers. This -# command is only valid if the contextual option is specified when -# creating the paginator. - -# @param name The reference to the paginator object. -# @param datasource The name of the multirow datasource to create -# @param pages A Tcl list of page numbers. - ad_proc -public template::paginator::get_context { name datasource pages } { + Gets the context cues for a set of pages in the form of a multirow + data source with 3 columns: rownum (starting with 1); page (number + of the page); and context (a short string such as the first few + letters of a name or title). The context cues may be used in the + paging interface along with or instead of page numbers. This + command is only valid if the contextual option is specified when + creating the paginator. + @param name The reference to the paginator object. + @param datasource The name of the multirow datasource to create + @param pages A Tcl list of page numbers. +} { get_reference if { ! [info exists properties(context_ids)] } { @@ -320,69 +305,75 @@ } } -# @public get_row_count - -# Gets the total number of records in the paginated query - -# @param name The reference to the paginator object. - -# @return A number representing the row count. - ad_proc -public template::paginator::get_row_count { name } { + Gets the total number of records in the paginated query + @param name The reference to the paginator object. + + @return A number representing the row count. +} { get_reference return $properties(row_count) } -# @public get_page_count - -# Gets the total number of pages in the paginated query - -# @param name The reference to the paginator object. - -# @return A number representing the page count. - ad_proc -public template::paginator::get_page_count { name } { + Gets the total number of pages in the paginated query + @param name The reference to the paginator object. + + @return A number representing the page count. +} { get_reference return $properties(row_count) } -# @public get_group_count - -# Gets the total number of groups in the paginated query - -# @param name The reference to the paginator object. - -# @return A number represeting the group count. - ad_proc -public template::paginator::get_group_count { name } { + Gets the total number of groups in the paginated query + @param name The reference to the paginator object. + + @return A number represeting the group count. +} { get_reference return $properties(group_count) } -# @public get_display_info - -# Make paginator display properties available as a onerow data source: -# next_page: following page or empty string if at end -# previous_page: preceeding page or empty string if at beginning -# next_group: page that begins the next page group or empty string if -# at end -# previous_group: page the begins the last page group or -# empty string if at endl. -# page_count: the number of pages -# -# @param name The reference to the paginator object. -# @param datasource The name of the onerow datasource to create -# @param page A page number representing the reference point from -# which the display properties are calculated. - ad_proc -public template::paginator::get_display_info { name datasource page } { + Make paginator display properties available as a onerow data source: + + + + + + + + + + + + + + + + + + + + + +
next_page:following page or empty string if at end
previous_page:preceeding page or empty string if at beginning
next_group:page that begins the next page group or empty string if + at end
previous_group:page that begins the last page group or + empty string if at endl.
page_count:the number of pages
+ + @param name The reference to the paginator object. + @param datasource The name of the onerow datasource to create + @param page A page number representing the reference point from + which the display properties are calculated. +} { get_reference upvar 2 $datasource info @@ -411,20 +402,17 @@ } } -# @public get_data - -# Sets a multirow data source with data for the rows on the current page. -# The pseudocolumn "all_rownum" is added to each row, indicating the -# index of the row relative to all rows across all pages. - -# @param name The reference to the paginator object. -# @param datasource The name of the datasource to create. -# @param query The query to execute, containing IN (CURRENT_PAGE_SET). -# @param id_column The name of the ID column in the display query (required -# to order rows properly). - ad_proc -public template::paginator::get_data { statement_name name datasource query id_column page } { + Sets a multirow data source with data for the rows on the current page. + The pseudocolumn "all_rownum" is added to each row, indicating the + index of the row relative to all rows across all pages. + @param name The reference to the paginator object. + @param datasource The name of the datasource to create. + @param query The query to execute, containing IN (CURRENT_PAGE_SET). + @param id_column The name of the ID column in the display query (required + to order rows properly). +} { set ids [get_row_ids $name $page] # calculate the base row number for the page @@ -468,12 +456,9 @@ " } -# @private get_reference - -# Get a reference to the paginator properties (internal helper) - -ad_proc -public template::paginator::get_reference {} { - +ad_proc -private template::paginator::get_reference {} { + Get a reference to the paginator properties (internal helper) +} { uplevel { variable parse_level Index: openacs-4/packages/acs-templating/tcl/parse-procs.tcl =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/tcl/parse-procs.tcl,v diff -u -r1.4 -r1.5 --- openacs-4/packages/acs-templating/tcl/parse-procs.tcl 10 Feb 2002 22:11:31 -0000 1.4 +++ openacs-4/packages/acs-templating/tcl/parse-procs.tcl 31 Aug 2002 02:01:41 -0000 1.5 @@ -11,21 +11,19 @@ # License. Full text of the license is available from the GNU Project: # http://www.fsf.org/copyleft/gpl.html -# @private adp_parse +ad_proc -private template::adp_parse { __adp_stub __args } { + Execute procedures to prepare data sources and then to output + template. -# Execute procedures to prepare data sources and then to output -# template. - -# @param __adp_stub The root (without the file extension) of the -# absolute path to the template and associated code. -# @param __args One list containing any number of key-value pairs passed -# to an included template from its container. All -# data sources may be passed by reference. - -ad_proc -public template::adp_parse { __adp_stub __args } { - + @param __adp_stub The root (without the file extension) of the + absolute path to the template and associated code. + @param __args One list containing any number of key-value pairs + passed to an included template from its container. + All data sources may be passed by reference. +} { # declare any variables passed in to an include or master # TODO: call adp_set_vars instead. + foreach {__key __value} $__args { if {[string match "&*" $__key]} { # "&" triggers call by reference if {[string compare "&" $__key]} { @@ -100,14 +98,11 @@ return $__adp_output ; # empty in non-templated page } -# @private adp_set_vars - -# Set variables passes from a container template, including onerow and -# multirow data sources. This code must be executed in the same stack frame -# as adp_parse, but is in a separate proc to improve code readability. - -ad_proc -public template::adp_set_vars {} { - +ad_proc -private template::adp_set_vars {} { + Set variables passes from a container template, including onerow and + multirow data sources. This code must be executed in the same stack frame + as adp_parse, but is in a separate proc to improve code readability. +} { uplevel { set __adp_level [adp_level 2] foreach {__adp_key __adp_value} $args { @@ -135,23 +130,21 @@ } } } - -# @public adp_abort - # Terminates processing of a template and throws away all output. -ad_proc -public template::adp_abort {} { error ADP_ABORT } +ad_proc -public template::adp_abort {} { + Terminates processing of a template and throws away all output. +} { + error ADP_ABORT +} -# @public adp_eval - -# Evaluates a chunk of compiled template code in the calling stack frame. -# The resulting output is placed in __adp_output in the calling frame, -# and also returned for convenience. - -# @return The output produced by the compiled template code. - ad_proc -public template::adp_eval { coderef } { + Evaluates a chunk of compiled template code in the calling stack frame. + The resulting output is placed in __adp_output in the calling frame, + and also returned for convenience. + @return The output produced by the compiled template code. +} { upvar $coderef code eval "uplevel { @@ -169,23 +162,20 @@ return $output } -# @public adp_level - -# Get the stack frame level at which the template is being evaluated. -# This is used extensively for obtaining references to data sources, -# as well template objects such as forms and wizards - -# @param up A relative reference to the "parse level" of interest. -# Useful in the context of an included template to reach into the -# stack frame in which the container template is being parsed, for -# accessing data sources or other objects. The default is the -# highest parse level. - -# @return A number, as returned by [info level], representing the stack frame -# in which a template is being parsed. - ad_proc -public template::adp_level { { up "" } } { + Get the stack frame level at which the template is being evaluated. + This is used extensively for obtaining references to data sources, + as well template objects such as forms and wizards + @param up A relative reference to the "parse level" of interest. + Useful in the context of an included template to reach into the + stack frame in which the container template is being parsed, for + accessing data sources or other objects. The default is the + highest parse level. + + @return A number, as returned by [info level], representing the stack frame + in which a template is being parsed. +} { set result "" variable parse_level @@ -203,29 +193,25 @@ return $result } -# @public adp_levels -# Get all stack frame levels ad_proc -public template::adp_levels {} { + @return all stack frame levels +} { variable parse_level if { [info exists parse_level] } {return $parse_level} return "" } +ad_proc -private template::adp_prepare {} { + Executes the code to prepare the data sources for a template. The + code is executed in the stack frame of the calling procedure + (adp_parse) so that variables are accessible when the compiled + template code is executed. If the preparation code executes the + set_file command, the procedure will recurse and execute the code + for the next template as well. -# @private adp_prepare - -# Executes the code to prepare the data sources for a template. The -# code is executed in the stack frame of the calling procedure -# (adp_parse) so that variables are accessible when the compiled -# template code is executed. If the preparation code executes the -# set_file command, the procedure will recurse and execute the code -# for the next template as well. - -# @return boolean (0 or 1): whether the (ultimate) script was found. - -ad_proc -public template::adp_prepare {} { - + @return boolean (0 or 1): whether the (ultimate) script was found. +} { uplevel { if { [file exists $__adp_stub.tcl] } { @@ -256,43 +242,37 @@ } } -# @public set_file - -# Set the path of the template to render. This is typically used to -# implement multiple "skins" on a common set of data sources. The -# initial code (which may be in a .tcl file not associated with a .adp -# file) sets up any number of data sources, and then calls set_file to -# specify the template to actually render. Any code associated with -# the specified template is executed in the same stack frame as the -# initial code, so that each "skin" may reference additional specific -# data or logic as necessary. - -# @param path The root (sans file extension) of the absolute path to the -# next template to parse. - ad_proc -public template::set_file { path } { - + Set the path of the template to render. This is typically used to + implement multiple "skins" on a common set of data sources. The + initial code (which may be in a .tcl file not associated with a .adp + file) sets up any number of data sources, and then calls set_file to + specify the template to actually render. Any code associated with + the specified template is executed in the same stack frame as the + initial code, so that each "skin" may reference additional specific + data or logic as necessary. + + @param path The root (sans file extension) of the absolute path to the + next template to parse. +} { set level [adp_level] upvar #$level __adp_stub file_stub set file_stub $path } -# @private adp_init +ad_proc -private template::adp_init { type file_stub } { + Ensures that both data source tcl files and compiled adp templates + are wrapped in procedures in the current interpreter. Procedures + are cached in byte code form in the interpreter, so this is more + efficient than sourcing a tcl file or parsing the template every + time. Also checks the modification time on the source file to + ensure that the procedure is up-to-date. -# Ensures that both data source tcl files and compiled adp templates -# are wrapped in procedures in the current interpreter. Procedures -# are cached in byte code form in the interpreter, so this is more -# efficient than sourcing a tcl file or parsing the template every -# time. Also checks the modification time on the source file to -# ensure that the procedure is up-to-date. - -# @param type Either adp (template) or tcl (code) -# @param file_stub The root (sans file extension) of the absolute path -# to the .adp or .tcl file to source. - -ad_proc -public template::adp_init { type file_stub } { - + @param type Either adp (template) or tcl (code) + @param file_stub The root (sans file extension) of the absolute path + to the .adp or .tcl file to source. +} { # this will return the name of the proc if it exists set proc_name [info procs ::template::mtimes::${type}::$file_stub] @@ -331,21 +311,18 @@ } } -# @public adp_compile - -# Converts an ADP template into a chunk of Tcl code. Caching this code -# avoids the need to reparse the ADP template with each request. - -# @param source_type Indicates the source of the Tcl code to compile. -# Valid options are -string or -file -# @param source A string containing either the template itself (for -# -string) or the path to the file containing the -# template (for -file) - -# @return The compiled code. - ad_proc -public template::adp_compile { source_type source } { + Converts an ADP template into a chunk of Tcl code. Caching this code + avoids the need to reparse the ADP template with each request. + @param source_type Indicates the source of the Tcl code to compile. + Valid options are -string or -file + @param source A string containing either the template itself (for + -string) or the path to the file containing the + template (for -file) + + @return The compiled code. +} { variable parse_list # initialize the compiled code set parse_list [list "set __adp_output \"\""] @@ -392,18 +369,15 @@ return $code } -# @private adp_compile_chunk +ad_proc -private template::adp_compile_chunk { chunk } { + Parses a single chunk of a template. A chunk is either the entire + template or the portion of a template contained within a balanced + tag. This procedure does not return the compiled chunk; compiled + code is assembled in the template::parse_list variable. -# Parses a single chunk of a template. A chunk is either the entire -# template or the portion of a template contained within a balanced -# tag. This procedure does not return the compiled chunk; compiled -# code is assembled in the template::parse_list variable. - -# @param chunk A string containing markup, potentially with embedded -# ATS tags. - -ad_proc -public template::adp_compile_chunk { chunk } { - + @param chunk A string containing markup, potentially with embedded + ATS tags. +} { # parse the template chunk inside the tag set remaining [ns_adp_parse -string $chunk] @@ -418,33 +392,27 @@ } } -# @private adp_append_string +ad_proc -private template::adp_append_string { s } { + Adds a line of code that appends a string to the Tcl output + from the compiler. -# Adds a line of code that appends a string to the Tcl output -# from the compiler. - -# @param s A string containing markup that does not contain any embedded -# ATS tags. Variable references and procedure calls are -# interpreted as for any double-quoted string in Tcl. - -ad_proc -public template::adp_append_string { s } { - + @param s A string containing markup that does not contain any embedded + ATS tags. Variable references and procedure calls are + interpreted as for any double-quoted string in Tcl. +} { adp_append_code "append __adp_output \"$s\"" } -# @private adp_append_code +ad_proc -private template::adp_append_code { code { nobreak "" } } { + Adds a line of code to the Tcl output from the compiler. -# Adds a line of code to the Tcl output from the compiler. + @param code A line of Tcl code -# @param code A line of Tcl code - -# @option nobreak Flag indicating that code should be appended to the -# current last line rather than adding a new line, for -# cases where code must continue on the same line, such -# as the else tag - -ad_proc -public template::adp_append_code { code { nobreak "" } } { - + @option nobreak Flag indicating that code should be appended to the + current last line rather than adding a new line, for + cases where code must continue on the same line, such + as the else tag +} { if { [string is space $code] } { return } variable parse_list @@ -461,29 +429,23 @@ } } -# @private adp_puts +ad_proc -private template::adp_puts { text } { + Add text to the ADP currently being rendered. May be used within escaped + Tcl code in the template to add to the output. -# Add text to the ADP currently being rendered. May be used within escaped -# Tcl code in the template to add to the output. - -# @param text A string containing text or markup. - -ad_proc -public template::adp_puts { text } { - + @param text A string containing text or markup. +} { upvar __adp_output __adp_output append __adp_output $text } -# @private adp_tag_init +ad_proc -private template::adp_tag_init { {tag_name ""} } { + Called at the beginning of every tag handler to flush the ADP buffer of + output accumulated from the last tag (or from the beginning of the file). -# Called at the beginning of every tag handler to flush the ADP buffer of -# output accumulated from the last tag (or from the beginning of the file). - -# @param tag_name The name of the tag. Used for debugging purposes only. - -ad_proc -public template::adp_tag_init { {tag_name ""} } { - + @param tag_name The name of the tag. Used for debugging purposes only. +} { # add everything either from the beginning of the template or from # the last balanced tag up to the current point in the template @@ -563,20 +525,17 @@ return $name } -# @private get_enclosing_tag +ad_proc -private -deprecated template::get_enclosing_tag { tag } { + Reach back into the tag stack for the last enclosing instance of a tag. + Typically used where the usage of a tag depends on its context, such + as the "group" tag within a "multiple" tag. + + Deprecated, use: + set tag [template::enclosing_tag ] + set attribute [template::tag_attribute tag ] -# Reach back into the tag stack for the last enclosing instance of a tag. -# Typically used where the usage of a tag depends on its context, such -# as the "group" tag within a "multiple" tag. -# -# Deprecated, use: -# set tag [template::enclosing_tag ] -# set attribute [template::tag_attribute tag ] - -# @param tag The name of the enclosing tag to look for. - -ad_proc -public -deprecated template::get_enclosing_tag { tag } { - + @param tag The name of the enclosing tag to look for. +} { set name "" variable tag_stack @@ -596,22 +555,19 @@ return $name } -# @private get_attribute +ad_proc -private template::get_attribute { tag params name { default "" } } { + Retrieves a named attribute value from the parameter set passed to a + tag handler. If a default is not specified, assumes the attribute + is required and throws an error. -# Retrieves a named attribute value from the parameter set passed to a -# tag handler. If a default is not specified, assumes the attribute -# is required and throws an error. + @param tag The name of the tag. + @param params The ns_set passed to the tag handler. + @param name The name of the attribute. + @param default A default value to return if the the attribute is + not specified in the template. -# @param tag The name of the tag. -# @param params The ns_set passed to the tag handler. -# @param name The name of the attribute. -# @param default A default value to return if the the attribute is -# not specified in the template. - -# @return The value of the attribute. - -ad_proc -public template::get_attribute { tag params name { default "" } } { - + @return The value of the attribute. +} { set value [ns_set iget $params $name] if { [string equal $value {}] } {