|
| 1 | +--- |
| 2 | +title: "Use Custom Chart" |
| 3 | +url: /appstore/widgets/charts-custom-usage/ |
| 4 | +weight: 20 |
| 5 | +description: "How to use the Custom Chart widget to create advanced charts" |
| 6 | +aliases: |
| 7 | + - /howto/front-end/charts-custom-usage/ |
| 8 | +--- |
| 9 | + |
| 10 | +## Introduction |
| 11 | + |
| 12 | +The basic charts provide a set of easy to configure charts such as line, bar, column, pie, and so forth. These charts can be fine tuned with the advanced options. |
| 13 | + |
| 14 | +When the advanced options are not enough, starting from charts version 6.0 and higher, the **Custom Chart** widget can be used. |
| 15 | + |
| 16 | +With **Custom Chart** you can build all the chart types that are possible with Plotly.js as well as options for configuring charts dynamically. So, if you want to build a 3D chart or have a dynamic set of series, **Custom Chart** is your friend. |
| 17 | +**Custom Chart** is a successor of **Any Chart** module that is compatible with **React client** mode. |
| 18 | + |
| 19 | +This how-to teaches you how to do the following: |
| 20 | + |
| 21 | +* Create a line chart with sample data |
| 22 | +* Export data for a chart |
| 23 | +* Fine tune the chart with the run-time playground |
| 24 | + |
| 25 | +## Prerequisites |
| 26 | + |
| 27 | +Before starting this how-to, make sure you have the following prerequisites: |
| 28 | + |
| 29 | +* The latest version of Mendix Studio Pro |
| 30 | +* The latest [Chart](/appstore/widgets/charts/) widget |
| 31 | +* An understanding of JSON data structures |
| 32 | + |
| 33 | +## Chart Structure |
| 34 | + |
| 35 | +A **Custom Chart** widget can be configured with a JSON **Data** array and **Layout** object. The configuration can be set statically, via the **Source attribute** or with the **Sample data**. |
| 36 | + |
| 37 | +The configuration in the **Source attribute** will be merged into the static settings and will overwrite any common properties. The **Sample data** is for demo purposes at run time when there is no **Source** attribute selected or when rendering sample data in the Studio Pro preview. |
| 38 | + |
| 39 | +## Creating a Chart |
| 40 | + |
| 41 | +To create a line chart with the **Custom Chart** widget, follow these steps: |
| 42 | + |
| 43 | +1. Create a page with a data view (Chart context). |
| 44 | +2. Add the Custom Chart widget in the data view. |
| 45 | +3. Select the line chart sample from the [Any Chart cheat sheet](/refguide/charts-any-cheat-sheet/#line-chart): |
| 46 | + |
| 47 | + ```json |
| 48 | + [ { "x": [ 1, 2 ], "y": [ 1, 2 ], "type": "scatter" } ] |
| 49 | + ``` |
| 50 | + |
| 51 | +4. In Studio Pro, copy the data into the Custom Chart widget property tab **Data**, field **Static**. |
| 52 | +5. Run the app to confirm the chart renders correctly. |
| 53 | +6. Split the data into static and dynamic parts that are going to be generated from the domain model. |
| 54 | + |
| 55 | + Static : |
| 56 | + |
| 57 | + ```json |
| 58 | + [ { "type": "scatter" } ] |
| 59 | + ``` |
| 60 | + |
| 61 | + Sample data : |
| 62 | + |
| 63 | + ```json |
| 64 | + [ { "x": [ 1, 2 ], "y": [ 1, 2 ] } ] |
| 65 | + ``` |
| 66 | + |
| 67 | + {{< figure src="/attachments/appstore/platform-supported-content/widgets/charts/charts-tutorials/charts-any-usage/any-chart-configuration.png" alt="Any Chart Configuration" class="no-border" >}} |
| 68 | + |
| 69 | +7. Run the app to preview the chart. |
| 70 | + |
| 71 | + {{< figure src="/attachments/appstore/platform-supported-content/widgets/charts/charts-tutorials/charts-any-usage/charts-any-sample.png" alt="Any Chart result" class="no-border" >}} |
| 72 | + |
| 73 | +## Exporting Data |
| 74 | + |
| 75 | +To generate JSON data for the Charts widget, follow these steps: |
| 76 | + |
| 77 | +1. Add a **Data** string (unlimited length) attribute to the Chart (context) entity. |
| 78 | +2. In the widget, set the **Source attribute** field in the **Data** tab. |
| 79 | + {{< figure src="/attachments/appstore/platform-supported-content/widgets/charts/charts-tutorials/charts-any-usage/custom-chart-configuration-attribute.png" alt="Select data attribute" class="no-border" >}} |
| 80 | +3. Create a **JSON Structure** and use the **Sample data** as the snippet. |
| 81 | + {{< figure src="/attachments/appstore/platform-supported-content/widgets/charts/charts-tutorials/charts-any-usage/any-chart-json-structure-line-chart-data.png" alt="Create export mapping" class="no-border" >}} |
| 82 | +4. Create an **Export Mapping** with the **JSON Structure**. |
| 83 | + {{< figure src="/attachments/appstore/platform-supported-content/widgets/charts/charts-tutorials/charts-any-usage/any-chart-line-chart-export-mapping-select.png" alt="Select data structure" class="no-border" >}} |
| 84 | + {{< figure src="/attachments/appstore/platform-supported-content/widgets/charts/charts-tutorials/charts-any-usage/any-chart-line-chart-export-mapping.png" alt="Map objects" class="no-border" >}} |
| 85 | +5. Create a microflow that retrieves the data. |
| 86 | +6. Use the **Export Mapping** to generate a **String Variable**. Store the value in the object attribute that is selected as **Source attribute**. |
| 87 | + {{< figure src="/attachments/appstore/platform-supported-content/widgets/charts/charts-tutorials/charts-any-usage/any-chart-export-microflow.png" alt="Export microflow" class="no-border" >}} |
| 88 | + {{< figure src="/attachments/appstore/platform-supported-content/widgets/charts/charts-tutorials/charts-any-usage/any-chart-export-microflow-structure.png" alt="Export microflow" class="no-border" >}} |
| 89 | + |
| 90 | +If need be, the layout can also be generated in the same way as the data. In most cases, a **Static** layout will suffice. |
| 91 | + |
| 92 | +## Fine tuning |
| 93 | + |
| 94 | +Editing the JSON configuration in Studio Pro can be cumbersome. With the live preview editor, developers can directly see the output of their changes. |
| 95 | + |
| 96 | +See (Chart advanced tuning)[/appstore/widgets/chart-advanced-tuning/] for more information on fine tuning **Custom Chart** with using **Chart Playground** widget. |
| 97 | + |
| 98 | +{{% alert color="info" %}} |
| 99 | +Since the introduction of design mode, react-ready widgets can render data as it is entered. This makes it possible for user to see Static data and configurations directly in design mode without the needs of running the apps. |
| 100 | +{{% /alert %}} |
| 101 | + |
| 102 | +## Dimension |
| 103 | + |
| 104 | +These are the dimension configurations for custom charts: |
| 105 | + |
| 106 | +- **Width** — Determines the width size for the custom charts. User can choose to use either pixels (px) or percentage (%). |
| 107 | +- **Height** — Determine the height size for the custom charts. User can choose to use either pixels (px), percentage (%), or Viewport (vh). Choosing setting to **Auto** will allow user to set minimum and maximum height instead. |
| 108 | +- **Minimum Height** — Determines the minimum size for the custom charts container. |
| 109 | +- **Maximum Height** — Determines the maximum size for the custom charts container. |
| 110 | +- **Vertical Overflow** — If maximum height is set, vertical overflow will determine the widget's behavior to show overflowing content if it reached height size larger than the maximum height allowed. |
| 111 | + |
| 112 | + |
| 113 | +## Events |
| 114 | + |
| 115 | +- **On Click** — Determines the actions that will be triggered if parts of the custom charts is clicked. |
| 116 | +- **Event data attribute** — The string value that the chart uses when click events occur. User can use this same attribute as the parameters for on-click events action to retrieve the data from the custom chart: |
| 117 | + |
| 118 | + {{< figure src="/attachments/appstore/platform-supported-content/widgets/charts/charts-tutorials/charts-any-usage/custom-chart-events-attribute.png" alt="Setup on click events" class="no-border" >}} |
| 119 | + |
| 120 | +## Read More |
| 121 | + |
| 122 | +* **Any Chart** properties: [Any Chart](/refguide/charts-any-configuration/) |
| 123 | +* The most common chart types: [Any Chart Cheat Sheet](/refguide/charts-any-cheat-sheet/) |
| 124 | +* The most common settings: [Configuration Cheat Sheet](/refguide/charts-advanced-cheat-sheet/) |
| 125 | +* The full JSON reference: [https://plot.ly/javascript/reference/](https://plot.ly/javascript/reference/) |
| 126 | +* [JSON Structures](/refguide/json-structures/) |
| 127 | +* [Export Mappings](/refguide/export-mappings/) |
0 commit comments