# Hello world: using the renderer library

This short tutorial is going to quickly take you through the configuration and code required to configure a new renderer and apply it on an HTML element.

## Define a Renderer

_Renderer definitions_ are configured in XML. Each renderer contains a `[<control>](https://docs.caplin.com/developer/xml/renderer/latest/control.html)` to display the value, a `[<downstream>](https://docs.caplin.com/developer/xml/renderer/latest/downstream.html)` to format and style the value before it is displayed and an `[<upstream>](https://docs.caplin.com/developer/xml/renderer/latest/upstream.html)` to parse the value before any listeners are notified of the changed data.

```xml
<renderer type="novox.novotrader.blade.amount">
    <control type="caplin.control.basic.InputControl">
    </control>
    <downstream>
        <transform className="caplin.element.formatter.ThousandsFormatter" />
    </downstream>
    <upstream>
        <transform className="caplin.element.parser.AmountParser" />
    </upstream>
</renderer>
```

## Create and bind your Renderer

Renderers can be bound directly to HTML elements using the [Renderer JavaScript API,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_element_Formatter).

```js
var oRendererFactory = caplin.element.ElementFactory.getRendererFactory();
var oRenderer = oRendererFactory.createRenderer("novox.novotrader.blade.amount", ["amount"]);
var eRendererHolder = document.getElementById("amountInputId");
eRendererHolder.innerHTML = oRenderer.createHtml();
oRenderer.bind(eRendererHolder.firstChild);
oRenderer.setValue("1000000"); // Displayed as 1,000,000
```

## User inputs new data

The `[AmountParser,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_element_parser_AmountParser)` in the renderer definition allows users to enter shortcuts for large amounts, e.g. "4M" to represent "4 million".

## Listen to Renderer Events

The example renderer definition is using a `[ChangeHandler,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_element_handler_ChangeHandler)` so this will fire the event "change" every time the value has changed.

```js
oRenderer.addRendererEventListener({
    onRendererEvent: function(oRenderer, oEvent) {
        if (oEvent.type == "change")
        {
            alert("new value is " + oRenderer.getParsedValue()); // alerts "new value is 2000000"
        }
    }
});
```

Renderers use useful for:

* Applying CSS classes and styles to data before it reaches the screen
* Flashing the screen in price updates
* Buffering fast-moving data to the screen

There are a number of existing renderer classes in the following packages:

* `[caplin.element.formatter,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/caplin_element_formatter)`
* `[caplin.element.parser,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/caplin_element_parser)`
* `[caplin.element.styler,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/caplin_element_styler)`
* `[caplin.element.handler,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/caplin_element_handler)`
* `[caplin.control,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/caplin_control)`

You can also write your own by programming to the interface for each package.