Generator (SIRIUS web 19.0-rc8 API)

java.lang.Object
- sirius.web.templates.Generator

```
public class Generator
extends Object
```
Used to generate content by either evaluating a template or directly supplied template code.
This uses a builder like pattern (a.k.a. fluent API) and requires to either call generate() or generateTo(OutputStream) to finally generate the content.

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`ENCODING` If a specific output encoding is required (other than the system encoding - most definitely UTF-8) a variable using this key can be supplied to the generator, specifying the name of the encoding to use.

Constructor Summary

Constructors
Modifier Constructor and Description

protected Generator()

Constructors
Modifier	Constructor and Description
`protected`	`Generator()`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Generator`	`applyContext(sirius.kernel.commons.Context ctx)` Applies the context to the generator.
`Generator`	`direct(String templateCode, String handlerType)` Sets the template code to be used directly as string.
`Generator`	`encoding(String encoding)` Sets the output encoding which is used to generate the output files.
`String`	`generate()` Invokes the appropriate `ContentHandler` and returns the generated content handler as string.
`Attachment`	`generateAttachment(String filename)` Convenience method to directly create an `Attachment` which can be added to an email.
`void`	`generateTo(OutputStream out)` Calls the appropriate `ContentHandler` to generate the output which is written into the given output stream.
`sirius.kernel.commons.Context`	`getContext()` Can be used by a `ContentHandler` to access the context which contains all previously set variables.
`String`	`getEncoding()` Can be used by a `ContentHandler` to determine the effective encoding used for the generated output.
`String`	`getHandlerType()` Contains the handler type.
`InputStream`	`getTemplate()` Uses the `Resolver` implementations or the classloader to load the template as input stream.
`String`	`getTemplateCode()` Can be used by a `ContentHandler` to obtain a preset templateCode.
`String`	`getTemplateName()` Can be used by a `ContentHandler` to obtain a preset templateName.
`Generator`	`handler(String handlerType)` Specifies which `ContentHandler` is used to generate the content.
`boolean`	`isTemplateEndsWith(String extension)` Can be used by a `ContentHandler` to determine the effective ending of the underlying template name.
`boolean`	`isTemplateFileExtension(String extension)` Can be used by a `ContentHandler` to determine the file ending of the selected template.
`Generator`	`put(String key, Object value)` Adds a variable with the given name (key) and value to the internal context.
`Generator`	`useTemplate(String templateName)` Determines which template file should be used.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - ENCODING
```
public static final String ENCODING
```
    If a specific output encoding is required (other than the system encoding - most definitely UTF-8) a variable using this key can be supplied to the generator, specifying the name of the encoding to use.
    If possible however it is preferable to use encoding(String) to set the encoding.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - Generator
```
protected Generator()
```
- Method Detail
  - applyContext
```
public Generator applyContext(sirius.kernel.commons.Context ctx)
```
    Applies the context to the generator.
    This will join the given context with the one previously set (Or the system context). All values with the same name will be overwritten using the values in the given context.
    
    Parameters:
    
    ctx - the context to be applied to the one already present
    
    Returns:
    
    the generator itself for fluent API calls
  - put
```
public Generator put(String key,
                     Object value)
```
    Adds a variable with the given name (key) and value to the internal context.
    If a value with the same key was already defined, it will be overwritten.
    
    Parameters:
    
    key - the name of the variable to set
    
    value - the value of the variable to set
    
    Returns:
    
    the generator itself for fluent API calls
  - encoding
```
public Generator encoding(String encoding)
```
    Sets the output encoding which is used to generate the output files.
    
    Parameters:
    
    encoding - the encoding to use for output files
    
    Returns:
    
    the generator itself for fluent API calls
  - useTemplate
```
public Generator useTemplate(String templateName)
```
    Determines which template file should be used.
    The content is resolved by calling Resources.resolve(String).
    
    Parameters:
    
    templateName - the name of the template to use
    
    Returns:
    
    the generator itself for fluent API calls
  - direct
```
public Generator direct(String templateCode,
                        String handlerType)
```
    Sets the template code to be used directly as string.
    Most probably this will be velocity code. Once a direct code is set, the template specified by useTemplate(String) will be ignored.
    
    Parameters:
    
    templateCode - the template code to evaluate
    
    handlerType - String reference for the handler to be used (i.e. TagliatelleContentHandler.PASTA)
    
    Returns:
    
    the generator itself for fluent API calls
  - handler
```
public Generator handler(String handlerType)
```
    Specifies which ContentHandler is used to generate the content.
    Most of the time, the content handler is auto-detected using the file name of the template. An example would be .pdf.vm which will force the TagliatellePDFContentHandler to generate a PDF file using the template. However, by using generator.handler("pdf-vm") it can be ensured, that this handler is picked, without relying on the file name.
    
    Parameters:
    
    handlerType - the name of the handler type to use. Constants can be found by looking at the Register annotations of the implementing classes of ContentHandler.
    
    Returns:
    
    the generator itself for fluent API calls
  - generateTo
```
public void generateTo(OutputStream out)
```
    Calls the appropriate ContentHandler to generate the output which is written into the given output stream.
    
    Parameters:
    
    out - the output stream to which the generated content is written
  - generateAttachment
```
public Attachment generateAttachment(@Nonnull
                                     String filename)
```
    Convenience method to directly create an Attachment which can be added to an email.
    Internally a buffer is created and generateTo(OutputStream) is invoked to generate the actual content of the attachment.
    
    Parameters:
    
    filename - the filename of the attachment.
    
    Returns:
    
    the attachment which can be passed to MailSender.addAttachment(DataSource).
  - generate
```
public String generate()
```
    Invokes the appropriate ContentHandler and returns the generated content handler as string.
    Most probably the input will be a velocity template which generates readable text (which also might be XML or HTML).
    
    Returns:
    
    the generated string contents
  - getTemplateName
```
public String getTemplateName()
```
    Can be used by a ContentHandler to obtain a preset templateName.
    
    Returns:
    
    the templateName which was previously set or null if no template name was given
  - getTemplateCode
```
public String getTemplateCode()
```
    Can be used by a ContentHandler to obtain a preset templateCode.
    
    Returns:
    
    the templateCode which was previously set or null if no template code was given
  - getContext
```
public sirius.kernel.commons.Context getContext()
```
    Can be used by a ContentHandler to access the context which contains all previously set variables.
    
    Returns:
    
    the previously set context containing all applied variables.
  - isTemplateFileExtension
```
public boolean isTemplateFileExtension(@Nonnull
                                       String extension)
```
    Can be used by a ContentHandler to determine the file ending of the selected template. This is used to select which content handler is actually used to generate the output.
    
    Parameters:
    
    extension - the expected file extension, without a "." at the beginning
    
    Returns:
    
    true if the given template ends with the given extension, false otherwise. This first dot is considered the start of the file extension so "foobar.test.js" has "test.js" as extension. If the templateName is null, this method always returns false.
  - isTemplateEndsWith
```
public boolean isTemplateEndsWith(@Nonnull
                                  String extension)
```
    Can be used by a ContentHandler to determine the effective ending of the underlying template name.
    
    Parameters:
    
    extension - the expected end of the file name.
    
    Returns:
    
    true if the given template ends with the given extension, false otherwise. In contrast to isTemplateFileExtension(String) this will not consider the first "." to be the file extension but rather really check if the template name ends with the given extension. Therefore for a template named test.js.vm this will return true for isTemplateEndsWith(".vm") but false for isTemplateFileExtension("vm")
  - getEncoding
```
public String getEncoding()
```
    Can be used by a ContentHandler to determine the effective encoding used for the generated output. This is either set via encoding(String) or by placing a variable named ENCODING in the context or it is the default encoding used by the JVM (most probably UTF-8).
    
    Returns:
    
    the effective encoding used to generate the output
  - getHandlerType
```
public String getHandlerType()
```
    Contains the handler type. This can be used by a ContentHandler to skip all filename checks and always generate its output.
    
    Returns:
    
    the handlerType previously set using handler(String) or null if no handler type was set.
  - getTemplate
```
public InputStream getTemplate()
```
    Uses the Resolver implementations or the classloader to load the template as input stream.
    
    Returns:
    
    the contents of the template as stream or null if the template cannot be resolved

Class Generator

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ENCODING

Constructor Detail

Generator

Method Detail

applyContext

put

encoding

useTemplate

direct

handler

generateTo

generateAttachment

generate

getTemplateName

getTemplateCode

getContext

isTemplateFileExtension

isTemplateEndsWith

getEncoding

getHandlerType

getTemplate