Create a Custom Visualization

One of the most powerful features in White Label Data is the ability to map arbitrary data returned from your queries to any HTML markup. You can do that by creating a custom visualization. Custom visualizations can be written with or without Javascript. If you are simply trying to format a table or arrange some div’s on a page, you won’t need Javascript. If you want to do something more complicated, you can connect the visualization into any Javascript code using pre-defined callbacks.

White Label Data’s front-end is based on Vue.js. The complexity of creating a Vue.js has been hidden from you, but you still have access to some of Vue’s powerful features.

Custom Visualization Files

Visualization files are located in the /visualizations folder in your Git repository. These files are HTML files. However, they can include a special tag called <methods> where all of your Javascript methods must be placed.

The HTML in the file can be marked up with Vue syntax for binding reactive data to elements in the DOM at runtime. Here is an example of how a custom single value visualization template might look:

<div class="sv-container">
	<div class=sv-outer>
		<div class="sv-value">[[ figure.value ]]</div>
		<div class="sv-title">[[ figure.title ]]</div>
	</div>
</div>

In this example, the values for “value” and “title” are included in square braces. Although Vue typically uses ‘{{’ and ‘}}’ as delimeters, White Label Data requires square brackets so as not to be confused with server-side templating.

When your layer is rendered and the mapped figure is created, it is sent to the client and is bound to a data variable called figure. You can then reference any data or attributes that you placed in the figure in your layer file from the HTML template. For example, if you created a mapping rule for a field called “values”, you would reference that as figure.values from within the HTML markup. To learn more about Vue syntax read the specification here.

Useful Vue Features

Conditionally display some HTML based on some value in your figure:

<div v-if="figure.myvalue">
   <h1>Title</h1>
</div>

Loop through data in a mapped table in your figure:

<ul>
   <li v-for="row in figure.mytable">[[ row.col1 ]]</li>
</ul>

Adding Methods

Adding script tags to the visualization is not allowed. Any Javascript you want to add to a visualization file must be contained within the <methods> tag. This is a special tag that contains a list of methods. They can be methods you define and reference in the Vue markup within the HTML or they can be one of the White Label Data callbacks. You can use these callbacks to learn when the data is available or changed so that you can refresh your visualization.

<methods>
wldDOMUpdated: function () {
   // Called anytime the DOM is updated for this visualization
},
wldVisible: function() {
   // Called when the visualization first becomes visible.
   // For example if it's hidden in a closed tab.
},
wldFigureInit: function() {
   // Called when the visualization first has data from a rendered layer/
},
wldFigureUpdated: function () {
   // Called when the figure has been updated
}
</methods>

Using Your Custom Visualization

To use your custom visualization, you create a visualization as you would any other visualization–using layers. Then, the layer <config> is specified as follows:

{
	    "custom_visualization" : "mycustomvis",
	    "depends_on": ["custom-template"],
}

where mycustomvis matches the name of the HTML file in /visualizations.