Developing Custom Components for Dashbuilder
Dashbuilder is the component of Business Central that allows users to create pages and dashboards. Pages are made of small components that can show data, they are so-called displayers.
By default dashbuilder provides multiple displayers that users can drag to pages, for instance:
In Business Central 7.43, we introduced a new way of displaying data by allowing users to create their own custom components that can be based on any modern Javascript library, opening to new possibilities to display business data.
In this article, we will introduce the brand new External Components API and how to use it in Business Central.
External Components API
External components are custom page parts that can be developed in order to consume datasets from Business Central and display data in any way that you want. Users can also configure components using parameters provided by the component itself. Dashbuilder allows users to set these parameters values and send it to the component when it is rendered.
In order to create your first component, the entry point to create components is the file manifest.json, which must be placed in the component root directory. Manifest files must have at least the text parameter called “name”, but other parameters are supported:
- Name: The component name that will be displayed in the component pallet;
- Icon: Icon that will be displayed in the component pallet.
- noData: A flag that indicates that the component does not require a dataset;
- parameters: A list of parameters that the components need to be collected by the user.
The list of parameters supported by the component uses ComponentParameter type, which has the following:
- name: The parameter internal name.
- type: Parameter type. Possible values are text, natural_number, combo, and color. When using combo type you must set comboValues.
- category: The category which the field property will be grouped into;
- defaultValue: The initial value presented to the user;
- label: The label used in the component parameters UI;
- comboValues: A list of text values for combo parameters;
- noData: Special attribute which when true will not consume a dataset.
A complete manifest would look similar to this:
When users drag the component to the page a wizard shows up, renders a component preview and the properties form according to the properties defined in the manifest:
Building data visualization with external components
After manifest.json is finished you can start building your own dashboards. The entry point is index.html. From the index file, you can link javascript and css resources. In javascript code, we can then listen for messages that will be sent by dashbuilder.
window.addEventListener(“message”, receiveMessage, false);
function receiveMessage(event) {
// consume the message
const params = new Map(event.data.properties);
}
The message sent by dashbuilder contains data of type ExternalComponentMessage and contains only an attribute called properties of type Map<String, Object>. In this object you will find:
- The value for any property you have according to what user set in the UI. To retrieve the value uses the attribute name as the key, for example:
params.get(“svg”)
- A special attribute called dataSet, which is of type ExternalDataSet. This is what you should use to get the data from dashbuilder:
params.get(“dataSet”)
The returned dataset object has the following attributes:
- columns: List of columns which is of ExternalColumn type;
- rows: a two-dimensional array with dataset values.
All the rows values are of string type, to get the actual type you can get the column information and find the actual type: rows[row index][column index]. With the “column index” you can get the column information in columns attribute, a column is represented by ExternalColumn object, which has text attributes name, type, and a complex columnSettings attribute. ColumnSettings holds all the user settings for a specific column, it is represented by object ExternalColumnSettings which has the following attributes:
- columnName: The name set by the user in the UI;
- valueExpression: A javascript expression that should be evaluated over the column value;
- emptyTemplate: The text that should be used when the column value is empty;
- valuePattern: A pattern to format column values. Useful for number.
All column settings are configured by the user when the component is dragged to a page:
External Components configuration
By default, external components are disabled. You can enable it by setting the system property dashbuilder.components.enable as true.
Dashbuilder looks for components in the directory configured using the system property dashbuilder.components.dir. The default value is /tmp/dashbuilder/components and this directory should not be shared with Dashbuilder Runtime. Your components will live inside this directory
Components assets are served by ExternalComponentServlet. In Business Central or in Dashbuilder Runtime you can control cache in web.xml using init-param cache-control.
External components in Dashbuilder Runtime
Recently, we introduced the Dashbuilder Runtime web application and export/import feature. All the components you have configured in Business Central will be packaged with the ZIP file exported from the Data Transfer feature. When imported in Runtime then it will be partitioned by import if you are using multi-mode.
Also notice that Runtime caches all the components assets, this can be changed in dashbuilder-runtime.war/WEB-INF/web.xml.
External component servlet mapping. Never change the url-pattern for external components.
It is also recommended to avoid sharing the components directory between Dashbuilder Runtime and Business Central.
Learning more
There’s no limit to what you can do, or what library you can use! For this reason, we have a growing library of components with some cool external components, like heatmaps, an alternative chart library (Victory Charts), and soon a new Maps component. Check it in Github.
To get started check out the hello_user example, a very simple component, and then simplest_component, which uses all external component library, including a filter feature that is also available on this new API.
Conclusion
In this article, we introduced the external components API. This is a new milestone for Dashbuilder and Business Central and it makes it possible to explore Business Central data in ways we didn’t imagine before!
Next, we will bring tutorials putting all Dashbuilder Runtime features together, stay tuned!
