+
Snippet1 - this is webservice no. 1
+
Snippet1 - message a
+
Success! Status code : 200
+
+```
+Finally Fragment Content is replaced with merged result.
+
+## How to configure?
+Handlebars Knot is deployed using Vert.x service factory as a separate [verticle](http://vertx.io/docs/apidocs/io/vertx/core/Verticle.html) and it's shipped with default configuration.
+
+Default configuration shipped with the verticle as `io.knotx.HandlebarsKnot.json` file available in classpath.
+```json
+{
+ "main": "io.knotx.knot.templating.HandlebarsKnotVerticle",
+ "options": {
+ "config": {
+ "address": "knotx.knot.handlebars"
+ }
+ }
+}
+```
+In general, it:
+- Listens on event bus address 'knotx.knot.handlebars'
+- Renders HTML debug comments on the output HTML
+
+Detailed description of each configuration option is described in the next subsection.
+
+### Handlebars Knot options
+
+Main Handlebars Knot options available.
+
+| Name | Type | Mandatory | Description |
+|-------: |:-------: |:-------: |-------|
+| `address` | `String` | ✔ | Event bus address of the Handlebars Knot verticle. |
+| `cacheSize` | `Long` | | Max cache size for compiled Handlebars snippets. The default is 1000. |
+| `cacheKeyAlgorithm` | `String: MD5,SHA-1,SHA-256` | | Fragment content hashing algorithm. The default is `MD5`. |
+
+## How to extend?
+
+### Extending handlebars with custom helpers
+
+If the list of available handlebars helpers is not enough, you can easily extend it. To do this the
+following actions should be undertaken:
+
+1. Use io.knotx:knotx-knot-handlebars module as dependency
+2. Create a class implementing ```io.knotx.knot.templating.handlebars.CustomHandlebarsHelper``` interface.
+This interface extends [com.github.jknack.handlebars.Helper](https://jknack.github.io/handlebars.java/helpers.html)
+3. Register the implementation as a service in the JAR file containing the implementation
+ * Create a configuration file called META-INF/services/io.knotx.handlebars.CustomHandlebarsHelper
+ in the same project as your implementation class
+ * Paste a fully qualified name of the implementation class inside the configuration file. If you're
+ providing multiple helpers in a single JAR, you can list them in new lines (one name per line is allowed)
+ * Make sure the configuration file is part of the JAR file containing the implementation class(es)
+3. Run Knot.x with the JAR file in the classpath
+
+#### Example extension
+
+Sample application contains an example custom Handlebars helper - please take a look at the implementation of ```BoldHelper```:
+* Implementation class: ```io.knotx.example.monolith.handlebars.BoldHelper```
+* service registration: ```knotx-example/knotx-example-app/src/main/resources/META-INF/services/io.knotx.knot.templating.handlebars.CustomHandlebarsHelper```
+
+# Adapters
+Adapters are modules which are responsible for communication between Knot.x (exactly [[Knots|Knot]])
+and external services.
+
+[[assets/knotx-adapters.png|alt=Adapters]]
+
+## How does it work?
+Adapters can be thought as extension points where project specific logic appears. With custom [[Knots|Knot]]
+they provides very flexible mechanism to inject project specific requirements.
+
+We recommend to create a dedicated Adapter every time some service-level business logic or service
+response adaption to other format is required. E.g. we need to
+[inject the data directly form the database](http://knotx.io/blog/adapt-service-without-webapi/).
+
+
+### Types of adapters
+Knot.x Core by default introduces two types of Adapters connected with Knot implementations:
+- [[Service Adapter|ServiceAdapter]] for [[Service Knot|ServiceKnot]],
+- [[Action Adapter|ActionAdapter]] for [[Action Knot|ActionKnot]]
+
+Knot.x comes with a generic implementation of [[Service Adapter|ServiceAdapter]], that enables communication
+with external services using HTTP Protocol (only GET requests).
+This [Hello Rest Service Tutorial](http://knotx.io/blog/hello-rest-service/) contains an example of
+how to integrate external Web based service data into your webpage. See also [[Http Service Adapter|HttpServiceAdapter]]
+for more information. Please note, that this implementation is very generic and we recommend to create
+project-specific Adapters for any custom requirements.
+
+Action Adapters are project specific in terms of error handling and redirection mechanisms. Knot.x Core
+is not going to provide any generic Action Adapters.
+
+For custom Knots we can introduce custom Adapter types. As far as Knots must follow [[Knot contract|Knot#how-does-it-work]],
+Adapters are coupled with Knot directly so they can define their custom request, response or
+configuration. The communication between Knot and Adapter can be custom too.
+
+Communication contract between [[Service Knot|ServiceKnot]] and [[Http Service Adapter|HttpServiceAdapter]] is defined by:
+- `AdapterRequest` input,
+- `AdapterResponse` output.
+
+#### Adapter Request
+The table below shows all the fields in the `AdapterRequest` - the communication model between Knot.x Service Knot and Service Adapters.
+
+| Name | Type | Mandatory | Description |
+|-------: |:-------: |:-------: |-------|
+| `clientRequest.path` | `String` | ✔ | client request url, e.g. `/services/mock/first.json` |
+| `clientRequest.method` | `HttpMethod` | ✔ | client request method, e.g. `GET`, `PUT`, etc. |
+| `clientRequest.headers` | `MultiMap` | ✔ | client request headers |
+| `clientRequest.params` | `MultiMap` | ✔ | client request parameters |
+| `params` | `JsonObject` | ✔ | `JsonObject` with additional params that can be passed via configuration file, e.g. `"params": { "example": "example-value" }` |
+| `adapterParams` | `JsonObject` | | `JsonObject` with additional adapter parameters that can be set in the form of `data-knotx-adapter-params` in the snippet, e.g. `data-knotx-adapter-params='{"myKey":"myValue"}'` |
+
+#### Adapter Response
+The table below shows all the fields in the `AdapterResponse` - an object returned by the Adapter to the Service Knot.
+
+| Name | Type | Mandatory | Description |
+|-------: |:-------: |:-------: |-------|
+| `clientResponse.statusCode` | `int` | ✔ | status code of service response, e.g. `200`, `302`, `404` |
+| `clientResponse.headers` | `MultiMap` | ✔ | client response headers |
+| `clientResponse.body` | `Buffer` | | final response body |
+| `signal` | `String` | | defines how original request processing should be handled (currently used only by Action Knot), e.g. `next` |
+
+
+## How to configure?
+The Adapter API specifies an abstract class - `AdapterConfiguration` to handle JSON configuration support. This
+abstraction can be used while implementing a custom Adapter but it is not required. Every Adapter must be
+exposed with a unique Event Bus address - that's the only obligation (as is the case with Knots).
+Please see an example configuration for [[Http Service Adapter|HttpServiceAdapter#how-to-configure]]
+
+## How to implement your own Adapter?
+Knot.x provides the [maven archetypes](https://github.com/Knotx/knotx-extension-archetype) to generate custom Adapters.
+It is the **recommended** way to create your own Adapter.
+
+An Adapter logic is executed on a [Vert.x event loop](http://vertx.io/docs/vertx-core/java/#_reactor_and_multi_reactor). [The
+Vert.x Golden Rule](http://vertx.io/docs/vertx-core/java/#golden_rule) says that the code should **never block** the
+event loop. So all time-consuming operations should be coded in an asynchronous way. Default Knot.x Adapters use [RxJava](http://vertx.io/docs/vertx-rx/java/)
+which is a popular library for composing asynchronous and event-based programs using observable sequences for the Java VM.
+RxJava introduce a Reactive Programming that is a development model structured around asynchronous data streams.
+
+| Note |
+|:------ |
+| Reactive programming code first requires a mind-shift. You are notified of asynchronous events. Then, the API can be hard to grasp (just look at the list of operators). Don’t abuse, write comments, explain, or draw diagrams. RX is powerful, abusing it or not explaining it will make your coworkers grumpy. [Read more](https://developers.redhat.com/blog/2017/06/30/5-things-to-know-about-reactive-programming/) |
+
+Implementation of an Adapter does not require knowledge of how to communicate via the Vert.x event bus.
+It's wrapped by the **Vert.x Service Proxy** functionality so any new implementation can focus on
+the business logic of the Adapter.
+
+In order to implement an Adapter generate a new Adapter module using maven archetype:
+
+ `mvn archetype:generate -DarchetypeGroupId=io.knotx.archetypes -DarchetypeArtifactId=knotx-adapter-archetype -DarchetypeVersion=X.Y.Z`
+
+Note that, the Adapter archetype generates not only a skeleton of your custom Adapter, but also all
+the configuration files that's required to run a Knot.x instance.
+More details about the Knot.x deployment can be found in the [[deployment section|KnotxDeployment]].
+
+Archetype generates 3 important java files:
+
+ - `ExampleServiceAdapterConfiguration` a simple POJO with configuration of the Adapter,
+ - `ExampleServiceAdapterProxy` implement your business logic here in the `processRequest()` method with the return type of `Observable