org.dashbuilder.displayer.DisplayerSettingsBuilder Maven / Gradle / Ivy
Show all versions of dashbuilder-displayer-api Show documentation
/*
* Copyright 2014 Red Hat, Inc. and/or its affiliates.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.dashbuilder.displayer;
import org.dashbuilder.dataset.DataSet;
import org.dashbuilder.dataset.DataSetLookupBuilder;
/**
* A DisplayerSettingsBuilder allows for the assembly of a DisplayerSettings instance in a friendly manner.
*
*
* DisplayerSettingsFactory.newBarChartSettings()
* .title("By Product")
* .titleVisible(false)
* .margins(10, 50, 100, 100)
* .column("Product")
* .column("Total amount")
* .horizontal()
* .buildSettings();
*
*
* @see DisplayerSettings
*/
public interface DisplayerSettingsBuilder extends DataSetLookupBuilder {
/**
* Set the DisplayerSettings' UUID.
*
* @param uuid The UUID of the DisplayerSettings that is being assembled.
* @return The DisplayerSettingsBuilder instance that is being used to configure a DisplayerSettings.
*/
T uuid(String uuid);
/**
* Set a direct reference to the source data set that will be used by the Displayer that is being assembled.
* When using this dataset provided mode the data set lookup operations set (if any): filter, group & sort will not be taking into account).
*
* @return The DisplayerSettingsBuilder instance that is being used to configure a DisplayerSettings.
* @see org.dashbuilder.dataset.DataSet
*/
T dataset(DataSet dataSet);
/**
* Sets the caption that will be shown for this particular visualization of the data.
* @param title The caption to be shown
* @return The DisplayerSettingsBuilder instance that is being used to configure a DisplayerSettings.
*/
T title(String title);
/**
* Set whether the caption should be visible or not.
* @param visible True if the caption is to be visible, false if not.
* @return The DisplayerSettingsBuilder instance that is being used to configure a DisplayerSettings.
*/
T titleVisible(boolean visible);
/**
* Set the background color for the displayer.
* @param backgroundColor The background color code.
* @return The DisplayerSettingsBuilder instance that is being used to configure a DisplayerSettings.
*/
T backgroundColor(String backgroundColor);
/**
* Set the renderer that will be used for visualizing this DisplayerSettings.
* @param renderer The identifier of the renderer.
* @return The DisplayerSettingsBuilder instance that is being used to configure a DisplayerSettings.
*/
T renderer(String renderer);
/**
* Set the DisplayerSettings' subtype.
*
* @param displayerSubType The displayer's subtype.
* @return The DisplayerSettingsBuilder instance that is being used to configure a DisplayerSettings.
*/
T subtype(DisplayerSubType displayerSubType);
/**
* Enable the ability to select/filter values (or range of values) within the data displayer.
*
*
Usually, in a dashboard there exists a unique coordinator which takes cares of propagate all the data
* selection events among the other displayers. If enabled then there exists also the ability to configure how to
* interact with other displayers in the same dashboard.
* @param applySelf If true then any filter request issued within the data displayer will be applied to the own displayer.
* @param notifyOthers If true then any filter request issued within the data displayer will be propagated to other interested displayers.
* @param receiveFromOthers If true then the data displayer will listen for filter requests coming from other displayers.
*
* @return The DisplayerSettingsBuilder instance that is being used to configure a DisplayerSettings.
*/
T filterOn(boolean applySelf, boolean notifyOthers, boolean receiveFromOthers);
/**
* Disable the ability to select/filter values (or range of values) within the displayer.
*
* @param receiveFromOthers If true then the data displayer will listen for filter requests coming from other displayers.
* @see DisplayerSettingsBuilder#filterOn DisplayerSettingsBuilder's filterOn method.
* @return The DisplayerSettingsBuilder instance that is being used to configure a DisplayerSettings.
*/
T filterOff(boolean receiveFromOthers);
/**
* Force the displayer to redraw only when data becomes stale.
*
* @return The DisplayerSettingsBuilder instance that is being used to configure a DisplayerSettings.
*/
T refreshOn();
/**
* Force the displayer to redraw every time interval.
*
* @param seconds The refresh time frame in seconds. If < 0 then periodic refresh is disabled.
* @param onStale Refresh when the data becomes stale.
*
* @return The DisplayerSettingsBuilder instance that is being used to configure a DisplayerSettings.
*/
T refreshOn(int seconds, boolean onStale);
/**
* Switch off the automatic refresh.
*
* @see DisplayerSettingsBuilder#refreshOn DisplayerSettingsBuilder's refreshOn method.
* @return The DisplayerSettingsBuilder instance that is being used to configure a DisplayerSettings.
*/
T refreshOff();
/**
* Defines the display name for the last specified data set column.
*
* NOTE: This method can only be called right after a call to DataSetLookupBuilder#column(...).
*
* @param name The column display name.
* @return The DisplayerSettingsBuilder instance that is being used to configure a DisplayerSettings.
*/
T format(String name);
/**
* Defines the display format for the last specified data set column.Every data set value will be formatted
* according to the specified pattern parameter which defines the string format of the data set value.
* Examples:
*
* - format("Amount", "$ #,###.##") => "$ 10,450.5"
* - format("Amount", "$ #,### K") => "$ 450 K"
*
*
* NOTE: This method can only be called right after a call to DataSetLookupBuilder#column(...).
*
* @param name The column display name.
* @param pattern The standard java DecimalFormat and DateFormat can be used used for both number and date columns.
* @see java.text.DecimalFormat
* @see java.text.SimpleDateFormat
* @return The DisplayerSettingsBuilder instance that is being used to configure a DisplayerSettings.
*/
T format(String name, String pattern);
/**
* Defines the display format for the specified data set column. Every data set value will be formatted
* according to the specified pattern parameter which defines the string format of the data set value.
* Examples:
*
* - format("Amount", "$ #,###.##") => "$ 10,450.5"
* - format("Amount", "$ #,### K") => "$ 450 K"
*
*
* @param columnId The column identifier.
* @param name The column display name.
* @param pattern The standard java DecimalFormat and DateFormat are used for both number and date columns.
* @see java.text.DecimalFormat
* @see java.text.SimpleDateFormat
* @return The DisplayerSettingsBuilder instance that is being used to configure a DisplayerSettings.
*/
T format(String columnId, String name, String pattern);
/**
* Defines a mathematical expression used to calculate the real values to display for the last specified data set
* column.
*
* For numeric columns the expression can be any basic math expression where the value keyword represent
* the source data set value and any of the basic math operators "/ * + -" are allowed. Examples:
*
* - format("Amount", "$ #,###.##").expression("value") => "$ 10,450.5"
* - format("Amount", "$ #,###.##").expression("value-1") => "$ 10,449.5"
* - format("Amount", "$ #,##0.00 K").expression("value/1000") => "$ 10.45 K"
*
*
* For text columns you can manipulate the string using any javascript statement: Examples
*
* - format("Quarter").expression("["1st Q", "2nd Q", "3rd Q", "4th Q"][value+1]") => "3rd Q" (value=1 in a date fixed grouped column)
* - format("3 chars").expression("value.substring(0, 3) + "...") => "Dav..." it takes the first 3 chars only
*
*
* NOTE: This method can only be called right after a call to DataSetLookupBuilder#column(...)
*
* @param expression The expression used to calculate the value to display
* @return The DisplayerSettingsBuilder instance that is being used to configure a DisplayerSettings.
*/
T expression(String expression);
/**
* Sames as expression(String expression) but using the specified column.
*
* @param columnId The column identifier.
* @param expression The expression used to calculate the value to display
* @return The DisplayerSettingsBuilder instance that is being used to configure a DisplayerSettings.
*/
T expression(String columnId, String expression);
/**
* Support for user-provided HTML templates. For instance, a metric displayer could be configured as follows:
*
*
* {@code
* ${title}
* ${value}
*
* }
*
* Notice that, references (like "${value.ref}" in the example above) can be added to any of the HTML elements so that they can be referenced from the Javascript template.
* See {@link #jsTemplate(String)} for further details.
*
* @param html The HTML template used to render the displayer. The following enumeration contains all the available variables:
*
* - id: An identifier that it is unique among all the displayers
* - title: The metric title
* - value: The formatted value
* - value.raw: The raw value
* - width: The metric width
* - height: The metric height
* - marginTop: The top margin
* - marginBottom: The bottom margin
* - marginLeft: The left margin
* - marginRight: The right margin
* - bgColor: The background color
* - isFilterEnabled: true or false depending whether the filter setting is enabled (see {@link #filterOn(boolean, boolean, boolean)})
* - isFilterOn: true or false depending whether the filter function is currently on or of
*
* @return The DisplayerSettingsBuilder instance that is being used to configure a DisplayerSettings.
*/
T htmlTemplate(String html);
/**
* Specifies the JS template that is invoked every time the displayer is drawn.
*
* Notice, HTML elements tagged as "${...}" can be referenced from the JS template. For instance, given the following
* HTML template:
*
*
* {@code
* ${title}
* ${value}
*
* }
*
* It is possible to implement some conditional into the JS so that the color of the text displayed depends on its value:
*
*
* {@code ${valref}.style.color= ${value.raw} > 1000 ? "red" : "black";
* }
*
* where the "${valref}" is the identifier of the HTML element holding the value.
*
* @param js A JS template. Notice, the same variables supported in {@link #htmlTemplate(String)} can be used in the JS.
* @return The DisplayerSettingsBuilder instance that is being used to configure a DisplayerSettings.
*/
T jsTemplate(String js);
/**
* @return The DisplayerSettings instance that has been configured.
* @see DisplayerSettings
*/
DisplayerSettings buildSettings();
}