Terminates processing of a template and throws away all output.

Testcases:

No testcase defined.

Adds a line of code to the Tcl output from the compiler. Called by basically any adp custom tag implementation and also from developer support.

Parameters:

code (required)

A line of Tcl code

nobreak (optional)

Options:

-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.

Testcases:

template_widget_file, adp_parse_tags

Adds a line of code that appends a string to the Tcl output from the compiler.

Parameters:

s (required)

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.

Testcases:

No testcase defined.

The regexp pattern used to find adp array variables in a piece of text (i.e. @array_name.variable_name@). Captures the character preceding the first @ in \1, the array_name in \2, and variable_name in \3

Author:

Peter Marklund <peter@collaboraid.biz>

Created:

25 October 2002

Testcases:

template_variable

adp_array_variable_regexp's pattern augmented by "literal"

Author:

Gustaf Neumann

Created:

December 2012

Testcases:

template_variable

adp_array_variable_regexp's pattern augmented by "noi18n"

Author:

Gustaf Neumann

Created:

June 2015

Testcases:

template_variable

adp_array_variable_regexp's pattern augmented by "noquote"

Author:

Dirk Gomez <openacs@dirkgomez.de>

Created:

12 February 2003

Testcases:

template_variable

Converts an ADP template into a chunk of Tcl code. Caching this code avoids the need to reparse the ADP template with each request.

Switches:

-file (optional)

The filename of the source

-string (optional)

string to be compiled

Returns:

The compiled code. Valid options are either -string or -file

Testcases:

ad_dimensional, template_widget_file, xowiki_test_cases

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.

Parameters:

chunk (required)

A string containing markup, potentially with embedded ADP tags.

Testcases:

adp_parse_tags

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.

Parameters:

coderef (required)

Returns:

The output produced by the compiled template code.

Testcases:

ad_dimensional, template_widget_file, xowiki_test_cases

return the output of a Tcl/ADP pair as a string. adp_level is set to the calling procedure so that pass by reference works. and example of using this is in the search indexer for various content types:

    bookshelf::book::get -book_id $book_id -array bookdata
    set body [template::adp_include /packages/bookshelf/lib/one-book  [list &book "bookdata" base $base style feed]]
    

Switches:

-uplevel (optional, defaults to "1")

how far up the stack should the adp_level be set to (default is the calling procedures level)

Parameters:

src (required)

should be the path to the Tcl/ADP pair relative to the server root, as with the src attribute to the include tag.

varlist (required)

a list of {key value key value ... } varlist can also be &var foo for things passed by reference (arrays and multirows)

Returns:

the string generated by the Tcl/ADP pair.

Author:

Jeff Davis davis@xarg.net

Created:

2004-06-02

See Also:

• template::adp_parse

Testcases:

page_contracts, templates_and_scripts

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.

Parameters:

type (required)

Either ADP (template) or Tcl (code)

file_stub (required)

The root (sans file extension) of the absolute path to the .adp or .tcl file to source.

Testcases:

callgraph__bad_page_calls

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

Parameters:

up (optional)

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.

Returns:

A number, as returned by [info level], representing the stack frame in which a template is being parsed.

Testcases:

adp_level

Returns:

all stack frame levels

See Also:

• template::adp_level

Testcases:

No testcase defined.

Execute procedures to prepare data sources and then to output template. Assumes adp_level is set on entry. in general the public version template::adp_include should be used for generating strings from adp files.

Parameters:

__adp_stub (required)

The root (without the file extension) of the absolute path to the template and associated code.

__args (required)

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.

See Also:

• template::adp_include

Testcases:

xowiki_test_cases

Parse the tags of the provided HTML text. This function is similar to

template::adp_compile -string $HTML

Parameters:

HTML (required)

text containing potentially ADP tags

Returns:

HTML text with substituted ADP tags

Testcases:

adp_parse_tags

Helper proc to combine "adp_parse_tags" and "lang::util::localize" as used in the regsub operations for resolving template variables.

Parameters:

HTML (required)

Testcases:

No testcase defined.

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.

Returns:

boolean (0 or 1): whether the (ultimate) script was found.

Testcases:

No testcase defined.

Add text to the ADP currently being rendered. Maybe used within escaped Tcl code in the template to add to the output.

Parameters:

text (required)

A string containing text or markup.

Testcases:

No testcase defined.

Quotes (precedes by backslash) all square brackets, curly braces, double quotes, backslashes, and dollar signs in a chunk of adp.

Parameters:

chunk_var_name (required)

The name of the variable to quote

quoted_var_name (required)

The name of the variable to put the quoted result in

Author:

Peter Marklund <peter@collaboraid.biz>

Created:

2002-10-16

Testcases:

No testcase defined.

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.

Testcases:

No testcase defined.

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).

Parameters:

tag_name (optional)

The name of the tag. Used for debugging purposes only.

Testcases:

No testcase defined.

The regexp pattern used to find adp variables in a piece of text, i.e. occurrences of @variable_name@. Captures the character preceding the first @ in \1 and the variable_name in \2.

Author:

Peter Marklund <peter@collaboraid.biz>

Created:

25 October 2002

Testcases:

template_variable

adp_variable_regexp augmented by "literal"

Author:

Gustaf Neumann

Created:

December 2012

Testcases:

template_variable

adp_variable_regexp augmented by "noi18n"

Author:

Gustaf Neumann

Created:

June 2015

Testcases:

template_variable

adp_variable_regexp augmented by "noquote"

Author:

Dirk Gomez <openacs@dirkgomez.de>

Created:

12 February 2003

Testcases:

template_variable

Return the top level tag from the stack.

Returns:

the tag from the top of the tag stack.

Author:

Lee Denison <lee@runtime-collective.com>

Created:

2002-01-30

Testcases:

No testcase defined.

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.

Parameters:

tag (required)

the type (e.g. multiple) of the enclosing tag to look for.

Returns:

the tag identifier for the enclosing tag

Author:

Lee Denison <lee@runtime-collective.com>

Created:

2002-01-30

Testcases:

No testcase defined.

Expand variables marked with percentage signs in caller's scope. Some examples - if example and array(variable) has the values Erik and Oluf in the caller's scope - the following expansion will occur: Here is an %example% variable. -> Here is an Erik variable. Here is an %array.variable% for you -> Here is an Oluf for you

Parameters:

message (required)

Author:

Christian Hvid

Testcases:

expand_percentage_signs

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.

Parameters:

tag (required)

The name of the tag.

params (required)

The ns_set passed to the tag handler.

name (required)

The name of the attribute.

default (optional, defaults to "ERROR")

A default value to return if the attribute is not specified in the template. A default value of "ERROR" will cause the proc to throw an error if the attribute wasn't supplied.

Returns:

The value of the attribute.

Testcases:

No testcase defined.

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.

Parameters:

path (required)

The root (sans file extension) of the absolute path to the next template to parse.

Testcases:

No testcase defined.

Return an attribute from a tag that has already been processed.

Parameters:

tag (required)

the tag identifier

attribute (required)

the attribute name

Returns:

the value of the tag's attribute

Author:

Lee Denison <lee@runtime-collective.com>

Created:

2002-01-30

Testcases:

No testcase defined.