Index: openacs-4/packages/acs-templating/tcl/request-procs.tcl =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/tcl/request-procs.tcl,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-templating/tcl/request-procs.tcl 9 May 2001 05:15:58 -0000 1.2 +++ openacs-4/packages/acs-templating/tcl/request-procs.tcl 1 Sep 2002 02:24:57 -0000 1.3 @@ -23,17 +23,14 @@ eval request::$command $args } -# @public create - -# Create the request data structure. Typically called at the beginning -# of the code for any page that accepts query parameters. - -# @option params A block of parameter declarations, separated by newlines. -# Equivalent to calling set_param for each parameter, but -# requiring slightly less typing. - ad_proc -public template::request::create { args } { + Create the request data structure. Typically called at the beginning + of the code for any page that accepts query parameters. + @option params A block of parameter declarations, separated by newlines. + Equivalent to calling set_param for each parameter, but + requiring slightly less typing. +} { eval template::form::create request $args set level [template::adp_level] @@ -56,36 +53,33 @@ } } -# @public set_param +ad_proc -public template::request::set_param { name args } { + Declares a query parameter as part of the page request. Validates + the values associated with the parameter, in the same fashion as for + form elements. -# Declares a query parameter as part of the page request. Validates -# the values associated with the parameter, in the same fashion as for -# form elements. + @param name The name of the parameter to declare. -# @param name The name of the parameter to declare. + @option name The name of parameter in the query (may be different + from the reference name). + @option multiple A flag indicating that multiple values may be specified + for this parameter. + @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 optional A flag indicating that no value is required for this + element. If a default value is specified, the default + is used instead. + @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 name The name of parameter in the query (may be different -# from the reference name). -# @option multiple A flag indicating that multiple values may be specified -# for this parameter. -# @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 optional A flag indicating that no value is required for this -# element. If a default value is specified, the default -# is used instead. -# @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. - -# @see element::create - -ad_proc -public template::request::set_param { name args } { - + @see element::create +} { set level [template::adp_level] eval template::element::create request $name $args @@ -100,16 +94,14 @@ } # " -# @public get_param -# Retrieves the value(s) of the specified parameter. - -# @param name The name of the parameter. - -# @return The value of the specified parameter. - ad_proc -public template::request::get_param { name } { + Retrieves the value(s) of the specified parameter. + @param name The name of the parameter. + + @return The value of the specified parameter. +} { set level [template::adp_level] upvar #$level request:$name param @@ -126,19 +118,16 @@ return $value } -# @public error - -# Manually report request error(s) by setting error messages and then -# calling is_valid to handle display. Useful for conditions not tied -# to a single query parameter. The arguments to the procedure may be -# any number of name-message combinations. - -# @param name A unique identifier for the error condition, which may -# be used for layout purposes. -# @param msg The message text associated with the condition. - ad_proc -public template::request::error { args } { + Manually report request error(s) by setting error messages and then + calling is_valid to handle display. Useful for conditions not tied + to a single query parameter. The arguments to the procedure may be + any number of name-message combinations. + @param name A unique identifier for the error condition, which may + be used for layout purposes. + @param msg The message text associated with the condition. +} { set level [template::adp_level] upvar #$level request:error requesterror foreach { name msg } $args { @@ -148,21 +137,18 @@ is_valid } -# @public is_valid - -# Checks for any param errors. If errors are found, sets the display -# template to the specified URL (a system-wide request error page by -# default). - -# @param url The URL of the template to use to display error messages. -# The special value "self" may be used to indicate that the template -# for the requested page itself will handle reporting error -# conditions. - -# @return 1 if no error conditions exist, 0 otherwise. - ad_proc -public template::request::is_valid { { url "" } } { + Checks for any param errors. If errors are found, sets the display + template to the specified URL (a system-wide request error page by + default). + @param url The URL of the template to use to display error messages. + The special value "self" may be used to indicate that the template + for the requested page itself will handle reporting error + conditions. + + @return 1 if no error conditions exist, 0 otherwise. +} { set level [template::adp_level] upvar #$level request:error requesterror Index: openacs-4/packages/acs-templating/tcl/tag-procs.tcl =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/tcl/tag-procs.tcl,v diff -u -r1.6 -r1.7 --- openacs-4/packages/acs-templating/tcl/tag-procs.tcl 13 Mar 2002 22:50:53 -0000 1.6 +++ openacs-4/packages/acs-templating/tcl/tag-procs.tcl 1 Sep 2002 02:24:57 -0000 1.7 @@ -64,10 +64,10 @@ template::adp_append_code "\}" } -# append all the tags together and then eval as a list to restore -# quotes - ad_proc -public template_tag_if_concat_params { params } { + append all the tags together and then eval as a list to restore + quotes +} { set size [ns_set size $params] @@ -86,9 +86,9 @@ return $tokens } -# Interpret an expression as part of the simplified IF syntax - ad_proc -public template_tag_if_interp_expr {} { + Interpret an expression as part of the simplified IF syntax +} { upvar args args condition condition Index: openacs-4/packages/acs-templating/tcl/util-procs.tcl =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/tcl/util-procs.tcl,v diff -u -r1.6 -r1.7 --- openacs-4/packages/acs-templating/tcl/util-procs.tcl 13 Aug 2002 16:45:49 -0000 1.6 +++ openacs-4/packages/acs-templating/tcl/util-procs.tcl 1 Sep 2002 02:24:57 -0000 1.7 @@ -13,17 +13,15 @@ namespace eval template::util {} namespace eval template::query {} -# @public get_opts - -# Builds an array named "opts" in the calling frame, containing all -# switches passed at the end of a proc. The array values are either -# switch parameters or 1 if no parameter was specified. - -# Problem: there is currently no way to specify an option parameter that -# begins with a dash. This particularly problematic for negative numbers. - ad_proc -public template::util::get_opts { argv } { + Builds an array named "opts" in the calling frame, containing all + switches passed at the end of a proc. The array values are either + switch parameters or 1 if no parameter was specified. + Problem: there is currently no way to specify an option parameter that + begins with a dash. This particularly problematic for negative numbers. +} { + upvar opts opts set size [llength $argv] @@ -59,17 +57,15 @@ # * Utility procedures for manipulating lists, arrays and ns_sets * # * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * -# @public list_opts +ad_proc -public template::util::list_opts { {array_ref opts} } { + Converts an array to an option list -# Converts an array to an option list + @param array_ref The name of the array in the calling frame containing + option-value pairs. Defaults to "opts". -# @param array_ref The name of the array in the calling frame containing -# option-value pairs. Defaults to "opts". + @return A list of option-value pairs suitable for appending to a command. +} { -# @return A list of option-value pairs suitable for appending to a command. - -ad_proc -public template::util::list_opts { {array_ref opts} } { - upvar $array_ref arr set ret [list] @@ -80,17 +76,15 @@ return $ret } -# @public is_nil +ad_proc -public template::util::is_nil { ref } { + Determines whether a variable both exists and is not an empty string. -# Determines whether a variable both exists and is not an empty string. + @param ref The name of a variable to test in the calling frame. -# @param ref The name of a variable to test in the calling frame. + @return 1 if the variable either not exist or is an empty string. 0 if + the variable is either an array reference or a non-empty scalar. +} { -# @return 1 if the variable either not exist or is an empty string. 0 if -# the variable is either an array reference or a non-empty scalar. - -ad_proc -public template::util::is_nil { ref } { - upvar $ref var # check for an array as well @@ -104,20 +98,18 @@ return $result } -# @public is_unique +ad_proc -public template::util::is_unique { table columns values } { + Queries a database table for the existence of a particular row. + Useful for validating form input to reduce the possibility of + unique constraint violations. -# Queries a database table for the existence of a particular row. -# Useful for validating form input to reduce the possibility of -# unique constraint violations. + @param table The name of a database table. + @param columns A list of columns on which to select the row. + @param values A list of values for each specified column. -# @param table The name of a database table. -# @param columns A list of columns on which to select the row. -# @param values A list of values for each specified column. + @return 1 if the row exists, 0 if not +} { -# @return 1 if the row exists, 0 if not - -ad_proc -public template::util::is_unique { table columns values } { - set query "select count(*) from $table where " for { set i 0 } { $i < [llength $columns] } { incr i } { @@ -133,44 +125,43 @@ return [expr $count == 0] } +ad_proc -public template::util::is_true { x } { + interprets its argument as a boolean. -# @public is_true + @param x the value to test -# interprets its argument as a boolean. - -# @param x the value to test - -# @return 0 if the variable can be interpreted as false; 1 for true if it can't. - -ad_proc -public template::util::is_true { x } { + @return 0 if the variable can be interpreted as false; + 1 for true if it can't. +} { expr [lsearch -exact {0 f false n no off ""} [string tolower $x]] == -1 } # @public lpop -# Removes the last item from a list. The operation is performed -# in-place, rather than returning the new list. -# @param ref The name of a list in the calling frame on which to operate. - ad_proc -public template::util::lpop { ref } { + Removes the last item from a list. The operation is performed + in-place, rather than returning the new list. + @param ref The name of a list in the calling frame on which to operate. +} { + upvar $ref the_list set the_list [lrange $the_list 0 [expr [llength $the_list] - 2]] } -# Recursive procedure for building a hierarchical or multidimensional -# data structure in a list. - -# @param value Either a list or scalar value to store in the list. -# @param next A key value that determines the next node to -# traverse outward in the data structure. -# @param args Subsequent nodes to traverse. - ad_proc -public template::util::lnest { listref value next args } { + Recursive procedure for building a hierarchical or multidimensional + data structure in a list. + @param value Either a list or scalar value to store in the list. + @param next A key value that determines the next node to + traverse outward in the data structure. + @param args Subsequent nodes to traverse. +} { + upvar $listref inlist if { ! [info exists inlist] } { set inlist [list] @@ -225,19 +216,17 @@ set inlist [array get values] } -# @public set_to_list +ad_proc -public template::util::set_to_list { set args } { + Turns an ns_set into a key-value list, excluding any number of + specified keys. Useful for turning the contents on an ns_set into + a form that may be cached or manipulated as a native Tcl data structure. -# Turns an ns_set into a key-value list, excluding any number of -# specified keys. Useful for turning the contents on an ns_set into -# a form that may be cached or manipulated as a native Tcl data structure. + @param set A reference to an ns_set. + @param args Any number of key names to exclude from the list. -# @param set A reference to an ns_set. -# @param args Any number of key names to exclude from the list. + @return A list in the form { key value key value key value ... } +} { -# @return A list in the form { key value key value key value ... } - -ad_proc -public template::util::set_to_list { set args } { - set result [list] for { set i 0 } { $i < [ns_set size $set] } { incr i } { @@ -251,15 +240,13 @@ return $result } -# @public set_to_vars - -# Declare local variables for set values - -# @param set A reference to an ns_set. -# @param args Any number of keys to declare as local variables. - ad_proc -public template::util::set_to_vars { set args } { + Declare local variables for set values + @param set A reference to an ns_set. + @param args Any number of keys to declare as local variables. +} { + if { [llength $args] == 0 } { for { set i 0 } { $i < [ns_set size $set] } { incr i } { @@ -277,30 +264,25 @@ } } -# @public array_to_vars - -# Declare local variables for every key in an array. - -# @param arrayname The name of an array in the calling frame. - ad_proc -public template::util::array_to_vars { arrayname } { + Declare local variables for every key in an array. + @param arrayname The name of an array in the calling frame. +} { + upvar $arrayname arr foreach { key value } [array get arr] { uplevel "set \{${key}\} \{$value\}" } } -# @public vars_to_array - -# Place local variables into an array - -# @param arrayname The name of an array in the calling frame. -# @param args Any number of local variables to include in the array - ad_proc -public template::util::vars_to_array { arrayname args } { + Place local variables into an array + @param arrayname The name of an array in the calling frame. + @param args Any number of local variables to include in the array +} { upvar $arrayname arr foreach var $args { @@ -309,19 +291,17 @@ } } -# @public list_to_array - -# Converts a list of values into an array, using a list of -# corresponding column names for the array keys. - -# @param values A list of values -# @param array_ref The name of the array to create in the calling frame. -# @param columns A list of column names to use for the array keys. -# The length of this list should be the same as the values -# list. - ad_proc -public template::util::list_to_array { values array_ref columns } { + Converts a list of values into an array, using a list of + corresponding column names for the array keys. + @param values A list of values + @param array_ref The name of the array to create in the calling frame. + @param columns A list of column names to use for the array keys. + The length of this list should be the same as the values + list. +} { + upvar $array_ref array for { set i 0 } { $i < [llength $values] } { incr i } { @@ -333,12 +313,10 @@ } } -# @public list_of_lists_to_array - -# Converts a list of lists in the form { { key value } { key value } ... } -# to an array. - ad_proc -public template::util::list_of_lists_to_array { lists array_ref } { + Converts a list of lists in the form { { key value } { key value } ... } + to an array. +} { upvar $array_ref array @@ -351,17 +329,14 @@ } } -# @public list_to_lookup - -# Turn a list into an array where each key corresponds to an element -# of the list... Sort of like a sparse bitmap. Each value corresponds -# to the key's position in the input list. - -# @param values A list of values -# @param array_ref The name of the array to create in the calling frame. - ad_proc -public template::util::list_to_lookup { values array_ref } { - + Turn a list into an array where each key corresponds to an element + of the list... Sort of like a sparse bitmap. Each value corresponds + to the key's position in the input list. + + @param values A list of values + @param array_ref The name of the array to create in the calling frame. +} { upvar $array_ref array set i 1 @@ -372,11 +347,18 @@ } } -# Return a representation of a multirow data source as a list, -# suitable for passing by value in the form { { row } { row } { row } ... } ad_proc -public template::util::multirow_to_list { name } { + generate a list structure representitive of a multirow data source + @param name the name of an existing multirow data source + + @return a representation of a multirow data source as a list, + suitable for passing by value in the form { { row } { row } { row } ... } + + @see proc template::util::list_to_multirow +} { + upvar $name:rowcount rowcount set rows [list] @@ -391,7 +373,16 @@ } ad_proc -public template::util::list_to_multirow { name rows { level 1 } } { + populate a multirow data source from a list string gotten from + a call to template::util::multirow_to_list + @param name the name of a multirow data source + @param rows a representation of a multirow data source as a list, + suitable for passing by value in the form { { row } { row } { row } ... } + + @see proc template::util::multirow_to_list +} { + upvar $level $name:rowcount rowcount set rowcount [llength $rows] set rownum 1 @@ -434,32 +425,28 @@ # * Utility procedures for interacting with the file system * # * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * -# @public read_file +ad_proc -public template::util::read_file { path } { + Reads a text file. -# Reads a text file. + @param path The absolute path to the file -# @param path The absolute path to the file + @return A string with the contents of the file. +} { -# @return A string with the contents of the file. - -ad_proc -public template::util::read_file { path } { - set fd [open $path] set text [read $fd] close $fd return $text } -# @public write_file - -# Writes a text file - -# @param path The absolute path to the file -# @param text A string containing the text to write to the file. - ad_proc -public template::util::write_file { path text } { + Writes a text file + @param path The absolute path to the file + @param text A string containing the text to write to the file. +} { + file mkdir [file dirname $path] set fd [open $path w] @@ -469,9 +456,10 @@ # @public url_to_file -# Resolve a URL into an absolute file path. ad_proc -public template::util::url_to_file { url {reference_url ""} } { + Resolve a URL into an absolute file path. +} { if { [string index $url 0] != "/" } { @@ -485,12 +473,9 @@ return [ns_normalizepath $path] } -# @public resolve_directory_url - -# Resolve the file name for a directory URL - ad_proc -public template::util::resolve_directory_url { url } { - + Resolve the file name for a directory URL +} { set path [ns_info pageroot]$url if { [file isdirectory $path] && [file exists ${path}index.adp] } { @@ -500,13 +485,10 @@ return $url } -# @public get_url_directory - -# Get the directory portion of a URL. If the URL has a trailing -# slash, then return the entire URL. - ad_proc -public template::util::get_url_directory { url } { - + Get the directory portion of a URL. If the URL has a trailing + slash, then return the entire URL. +} { set directory $url set lastchar [string range $url [expr [string length $url]-1] end] @@ -524,13 +506,10 @@ return $directory } -# @public get_cookie - -# Retrieve the value of a cookie and return it -# Return the default if no such cookie exists - ad_proc -public template::util::get_cookie { name {default_value ""} } { - + Retrieve the value of a cookie and return it + Return the default if no such cookie exists +} { set headers [ns_conn headers] set cookie [ns_set iget $headers Cookie] @@ -542,13 +521,11 @@ return $default_value } -# @public set_cookie - -# Create a cookie with specified parameters. The expiration state -# may be persistent, session, or a number of minutes from the current -# time. - ad_proc -public template::util::set_cookie { expire_state name value { domain "" } } { + Create a cookie with specified parameters. The expiration state + may be persistent, session, or a number of minutes from the current + time. +} { if { [string match $domain {}] } { set path "ns/server/[ns_info server]/module/nssock" @@ -577,12 +554,9 @@ ns_set put [ns_conn outputheaders] "Set-Cookie" $cookie } -# @public clear_cookie - -# Expires an existing cookie. - ad_proc -public template::util::clear_cookie { name { domain "" } } { - + Expires an existing cookie. +} { if { [string match $domain {}] } { set path "ns/server/[ns_info server]/module/nssock" set domain [ns_config $path Hostname] @@ -601,16 +575,15 @@ return $html } +ad_proc -public template::util::multirow_quote_html {multirow_ref column_ref} { + implements template::util::quote_html on the designated column of a multirow -# @public multirow_quote_html -# implements template::util::quote_html on the designated column of a multirow + @param multirow_ref name of the multirow + @param column_ref name of the column to be -# @param multirow_ref name of the multirow -# @param column_ref name of the column to be + @author simon +} { -# @author simon - -ad_proc -public template::util::multirow_quote_html {multirow_ref column_ref} { upvar $multirow_ref:rowcount rowcount for { set i 1 } { $i <= $rowcount } { incr i} { @@ -621,21 +594,27 @@ } -# @public multirow_foreach -# runs a block of code foreach row in a multirow +ad_proc -public template::util::multirow_foreach { name code_text } { + runs a block of code foreach row in a multirow -# @param name the name of the multirow over which the block of code is iterated -# @param code_text the block of code in the for loop; this block can reference -# any of the columns belonging to the multirow specified; with the multirow -# named "fake_multirow" containing columns named "spanky" and "foobar",to set the column -# spanky to the value of column foobar use: -# set fake_multirow.spanky @fake_multirow.foobar@ -# note: this block of code is evaluated in the same scope as the .tcl page that uses -# this procedure + @param name the name of the multirow over which the block of + code is iterated -# @author simon + @param code_text the block of code in the for loop; this block can + reference any of the columns belonging to the + multirow specified; with the multirow named + "fake_multirow" containing columns named "spanky" + and "foobar",to set the column spanky to the value + of column foobar use:
+ set fake_multirow.spanky + @fake_multirow.foobar@ +

+ note: this block of code is evaluated in the same + scope as the .tcl page that uses this procedure -ad_proc -public template::util::multirow_foreach { name code_text } { + @author simon +} { + upvar $name:rowcount rowcount $name:columns columns i i upvar running_code running_code @@ -660,15 +639,11 @@ } - - -# @public get_param - -# Retreive a stored parameter, or "" if no such parameter -# If section/key are present, read the parameter from the specified -# section.key in the INI file, and cache them under the given name - ad_proc -public template::util::get_param { name {section {}} {key {}} } { + Retreive a stored parameter, or "" if no such parameter + If section/key are present, read the parameter from the specified + section.key in the INI file, and cache them under the given name +} { if { ![nsv_exists __template_config $name] } { @@ -698,45 +673,39 @@ } } -# @public set_param - -# Set a stored parameter - ad_proc -public template::util::set_param { name value } { + Set a stored parameter +} { nsv_set __template_config $name $value } -# @public nvl - -# Analogous to SQL NVL - ad_proc -public template::util::nvl { value value_if_null } { + Analogous to SQL NVL +} { + if { [template::util::is_nil value] } { return $value_if_null } else { return $value } } -# @public number_list - -# Return a list of numbers, {1 2 3 ... n} - ad_proc -public template::util::number_list { last_number {start_at 0} } { + Return a list of numbers, {1 2 3 ... n} +} { + set ret [list] for {set i $start_at} { $i <= $ret } {incr i} { lappend ret $i } return $ret } - -# @public tcl_to_sql_list - -# Convert a TCL list to a SQL list, for use with the "in" statement -# why doesn't this use ns_dbquotevalue? - ad_proc -public template::util::tcl_to_sql_list { lst } { + Convert a TCL list to a SQL list, for use with the "in" statement + why doesn't this use ns_dbquotevalue? +} { + if { [llength $lst] > 0 } { set sql "'" append sql [join $lst "', '"] @@ -749,16 +718,19 @@ -# Get the template directory -# The body is doublequoted, so it is interpreted when this file is read -ad_proc -public template::get_resource_path {} " +ad_proc -public template::get_resource_path {} { + Get the template directory + The body is doublequoted, so it is interpreted when this file is read +} " return \"[file dir [file dir [info script]]]/resources\" " -# return the variables and arrays of one frame as HTML ad_proc -public stack_frame_values {level} { + return the variables and arrays of one frame as HTML +} { + set varlist "" foreach i [if $level { uplevel \#$level {info locals} @@ -788,8 +760,9 @@ -# return the whole call stack as HTML ad_proc -public stack_dump {} { + return the whole call stack as HTML +} { append page "

Tcl Call Trace