A walkthrough for creating a new field formatter, the feature introduced in Kibana 4.1 that allows users to visually convert fields on the fly.

<html><head></head><body>Kibana 4.1 introduced a new feature called field formatters, giving us the ability to visually convert fields on the fly. &#xA0;Field formatters provide a great way to display data in a different way&#xA0;without changing how it is stored. &#xA0;For a more in depth overview of what field formatters do, you can read a previous blog post&#xA0;<a href="https://www.elastic.co/blog/kibana-4-1-field-formatters">here</a>. 
The goal for this post is to walk through the steps of creating a new formatter. &#xA0;We will start by going over the field formatter API, then implement a basic formatter that will draw attention to the word &quot;error&quot;, and finally generalize our solution.
<h2>Getting Started</h2>Instructions on pulling down the Kibana development environment can be found at the <a href="https://github.com/elastic/kibana/blob/master/CONTRIBUTING.md#development-environment-setup">Kibana repository</a>.
Starting from the Kibana root directory, field formatters are stored in <code>/src/ui/public/stringify</code>. The resulting folder structure looks like:
<pre class="prettyprint">/stringify
|--type //Contains different formatters
|--icons
|--editors //HTML used by the formatter to request or display additional information
|--__tests__
|--register.js //Every formatter is registered with the application here
</pre>In Kibana&#xA0;4.1, formatters can be found at <code>/src/kibana/components/stringify</code>. If using 4.1, paths in the code samples will need to be updated.
Let&#x2019;s create a new file called <code>Highlight.js</code> in the <code>type</code> folder and add some initialization code:
<pre class="prettyprint">define(function (require) {
 return function HighlightFormatProvider(Private) {
 var _ = require(&apos;lodash&apos;);
 var FieldFormat = Private(require(&apos;ui/index_patterns/_field_format/FieldFormat&apos;));
 _.class(Highlight).inherits(FieldFormat);
 function Highlight(params) {
 Highlight.Super.call(this, params);
 }
 Highlight.id = &apos;highlight&apos;;
 Highlight.title = &apos;Highlight&apos;;
 Highlight.fieldType = [&apos;string&apos;];
 Highlight.prototype._convert = {
 text: _.escape,
 html: _.escape
 };
 return Highlight;
 };
});
</pre>A class extending FieldFormat is implemented for each field format. &#xA0;<code>Highlight.id</code> is used internally by Kibana to keep track of the formatter and should not conflict with any other formatter id. &#xA0;<code>Highlight.title</code> is the displayed text&#xA0;when selecting from a list of formatters, and <code>Highlight.fieldType</code> describes what types of fields this formatter is available for.
<code>Highlight.prototype._convert</code> is where the formatting happens. It has methods for converting both text and html. The text method is used for tooltips, filters, legends, and axis markers. The html method is used for search tables. Both take a field value as input, and return what we want displayed visually. If you want both methods to behave the same, <code>Highlight.prototype._convert</code> can be assigned as a function instead. Adding code to draw attention to errors looks like:
<pre class="prettyprint">Highlight.prototype._highlight = function (val, replace) {
 return _.escape(val).replace(/(error)/g, replace);
};
Highlight.prototype._convert = {
 text: function(val) {
 return this._highlight(val, function convertToUpperCase(match) {
 return match.toUpperCase();
 });
 },
 html: function(val) {
 return this._highlight(val, &apos;&lt;mark&gt;$&amp;&lt;/mark&gt;&apos;);
 }
};
</pre>Any time a field has the text &quot;error&quot;, we either wrap it in a mark element or convert it to uppercase depending on whether HTML or text is requested. It&apos;s important to use <code>_.escape(val)</code> here, we want to avoid HTML injection and cross-site scripting attacks.
We also need to register this field formatter with the application. In <code>register.js</code> we add:
<pre class="prettyprint">fieldFormats.register(require(&apos;ui/stringify/types/Highlight&apos;));
</pre>In the future, we (the Kibana team) will be&#xA0;working on providing this functionality as a plugin, which will help simplify the registration process.
We should now be able to add Highlight as a field formatter on fields with a string type!
<img src="https://api.contentstack.io/v2/assets/575e4ca7d8edd48f7693621c/download?uid=blt27403778542f7db7?uid=blt27403778542f7db7" data-sys-asset-uid="blt3b40cdcf8a606803" style="max-width: 100%;">
Testing it on the Discover page shows us it is working:
<img src="https://api.contentstack.io/v2/assets/575e4ca758208ba076e284bc/download?uid=blt8d6c87e6e171de69?uid=blt8d6c87e6e171de69" data-sys-asset-uid="bltbd8a84ea59294648" style="max-width: 100%;">
<h2>Generalize </h2>This works, but what if we want to highlight more than just errors? Instead of making a new field formatter for every input, let&#x2019;s match against an inputted regular expression.
In the editor folder, add a new file called <code>highlight.html</code> with the following:
<pre class="prettyprint">&lt;div class=&quot;form-group&quot;&gt;
 &lt;label&gt;Pattern&lt;/label&gt;
 &lt;input class=&quot;form-control&quot; ng-model=&quot;editor.formatParams.pattern&quot;/&gt;
&lt;/div&gt;
</pre>Back in Highlight.js we need to define <code>highlight.html</code> as our editor and update our <code>_highlight</code> method to use its input field as our pattern to match on.
<pre class="prettyprint">Highlight.editor = require(&apos;ui/stringify/editors/highlight.html&apos;);
Highlight.prototype._highlight = function (val, replace) {
 var escapedVal = _.escape(val);
 var highlightPattern;
 try {
 var inputRegex = this.param(&apos;pattern&apos;).split(&apos;/&apos;);
 var pattern = inputRegex[0] || inputRegex[1];
 var flags = inputRegex[2];
 highlightPattern = new RegExp(pattern, flags);
 } catch(e) {
 return escapedVal;
 }
 return escapedVal.replace(highlightPattern, replace);
};
</pre><h2>Samples </h2>It may be beneficial to see how an&#xA0;inputted&#xA0;pattern&#xA0;behaves before applying the&#xA0;formatter. There&#x2019;s a directive that has already been built that will let us see some example conversions as we modify our pattern.
We can use this by adding sample field values, and including the directive in our template. In highlight.html, append:
<pre class="prettyprint">&lt;field-format-editor-samples inputs=&quot;editor.field.format.type.sampleInputs&quot;&gt;&lt;/field-format-editor-samples&gt;
</pre>In Highlight.js:
<pre class="prettyprint">Highlight.sampleInputs = [
 &apos;Hello world&apos;,
 &apos;The quick brown fox jumps over the lazy dog&apos;,
 &apos;112345&apos;
];
</pre>The end&#xA0;result is:
<img src="https://api.contentstack.io/v2/assets/575e4ca743e9adc538713f50/download?uid=blt67e547859e2798ea?uid=blt67e547859e2798ea" data-sys-asset-uid="blt8bbd181d804191a0" style="max-width: 100%;">
<h2>Conclusion</h2>The field formatter API provides an easy way to customize how your fields are displayed. Kibana comes with several built in formatters but in the event that none match your needs, this feature was built in a way to let anyone add their own. If you are planning on adding your own formatters, you can check back here after Kibana 4.2 has been released to be notified of any API changes.
</body></html>

highlight-error.png

highlight-error-thumb.png

Writing Custom Field Formatters for Kibana

Start free trial

Blog Footer CTA

Sign up for Elastic Cloud free trial

Blog Footer

Jon Budzenski

Can't make it? Register and we'll send you the recording. You'll also receive an email with related content

Can't make it? Register and we'll send you the recording. You'll also receive an email with related content.

You'll also receive an email with related content.

You'll also receive an email with related content

Load More

By submitting you acknowledge that you've read and agree to our <a href="/legal/elastic-cloud-account-terms" target="_blank">Terms of Service</a>, and that Elastic may <a href="/legal/privacy-statement#how-we-use-the-information" target="_blank">contact you</a> about our related products and services, using the details you provide above. See <a href="/legal/privacy-statement/" target="_blank">Elastic’s Privacy Statement</a> for more details or to opt-out at any time.

Newsletter GDPR Text

Speakers

Close

See more insights

The content on this page is not available in the selected language. As Elastic grows globally, we continue to support content in multiple languages.

Elastic Search AI Platform

ELK Stack

Elastic Cloud

Observability

Security

Search

By industry

By solution

Customer spotlight

Developers

Connect

Learn

Help

See what's happening at Elastic

Author

Articles by Jon Budzenski

Writing Custom Field Formatters for Kibana

Follow us

About us

Join us

Press

Partners

Trust & Security

Investor relations

EXCELLENCE AWARDS