Object object, ModelFactory factory Deprecated. Map classInfo, java. Map keyMap, java. Class clazz, java. String key Overridden to invoke the getObject method of the resource bundle. String key Overridden to invoke the generic get method by casting to Map instead of through reflection - should yield better performance. Object object, java. Method method, java.
Object[] args Invokes the specified method, wrapping the return value. Field field Reads the specified field, returns its value as TemplateModel. Object object Wraps the object with a template model that is most specific for the object's class. Object obj. List args. Object context, java. String xpathQuery. NodeListModel Deprecated. Retrieves the i-th element of the node list.
String key Deprecated. TaglibFactory A hash model associated with a servlet context that can load JSP tag libraries associated with that servlet context. JythonModel Generic model for arbitrary Jython objects. String key Calls PyObject. Object obj Wraps the passed Jython object into a FreeMarker template model. AllHttpScopesHashModel An extension of SimpleHash that looks up keys in the hash, then in the request, session, and servlet context scopes.
IncludePage A model that when invoked with a 'path' parameter will perform a servlet include. ServletContext servletContext, javax. HttpServletRequest request, javax. HttpServletResponse response. String key, TemplateModel model Stores a model in the hash so that it doesn't show up in keys and values methods. WrapperTemplateModel A generic interface for template models that wrap some underlying object, and wish to provide access to that wrapped object. Object object, ObjectWrapper wrapper Create a wrapping model for the specified object that belongs to the specified wrapper.
AdapterTemplateModel A TemplateModel that can be unwrapped and then it considers a provided desired hint class. TemplateBooleanModel "boolean" template language data type; same as in Java; either true or false. TemplateCollectionModel "collection" template language data type: a collection of values that can be enumerated, but can't be or not meant to be accessed by index or key, nor the number of elements in it is known.
TemplateDateModel "date", "time" and "date-time" template language data types: corresponds to Date. TemplateDirectiveModel "directive" template language data type: used as user-defined directives much like macros in templates. The recommended values are: In production systems: TemplateExceptionHandler.
The difference is in what they print on the output before they do that. Neither is it meant to be used to roll back the printed output. These should be solved outside template processing when the exception raises from Template. TemplateExceptionHandler meant to be used if you want to include special content in the template output, or if you want to suppress certain exceptions. If you suppress an exception, and the Configurable. The default value is AttemptExceptionReporter. Note that attempt is not supposed to be a general purpose error handler mechanism, like try is in Java.
It's for decreasing the impact of unexpected errors, by making it possible that only part of the page is going down, instead of the whole page. But it's still an error, something that someone should fix. So the error should be reported, not just ignored in a custom AttemptExceptionReporter -s. The default is true for backward compatibility, but that results in logging the exception twice in properly written applications, because there the TemplateException thrown by the public FreeMarker API is also logged by the caller even if only as the cause exception of a higher level exception.
Hence, in modern applications it should be set to false. The default is false for backward compatibility as some applications catch certain unchecked exceptions thrown by the template processing to do something special , but the recommended value is true. When this is true , the unchecked exceptions will be wrapped into a TemplateException -s, thus the exception will include the location in the template not just the Java stack trace.
Another consequence of the wrapping is that the TemplateExceptionHandler will be invoked for the exception as that only handles TemplateException -s, it wasn't invoked for unchecked exceptions. When this setting is false , unchecked exception will be thrown by Template. Note that plain Java methods called from templates aren't user defined TemplateMethodModel -s, and have always wrapped the thrown exception into TemplateException , regardless of this setting.
Specified by: getStrictSyntaxMode in interface ParserConfiguration setIncompatibleImprovements public void setIncompatibleImprovements Version incompatibleImprovements Use Configuration Version instead if possible; see the meaning of the parameter there. If the default value of a setting depends on the incompatibleImprovements and the value of that setting was never set in this Configuration object through the public API, its value will be set to the default value appropriate for the new incompatibleImprovements.
This adjustment of a setting value doesn't count as setting that setting, so setting incompatibleImprovements for multiple times also works as expected. Note that the default output format, UndefinedOutputFormat , is a non-escaping format, so there auto-escaping will be off.
About auto-escaping. If auto-escaping is on, FreeMarker will assume that the value is plain text as opposed to markup or some kind of rich text , so it will escape it according the current output format see setOutputFormat OutputFormat and TemplateConfiguration. If auto-escaping is off, FreeMarker will assume that the string value is already in the output format, so it prints it as is to the output.
When printing TemplateMarkupOutputModel -s, they aren't escaped again they are already escaped. Auto-escaping doesn't do anything if the current output format isn't an MarkupOutputFormat. The output format inside a string literal expression is always PlainTextOutputFormat regardless of the output format of the containing template , which is a non-escaping format.
Note that what you set here is just a default, which can be overridden for individual templates via setTemplateConfigurations TemplateConfigurationFactory. This setting is also overridden by the standard file extensions; see them at setRecognizeStandardFileExtensions boolean. Usually, you should leave this on its default, which is UndefinedOutputFormat. Where you can't use the standard extensions, templates still can be associated to output formats with patterns matching their name their path using setTemplateConfigurations TemplateConfigurationFactory.
Also isOutputFormatExplicitlySet will return false. Parameters: name - Either the name of the output format as it was registered with setRegisteredCustomOutputFormats Collection , or a combined output format name. A combined output format is created ad-hoc from the registered formats. Returns: Not null. Throws: UnregisteredOutputFormatException - If there's no output format registered with the given name.
Names are also used to look up the OutputFormat for standard file extensions; see them at setRecognizeStandardFileExtensions boolean. When there's a clash between a custom output format name and a standard output format name, the custom format will win, thus you can override the meaning of standard output format names. The default value is an empty collection. IllegalArgumentException - When multiple different OutputFormat -s have the same name in the parameter collection. When the same OutputFormat object occurs for multiple times in the collection.
If an OutputFormat name is 0 long. If an OutputFormat name doesn't start with letter or digit. For backward compatibility, it defaults to false if getIncompatibleImprovements is less than 2. Starting from incompatibleImprovements 2. These file extensions are not case sensitive. The file extension is the part after the last dot in the source name. If the source name contains no dot, then it has no file extension.
The settings activated by these file extensions override the setting values dictated by setTemplateConfigurations TemplateConfigurationFactory. Don't confuse this with the interpolation syntax setInterpolationSyntax int ; they are independent. In FreeMarker 2. Starting from 2. This setting is ignored for the templates that have ftl directive in it.
For those templates the syntax used for the ftl directive determines the syntax. Don't confuse this with the tag syntax setTagSyntax int ; they are independent. The default is auto-detect, which detects the naming convention used and enforces that same naming convention for the whole template. This setting doesn't influence what naming convention is used for the setting names outside templates.
It only influences the names of the built-in directives elseIf VS elseif , built-ins? Which convention to use: FreeMarker prior to 2. However, it's no necessary to make a application-wide decision; see auto-detection below. The naming convention of a template is decided when the first core non-user-defined identifier is met during parsing not during processing where the naming convention is relevant like for s?
At that point, the naming convention of the template is decided, and any later core identifier that uses a different convention will be a parsing error. FreeMarker always enforces the same naming convention to be used consistently within the same template "file". Thus such a setup can be used to enforce an application-wide naming convention. IllegalArgumentException - If the parameter isn't one of the valid constants. So for example if the users edit templates in an editor where the tab width is set to 4, you should set this to 4 so that the column numbers printed by FreeMarker will match the column number shown in the editor.
This setting doesn't affect the output of templates, as a tab in the template will remain a tab in the output too.
If you set this setting to 1, then tab characters will be kept in the return value of Template. Parameters: tabSize - At least 1, at most For backward compatibility the default is true. The recommended value for new projects is false , as otherwise adding new variables to higher scopes typically to the data-model can unintentionally change the behavior of templates. You have to be quite unlucky for that to happen though: The newly added variable has to have the same name as the loop variable, and there must be some null missing values in what you loop through.
This setting doesn't influence the behavior of lambdas, like items? Reading a lambda argument never falls back to higher scopes. This is a shorthand for getTemplate name, null, null, null, true, false ; see more details there. See Configuration for an example of basic usage.
IOException Shorthand for getTemplate name, locale, null, null, true, false. IOException Shorthand for getTemplate name, null, null, encoding, true, false. IOException Shorthand for getTemplate name, locale, null, encoding, true, false. IOException Since: 2. This method is thread-safe. Parameters: name - The name or path of the template, which is not a real path, but interpreted inside the current TemplateLoader.
Can't be null. The exact syntax of the name depends on the underlying TemplateLoader , but the cache makes some assumptions.
First, the name is expected to be a hierarchical path, with path components separated by a slash character not with backslash! The path the name given here must not begin with slash; it's always interpreted relative to the "template root directory". Then, the.. The path must not reach outside the template root directory, that is, it can't be something like ".. This path meta-element triggers the acquisition mechanism.
If the template is not found in the location described by the concatenation of the path left to the asterisk called base path and the part to the right of the asterisk called resource path , the cache will attempt to remove the rightmost path component from the base path "go up one directory" and concatenate that with the resource path.
The process is repeated until either a template is found, or the base path is completely exhausted. This is what Configurable. This parameter can be null since 2. This parameter also drives localized template lookup. Note that when the locale setting is overridden with a TemplateConfiguration provided by getTemplateConfigurations , that overrides the value specified here, but only after the localized lookup, that is, it modifies the template found by the localized lookup.
Can be null though it's up to the custom TemplateLookupStrategy if it allows that. This object will be used as part of the cache key, so it must to have a proper Object. It also should have reasonable Object. The expected type is up to the custom TemplateLookupStrategy. See also: TemplateLookupContext. Can be null since 2.
Why is this deprecated: It doesn't make sense to get the same template with different encodings, hence, it's error prone to specify the encoding where you get the template. Instead, if you have template "files" with different charsets, you should use setTemplateConfigurations TemplateConfigurationFactory , where you can associate encodings to individual templates based on their names like which "directory" are they in, what's their file extension, etc.
The encoding associated with the templates that way overrides the encoding that you specify here. Other kind of exceptions won't be suppressed. Returns: the requested template; maybe null when the ignoreMissing parameter is true. Note that this exception extends IOException. ParseException - extends IOException if the template is syntactically bad. IOException - If there was some other problem with reading the template "file". Note that the other exceptions extend IOException , so this should be catched the last.
Note that by default there is no locale specified for any locale, so the default encoding is always in effect. Defaults to the default system encoding, which can change from one server to another, so you should always set this setting. If you don't know what charset your should chose, "UTF-8" is usually a good choice. Defaults to the default system encoding.
Parameters: locale - Shouldn't be null , though for backward compatibility it's accepted when the locale to encoding Map see earlier is empty.
If there is no explicit encoding set for some locale, then the default encoding will be used, what you can set with setDefaultEncoding java. Shared sharedVariables are sharedVariables that are visible as top-level sharedVariables for all templates which use this configuration, if the data model does not contain a variable with the same name.
Never use TemplateModel implementation that is not thread-safe for shared sharedVariables, if the configuration is used by multiple threads!
It is the typical situation for Servlet based Web sites. This method is not thread safe; use it with the same restrictions as those that modify setting values. Parameters: name - the name used to access the data object from your template. If a shared variable with this name already exists, it will replace that.
See Also: setAllSharedVariables freemarker. The method returns a new Set object on each call that is completely disconnected from the Configuration. That is, modifying the set will have no effect on the Configuration object. The added value should be thread safe, if you are running templates from multiple threads with this configuration. The values in the map can be TemplateModel -s or plain Java objects which will be immediately converted to TemplateModel with the ObjectWrapper returned by Configurable.
If setObjectWrapper ObjectWrapper is called later, this conversion will be re-applied. Thus, ignoring some extra resource usage, it doesn't mater if in what order are setObjectWrapper ObjectWrapper and setSharedVaribles Map called. This is essential when you don't have control over the order in which the setters are called. The values in the map must be thread safe, if you are running templates from multiple threads with this configuration.
It's also kept as meta-info returned by getEncoding. It also has an impact when include -ing or import -ing another template from this template, as its default encoding will be this. But this behavior of said directives is considered to be harmful, and will be probably phased out. This is mostly meant to be used by FreeMarker internally, but advanced users might still find this useful.
Parameters: customParserConfiguration - Overrides the parsing related configuration settings of the Configuration parameter; can be null. This is useful as the Configuration is normally a singleton shared by all templates, and so it's not good for specifying template-specific settings.
While Template itself has methods to specify settings just for that template, those don't influence the parsing, and you only have opportunity to call them after the parsing anyway. This objects is often a TemplateConfiguration whose parent is the Configuration parameter, and then it practically just overrides some of the parser settings, as the others are inherited from the Configuration. Note that if this is a TemplateConfiguration , you will also want to call TemplateConfiguration.
When it's non- null , it overrides the value coming from the TemplateConfiguration. Reader reader throws java. IOException Deprecated. Equivalent to Template name, reader, null.
Parameters: name - See getName for more details. If null , it will be the same as the name. Writer out throws TemplateException , java. IOException Executes template, using the data-model provided, writing the generated output to the supplied Writer. For finer control over the runtime environment setup, such as per-HTTP-request configuring of FreeMarker settings, you may need to use createProcessingEnvironment Object, Writer instead.
You can also use an object that already implements TemplateHashModel ; in that case it won't be wrapped. If it's null , an empty data model is used. Note that unless you have used Configurable. Can't be null. Throws: TemplateException - if an exception occurs during template processing java. That node is accessed in the template with. Parameters: rootNode - The root node for recursive processing or null. Writer out, ObjectWrapper wrapper throws TemplateException , java.
Parameters: wrapper - The ObjectWrapper to be used instead of what Configurable. Throws: TemplateException java. IOException Creates a Environment object, using this template, the data-model provided as parameter. You have to call Environment. Use this method if you want to do some special initialization on the Environment before template processing, or if you want to read the Environment after template processing.
Otherwise using process Object, Writer is simpler. Normally you left it null , in which case Configurable. Returns: the Environment object created for processing. Call Environment.
Throws: TemplateException - if an exception occurs while setting up the Environment object. IOException - if an exception occurs doing any auto-imports createProcessingEnvironment public Environment createProcessingEnvironment java. IOException toString public java. Overrides: toString in class java. Object getName public java. It's not a real path in a file-system, it's just a name that a TemplateLoader used to load the backing resource in simple cases; actually that name is getSourceName , but see it there.
Or, it can also be a name that was never used to load the template directly created with Template String, Reader, Configuration. See the license here Note that the project is owned by the Apache Software Foundation since 2.
Earlier releases, such as 2. Last generated: GMT.
0コメント