Overview

Mendix widget to use AntDesign TreeSelect. The widget is designed to display a list of objects that have a self-association or do raw JSON input and output.

Documentation

See the formatted documentation on the GitHub ReadMe.

## Mendix Antd Tree Select

Mendix widget to use [AntDesign TreeSelect](https://ant.design/components/tree-select). The widget is designed to display a list of objects that have a self-association or do raw JSON input and output.


## Features

- Search the data set

- Data source can be Mendix Objects or raw JSON

- Can show the options as checkboxes or cells

- Option to use tree lines

- Option to have all context expanded or collapsed by default

- Select a reference or reference set

## Usage

1. Add this widget to the Mendix Project

1. Download the mpk file from [GitHub](https://github.com/bsgriggs/mendix-tree-select/releases) or the Mendix Marketplace.

2. Copy the mpk file to your Mendix Project directory `{YourMendixProjectFolder}/widgets/`.

3. Open your Mendix Project with Mendix Studio Pro and click on the menu `Menu > App > Synchronize App Directory`.

2. Domain model properties

The entity you want to display must include an attribute that uniquely identifies an object. For me, this is the ItemNo AutoNumber.


*Note:*

- The "Item" entity will be displayed in the dropdown

- The "ItemSelection" entity is the owner of the association that is set when option(s) are selected

- If you are using Input Type "JSON", you will need 2 non-persistent entities to store the state of the widget and manage the selected objects

3. General properties of the widget


*Note: Checkable is only allowed if Reference Type = Reference Set*


**Input Type** - How the widget expects to receive the selectable objects and how the widget sets the selected value. Detailed setup for both types below.

**Reference type** - Should the user be able to select a list of options of only one option?

**Selection Type** - Determines which items get returned if a parent and all of its children are selected (Only for reference sets)

All

Parent only

Children only

3a. Input Type "Mendix"

The widget will generate the widget's structure using the selected data source.


*Note:*

- Parent key must be the SAME attribute as the key but navigates across the self-association. It is used to match each child with by its parent's key

- If the parent key for an object is empty or is not found, the widget will display that record as a root option

- Association is the reference set on the page object that get set when the user selects an option

- Large data sets can run into performance issues while converting the data, consider using JSON mode

3b. Input Type "JSON"


**Tree data type** - Controls which JSON structure the widget expects.

Flat

Tree

```json [ { "label": "", "value": 0, "id": 0, "pId": 0 } ] ```

```json [ { "label": "Node1", "value": 0, "children": [ { "label": "Child Node1", "value": 0, "children": [ { "label": "Grand Child Node1", "value": 0 } ] } ] } ] ``` Note: You can add as much depth as you need. Just add more children to the lowest level of the JSON structure

1. Create a JSON Structure using the JSON Snippets above. If your unique identifier is a string, change the integers in the structures below to also be a string.

2. Wrap the widget with a data view.


The functionality of DS_TreeSelectHelper and the On Change action depends on the reference type: reference or reference set:

JSON Reference

3. DS_TreeSelectHelper returns the TreeSelectHelper from the domain model above.


3a. Retrieve across the reference you're going to set to see if there is already a value. **If there is no current value, be sure to set $TreeSelectHelper/Selected as *empty*. Setting '' does not work.**

3b. For Tree Data Type "Flat", retrieve all the objects you want displayed. For Tree Data Type "Tree", ONLY retrieve the root level objects. Children will be retrieved by the subsequent export mapping.

3c. Use an export mapping to get the JSON structure for your selectable objects. These should be based on the JSON structures in the Tree Data Type section above.

Flat

Tree

Label - the text shown for the option Value & Id & PId - should all be the SAME unique identifier for the object PId must have a conversion Microflow get the parent's unique identifier. Example:

The first JsonObject should be Method: Parameter. All subsequent children should be Method: By Microflow to get the list of those children's children. Example:

4. Add an on change microflow that converts the JSON stored on the "selected attribute" back to Mendix objects.


4a. If trim($TreeSelectHelper/Selected) != '', then retrieve the original object by the unique identifier on $TreeSelectHelper/Selected.

4b. Otherwise, set the association as empty.

JSON Reference Set

3. DS_TreeSelectHelper returns the TreeSelectHelper from the domain model above.


3a. Retrieve across the reference you're going to set to see if there is already a value. Export that list by creating a JSON Structure with the following. If your unique identifier is a string, encase the 1 with quotation marks.

```json

[1]

```

Then, use that JSON Structure to create the following Import and Export Mappings. "Value" should be your entity's unique identifier ... in my case ItemNo.

Import

Export

3b. For Tree Data Type "Flat", retrieve all the objects you want displayed. For Tree Data Type "Tree", ONLY retrieve the root level objects. Children will be retrieved by the subsequent export mapping.

3c. Use an export mapping to get the JSON structure for your selectable objects. These should be based on the JSON structures in the Tree Data Type section above.

Flat

Tree

Label - the text shown for the option Value & Id & PId - should all be the SAME unique identifier for the object PId must have a conversion Microflow get the parent's unique identifier. Example:

The first JsonObject should be Method: Parameter. All subsequent children should be Method: By Microflow to get the list of those children's children. Example:

4. Add an on change microflow that converts the JSON stored on the "selected attribute" back to Mendix objects.


4a. Use the Import mapping from #3a and import from $TreeSelectHelper/Selected.

4b. Iterate that list and retrieve the original objects by their unique identifier attribute.

4c. Change the page object's reference set to the list retrieve by the loop.

## Demo project

https://demo-antdwidgets100-accp.apps.ap-2a.mendixcloud.com/p/tree-select

## Issues, suggestions and feature requests

https://github.com/bsgriggs/mendix-tree-select/issues

## Development and contribution

1. Install NPM package dependencies by using: `npm install`. If you use NPM v8, which can be checked by executing `npm -v`, execute: `npm install --legacy-peer-deps`.

2. Run `npm start` to watch for code changes. On every change:

- the widget will be bundled;

- the bundle will be included in a `dist` folder in the root directory of the project;

- the bundle will be included in the `deployment` and `widgets` folder of the Mendix test project.

[AntDesign TreeSelect](https://ant.design/components/tree-select)

Benjamin Griggs

Jonathan Schmitt