- Publicity: Public Only All
defs-procs.tcl
ACS-specific general utility routines.
- Location:
- packages/acs-tcl/tcl/defs-procs.tcl
- Created:
- 2 April 1998
- Authors:
- Philip Greenspun <philg@arsdigita.com>
- Many others at ArsDigita and in the OpenACS community.
- CVS Identification:
$Id: defs-procs.tcl,v 1.83 2024/09/11 06:15:48 gustafn Exp $
Procedures in this file
- acs_community_member_admin_link (public)
- acs_community_member_admin_url (public)
- acs_community_member_link (public)
- acs_community_member_page (public)
- acs_community_member_url (public)
- ad_acs_release_date (public)
- ad_acs_version (public)
- ad_admin_home (public)
- ad_decorate_top (public, deprecated)
- ad_host_administrator (public)
- ad_outgoing_sender (public)
- ad_package_admin_home (public, deprecated)
- ad_parameter_all_values_as_list (public, deprecated)
- ad_parameter_cache (public)
- ad_parameter_from_configuration_file (public)
- ad_parameter_from_file (public, deprecated)
- ad_progress_bar_begin (public)
- ad_progress_bar_end (public)
- ad_publisher_name (public)
- ad_pvt_home (public)
- ad_pvt_home_link (public)
- ad_pvt_home_name (public)
- ad_return_complaint (public)
- ad_return_error (public)
- ad_return_exception_page (public)
- ad_return_forbidden (public)
- ad_return_if_another_copy_is_running (public)
- ad_return_string_as_file (public)
- ad_return_url (public)
- ad_return_warning (public)
- ad_site_home_link (public)
- ad_system_name (public)
- ad_system_owner (public)
- ad_url (public)
- doc_return (public)
Detailed information
acs_community_member_admin_link (public)
acs_community_member_admin_link -user_id user_id [ -label label ]
- Switches:
- -user_id (required)
- -label (optional)
- Returns:
- the HTML link of the community member page of a particular admin user.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- user_links_api
acs_community_member_admin_url (public)
acs_community_member_admin_url -user_id user_id
- Switches:
- -user_id (required)
- Returns:
- the URL for the community member admin page of a particular user
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- user_links_api, web_forum_new, web_forum_view, web_forum_edit, web_forums_message_and_reply
acs_community_member_link (public)
acs_community_member_link -user_id user_id [ -label label ]
- Switches:
- -user_id (required)
- -label (optional)
- Returns:
- the link of the community member page of a particular user
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- user_links_api
acs_community_member_page (public)
acs_community_member_page
- Returns:
- the URL for the community member page
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- user_links_api
acs_community_member_url (public)
acs_community_member_url -user_id user_id
- Switches:
- -user_id (required)
- Returns:
- the URL for the community member page of a particular user
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- user_links_api
ad_acs_release_date (public)
ad_acs_release_date
The OpenACS release date of this instance. Uses the release date of the acs-kernel package.
- Author:
- Peter Marklund
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- acs_system_information_api
ad_acs_version (public)
ad_acs_version
The OpenACS version of this instance. Uses the version name of the acs-kernel package.
- Author:
- Peter Marklund
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- acs_system_information_api
ad_admin_home (public)
ad_admin_home
Returns the directory for the admin home.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- user_links_api
ad_decorate_top (public, deprecated)
ad_decorate_top simple_headline potential_decoration
Deprecated. Invoking this procedure generates a warning.
Use this for pages that might or might not have an image defined in ad.ini; if the second argument isn't the empty string, ad_decorate_top will make a one-row table for the top of the page DEPRECATED: use the template system, e.g. master and slave tags to achieve better control of headers.
- Parameters:
- simple_headline (required)
- potential_decoration (required)
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
ad_host_administrator (public)
ad_host_administrator
As defined in the HostAdministrator kernel parameter.
- Returns:
- The e-mail address of a technical person who can fix problems
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- host_admin_and_outgoing_sender
ad_outgoing_sender (public)
ad_outgoing_sender
- Returns:
- The email address that will sign outgoing alerts
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- auth_registration_implementations, host_admin_and_outgoing_sender
ad_package_admin_home (public, deprecated)
ad_package_admin_home package_key
Deprecated. Invoking this procedure generates a warning.
- Parameters:
- package_key (required)
- Returns:
- directory for the especified package's admin home. # is this accurate? (rbm, aug 2002) DEPRECATED: a package URL may not have anything to do with the package key. Furthermore, the admin pages are normally located in "-package-/admin" and not in "/admin/-package-". One is better off generating package URLs by way of the site_nodes.
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
ad_parameter_all_values_as_list (public, deprecated)
ad_parameter_all_values_as_list [ -package_id package_id ] name \ [ subsection ]
Deprecated. Invoking this procedure generates a warning.
Returns multiple values for a parameter as a list. DEPRECATED: this proc does not do much that joining a string coming from a parameter, which does not make an invalid string into a list. Best to take the value from the parameter directly and rely on proper quoting by the user. Furthermore, the 'subsection' argument is not used anywhere.
- Switches:
- -package_id (optional)
- Parameters:
- name (required)
- subsection (optional)
- See Also:
- parameter::get
- join
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
ad_parameter_cache (public)
ad_parameter_cache [ -set set ] [ -delete ] [ -global ] key \ parameter_name
Manages the cache for ad_parameter.
- Switches:
- -set (optional)
- Use this flag to indicate a value to set in the cache.
- -delete (optional, boolean)
- Delete the value from the cache
- -global (optional, boolean)
- If true, global param, false, instance param
- Parameters:
- key (required)
- Specifies the key for the cache'd parameter, either the package instance id (instance parameter) or package key (global parameter).
- parameter_name (required)
- Specifies the parameter name that is being cached.
- Returns:
- The cached value.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- auth_password_change, auth_use_email_for_login_p, auth_email_on_password_change, parameter__check_procs
ad_parameter_from_configuration_file (public)
ad_parameter_from_configuration_file name [ package_key ]
Return the value of a parameter that has been set in the configuration file. It is possible to set Example snippets of the configuration file:
ns_section ns/server/$server/acs { ns_param CSPEnabledP 1 ns_param PasswordHashAlgorithm "argon2-12288-3-1 scram-sha-256 salted-sha1" } ns_section ns/server/$server/acs/acs-templating { ns_param UseHtmlAreaForRichtextP 2 } ns_section ns/server/$server/acs/xowiki { ns_param MenuBar 1 }Note that kernel parameters have no package key included in the section name of the configuration file (see above).
- Parameters:
- name (required)
- The name of the parameter.
- package_key (optional)
- package key of the package from which the parameter value is to be retrieved. When the package_key is omitted, the kernel parameters are assumed
- Returns:
- The parameter of the object or if it doesn't exist, the default.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- ad_parameter_from_configuration_file
ad_parameter_from_file (public, deprecated)
ad_parameter_from_file name [ package_key ]
Deprecated. Invoking this procedure generates a warning.
Old version of ad_parameter_from_configuration_file
- Parameters:
- name (required)
- package_key (optional)
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
ad_progress_bar_begin (public)
ad_progress_bar_begin -title title [ -message_1 message_1 ] \ [ -message_2 message_2 ] [ -template template ]
Return a progress bar.
Example:
ad_progress_bar_begin -title "Installing..." -message_1 "Please wait..." -message_2 "Will continue automatically"...ad_progress_bar_end -url $next_page
- Switches:
- -title (required)
- The title of the page
- -message_1 (optional)
- Message to display above the progress bar.
- -message_2 (optional)
- Message to display below the progress bar.
- -template (optional, defaults to
"/packages/acs-tcl/lib/progress-bar"
)- Name of template to use. Default value is recommended.
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
ad_progress_bar_end (public)
ad_progress_bar_end -url url \ [ -message_after_redirect message_after_redirect ]
Ends the progress bar by causing the browser to redirect to a new URL.
- Switches:
- -url (required)
- -message_after_redirect (optional)
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
ad_publisher_name (public)
ad_publisher_name
A human-readable name of the publisher, suitable for legal blather.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- user_links_api
ad_pvt_home (public)
ad_pvt_home
This is the URL of a user's private workspace on the system, usually [subsite]/pvt/home.tcl
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- user_links_api
ad_pvt_home_link (public)
ad_pvt_home_link
- Returns:
- the HTML fragment for the /pvt link
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- user_links_api
ad_pvt_home_name (public)
ad_pvt_home_name
This is the name that will be used for the user's workspace (usually "Your Workspace").
- Returns:
- the name especified for the user's workspace in the HomeName kernel parameter.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- user_links_api
ad_return_complaint (public)
ad_return_complaint exception_count exception_text
Return a page complaining about the user's input (as opposed to an error in our software, for which ad_return_error is more appropriate)
- Parameters:
- exception_count (required)
- Number of exceptions. Used to say either 'a problem' or 'some problems'.
- exception_text (required)
- HTML chunk to go inside an UL tag with the error messages.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- create_folder_with_page, create_workflow_with_instance, xowiki_test_cases, create_form_with_form_instance
ad_return_error (public)
ad_return_error title explanation
Returns a page with the HTTP 500 (Error) code, along with the given title and explanation. Should be used when an unexpected error is detected while processing a page.
- Parameters:
- title (required)
- explanation (required)
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
ad_return_exception_page (public)
ad_return_exception_page status title explanation
Returns an exception page.
- Parameters:
- status (required)
- HTTP status to be returned (e.g. 500, 404)
- title (required)
- Title to be used for the error (will be shown to user)
- explanation (required)
- Explanation for the exception.
- Author:
- Unknown
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
ad_return_forbidden (public)
ad_return_forbidden [ title ] [ explanation ]
Returns a page with the HTTP 403 (Forbidden) code, along with the given title and explanation. Should be used by access-control filters that determine whether a user has permission to request a particular page. Title and explanation are optional. If 'title' is not specified, then a default localized system message will be displayed. If 'explanation' is not specified, it will default to the title.
- Parameters:
- title (optional)
- explanation (optional)
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
ad_return_if_another_copy_is_running (public)
ad_return_if_another_copy_is_running [ max_simultaneous_copies ] \ [ call_adp_break_p ]
Returns a page to the user about how this server is busy if another copy of the same script is running. Then terminates execution of the thread. Useful for expensive pages that do sequential searches through database tables, etc. You don't want to tie up all of your database handles and deny service to everyone else. The call_adp_break_p argument is essential if you are calling this from an ADP page and want to avoid the performance hit of continuing to parse and run.
- Parameters:
- max_simultaneous_copies (optional, defaults to
"1"
)- call_adp_break_p (optional, defaults to
"0"
)- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
ad_return_string_as_file (public)
ad_return_string_as_file -string string -filename filename \ -mime_type mime_type
Return a string as the content of a file
- Switches:
- -string (required)
- Content of the file to be sent back
- -filename (required)
- Name of the file to be returned
- -mime_type (required)
- Mime Type of the file being returned
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
ad_return_url (public)
ad_return_url [ -urlencode ] [ -path_encode ] [ -qualified ] \ [ -default_url default_url ] [ extra_args ]
Build a return url suitable for passing to a page you expect to return back to the current page. Per default, the result is URL-encoded (like the result of "export_vars" or ":pretty_link").
Example for direct inclusion in a link:
ad_returnredirect "foo?return_url=[ad_return_url]"Example setting a variable to be used by export_vars:set return_url [ad_return_url] set edit_link [export_vars -base edit item_id return_url]Example setting a variable with extra_vars:set return_url [ad_return_url [list [list some_id $some_id] [list some_other_id $some_other_id]]]
- Switches:
- -urlencode (optional, boolean)
- -path_encode (optional, boolean, defaults to
"true"
)- If false do no URL-encode the result
- -qualified (optional, boolean)
- If provided the return URL will be fully qualified including http or https.
- -default_url (optional, defaults to
"."
)- When there is no connection, fall back to this URL
- Parameters:
- extra_args (optional)
- A list of {name value} lists to append to the query string
- Author:
- Don Baccus <dhogaza@pacifier.com>
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- login_logout_urls, xowiki_test_cases
ad_return_warning (public)
ad_return_warning title explanation
Returns a page with the HTTP 200 (Success) code, along with the given title and explanation. Should be used when an exceptional condition arises while processing a page which the user should be warned about, but which does not qualify as an error.
- Parameters:
- title (required)
- explanation (required)
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
ad_site_home_link (public)
ad_site_home_link
- Returns:
- a link to the user's workspace if the user is logged in. Otherwise, a link to the page root.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- user_links_api
ad_system_name (public)
ad_system_name
This is the main name of the Web service that you're offering on top of the OpenACS Web Publishing System.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- user_links_api
ad_system_owner (public)
ad_system_owner
Person who owns the service this person would be interested in user feedback, etc.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- acs_mail_lite_inbound_procs_check
ad_url (public)
ad_url
This will be called by email alerts. Do not use ad_conn location
- Returns:
- the system url as defined in the kernel parameter SystemURL.
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- sync_http_get_document, data_links_scan_links, data_links_scan_links_with_tag, util_http_json_encoding
doc_return (public)
doc_return [ args... ]
A wrapper to be used instead of ns_return. It calls
db_release_unused_handles
prior to calling ns_return. This should be used instead ofns_return
at the bottom of every non-templated user-viewable page.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.