diff --git a/docs/manuals/gui/extension.md b/docs/manuals/gui/extension.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/userman/gui/extension/chart.md b/docs/userman/gui/extension/chart.md new file mode 100644 index 000000000..c0d73157a --- /dev/null +++ b/docs/userman/gui/extension/chart.md @@ -0,0 +1,184 @@ +# Chart + +In this section, we’ll dive into creating and integrating charts using [`Plotly`](https://plotly.com/graphing-libraries/) in your extension library. +Charts are invaluable for visualizing data, offering clear and interactive insights that enhance the user experience. +We’ll walk through the steps to implement different types of charts, configure their properties, +and seamlessly embed them into your application. + +## Prerequisites + +Before you start creating charts, ensure you have the following prerequisites: + +- **Install the necessary libraries:** To use Plotly.js with React, you’ll need to install the react-plotly.js library. + + ```bash + $ npm install react-plotly.js plotly.js + ``` + +!!!Note + When using TypeScript, you’ll need to install the type definitions for Plotly.js as well. + + ```bash + $ npm install --dev @types/react-plotly.js + ``` + +## Declaring the element {data-source="gui:doc/extension/example_library/example_library.py#L69"} + +To create a chart element, you need to define the element in your extension library. + +```python title="example_library.py" +from taipy.gui.extension import Element, ElementLibrary, ElementProperty, PropertyType + +class ExampleLibrary(ElementLibrary): + def __init__(self) -> None: + # Initialize the set of visual elements for this extension library + self.elements = { + "dashboard": Element( + "data", + { + "data": ElementProperty(PropertyType.dict), + "layout": ElementProperty(PropertyType.dict), + }, + ) + } +``` + +The detailed explanation of the code is as follows: + +- The *dashboard* element includes two properties: *data* and *layout*. +- The *data* property has the type `PropertyType.dict`, meaning it holds a dictionary of data. +- The *layout* property has the type `PropertyType.dict`, meaning it holds a dictionary of layout properties. + +## Creating the React component {data-source="gui:doc/extension/example_library/front-end/src/Dashboard.tsx"} + +The React component for the *dashboard* element is defined as follows: + +```tsx title="Dashboard.tsx" +import React, { useMemo } from "react"; +import { useDynamicJsonProperty, } from "taipy-gui"; + +import Plot from "react-plotly.js"; +import { Data, Layout } from "plotly.js"; + +interface DashboardProps { + data?: string; + defaultData?: string; + layout?: string; + defaultLayout?: string; +} + +const Dashboard = (props: DashboardProps) => { + const value = useDynamicJsonProperty(props.data, props.defaultData || "", {} as Partial); + const dashboardLayout = useDynamicJsonProperty(props.layout, props.defaultLayout || "", {} as Partial); + + const data = useMemo(() => { + if (Array.isArray(value)) { + return value as Data[]; + } + return [] as Data[]; + }, [value]); + + const baseLayout = useMemo(() => { + const layout = { + ...dashboardLayout, + }; + return layout as Partial; + }, [dashboardLayout]); + + return ( +
+ +
+ ); +}; + +export default Dashboard; +``` + +The detailed explanation of the code is as follows: + +- The **Dashboard** component accepts two props: *data* and *layout*. +- The [`useDynamicJsonProperty()`](../../../refmans/reference_guiext/functions/useDynamicJsonProperty.md) hook is used to handle dynamic properties. It accepts the following arguments: + + - *data*: The dynamic property that holds the data for the chart. + - *defaultData*: The default value for the data property. + - *layout*: The dynamic property that holds the layout properties for the chart. + - *defaultLayout*: The default value for the layout property. + +- The **Plot** component utilizes the [`react-plotly.js`](https://github.com/plotly/react-plotly.js) library to render the chart. It accepts two props: + + - *data*: An array of data objects to define the chart's datasets. + - *layout*: An object specifying the layout properties of the chart. + +For more information on how to use `react-plotly.js`, refer to the official documentation [here](https://github.com/plotly/react-plotly.js). + + + +## Exporting the React component {data-source="gui:doc/extension/example_library/front-end/src/index.ts"} + +When the component is entirely defined, it must be exported by the library's JavaScript bundle. +This is done by adding the export directive in the file */front-end/src/index.ts*. + +```ts title="index.ts" +import Dashboard from "./Dashboard"; + +export { Dashboard }; +``` + +## Configuring the webpack configuration {data-source="gui:doc/extension/example_library/front-end/webpack.config.js#L39"} + +To bundle the React component, you must configure the webpack configuration file. +Since Plotly.js is a JavaScript library, you need to include JavaScript in the webpack’s resolve.extensions setting. + +```js title="webpack.config.js" +module.exports = { + // ... + resolve: { + extensions: [".ts", ".tsx", ".js"], + }, + // ... +}; +``` + +After configuring the webpack file, you can build the library as mentioned in the [Building the front-end module](dynamic_element/index.md) section. + +## Using the element {data-source="gui:doc/extension/example_library/dashboard.py"} + +To use the *dashboard* element in a Python script, you can follow the example below: + +```python title="dashboard.py" +trace1 = { + "x": [1, 2, 3, 4, 4, 4, 8, 9, 10], + "type": "box", + "name": "Set 1" +} + +trace2 = { + "x": [2, 3, 3, 3, 3, 5, 6, 6, 7], + "type": "box", + "name": "Set 2" +} + +data = [trace1, trace2] + +layout = { + "title": { + "text": "Horizontal Box Plot" + } +} + +page = """ +<|{data}|dashboard|layout={layout}|> +""" +``` + +In this example, we define two traces and a layout for a horizontal box plot. +When you run the script, the *dashboard* element will display like this: + +
+ Horizontal Box Plot +
Horizontal Box Plot
+
+ + + diff --git a/docs/userman/gui/extension/dashboard.png b/docs/userman/gui/extension/dashboard.png new file mode 100644 index 000000000..eabb91f82 Binary files /dev/null and b/docs/userman/gui/extension/dashboard.png differ diff --git a/docs/userman/gui/extension/index.md b/docs/userman/gui/extension/index.md index 8967c9866..32e6769a8 100644 --- a/docs/userman/gui/extension/index.md +++ b/docs/userman/gui/extension/index.md @@ -232,5 +232,6 @@ make your way from one example to the next. - [Using scalar properties](dynamic_element/scalar_props.md) - [Using List of Values](list_of_values.md) - [Using tabular data](tabular_data.md) +- [Using charts](chart.md) - [Accessing assets](accessing_assets.md) - [Packaging an element library](extension_packaging.md) diff --git a/mkdocs.yml_template b/mkdocs.yml_template index f458b6d15..3c2f477dc 100644 --- a/mkdocs.yml_template +++ b/mkdocs.yml_template @@ -102,6 +102,7 @@ nav: - "Scalar properties": userman/gui/extension/dynamic_element/scalar_props.md - "List of Values Elements": userman/gui/extension/list_of_values.md - "Tabular Elements": userman/gui/extension/tabular_data.md + - "Chart Elements": userman/gui/extension/chart.md - "Accessing assets": userman/gui/extension/accessing_assets.md - "Packaging extensions": userman/gui/extension/extension_packaging.md