Class RenderingConfig.Builder

A mutable API with the same properties as RenderingConfig. Allows setting up a desired state before being used to create an immutable configuration object via GetConfig().

Inheritance
System.Object
RenderingConfig.Builder
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 Builder
Remarks

Rendering configuration object are immutable and may not be altered once they have been created. Use a configuration builder to set the properties/configuration settings as desired, before building the configuration object itself.

Properties

| Improve this Doc View Source

ContextBuilder

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

Declaration
public Action<IConfiguresRootContext, IServiceProvider> ContextBuilder { get; set; }
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

DefaultExpressionType

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

Declaration
public string DefaultExpressionType { get; set; }
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 or sets the encoding which will be used to read & write documents, where the document provider supports it.

Declaration
public Encoding DocumentEncoding { get; set; }
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 or sets the type of document provider implementation which is to be used for the current rendering task.

Declaration
public Type DocumentProviderType { get; set; }
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 or sets a value which indicates whether or not source annotation should be written to the rendered document.

Declaration
public bool IncludeSourceAnnotation { get; set; }
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 or sets a collection of name/value pairs available at the root TALES context (variable) named options.

Declaration
public IDictionary<string, object> KeywordOptions { get; set; }
Property Value
Type Description
System.Collections.Generic.IDictionary<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 or sets 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 bool OmitXmlDeclaration { get; set; }
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 or sets a 'factory delegate' which provides the root contexts for expression resolution.

Declaration
public Func<ExpressionContext, IGetsDictionaryOfNamedTalesValues> RootContextsProvider { get; set; }
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 or sets a file system path which is used as the base path to shorten source annotation filenames, when IncludeSourceAnnotation is true.

Declaration
public string SourceAnnotationBasePath { get; set; }
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 or sets a custom XML URL resolver which should be used to resolve XML namespaces for XML-based document providers.

Declaration
public XmlUrlResolver XmlUrlResolver { get; set; }
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

GetConfig()

Builds and returns a configuration object based on the state of the current builder instance. This method may be used only once per builder instance.

Declaration
public RenderingConfig GetConfig()
Returns
Type Description
RenderingConfig

The immutable rendering configuration.
Remarks

Rendering configuration objects (as returned by this method) are immutable and may not be modified in any way after they are created.

In addition, this method may be used only once per builder instance. After a configuration object has been created, the builder which created it is no longer usable. It is possible to build another configuration object based upon an existing one, though, by use of CloneToNewBuilder().