Class ExpressionContext

An object which provides contextual values for the rendering of TALES expressions.

Inheritance

System.Object

ExpressionContext

Inherited Members

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.ToString()

Namespace: ZptSharp.Expressions

Assembly: ZptSharp.Abstractions.dll

Syntax

public class ExpressionContext

Remarks

This class encapsulates the state for every ZPT operation performed upon a DOM node. That state is contextual, related to the current position in the DOM document and other operations which have occured previously.

Some ZPT operations, such as tal:define, will make alterations to the current context. Others might just read it.

Apart from the root context (see IsRootContext), every context is created by cloning its parent context and substituting a different 'current' DOM node. The structure of parent-to-child expression contexts follows the structure of the DOM.

Constructors

ExpressionContext(INode)

Initializes a new instance of the ExpressionContext class.

Declaration

public ExpressionContext(INode node)

Parameters

Type	Name	Description
INode	node	The DOM node for this context.

Remarks

This constructor is typically used for the root expression context. All of the other state of the context (apart from the current node) will be initialized with default/empty values. Even if this is for a root context, IsRootContext must still be set manually.

ExpressionContext(INode, IDictionary<String, Object>, IDictionary<String, Object>, IDictionary<String, RepetitionInfo>, Stack<ErrorHandlingContext>)

Initializes a new instance of the ExpressionContext class; this is (to a degree) a copy-constructor.

Declaration

public ExpressionContext(INode node, IDictionary<string, object> localDefinitions, IDictionary<string, object> globalDefinitions, IDictionary<string, RepetitionInfo> repetitions, Stack<ErrorHandlingContext> errorHandlers)

Parameters

Type	Name	Description
INode	node	The DOM node for this context.
System.Collections.Generic.IDictionary<System.String, System.Object>	localDefinitions	Local definitions.
System.Collections.Generic.IDictionary<System.String, System.Object>	globalDefinitions	Global definitions.
System.Collections.Generic.IDictionary<System.String, RepetitionInfo>	repetitions	Repetitions.
System.Collections.Generic.Stack<ErrorHandlingContext>	errorHandlers	Error handlers

Remarks

The localDefinitions, repetitions & errorHandlers are shallow-copied by this constructor. This is because changes to these collections which are made inside of a context should not affect any other context

On the other hand, globalDefinitions is used directly without copying, because changes to the global definitions should affect other contexts, including those 'outside' of this one.

Properties

CurrentNode

Gets or sets the current DOM node being rendered by this context.

Declaration

public INode CurrentNode { get; set; }

Property Value

Type	Description
INode	The DOM node (typically an element node).

Remarks

Every ZPT operation has a current DOM node, because the ZPT operations are declared within the attributes of element nodes. It would be very unusual for this node object not to be a DOM element node.

Error

Gets or sets an object representing an error which was encountered whilst rendering or evaluating an expression.

Declaration

public object Error { get; set; }

Property Value

Type	Description
System.Object	The error (usually an exception).

Remarks

The error object will almost always derive from System.Exception. If it is null then no error has occurred when rendering; if not then it will describe the error which is currently being handled.

ErrorHandlers

Gets a collection of the contexts & handlers which might be able to deal with errors encountered whilst processing this context.

Declaration

public Stack<ErrorHandlingContext> ErrorHandlers { get; }

Property Value

Type	Description
System.Collections.Generic.Stack<ErrorHandlingContext>	The error handlers.

Remarks

Error handlers are added to this property by the parent contexts. Much like the C# try & catch keywords, ZPT rendering errors 'propagate upwards' through the DOM. This occurs until either they are handled by a tal:on-error attribute or until they 'escape' the root of the DOM. In the second case, this will lead to an exception being raised for the overall rendering operation. A rendering error upon an element might be handled by a tal:on-error attribute defined upon that same element, its parent element, grandparent or more disatant ancestor.

GlobalDefinitions

Gets the global variable definitions for the current context.

Declaration

public IDictionary<string, object> GlobalDefinitions { get; }

Property Value

Type	Description
System.Collections.Generic.IDictionary<System.String, System.Object>	The global definitions.

Remarks

Definitions are the variables which are available to ZPT operations using this context. There are three types of definitions.

• LocalDefinitions
• GlobalDefinitions (this property)
• Repetitions

Local definitions are scoped to the DOM element upon which they are created (via the tal:define keyword) and that DOM element's descendents. A locally-defined variable is not visible 'outside' of the element where it was defined.

Global definitions are in-scope from the document position at which they were defined and onwards in the document (in source code order). Globally-defined variables do not use the DOM structure; global variables are usable outside of the element & descendents where they were defined, as long as it is after the point of definition in the document source code.

Repetitions are a special type of variable which are created only by the tal:repeat operation. They behave identically to locally-defined variables except that they have a standard set of properties, defined by the RepetitionInfo class.

IsRootContext

Gets or sets a value indicating whether this ExpressionContext is the root context.

Declaration

public bool IsRootContext { get; set; }

Property Value

Type	Description
System.Boolean	true if this is the root context; otherwise, false.

Remarks

The root context is typically synonymous with the root DOM node in the document. The root context is one which was not created from a parent context.

LocalDefinitions

Gets the local variable definitions for the current context.

Declaration

public IDictionary<string, object> LocalDefinitions { get; }

Property Value

Type	Description
System.Collections.Generic.IDictionary<System.String, System.Object>	The local definitions.

Remarks

Definitions are the variables which are available to ZPT operations using this context. There are three types of definitions.

• LocalDefinitions (this property)
• GlobalDefinitions
• Repetitions

Local definitions are scoped to the DOM element upon which they are created (via the tal:define keyword) and that DOM element's descendents. A locally-defined variable is not visible 'outside' of the element where it was defined.

Global definitions are in-scope from the document position at which they were defined and onwards in the document (in source code order). Globally-defined variables do not use the DOM structure; global variables are usable outside of the element & descendents where they were defined, as long as it is after the point of definition in the document source code.

Repetitions are a special type of variable which are created only by the tal:repeat operation. They behave identically to locally-defined variables except that they have a standard set of properties, defined by the RepetitionInfo class.

Model

Gets or sets the model object from which this context was created.

Declaration

public object Model { get; set; }

Property Value

Type	Description
System.Object	The model.

Remarks

This is typically the model which was initially passed to the rendering process. It may be of any object (and could legitimately be null). Its precise semantics depend upon the application/current usage of ZptSharp.

Repetitions

Gets the repetition variable definitions for the current context.

Declaration

public IDictionary<string, RepetitionInfo> Repetitions { get; }

Property Value

Type	Description
System.Collections.Generic.IDictionary<System.String, RepetitionInfo>	The repetition definitions.

Remarks

Definitions are the variables which are available to ZPT operations using this context. There are three types of definitions.

• LocalDefinitions
• GlobalDefinitions
• Repetitions (this property)

Local definitions are scoped to the DOM element upon which they are created (via the tal:define keyword) and that DOM element's descendents. A locally-defined variable is not visible 'outside' of the element where it was defined.

Global definitions are in-scope from the document position at which they were defined and onwards in the document (in source code order). Globally-defined variables do not use the DOM structure; global variables are usable outside of the element & descendents where they were defined, as long as it is after the point of definition in the document source code.

Repetitions are a special type of variable which are created only by the tal:repeat operation. They behave identically to locally-defined variables except that they have a standard set of properties, defined by the RepetitionInfo class.

TemplateDocument

Gets or sets the DOM document being used as a template to render the current rendering request.

Declaration

public IDocument TemplateDocument { get; set; }

Property Value

Type	Description
IDocument	The template document.

Remarks

This is the document currently being rendered. In scenarios where a rendering request touches and draws source from many documents (METAL macro usage), this document is the primary/initial document which was selected as the template.

Methods

CreateChild(INode)

Gets a clone of the current expression context, using a specified node as the current node for the created context.

Declaration

public ExpressionContext CreateChild(INode node)

Parameters

Type	Name	Description
INode	node	The node for the cloned context.

Returns

Type	Description
ExpressionContext	The cloned expression context.

Remarks

This method is provided for the creation of child expression contexts. The node is intended to be a child of the CurrentNode.

Because this is intended to be a child context, the local definitions, repetitions & error handlers are cloned by this method, such that modifications to these collections upon the child context do not affect the parent.

The exception to this, is the GlobalDefinitions. Global definitions are intentionally not cloned, because a child's changes to global definitions may indeed affect parent contexts. A global definition is in-scope from the moment it is defined, for the remainder of the document, regardless of the DOM hierarchy.

Extension Methods

ExpressionContextExtensions.CreateChildren(ExpressionContext, IList<INode>)

ExpressionContextExtensions.CreateChildren(ExpressionContext, IReadOnlyList<INode>)