components/camel-stringtemplate/src/main/docs/string-template-component.adoc

= String Template Component
:doctitle: String Template
:shortname: string-template
:artifactid: camel-stringtemplate
:description: Transform messages using StringTemplate engine.
:since: 1.2
:supportlevel: Stable
:tabs-sync-option:
:component-header: Only producer is supported
//Manually maintained attributes
:camel-spring-boot-name: stringtemplate

*Since Camel {since}*

*{component-header}*

The String Template component allows you to process a message using a
http://www.stringtemplate.org/[String Template]. This can be ideal when
using Templating to generate responses for
requests.

Maven users will need to add the following dependency to their `pom.xml`
for this component:

[source,xml]
------------------------------------------------------------
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-stringtemplate</artifactId>
    <version>x.x.x</version>
    <!-- use the same version as your Camel core version -->
</dependency>
------------------------------------------------------------

== URI format

--------------------------------------
string-template:templateName[?options]
--------------------------------------

Where *templateName* is the classpath-local URI of the template to
invoke; or the complete URL of the remote template.



// component options: START
include::partial$component-configure-options.adoc[]
include::partial$component-endpoint-options.adoc[]
include::partial$component-endpoint-headers.adoc[]
// component options: END


== Usage

=== Headers

Camel will store a reference to the resource in the message header with
key, `org.apache.camel.stringtemplate.resource`. The Resource is an
`org.springframework.core.io.Resource` object.

=== String Template Context

Camel will provide exchange information in the String Template context (just a
`Map`). The `Exchange` is transferred as:

[width="100%",cols="10%,90%",options="header",]
|=======================================================================
|key |value

|`exchange` |The `Exchange` itself.

|`exchange.properties` |The `Exchange` properties.

|`variables` |The variables

|`headers` |The headers of the In message.

|`camelContext` |The Camel Context.

|`request` |The In message.

|`body` |The In message body.

|`response` |The Out message (only for InOut message exchange pattern).
|=======================================================================

=== Hot reloading

The string template resource is by default hot-reloadable for both file
and classpath resources (expanded jar). If you set `contentCache=true`,
Camel loads the resource only once and hot-reloading is not possible.
This scenario can be used in production when the resource never changes.

=== Dynamic templates

Camel provides two headers by which you can define a different resource
location for a template or the template content itself. If any of these
headers is set, then Camel uses this over the endpoint configured
resource. This allows you to provide a dynamic template at runtime.

=== StringTemplate Attributes

You can define the custom context map by setting the
message header "*CamelStringTemplateVariableMap*" just like the below
code.

[source,java]
--------------------------------------------------------------------------
Map<String, Object> variableMap = new HashMap<String, Object>();
Map<String, Object> headersMap = new HashMap<String, Object>();
headersMap.put("name", "Willem");
variableMap.put("headers", headersMap);
variableMap.put("body", "Monday");
variableMap.put("exchange", exchange);
exchange.getIn().setHeader("CamelStringTemplateVariableMap", variableMap);
--------------------------------------------------------------------------

== Examples

For example, you could use a string template as follows in order to
formulate a response to a message:

[source,java]
-----------------------------------------------
from("activemq:My.Queue").
  to("string-template:com/acme/MyResponse.tm");
-----------------------------------------------

=== The Email Example

In this sample, we want to use a string template to send an order
confirmation email. The email template is laid out in `StringTemplate`
as:

--------------------------------------------
Dear <headers.lastName>, <headers.firstName>

Thanks for the order of <headers.item>.

Regards Camel Riders Bookstore
<body>
--------------------------------------------

include::spring-boot:partial$starter.adoc[]