• Publicity: Public Only All

util-procs.tcl

Utility procedures for the ArsDigita Templating System

Location:
packages/acs-templating/tcl/util-procs.tcl
Authors:
Karl Goldstein <karlg@arsdigita.com>
Stanislav Freidin <sfreidin@arsdigita.com>
CVS Identification:
$Id: util-procs.tcl,v 1.43.2.7 2020/07/06 13:55:54 antoniop Exp $

Procedures in this file

Detailed information

anchor_form (public)

 anchor_form [ -id id ] [ -vars vars ] [ -action action ] \
    [ -label label ]

return an inline form with the appearance of an anchor

Switches:
-id (optional)
-vars (optional)
-action (optional)
-label (defaults to "link") (optional)

Partial Call Graph (max 5 caller/called nodes):
%3 packages/acs-admin/www/apm/package-delete-2.tcl packages/acs-admin/ www/apm/package-delete-2.tcl anchor_form anchor_form packages/acs-admin/www/apm/package-delete-2.tcl->anchor_form packages/acs-admin/www/apm/packages-install-4.tcl packages/acs-admin/ www/apm/packages-install-4.tcl packages/acs-admin/www/apm/packages-install-4.tcl->anchor_form

Testcases:
No testcase defined.

stack_dump (public, deprecated)

 stack_dump
Deprecated. Invoking this procedure generates a warning.

return the whole call stack as HTML DEPRECATED: does not comply with OpenACS naming convention.


See Also:

Partial Call Graph (max 5 caller/called nodes):
%3

Testcases:
No testcase defined.

template::resource_path (public)

 template::resource_path -type type -style style [ -relative ] \
    [ -subsite_id subsite_id ] [ -theme_dir theme_dir ]

Process the templating "style" and return the stub (path without extensions). When the style is not an absolute path, check if the resource can be obtained from the theme, if not fallback to the resources directory of acs-templating.

Switches:
-type (required)
type of resource (e.g. "forms" or "lists")
-style (required)
name of the resource within the type (e.g. "standard")
-relative (boolean) (optional)
return optionally the path relative to the OpenACS root directory
-subsite_id (optional)
subsite_id to determine theming information
-theme_dir (optional)
theming directory (alternative to determination via subsite), higher priority
Returns:
path of the resource (without extension)
Author:
Gustaf Neumann

Partial Call Graph (max 5 caller/called nodes):
%3 ad_dimensional ad_dimensional (public) template::resource_path template::resource_path ad_dimensional->template::resource_path packages/acs-templating/tcl/tag-init.tcl packages/acs-templating/ tcl/tag-init.tcl packages/acs-templating/tcl/tag-init.tcl->template::resource_path template::dat_page_filter template::dat_page_filter (private) template::dat_page_filter->template::resource_path template::form::template template::form::template (private) template::form::template->template::resource_path template::list::element::render template::list::element::render (public) template::list::element::render->template::resource_path

Testcases:
No testcase defined.

template::stack_dump (public)

 template::stack_dump

Return the whole call stack as HTML

Partial Call Graph (max 5 caller/called nodes):
%3 stack_dump stack_dump (public, deprecated) template::stack_dump template::stack_dump stack_dump->template::stack_dump

Testcases:
No testcase defined.

template::streaming_template (public)

 template::streaming_template [ -subsite_id subsite_id ]

Return the path of the streaming template

Switches:
-subsite_id (optional)
id of the subsite. Defaults to [ad_conn subsite_id]
Returns:
path to themed template

Partial Call Graph (max 5 caller/called nodes):
%3 Class ::xowf::test_item::Answer_manager Class ::xowf::test_item::Answer_manager (public) template::streaming_template template::streaming_template Class ::xowf::test_item::Answer_manager->template::streaming_template packages/acs-admin/www/apm/package-load-2.tcl packages/acs-admin/ www/apm/package-load-2.tcl packages/acs-admin/www/apm/package-load-2.tcl->template::streaming_template packages/acs-admin/www/apm/packages-install-4.tcl packages/acs-admin/ www/apm/packages-install-4.tcl packages/acs-admin/www/apm/packages-install-4.tcl->template::streaming_template packages/acs-admin/www/apm/write-all-specs.tcl packages/acs-admin/ www/apm/write-all-specs.tcl packages/acs-admin/www/apm/write-all-specs.tcl->template::streaming_template xowf::test_item::Answer_manager instproc render_answers xowf::test_item::Answer_manager instproc render_answers (public) xowf::test_item::Answer_manager instproc render_answers->template::streaming_template

Testcases:
No testcase defined.

template::themed_template (public)

 template::themed_template path

Given a path like /packages/acs-admin/www/index pointing to an .adp file, this function tries to locate this path in the ResourceDir of the subsite (determined by the theme). If found the themed template is returned, otherwise the passed template path.

Parameters:
path - absolute path within the open acs tree (without extension)
Returns:
path to themed template or input value (without extension)

Partial Call Graph (max 5 caller/called nodes):
%3 ad_page_contract ad_page_contract (public) template::themed_template template::themed_template ad_page_contract->template::themed_template adp_parse_ad_conn_file adp_parse_ad_conn_file (public) adp_parse_ad_conn_file->template::themed_template apidoc::xql_links_list apidoc::xql_links_list (private) apidoc::xql_links_list->template::themed_template apm_build_repository apm_build_repository (private) apm_build_repository->template::themed_template callback::user::workspace::impl::acs-subsite callback::user::workspace::impl::acs-subsite (private) callback::user::workspace::impl::acs-subsite->template::themed_template

Testcases:
No testcase defined.

template::util::array_to_vars (public)

 template::util::array_to_vars arrayname

Declare local variables for every key in an array.

Parameters:
arrayname - The name of an array in the calling frame.

Partial Call Graph (max 5 caller/called nodes):
%3

Testcases:
No testcase defined.

template::util::get_opts (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.

Parameters:
argv

Partial Call Graph (max 5 caller/called nodes):
%3 doc::get_proc_doc doc::get_proc_doc (private, deprecated) template::util::get_opts template::util::get_opts doc::get_proc_doc->template::util::get_opts publish::handle::image publish::handle::image (public) publish::handle::image->template::util::get_opts publish::handle::text publish::handle::text (public) publish::handle::text->template::util::get_opts publish::handle_binary_file publish::handle_binary_file (public) publish::handle_binary_file->template::util::get_opts publish::handle_item publish::handle_item (private) publish::handle_item->template::util::get_opts

Testcases:
No testcase defined.

template::util::get_url_directory (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.

Parameters:
url

Partial Call Graph (max 5 caller/called nodes):
%3 test_get_url_directory get_url_directory (test acs-templating) template::util::get_url_directory template::util::get_url_directory test_get_url_directory->template::util::get_url_directory

Testcases:
get_url_directory

template::util::is_nil (public)

 template::util::is_nil ref

Determines whether a variable both exists and is not an empty string.

Parameters:
ref - The name of a variable to test in the calling frame.
Returns:
1 if the variable either not exist or is an empty string. 0 if the variable is either an array reference or a nonempty scalar.

Partial Call Graph (max 5 caller/called nodes):
%3 content::get_content content::get_content (public) template::util::is_nil template::util::is_nil content::get_content->template::util::is_nil packages/acs-templating/tcl/tag-init.tcl packages/acs-templating/ tcl/tag-init.tcl packages/acs-templating/tcl/tag-init.tcl->template::util::is_nil publish::foreach_publish_path publish::foreach_publish_path (private) publish::foreach_publish_path->template::util::is_nil publish::get_main_item_id publish::get_main_item_id (private) publish::get_main_item_id->template::util::is_nil publish::get_main_revision_id publish::get_main_revision_id (private) publish::get_main_revision_id->template::util::is_nil

Testcases:
No testcase defined.

template::util::is_true (public)

 template::util::is_true x

interprets its argument as a boolean.

Parameters:
x - the value to test
Returns:
0 if the variable can be interpreted as false; 1 for true if it can't.

Partial Call Graph (max 5 caller/called nodes):
%3 test_acs_mail_lite_inbound_procs_check acs_mail_lite_inbound_procs_check (test acs-mail-lite) template::util::is_true template::util::is_true test_acs_mail_lite_inbound_procs_check->template::util::is_true acs_privacy::set_user_read_private_data acs_privacy::set_user_read_private_data (public) acs_privacy::set_user_read_private_data->template::util::is_true auth::authority::batch_sync auth::authority::batch_sync (public) auth::authority::batch_sync->template::util::is_true auth::sync::job::end auth::sync::job::end (public) auth::sync::job::end->template::util::is_true calendar::personal_p calendar::personal_p (public) calendar::personal_p->template::util::is_true group::member_p_not_cached group::member_p_not_cached (private) group::member_p_not_cached->template::util::is_true

Testcases:
acs_mail_lite_inbound_procs_check

template::util::is_unique (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.

Parameters:
table - The name of a database table.
columns - A list of columns on which to select the row.
values - A list of values for each specified column.
Returns:
1 if the row exists, 0 if not

Partial Call Graph (max 5 caller/called nodes):
%3

Testcases:
No testcase defined.

template::util::list_of_lists_to_array (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.

Parameters:
lists
array_ref

Partial Call Graph (max 5 caller/called nodes):
%3 callback::acs_mail_lite::incoming_email::impl::bug-tracker callback::acs_mail_lite::incoming_email::impl::bug-tracker (private) template::util::list_of_lists_to_array template::util::list_of_lists_to_array callback::acs_mail_lite::incoming_email::impl::bug-tracker->template::util::list_of_lists_to_array ref_countries::get_country_code ref_countries::get_country_code (public) ref_countries::get_country_code->template::util::list_of_lists_to_array

Testcases:
No testcase defined.

template::util::list_of_ns_sets_to_multirow (public)

 template::util::list_of_ns_sets_to_multirow -rows rows \
    -var_name var_name [ -level level ]

Transform a list of ns_sets (e.g. produced by db_list_of_ns_sets) into a multirow datasource.

Switches:
-rows (required)
The data to be transformed
-var_name (required)
The name of the multirow to create
-level (defaults to "1") (optional)
How many levels up the stack to place the new datasource, defaults to 1 level up.

Partial Call Graph (max 5 caller/called nodes):
%3

Testcases:
No testcase defined.

template::util::list_opts (public)

 template::util::list_opts [ array_ref ]

Converts an array to an option list

Parameters:
array_ref (defaults to "opts") - The name of the array in the calling frame containing option-value pairs. Defaults to "opts".
Returns:
A list of option-value pairs suitable for appending to a command.

Partial Call Graph (max 5 caller/called nodes):
%3

Testcases:
No testcase defined.

template::util::list_to_array (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.

Parameters:
values - A list of values
array_ref - The name of the array to create in the calling frame.
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.

Partial Call Graph (max 5 caller/called nodes):
%3

Testcases:
No testcase defined.

template::util::list_to_lookup (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.

Parameters:
values - A list of values
array_ref - The name of the array to create in the calling frame.

Partial Call Graph (max 5 caller/called nodes):
%3 packages/categories/www/categories-browse.tcl packages/categories/ www/categories-browse.tcl template::util::list_to_lookup template::util::list_to_lookup packages/categories/www/categories-browse.tcl->template::util::list_to_lookup packages/categories/www/include/widget.tcl packages/categories/ www/include/widget.tcl packages/categories/www/include/widget.tcl->template::util::list_to_lookup template::element::options template::element::options (private) template::element::options->template::util::list_to_lookup template::paginator::get_data template::paginator::get_data (public) template::paginator::get_data->template::util::list_to_lookup template::paginator::get_query template::paginator::get_query (public) template::paginator::get_query->template::util::list_to_lookup

Testcases:
No testcase defined.

template::util::list_to_multirow (public)

 template::util::list_to_multirow name rows [ level ]

populate a multirow data source from a list string gotten from a call to template::util::multirow_to_list

Parameters:
name - the name of a multirow data source
rows - a representation of a multirow data source as a list, suitable for passing by value in the form { { row } { row } { row } ... }
level (defaults to "1")

See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 packages/acs-api-browser/www/content-page-view.tcl packages/acs-api-browser/ www/content-page-view.tcl template::util::list_to_multirow template::util::list_to_multirow packages/acs-api-browser/www/content-page-view.tcl->template::util::list_to_multirow packages/acs-automated-testing/www/admin/proc-coverage.tcl packages/acs-automated-testing/ www/admin/proc-coverage.tcl packages/acs-automated-testing/www/admin/proc-coverage.tcl->template::util::list_to_multirow packages/acs-lang/www/admin/index.tcl packages/acs-lang/ www/admin/index.tcl packages/acs-lang/www/admin/index.tcl->template::util::list_to_multirow packages/categories/www/cadmin/index.tcl packages/categories/ www/cadmin/index.tcl packages/categories/www/cadmin/index.tcl->template::util::list_to_multirow packages/forums/lib/message/post.tcl packages/forums/ lib/message/post.tcl packages/forums/lib/message/post.tcl->template::util::list_to_multirow

Testcases:
No testcase defined.

template::util::lnest (public)

 template::util::lnest listref value next [ args... ]

Recursive procedure for building a hierarchical or multidimensional data structure in a list.

Parameters:
listref
value - Either a list or scalar value to store in the list.
next - A key value that determines the next node to traverse outward in the data structure.

Partial Call Graph (max 5 caller/called nodes):
%3 template::query::nestedlist template::query::nestedlist (private) template::util::lnest template::util::lnest template::query::nestedlist->template::util::lnest

Testcases:
No testcase defined.

template::util::lpop (public)

 template::util::lpop ref

Removes the last item from a list. The operation is performed in-place, rather than returning the new list.

Parameters:
ref - The name of a list in the calling frame on which to operate.

Partial Call Graph (max 5 caller/called nodes):
%3 test_create_form_with_form_instance create_form_with_form_instance (test xowiki) template::util::lpop template::util::lpop test_create_form_with_form_instance->template::util::lpop test_xowiki_test_cases xowiki_test_cases (test xowiki) test_xowiki_test_cases->template::util::lpop apm::process_install_xml apm::process_install_xml (public) apm::process_install_xml->template::util::lpop photo_album::search::photo::datasource photo_album::search::photo::datasource (private) photo_album::search::photo::datasource->template::util::lpop template::adp_eval template::adp_eval (public) template::adp_eval->template::util::lpop template::adp_include template::adp_include (public) template::adp_include->template::util::lpop template::adp_parse template::adp_parse (public) template::adp_parse->template::util::lpop

Testcases:
xowiki_test_cases, create_form_with_form_instance

template::util::master_to_file (public)

 template::util::master_to_file url [ reference_url ]

Resolve a URL into an absolute file path, but respect styled master configuration for named masters (e.g. acs-templating/resources/masters/... containing 2cols.adp)

Parameters:
url
reference_url (optional)

Partial Call Graph (max 5 caller/called nodes):
%3 packages/acs-templating/tcl/tag-init.tcl packages/acs-templating/ tcl/tag-init.tcl template::util::master_to_file template::util::master_to_file packages/acs-templating/tcl/tag-init.tcl->template::util::master_to_file

Testcases:
No testcase defined.

template::util::multirow_quote_html (public)

 template::util::multirow_quote_html multirow_ref column_ref

implements template::util::quote_html on the designated column of a multirow

Parameters:
multirow_ref - name of the multirow
column_ref - name of the column to be
Author:
simon

Partial Call Graph (max 5 caller/called nodes):
%3

Testcases:
No testcase defined.

template::util::multirow_to_list (public)

 template::util::multirow_to_list [ -level level ] name

generate a list structure representative of a multirow data source NB: if the multirow is generated by db_multirow, db_multirow must be called with the -local option

Switches:
-level (defaults to "1") (optional)
Parameters:
name - the name of an existing multirow data source
Returns:
a representation of a multirow data source as a list, suitable for passing by value in the form { { row } { row } { row } ... }

See Also:

Partial Call Graph (max 5 caller/called nodes):
%3 packages/workflow/www/admin/workflow-ae.tcl packages/workflow/ www/admin/workflow-ae.tcl template::util::multirow_to_list template::util::multirow_to_list packages/workflow/www/admin/workflow-ae.tcl->template::util::multirow_to_list packages/workflow/www/admin/workflow-clone.tcl packages/workflow/ www/admin/workflow-clone.tcl packages/workflow/www/admin/workflow-clone.tcl->template::util::multirow_to_list

Testcases:
No testcase defined.

template::util::number_list (public)

 template::util::number_list last_number [ start_at ]

Return a list of numbers, {1 2 3 ... n}

Parameters:
last_number
start_at (defaults to "0")

Partial Call Graph (max 5 caller/called nodes):
%3 test_number_list number_list (test acs-templating) template::util::number_list template::util::number_list test_number_list->template::util::number_list

Testcases:
number_list

template::util::nvl (public)

 template::util::nvl value value_if_null

Analogous to SQL NVL

Parameters:
value
value_if_null

Partial Call Graph (max 5 caller/called nodes):
%3 test_nvl nvl (test acs-templating) template::util::nvl template::util::nvl test_nvl->template::util::nvl

Testcases:
nvl

template::util::read_file (public)

 template::util::read_file path

Reads a text file.

Parameters:
path - The absolute path to the file
Returns:
A string with the contents of the file.

Partial Call Graph (max 5 caller/called nodes):
%3 test_sync_file_get_document sync_file_get_document (test acs-authentication) template::util::read_file template::util::read_file test_sync_file_get_document->template::util::read_file aa_test::parse_install_file aa_test::parse_install_file (public) aa_test::parse_install_file->template::util::read_file aa_test::parse_test_file aa_test::parse_test_file (public) aa_test::parse_test_file->template::util::read_file api_add_calling_info_to_procdoc api_add_calling_info_to_procdoc (private) api_add_calling_info_to_procdoc->template::util::read_file apidoc::get_xql_snippet apidoc::get_xql_snippet (private) apidoc::get_xql_snippet->template::util::read_file auth::sync::get_doc::file::GetDocument auth::sync::get_doc::file::GetDocument (private) auth::sync::get_doc::file::GetDocument->template::util::read_file

Testcases:
sync_file_get_document

template::util::resolve_directory_url (public)

 template::util::resolve_directory_url url

Resolve the filename for a directory URL

Parameters:
url

Partial Call Graph (max 5 caller/called nodes):
%3

Testcases:
No testcase defined.

template::util::set_file_encoding (public)

 template::util::set_file_encoding file_channel_id

Set encoding of the given file channel based on the OutputCharset parameter of AOLserver. All ADP, Tcl, and txt files are assumed to be in the same charset.

Parameters:
file_channel_id - The id of the file to set encoding for.
Author:
Peter Marklund

Partial Call Graph (max 5 caller/called nodes):
%3 template::util::read_file template::util::read_file (public) template::util::set_file_encoding template::util::set_file_encoding template::util::read_file->template::util::set_file_encoding template::util::write_file template::util::write_file (public) template::util::write_file->template::util::set_file_encoding

Testcases:
No testcase defined.

template::util::set_to_list (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.

Parameters:
set - A reference to an ns_set.
Returns:
A list in the form { key value key value key value ... }

Partial Call Graph (max 5 caller/called nodes):
%3 packages/acs-templating/tcl/tag-init.tcl packages/acs-templating/ tcl/tag-init.tcl template::util::set_to_list template::util::set_to_list packages/acs-templating/tcl/tag-init.tcl->template::util::set_to_list

Testcases:
No testcase defined.

template::util::set_to_vars (public)

 template::util::set_to_vars set [ args... ]

Declare local variables for set values

Parameters:
set - A reference to an ns_set.

Partial Call Graph (max 5 caller/called nodes):
%3

Testcases:
No testcase defined.

template::util::tcl_to_sql_list (public)

 template::util::tcl_to_sql_list lst

Convert a Tcl list to a SQL list, for use with the "in" statement. Uses double single quotes (similar to ns_dbquotevalue) to escape single quotes Note: this proc could be deprecated in the not so far future, as Naviserver now provides a native api for this and a tcl-implemented fallback exists in current OpenACS code.

Parameters:
lst

See Also:
  • ns_dbquotelist

Partial Call Graph (max 5 caller/called nodes):
%3 test_tcl_to_sql_list tcl_to_sql_list (test acs-templating) template::util::tcl_to_sql_list template::util::tcl_to_sql_list test_tcl_to_sql_list->template::util::tcl_to_sql_list callback::search::extra_arg::impl::package_ids callback::search::extra_arg::impl::package_ids (private) callback::search::extra_arg::impl::package_ids->template::util::tcl_to_sql_list cr_item_search::assert_in_queue cr_item_search::assert_in_queue (private) cr_item_search::assert_in_queue->template::util::tcl_to_sql_list cr_item_search::assert_not_in_queue cr_item_search::assert_not_in_queue (private) cr_item_search::assert_not_in_queue->template::util::tcl_to_sql_list packages/file-storage/www/copy.tcl packages/file-storage/ www/copy.tcl packages/file-storage/www/copy.tcl->template::util::tcl_to_sql_list packages/file-storage/www/move.tcl packages/file-storage/ www/move.tcl packages/file-storage/www/move.tcl->template::util::tcl_to_sql_list

Testcases:
tcl_to_sql_list

template::util::url_to_file (public)

 template::util::url_to_file url [ reference_url ]

Resolve a URL into an absolute file path.

Parameters:
url
reference_url (optional)

Partial Call Graph (max 5 caller/called nodes):
%3 ad_parse_template ad_parse_template (public) template::util::url_to_file template::util::url_to_file ad_parse_template->template::util::url_to_file ad_return_template ad_return_template (public) ad_return_template->template::util::url_to_file packages/acs-templating/tcl/tag-init.tcl packages/acs-templating/ tcl/tag-init.tcl packages/acs-templating/tcl/tag-init.tcl->template::util::url_to_file packages/faq/www/try.tcl packages/faq/ www/try.tcl packages/faq/www/try.tcl->template::util::url_to_file template::adp_include template::adp_include (public) template::adp_include->template::util::url_to_file

Testcases:
No testcase defined.

template::util::vars_to_array (public)

 template::util::vars_to_array arrayname [ args... ]

Place local variables into an array

Parameters:
arrayname - The name of an array in the calling frame.

Partial Call Graph (max 5 caller/called nodes):
%3

Testcases:
No testcase defined.

template::util::write_file (public)

 template::util::write_file path text

Writes a text file

Parameters:
path - The absolute path to the file
text - A string containing the text to write to the file.

Partial Call Graph (max 5 caller/called nodes):
%3 aa_test::write_test_file aa_test::write_test_file (private) template::util::write_file template::util::write_file aa_test::write_test_file->template::util::write_file auth::authority::batch_sync auth::authority::batch_sync (public) auth::authority::batch_sync->template::util::write_file content::deploy content::deploy (public, deprecated) content::deploy->template::util::write_file content::init content::init (public) content::init->template::util::write_file lang::test::setup_test_package lang::test::setup_test_package (private) lang::test::setup_test_package->template::util::write_file

Testcases:
No testcase defined.
[ show source ]