diff --git a/doc/reference/src/templating.xml b/doc/reference/src/templating.xml index 5fc77f98..e426eaa5 100644 --- a/doc/reference/src/templating.xml +++ b/doc/reference/src/templating.xml @@ -28,7 +28,7 @@ Introduction The Spring Framework features integration classes for templating - engine support. Currently, Spring supports the NVelocity templating engine. @@ -37,24 +37,34 @@ Dependencies The Spring NVelocity support depends on the Castle project's - NVelocity implementation which is provided in the lib directory of the - spring release. + NVelocity implementation which is located in the lib directory of the + Spring release.
- Using the NVelocity Factory Object + Configuring a VelocityEngine The NVelocity template engine is set up using a IFactoryObject with optional configuration parameters - to define where templates reside, define logging and more. + to define where templates reside, define logging and more. For more + information on IFactoryObjects see . A custom namespace + parser is provided to simplify the configuration of a NVelocity template + engine. For more information on custom namespace parser see .
Simple file based template engine definition - A simple definition of the template engine: + You create a simple definition of the template engine that uses + the default resource loader as follows: - <!-- Simple no arg file based configuration use's NVeclocity default file resource loader --> -<object id="velocityEngine" type="Spring.Template.Velocity.VelocityEngineFactoryObject, Spring.Template.Velocity" /> + <objects xmlns="http://www.springframework.net" xmlns:nv="http://www.springframework.net/nvelocity"> + + <!-- Simple no arg file based configuration use's NVeclocity default file resource loader --> + <nv:engine id="velocityEngine" /> + +</objects> The velocity engine could then be used to load and merge a local template using a simple relative path: @@ -65,6 +75,10 @@ modelTable.Add("var1", TEST_VALUE); VelocityContext velocityContext = new VelocityContext(modelTable); velocityEngine.MergeTemplate("Template/Velocity/MyTemplate.vm", Encoding.UTF8.WebName, velocityContext, stringWriter); string mergedContent = stringWriter.ToString(); + + To disable the use of NVelocity's file loader that tracks runtime + changes, set the element prefer-file-system-access of + <engine/> to false.
@@ -73,65 +87,51 @@ string mergedContent = stringWriter.ToString(); When templates are packaged in an assembly, NVelocity's assembly resource loader can be used to define where templates reside: - <!-- Assembly based template loading with NVelocity assembly resource loader --> -<object id="assemblyBasedVelocityEngine" type="Spring.Template.Velocity.VelocityEngineFactoryObject, Spring.Template.Velocity"> - <property name="VelocityProperties"> - <dictionary key-type="string" value-type="object"> - <entry key="resource.loader" value="assembly"/> - <entry key="assembly.resource.loader.class" value="NVelocity.Runtime.Resource.Loader.AssemblyResourceLoader"/> - <entry key="assembly.resource.loader.assembly" value="MyAssembly"/> - </dictionary> - </property> -</object> + <nv:engine id="velocityEngine" > + <nv:resource-loader> + <nv:assembly name="MyAssembly" /> + </nv:resource-loader> +</nv:nvelocity> Using the example above the template would be loaded using a namespace syntax for the template resource: velocityEngine.MergeTemplate("MyAssembly.MyNamespace.MyTemplate.vm", Encoding.UTF8.WebName, velocityContext, stringWriter); - - Using the custom namespace the same definition could be - simplified: - - <template:nvelocity id="velocityEngine" > - <template:resource-loader> - <template:assembly name="MyAssembly" /> - </template:resource-loader> -</template:nvelocity>
Using Spring's <literal>IResourceLoader</literal> to load templates - In some cases Spring's resource abstraction can be beneficial to - load templates from a variety of resources. A spring resource loader - extension to the NVelocity resource loader implementation is provided - for this use case. + In some cases Spring's IResource + abstraction can be beneficial to load templates from a variety of + resources. A Spring IResource loader extension to the NVelocity resource + loader implementation is provided for this use case. The following + object definition loads the NVelocity templates from a single + path - <object id="velocityEngine" type="Spring.Template.Velocity.VelocityEngineFactoryObject, Spring.Template.Velocity" > - <property name="ResourceLoaderPath" value="file://MyTemplateFolder/AnotherFolder/" /> -</object> - + <nv:engine id="velocityEngine"> + <nv:resource-loader> + <nv:file path="MyTemplateFolder/AnotherFolder/" /> + </nv:resource-loader> +</nv:engine> Or with multiple locations - <object id="velocityEngine" type="Spring.Template.Velocity.VelocityEngineFactoryObject, Spring.Template.Velocity" > - <property name="ResourceLoaderPaths" > - <list> - <value>file://MyTemplateFolder/</value> - <value>file://MyOtherTemplateFolder/</value> - </list> - </property> -</object> + <nv:engine id="velocityEngine"> + <nv:resource-loader> + <nv:file path="MyTemplateFolder/AnotherFolder/" /> + <nv:file path="MyOtherTemplateFolder/" /> + </nv:resource-loader> +</nv:engine> + By default spring will attempt to load resources using file based template loading (useful for detection of template changes at runtime). If this is not desirable you set the - preferFileSystemAccess property of the factory - object to false - (prefer-file-system-access="false" for custom - namespace use) + prefer-file-system-access element of the + </engine> element to false. Using the example above when resource loader paths are defined @@ -146,19 +146,22 @@ string mergedContent = stringWriter.ToString(); If so desired one could provide a custom configuration resource to customize the NVelocity configuration: - <object id="velocityEngine" type="Spring.Template.Velocity.VelocityEngineFactoryObject, Spring.Template.Velocity" > - <property name="ConfigLocation " value="file://Template/Velocity/config.properties" /> -</object> + <nv:engine id="velocityEngine" config-file="file://Template/Velocity/config.properties"/> - - - You can override specific properties by providing the VelocityProperties property to the NVelocity factory object (shown above) - - + You can override specific properties by providing the + VelocityProperties property to the NVelocity factory + object (shown above) + + <nv:engine id="customNamespaceVelocityTemplate" config-file="foo.prop"> + <nv:nvelocity-properties> + <entry key="input.encoding" value="ISO-8859-1"/> + <entry key="output.encoding" value="ISO-8859-1"/> + </nv:nvelocity-properties> +</nv:engine>
- + Logging @@ -166,30 +169,17 @@ string mergedContent = stringWriter.ToString(); By default Spring will override NVelocity's default ILogSystem implementation with its own - CommonsLoggingLogSystem implementation. If this is - not desirable, you can specify the following property of the NVelocity - factory object: + CommonsLoggingLogSystem implementation so that the + logging stream of NVelocity will go to the same logging subsystem that + Spring uses. If this is not desirable, you can specify the following + property of the NVelocity factory object: - <object id="velocityEngine" type="Spring.Template.Velocity.VelocityEngineFactoryObject, Spring.Template.Velocity" > - <property name="OverrideLogging" value="false" /> -</object> - - or - <template:nvelocity id="velocityEngine" override-logging="false" /> - - - - You can override specific NVelocity properties locally by - providing a dictionary as the VelocityProperties - property of the NVelocity factory object (shown above) - - - +
@@ -203,9 +193,19 @@ string mergedContent = stringWriter.ToString();
- Namespace + Configuring a VelocityEngine without a custom namespace - For convinience in defining NVelocity engine instances a custom + While most users will prefer to use the NVelocity custom namespace + to configure a VelocityEngine, you can also use standard <object/> + definition syntax as shown below: + + To create a VelocityEngine using the default file resource loader + use the definition: + + <!-- Simple no arg file based configuration use's NVeclocity default file resource loader --> +<object id="velocityEngine" type="Spring.Template.Velocity.VelocityEngineFactoryObject, Spring.Template.Velocity" /> + + For convenience in defining NVelocity engine instances a custom namespace is provided, for example the resource loader definition could be done this way: @@ -218,6 +218,69 @@ string mergedContent = stringWriter.ToString(); </template:resource-loader> </template:nvelocity> -</objects> +</objects + + When templates are packaged in an assembly, NVelocity's assembly + resource loader can be used to define where templates reside: + + <!-- Assembly based template loading with NVelocity assembly resource loader --> +<object id="assemblyBasedVelocityEngine" type="Spring.Template.Velocity.VelocityEngineFactoryObject, Spring.Template.Velocity"> + <property name="VelocityProperties"> + <dictionary key-type="string" value-type="object"> + <entry key="resource.loader" value="assembly"/> + <entry key="assembly.resource.loader.class" value="NVelocity.Runtime.Resource.Loader.AssemblyResourceLoader"/> + <entry key="assembly.resource.loader.assembly" value="MyAssembly"/> + </dictionary> + </property> +</object> + + To load NVelocity templates from a single path use the + definition: + + <object id="velocityEngine" type="Spring.Template.Velocity.VelocityEngineFactoryObject, Spring.Template.Velocity" > + <property name="ResourceLoaderPath" value="file://MyTemplateFolder/AnotherFolder/" /> +</object> + + + To load NVelocity templates from multiple paths use the + definition: + + <object id="velocityEngine" type="Spring.Template.Velocity.VelocityEngineFactoryObject, Spring.Template.Velocity" > + <property name="ResourceLoaderPaths" > + <list> + <value>file://MyTemplateFolder/</value> + <value>file://MyOtherTemplateFolder/</value> + </list> + </property> +</object> + + + By default spring will attempt to load resources using file based + template loading (useful for detection of template changes at runtime). + If this is not desirable you set the + preferFileSystemAccess property of the factory object + to false. + + + To refer to a property file based configuration of the + TemplateEngine use the definition: + + <object id="velocityEngine" type="Spring.Template.Velocity.VelocityEngineFactoryObject, Spring.Template.Velocity" > + <property name="ConfigLocation " value="file://Template/Velocity/config.properties" /> +</object> + + + You can override specific properties by providing the + VelocityProperties property. + + + To not integrate with the Common.Logging subsystem, set the + OverrideLogging property to false: + + <object id="velocityEngine" type="Spring.Template.Velocity.VelocityEngineFactoryObject, Spring.Template.Velocity" > + <property name="OverrideLogging" value="false" /> +</object> + +
diff --git a/src/Spring/Spring.Core/Objects/Factory/Xml/NamespaceParserRegistry.cs b/src/Spring/Spring.Core/Objects/Factory/Xml/NamespaceParserRegistry.cs index 0a35e257..89795201 100644 --- a/src/Spring/Spring.Core/Objects/Factory/Xml/NamespaceParserRegistry.cs +++ b/src/Spring/Spring.Core/Objects/Factory/Xml/NamespaceParserRegistry.cs @@ -103,7 +103,7 @@ namespace Spring.Objects.Factory.Xml wellknownNamespaceParserTypeNames["http://www.springframework.net/nms"] = "Spring.Messaging.Nms.Config.NmsNamespaceParser, Spring.Messaging.Nms"; wellknownNamespaceParserTypeNames["http://www.springframework.net/ems"] = "Spring.Messaging.Ems.Config.EmsNamespaceParser, Spring.Messaging.Ems"; wellknownNamespaceParserTypeNames["http://www.springframework.net/validation"] = "Spring.Validation.Config.ValidationNamespaceParser, Spring.Core"; - wellknownNamespaceParserTypeNames["http://www.springframework.net/template"] = "Spring.Template.Config.TemplateNamespaceParser, Spring.Template.Velocity"; + wellknownNamespaceParserTypeNames["http://www.springframework.net/nvelocity"] = "Spring.Template.Velocity.Config.TemplateNamespaceParser, Spring.Template.Velocity"; Reset(); } diff --git a/src/Spring/Spring.Template.Velocity/Spring.Template.Velocity.2008.csproj b/src/Spring/Spring.Template.Velocity/Spring.Template.Velocity.2008.csproj index 82731207..929db49c 100644 --- a/src/Spring/Spring.Template.Velocity/Spring.Template.Velocity.2008.csproj +++ b/src/Spring/Spring.Template.Velocity/Spring.Template.Velocity.2008.csproj @@ -2,7 +2,7 @@ Debug AnyCPU - 9.0.30729 + 9.0.21022 2.0 {BF3AB954-8375-407C-9E98-4C51D8072784} Library @@ -67,7 +67,7 @@ - + @@ -102,7 +102,7 @@ - +