Index: openacs.org-dev/packages/acs-templating/tcl/parse-procs.tcl =================================================================== RCS file: /usr/local/cvsroot/openacs.org-dev/packages/acs-templating/tcl/parse-procs.tcl,v diff -u -r1.1.1.1 -r1.1.1.2 --- openacs.org-dev/packages/acs-templating/tcl/parse-procs.tcl 9 Jul 2002 17:34:59 -0000 1.1.1.1 +++ openacs.org-dev/packages/acs-templating/tcl/parse-procs.tcl 8 Oct 2002 15:46:50 -0000 1.1.1.2 @@ -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,21 @@ 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 <tag-type>]
+  set attribute [template::tag_attribute tag <attribute>]
+    
+ @param tag The name of the enclosing tag to look for. -# 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 } { - + @see template::enclosing_tag + @see template::tag_attribute +} { set name "" variable tag_stack @@ -596,22 +559,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 {}] } {