Data Label

Guide for using data labels in your applications

Overview

Data Label is a label component based on a dataprovider value, that can show dynamic text and (optionally) an image.

The key differences between a Data Label and a Label and the main reasons for using Data Label instead of Label are the following:

• Data Label supports format, which is very useful when it comes to displaying dates, numbers for example

• The value displayed by the Data Label can be enhanced/transposed using a valuelist, which is used to get a display value for the actual columns real value like id -> name for example

To see a live sample of the component you can go here.

Data Label

Get Started

Add a Data Label to a form

In the Form Editor, drag the Data Label component from the Pallet onto the form, then select a dataprovider.

Create Data Label

If the component does not appear in the pallet, it means you do not have the Bootstrap Components package installed. Click "Get more components" at the top of the pallet to open the Servoy Package Manager and install it.

Modifying a Data Label at Design-Time

Data Labels, like all components, have properties that can be modified at design time to set the appearance and behavior of the component. Select the label in the Form Editor to see a list of properties in the Component Properties Editor. Below are some common properties and how to set them at design time.

See the reference docs for Data Label for a complete list of its properties.

Setting the data-provider

Data Label's dataprovider can be set after the component has been added to the form or by setting it in dataprovider property, found in the Component Properties Editor.

Setting a Tooltip message

Data Labels, like many components, can display tooltip messages when a user hovers their cursor, this can be done by modifying the tooltipText property using the Text Property Editor.

The tooltip text can be dynamic, data-driven, or localized.

Setting an Image / Font-Icon

Many times, a data label will be decorated with an image or font icon. To add an image before the text of the data label, edit the imageStyleClass property and choose the style class of the font icon you wish to use. For example, enter a value of fa fa-user to get a nice icon that represents a User.

Example: imageStyleClass: fa fa-user

In the same way, there is a trailingImageStyleClass property to add an image or icon after the text of the data label.

Example: trailingImageStyleClass: fa fa-user-lock

For more information, please see the Font Icon section of the guide on Styling and Themes

Styling

Like all components, a Data Label can be styled using themes and raw CSS. To apply any available style class, simply enter one or more space-delimited values for the styleClass property.

For example, styleClass="label-info"

Using a format

Data Label's Format can be set in Format property. Depending on the type of each dataprovider, this will be done via the format editors for date, text, integer/number.

Example: Let's consider a Data Label having requireddate set as dataprovider, with no Format set:

`requireddate` with no Format

We need the date to show the full name of the month, followed by day and full year, so we apply a Format, as shown below:

set `requireddate` Format

Here is how it looks after the Format has been set:

`requireddate` with applied Format

Using a Value List

Data Label's valuelist can be set it in valuelist property, found in the Component Properties Editor and it should match the set dataprovider.

Example:

In order to get a drop down menu with orders' ship countries, the followings settings should be made:

1. set shipcountry as the Data Label dataprovider
2. in case it doesn't exist, create a valuelist using Table values and shipcountry column as dataprovider
3. set the countries list in valuelist property of the Data Label

Handling Click Events

Like most components, Data Labels have events, which allow you to execute some logic when something happens in the UI. Of course, the most common event for a data label is the onAction event, which is triggered when the data label is clicked or the user hits the Enter key while the data label has focus.

To Handle the event, double-click the value for the onAction property in the Properties Editor. You will see the Method Selection Wizard. You'll have the option to select an existing Method or create a new Method. The method will be called when the data label's onAction event is fired and the Event object will be passed to it.

Create method to handle the onAction event

/**
 *
 * @param {JSEvent} event
 * @param {String} dataTarget
 *
 * @properties={typeid:24,uuid:"4FA50A53-70A6-4D14-83B8-EA3E675EBAEB"}
 */
function onAction(event, dataTarget) {
	application.showForm('order_details');
}

See the Data Label reference for a comprehensive list of all events

Modifying a Data Label at Runtime

Data Labels, like many components, can be modified at runtime through code. Below are a few examples of controlling a Data Label from code.

Enabling / Disabling a label

You can easily change the enabled state of a Data Label at runtime.

Example:

function disableDataLabel(){
	elements.myDataLabel.enabled = false;
}

Hiding/Showing a Data Label

You can easily change the visible state of a Data Label at runtime.

Example:

function hideDataLabel(){
	elements.myDataLabel.visible = false;
}

Calling Data Label API Methods

Like most components, a Data Label has API methods which can be called from code. Below is an example of common API calls.

Add CSS Style Class

You can easily add a style class to a Data Label using the addStyleClass method.

Example:

function AddStyleClassDataLabel(){
	elements.myDataLabel.addStyleClass('mycssclass');
}

See the Data Label reference for a complete list of programmable properties and methods.

Related Articles

The following articles are recommended for additional reading:

• Data Label Reference Documentation
• Styling and Themes
• Scripting the UI