What is a Layer?

Each visualization in White Label Data is created by one or more Layers. Layers form the configuration for, and fully describe, a given visualization. Each layer file is organized into sections containing configuration, queries, pipeline steps, figures, and mappings. The purpose of Layers is to allow visualization configuration to be broken up into smaller, re-usable parts that can be leveraged by multiple visualizations.

You can create a visualization in a single layer file or in two or more layer files. Each file has some subset of the visualization config. For example, if you want all bar charts within your application to share common styling, it would make sense to have a common layer for the styling of your bar charts. Then, additional bar chart layers that contain further configuration can reference the common bar chart layer.

Likewise, you may have queries that are shared between visualizations that you only want to run once per page. By splitting the visualization configuration in layers, you have the ability to organize your configuration in a way that simplifies your application development.

To render a visualization, White Label Data combines all the layers into a single, combined layer before processing:


Structure of a Layer File

Before you can create your layers, you must first understand how each layer file is contructed. Each layer file is organized into sections containing configuration, queries, pipeline steps, figures, and mappings. Layer files do not need to include all of these sections. In fact, creating sparse layers with only a subset of these sections is a common use case.

Note: In some cases, the final combined layer may not contain all sections. For example, when embedding iFrames, only the config section is needed. See Creating an Embed Layer.

Section|Separator|Description| ——-|———|———–|——— Config|<config>
</config>|Basic information about the visualization such as the type, dependent layers, and page filters.|Built-in types include:
-"periscope-embed" Query|<query name="myqueryname">
</query>|The SQL for a query. There can be multiple query sections per Layer file. The name is used in the pipeline to refer to the specific query.|

</pipeline>|A set of steps, such as querying a data warehouse or transforming the results, that produce a final Pandas DataFrame.|
</figure>|A declarative JSON data structure describing all aspects of the visualization including layout, styles and data from a dataframe.|
</mappings>|Mapping rules specify how data columns overlay on the figure, allowing any figure schema to be supported independent of the data.|

Stages for Processing Layers

White Label Data contains a rendering engine that creates visualizations from Layers. Visualizations can be charts, such as bar charts and line charts, embedded iFrames, or custom HTML visualizations. All can be described using layers. In order to create the final visualization that is displayed on the HTML page, Layers are processed using the following stages:

  1. Stage 1 - Combining: Read the config of each layer and combine all layers. Pipeline steps and mapping rules are combined between layers. Other config properties are merged as well.
  2. Stage 2 - Pipeline Execution: Step through the pipeline executing all queries and transforms in order to create the final DataFrame.
  3. Stage 3 - Figure Mapping: Starting with the initial figure specified in the layer, walk through the mapping rules to insert DataFrame columns and values into the figure.
  4. Stage 4 - Rendering: Create a visualization based on the mapped figure and the config.

The end result is a visualization like a bar chart:

Location and Naming of Layer Files

Layer files are located in the /layers folder of your Git repository. Layer files end in the extention .wld. The name of the layer is the name of the filename before the .wld extension. For example, a layer called ‘layer1’ would have a file name called layer1.wld.

You can organize layer files into subfolders under /layers as desired. White Label Data will find layer files regardless of what subfolder they are located in. Thus, layer names are globally unique within your project. In other words, having both /layers/folder1/layer1.wld and layers/folder2/layer1.wld is not allowed and will have undetermined results. The reason for this is that layer names are also created as unique HTML tags. See Add Visualizations Using Tags.