Class RenderingConfig

Represents per-operation configuration information which influences the behaviour of the rendering process. This class is immutable; use a builder to prepare & build configuration objects in a mutable manner.

Inheritance
System.Object
RenderingConfig
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.Config
Assembly: ZptSharp.Abstractions.dll
Syntax
public class RenderingConfig
Remarks

Each of the methods of IRendersZptFile or IRendersZptDocument accepts an optional rendering configuration parameter, which influences how that rendering operation will behave. The default for both of these APIs, if configuration is omitted or null, is to use a Default configuration instance.

Because every instance of rendering configuration is immutable, a builder object must be used to set-up the configuration object before it is used. The primary way to do this is:

  1. Use the CreateBuilder() method to get a builder
  2. Alter the settings as desired upon the builder
  3. Use GetConfig() to build the configuration object

An alternative way to get a customised rendering configuration is to copy the settings/state of an existing configuration object into a builder. This is performed via CloneToNewBuilder(). You may then use that builder from step 2 onward in the process described above, except that it will be pre-filled with the same state as in the cloned configuration.

Examples

The following logic creates a new rendering configuration which has source annotation enabled. 

var builder = RenderingConfig.CreateBuilder();
builder.IncludeSourceAnnotation = true;
var config = builder.GetConfig();

This logic then creates a second rendering configuration based upon the example above which also uses a default expression type of string. 

var builder2 = config.CloneToNewBuilder();
builder2.DefaultExpressionType = "string";
var config2 = builder2.GetConfig();

Constructors

| Improve this Doc View Source

RenderingConfig()

The constructor for RenderingConfig is intentionally langword_csharp_private. Instances of this class must be created via a RenderingConfig.Builder.

Declaration
protected RenderingConfig()

Properties

| Improve this Doc View Source

ContextBuilder

Gets a callback which is used to extend the root contexts, without needing to replace the RootContextsProvider.

Declaration
public virtual Action<IConfiguresRootContext, IServiceProvider> ContextBuilder { get; }
Property Value
Type Description
System.Action<IConfiguresRootContext, System.IServiceProvider>

The context builder action.
Remarks

This configuration setting provides a convenient way to add additional root contexts; pre-defined variables which are available to the entire rendering process. Using this setting avoids the need to use a custom RootContextsProvider implementation when all that was desired was to add extra variables.

| Improve this Doc View Source

Default

Gets an instance of RenderingConfig with default values.

Declaration
public static RenderingConfig Default { get; }
Property Value
Type Description
RenderingConfig

The default rendering config.
Remarks

The property values for a default rendering configuration are as follows. This applies to instances created via this static property and also the 'starting' state of a builder created via CreateBuilder().

DocumentEncodingEncoding.UTF8
DocumentProviderTypenull
OmitXmlDeclarationfalse
RootContextsProvidernull
KeywordOptionsAn empty dictionary
ContextBuilderAn empty/no-op action
IncludeSourceAnnotationfalse
SourceAnnotationBasePathnull
DefaultExpressionTypeThe string path
XmlUrlResolvernull
| Improve this Doc View Source

DefaultExpressionType

Gets the default expression type name/prefix, used for TALES expressions which do not have a prefix.

Declaration
public virtual string DefaultExpressionType { get; }
Property Value
Type Description
System.String

The default expression-type prefix.
Remarks

In TALES expressions used by the ZPT rendering process, prefixing the expression with an expression-type is optional. The rendering process always has a configured default expression type. Unprefixed expressions are assumed to be of that default type.

This configuration setting permits the changing of that default expression type.

| Improve this Doc View Source

DocumentEncoding

Gets the encoding which will be used to read & write documents, where the document provider supports it.

Declaration
public virtual Encoding DocumentEncoding { get; }
Property Value
Type Description
System.Text.Encoding

The document encoding.
Remarks

Not all document providers will honour this encoding configuration setting; it is respected only where the underlying DOM document reader/writer supports it. Refer to the documentation of the document provider used - the implementation of IReadsAndWritesDocument - to see if this configuration property is supported.

Where supported, this configuration setting allows the reading & writing of ZPT documents which use different character encodings.

In all modern cases, of course, UTF8 is the recommended encoding.

See Also
| Improve this Doc View Source

DocumentProviderType

Gets the type of document provider implementation which is to be used for the current rendering task.

Declaration
public virtual Type DocumentProviderType { get; }
Property Value
Type Description
System.Type

The document provider implementation type to be used by the document-renderer service.
Remarks

When using IRendersZptFile, this configuration property is irrelevant and ignored. The file-rendering service will select an appropriate document renderer type based upon the filename & extension of the source file.

This configuration property is important when making use of IRendersZptDocument, though. Because the document-rendering service does not use a file path, there is no filename or extension to analyse. When using the document rendering service, this configuration property is used to specify which document provider implementation should be used to read & write the underlying DOM document.

See Also
| Improve this Doc View Source

IncludeSourceAnnotation

Gets a value which indicates whether or not source annotation should be written to the rendered document.

Declaration
public virtual bool IncludeSourceAnnotation { get; }
Property Value
Type Description
System.Boolean

true if source annotation should be included in the output; otherwise, false.
Remarks

Source annotation is a useful ZPT feature used for debugging and understanding the rendering process, such as when diagnosing a problem. When source annotation is enabled, each time there is an insertion of markup from a different source, an HTML/XML comment is added indicating that source and source line number. The insertion of markup most commonly refers to the usage of METAL macros and the filling of slots. It helps developers confidently understand "where did this output come from"?

The "source" for any document is simplest when IRendersZptFile is used, since it is quite simply the path to the file, relative to SourceAnnotationBasePath where applicable. When IRendersZptDocument is used instead then a source info object would be passed (via optional parameter) to RenderAsync(Stream, Object, RenderingConfig, CancellationToken, IDocumentSourceInfo). A custom implementation of IDocumentSourceInfo could represent anything, such as a database key, API URI or whatever application-specific information is applicable.

Examples

Here is a sample of what source annotation could look like the following in the rendered output. It appears as an HTML or XML comment, designated by a block of = symbols. It then shows the string representation of the source information and the line number at which the included content originated. 

<span>This span element was originally defined in "MyMacro.pt", line 4</span><!--
==============================================================================
MySourceFiles\MyMacro.pt (line 4)
==============================================================================
-->
    This is further content in the rendered output document.
See Also
| Improve this Doc View Source

KeywordOptions

Gets a collection of name/value pairs available at the root TALES context (variable) named options.

Declaration
public virtual IReadOnlyDictionary<string, object> KeywordOptions { get; }
Property Value
Type Description
System.Collections.Generic.IReadOnlyDictionary<System.String, System.Object>

The keyword options collection.
Remarks

Keyword options are a series of arbitrary name/value pairs. Their precise semantics are loosely-defined by the ZPT syntax specification and the functionality is very rarely-used in real-life implementations, nor is it recommended to begin using them if not absolutely neccesary. Keyword options could, for example, be used to contain arbitrary name/value arguments passed to a command-line app. In all foreseeable use-cases though, the model is a far better way to make data available to document templates.

Note that because options is a root TALES context, if the RootContextsProvider configuration setting is also specified, then that could mean that this setting is not honoured. It is up to a custom implementation of the root contexts provider to include the keyword options.

| Improve this Doc View Source

OmitXmlDeclaration

Gets a value which indicates whether the XML document declaration should be omitted when writing XML documents. Has no effect unless an XML-based document provider is used.

Declaration
public virtual bool OmitXmlDeclaration { get; }
Property Value
Type Description
System.Boolean

true if the XML document declaration should be omitted; otherwise, false.
Remarks

This controls XML-style document provider implementations and instructs them whether to write or whether to omit the <?xml ... ?> declarations on the first line of the file.

Obviously, document providers which render HTML and not XML documents will ignore this configuration setting.

| Improve this Doc View Source

RootContextsProvider

Gets a 'factory delegate' which provides the root contexts for expression resolution.

Declaration
public virtual Func<ExpressionContext, IGetsDictionaryOfNamedTalesValues> RootContextsProvider { get; }
Property Value
Type Description
System.Func<ExpressionContext, IGetsDictionaryOfNamedTalesValues>

The root contexts provider.
Remarks

The root contexts are the variables which are available to all TALES expressions before any further variables are defined. They are essentially the pre-defined variables which are already in-scope at the root of the DOM document. These variables are available in their own right or also as properties of a special root contexts object, accessible via the TALES keyword CONTEXTS. That contexts keyword may not be overridden by any other variable definition, meaning that the root contexts are always available via that reference.

This configuration property allows the use of a customised service which gets those root contexts. A developer may write their own implementation of IGetsDictionaryOfNamedTalesValues which contains any arbitrary logic to retrieve those variables. The format of this property is a 'factory delegate' (a function) taking a parameter of type ExpressionContext and returning the implementation of IGetsDictionaryOfNamedTalesValues.

For the majority of foreseen usages, this configuration property does not need to be used. If this property is null then the rendering process will use a default implementation of IGetsDictionaryOfNamedTalesValues which provides the standard root contexts. In particular, developers do not need to write their own implementation of IGetsDictionaryOfNamedTalesValues in order to simply add extra root contexts/variables to the rendering process. In order to add additional variables, developers should use the ContextBuilder configuration property instead. Passing model data to the rendering process also does not need a customised root contexts provider. Model data is passed as a separate parameter to the rendering process and is accessible via the built-in root context here.

Please note that if this property is specified then it is up to the custom implementation of IGetsDictionaryOfNamedTalesValues to include the keyword options in the root contexts, using the name options. If the custom implementation does not do this, then the configuration property KeywordOptions will not be honoured. There are two ways in which a custom implementation may achieve this.

  • It may constructor-inject an instance of RenderingConfig and include the keyword options in its own output.
  • It may derive from the standard implementation of IGetsDictionaryOfNamedTalesValues found in the ZptSharp implementations package and override/supplement its returned results.
| Improve this Doc View Source

SourceAnnotationBasePath

Gets a file system path which is used as the base path to shorten source annotation filenames, when IncludeSourceAnnotation is true.

Declaration
public virtual string SourceAnnotationBasePath { get; }
Property Value
Type Description
System.String

The base path used for shorting the paths of source files in logs and source annotation.
Remarks

This configuration setting is only relevant when IncludeSourceAnnotation is true and also when documents are rendered from file system files, such as when IRendersZptFile is being used. In any other scenario this configuration setting will not be used and will have no effect.

When source annotation comments are added to the rendered output, if the source of a document is a filesystem file, the comment will include the path to that file. If this configuration setting is not specified or is null then the full, absolute file path will be recorded in the comment. If this configuration setting is specified, and the source file (receiving the source annotation comment) is a descendent of this base path, then only the relative portion of the file path will be recorded in the source annotation comment.

If the document file receiving the source annotation comment is not a descendent of this base path, then the full absolute path will still be used.

Examples

These examples show a few combinations of what would be written in the source annotation comments for various scenarios.

  • If IncludeSourceAnnotation is false then no source annotation would be written at all, and this setting (and all other scenarios listed here) would be meaningless.
  • If the source of the documents involved is not a file from a file system: FileSourceInfo then this configuration setting is meaningless. The source information written to the comments would always come directly from the implementation of IDocumentSourceInfo.
  • If the source of the document were C:\MyDirectory\MyFile.html and this configuration setting is null then source annotation comments would refer to that document using the path C:\MyDirectory\MyFile.html.
  • If the source of the document were C:\MyDirectory\MyFile.html and this configuration setting is C:\MyDirectory then source annotation comments would refer to that document using the path MyFile.html.
  • If the source of the document were C:\MyDirectory\MySubDir\MyFile.html and this configuration setting is C:\MyDirectory then source annotation comments would refer to that document using the path MySubDir\MyFile.html.
  • If the source of the document were C:\OtherDirectory\MyFile.html and this configuration setting is C:\MyDirectory then source annotation comments would refer to that document using the path C:\OtherDirectory\MyFile.html. The absolute path would be used because the source file is outside the base path.
See Also
| Improve this Doc View Source

XmlUrlResolver

Gets a custom XML URL resolver which should be used to resolve XML namespaces for XML-based document providers.

Declaration
public virtual XmlUrlResolver XmlUrlResolver { get; }
Property Value
Type Description
System.Xml.XmlUrlResolver
Remarks

When using an XML-based document provider (and only when using an XML-based document provider), in order to fully validate these documents (and provide appropriate entity support), supporting assets are required. These can include DTDs, modules and the like. When making use of an XML document which conforms to a DTD, it is usually desirable (for both performance and security purposes) to use a custom XML URL resolver. This allows techniques such as caching, security-enforcement and perhaps even the local serving of those assets without making any HTTP(s) requests at all.

When set, this configuration setting specifies the custom XML URL resolver which should be used by XML-based document providers. It has no effect at all upon HTML-based document providers.

Please note that the official ZptSharp XML document provider includes a URL provider which serves XHTML assets from embedded resources, bypassing all HTTP requests. This built-in URL provider will be used if this configuration setting is null.

Methods

| Improve this Doc View Source

CloneToNewBuilder()

Creates and returns a new RenderingConfig.Builder instance which has its initial state/settings copied from the current configuration instance.

Declaration
public RenderingConfig.Builder CloneToNewBuilder()
Returns
Type Description
RenderingConfig.Builder

A configuration builder.
Remarks

Use this method to create a new configuration builder which is based upon the current configuration, but may then be modified before it is used to create a new configuration. Rendering configuration objects are immutable and cannot be altered after they have been built/created. This method is a convenience to allow the next-best-thing: creating a new builder, cloned from an existing configuration.

This method does not allow editing of the configuration from which the builder was cloned. Changes made to the returned builder object will not affect the original configuration object.

| Improve this Doc View Source

CreateBuilder()

Creates a new configuration builder object with a default set of state.

Declaration
public static RenderingConfig.Builder CreateBuilder()
Returns
Type Description
RenderingConfig.Builder

A configuration builder with default initial state.
Remarks

The initial state of the builder object returned by this method will be the same as the state which would be created by Default. Refer to the documentation of the default property to see what that state would be.

The builder may be used to set-up the intended state of a configuration object. Use GetConfig() to build and return a configuration object from that builder, once the desired settings have been made.

See Also