If you add a component to your xap it will have a set of configurable fields that let you control the mapping of your data onto the different facets (a.k.a. channels) of the component's targets. This article explains the user interface for those fields.

We recommend you read Part 1 and that you understand the Exaptive Data Model before launching into this article. Then part 3 is a syntax reference for mapping data to a component's channels.

Data Mapping: Value Selectors

Value selectors let you select which value from the data gets mapped to an element of the component, your target. There will be a value selector for each channel of the target for the data, e.g. the target for the data in the scatter plot is the points which have x- and y-axis channels. The value selectors will have the name of the channel and are nested under the name of the target. Notice in the example below, the "data" port has a "points" target which has x and y channels

An attribute from the data is mapped to the channel of the target by entering the name of that attribute in the field. In the above example, the x channel is set to age while the y channel is set to income. (Notice the chart render in the background as these update.) 

The syntax you use must match that of the data type the port can accept. When a channel expects a value of a different type than you want to map to it, you can cast it to the required type. The autocomplete feature suggests how you might do this based on the data, once data has been sent to the port in the DATAFLOW. 

More complex expressions can also be used.

NOTE: Value selectors are a part of the architectural concept we call projections. You may here that word often in the component-authoring documentation.


Data Mapping: Entity Filtering

Entity filters are for filtering out some of the entities in the incoming data. After you map data attributes to the channels of the target, you can filter out some of the data based on values. The entity filter input is hidden by default but can be found in the ellipses for a target. Here's an example setting an entity filter: 



In the example, we've filtered for all data points where the age attribute is greater than 30. This filtering expression should evaluate to true or false for each entity in your duffle. 

More on advanced filtering expressions are explained in part 3 of projections articles series. 

NOTE: Entity filters are a part of the architectural concept we call projections. You may hear that word often in the component-authoring documentation.


Data Mapping: Duffle Selector 

Duffle Selectors are like Entity Filters, except you're selecting an entire duffle, instead of an entity. Why might this matter? It can often be the case that we're passing in more than one duffle as an entity, we'll do this with the network diagram where we pass in a duffle of nodes and a duffle of edges. The duffle selector input is just to the right of the target name and "edges" in the example. 



In most cases there is no need to use the Duffle Selector and it will be set properly by default.    

Make sure to review the expressions syntax and keep that article handy as you learn to build xaps!

NOTE: Duffle selectors are a part of the architectural concept we call projections. You may hear that word often in the component-authoring documentation. 

Working with the Data You've Mapped - Inputs (Select and Highlight)

Other inputs often let you work with the data you've selected or filtered. Suppose you've mapped data to the scatter plot with a duffle of entities. There are other inputs and outputs in the component that accept data in the same format and do more with it. 

NOTE: We call these subsequent ports projected ports, as opposed to projections, because they allow users to work with data coming from a projection port. Projected is a word you'll hear about more in the component-authoring documentation.

STEP 1: To work with projected ports you must first set the 'id' property of the data target you worked with. To access the 'id' property, hover over the target's section of the component, e.g. "nodes" in the example below. Then select the ellipsis and click on 'set id'. An id input will be added just above the target's channels. Set this id input to a property that is unique to each entity in your data. For our example, each entity has a unique guid. So, that will serve as an id.

STEP 2: Expand the projected input. In this example, the projected input is the "selection" port. Then, set the value of that input to a duffle of entities. Each entity must contain a property that corresponds to the id from the projection above. This tells the component to retrieve the entities corresponding to these ids. In our example component, we are using a projected output to display the entities that the projected input returns. 

If the entities in your selection port use a different key to represent the required id, then you can use the join condition port. Expand the selection port options by clicking on the arrow to the right of the grey bar. You will see two fields called "selection input". The port on the bottom is the join condition. As you will see in the example below, the selection content now contains entities with id attributes. However, we need to let the component know that the id's are the same as guid's. So, we provide the following expression:

//   _l is a special variable corresponding to a projection data entity
//   _r is a special variable corresponding to an entity from projected input dat

_l.guid == _r.id

With this expression, we are telling the component to interpret every id in our selection content as a guid from our data. The result is that our selection content does not need to follow the exact same format as our data in order to access the same data. The join condition adds an additional level of flexibility.

Working with the Data You've Mapped - Outputs

Outputs can be used in the dataflow to select data that an output port returns and sends onward in the dataflow. 

STEP 1: Look for a field in the data target with the same name as the output you want to configure. In the example below, we're working with the data target, "nodes," which has a channel called "selected," the same as the output "selected." 

The default setting will be to return all of the data, {*}. However, if you would like to filter for certain properties, you can provide a selection. For example, providing { age: age } would produce a duffle of entities containing only the attribute-value pairs for age.

Now, available in the output for further use in the dataflow are the attribute-value pairs for age in the data. 

A concrete example would be the scatter plot outputs, which include "click" and "mouseover," where the xap builder can select what data will be returned when an end-user clicks on a point in the plot.

Configuration Schemes

For complex components, often visualizations, the component interface will offer a choice of configuration schemes - auto, fixed, or projected. In auto mode, the system will attempt to understand how the data entering the component should get mapped to its targets and channels. In fixed mode, the xap builder can configure the fields. In projected mode, the xap builder can work with data that's already been mapped to the component in a different port. 

NOTE: When you select a mode, you'll see a warning. You are being warned that you if you proceed to change modes the values you've already entered, if any, will not get saved. You'll have to start over in the new mode.

NOTE: This configuration scheme option is only available for components that utilize mutliplex channels, an architectural concept you'd learn more about in component-authoring documentation. 

Now proceed to part 3 to learn syntax for configuring these fields.