Overview
Version
Report Server Version | Functional Change |
11.0 | / |
11.0.6 | Parent nodes of the root node in a tree dataset can be non-empty when you create a drop-down tree widget through automatic construction methods.
Renamed Async Load in parameter widgets to Asynchronously Expand Tree Node. The asynchronous loading logic is unified after you set default values. For details, see section "Widget in Parameter Panel" in "Widget Introduction".
|
11.0.7 | Renamed Async Load in data entry widgets to Asynchronously Expand Tree Node. The asynchronous loading logic is unified after you set default values. For details, see section "Widget in Data Entry Report" in "Widget Introduction". Added the option Returned Value's Type. For details, see attribute tables in section "Attribute". Optimized the default value setting method. You can set default values without entering complete paths. For details, see section "Parameter Widget".
|
Application Scenario
Data Entry Widget
You can select data with multi-level tree structures and enter the data in data entry reports through the view tree widget.

Drop-down tree widget cannot be submitted to databases.
Parameter Widget
You can select data with multi-level tree structures and enter query parameters on the parameter panel through the view tree widget.

Adding Method
Data Entry Widget
Select a cell, click the widget setting icon on the right attribute panel, and select Drop-down Tree from the dropdown menu of Select Widget.

Parameter Widget
Drag the Drop-down Tree widget on the parameter panel widget toolbar into the parameter panel.

Notes
1. Difference between the view tree and the drop-down tree:
They have different display effects on browsers during preview, with same definition method. /

2. The following table is the comparison of three different ways to build a drop-down tree.
| Fast Layered Creation | Automatic Creation | Basic Layered Creation |
Number of Required Datasets | One or multiple | One | Multiple |
Required Dataset Type | General dataset | Tree dataset | General dataset |
Required Data Structure | Multiple column fields with dependency relationships | Multiple root nodes can exist in a column or two columns of fields with corresponding relationships and complete tree relationships. Note: Parent nodes of a root node must be empty in FineReport V11.0.6 and earlier versions. | Multiple column fields with corresponding relationships need to be filtered through the treelayer function in SQL. |
Performance | Better than Basic Layered Creation under normal circumstances | Automatic Creation cannot be compared with the other two creation methods due to its unique data structure. | Average performance with large amounts of data or excessive levels |
Others | Cannot automatically filter empty nodes. | Cannot automatically filter empty nodes. | Allows you to hide empty nodes. |
Widget Introduction
Attribute
Data Entry Widget
The attribute setting page of the drop-down tree widget is shown in the following figure.

The following table introduces the settings of each attribute in detail.
Classification | Settings | Introduction |
Basic | Widget Name | Name (empty by default) of the widget is manually entered and usually used in conjunction with parameters, such as passing the widget value to the corresponding parameter after the widget is obtained through Widget Name. |
Available | Determines whether the widget is available. Check (default setting): Widget can be edited during data entry. Uncheck: Widget is grayed out and cannot be edited during data entry. |
Visible | Determines whether the widget is visible. Check (default setting): Widget is displayed on the page during data entry. Uncheck: Widget is not displayed on the page during data entry. |
| Data Dictionary | Allows you to define the actual value and display value of the drop-down tree widget. There are three creation methods: Automatic Creation, Basic Layered Creation, and Fast Layered Creation. 1. Automatic Creation: automatically creates a drop-down tree based on the hierarchical relationship of the tree dataset, with no need to define data layer by layer. 2. Basic Layered Creation: defines the view tree layer by layer through the data dictionary. Some layer parameters are needed to be defined in datasets during the process. That is to say, take the values from the previous layer as parameter values to filter data of the next layer.  Check: If there are no child nodes under a directory, the icon + is still displayed, but there is no data after you expand the directory. 
3. Fast Layered Creation: defines the hierarchy of the drop-down tree through datasets. Compared to Basic Layered Creation, it does not need the help of layer parameters. Data is arranged by category, with each layer bound to a data column.
You cannot adjust the font size and color of options in the data dictionary by setting those of cells. |
Advanced | Watermark | Light gray watermarks are displayed in widgets during data entry. You need to manually enter the watermark content (empty by default) to prompt users for the required information. Watermarks disappear after you click the widget editing area. |
Multiselect | Check: You can select multi-options from the drop-down tree widget during data entry. Uncheck (default setting): You can select only one option during data entry.  |
Asynchronously Expand Tree Node Note: In FineReport of versions earlier than V11.0.7, it was called Async Load. | Node loading logic, which affects performance. It is checked by default. Checked: Only data of parent nodes are loaded and all child nodes remain collapsed by default after you expand options, which is suitable for cases with large amounts of data. If there is a default value for the widget, the default value node is expanded and selected by default, while other nodes are not expanded.  Unchecked: All child nodes are expanded at once after you expand options, which is suitable for cases with small data volume. If there is a default value for the widget, all child nodes are expanded at once and default value nodes are selected.  |
Return Only Leaf Node | Determines whether child nodes can be selected automatically after parent nodes are selected in multiple options. Check (default setting): Child nodes can be selected automatically after parent nodes are selected.  Unchecked: Child nodes cannot be selected automatically when parent nodes are selected. 
Return Only Leaf Node is a function setting option for multi-select drop-down trees, which does not affect single-select drop-down trees. |
Return Full Hierarchical Path | Drop-down tree is a widget with hierarchical structures. Each leaf node at the bottom level has its full hierarchical path. This option determines whether to return full hierarchical paths after a value is selected, with returned value as array-type data. Checked: Full paths are returned. For example, select Director, and returned values are Headquarter, Marketing department, and Director.  Unchecked: Only the leaf node is returned. For example, select Director, and the returned value is Director. |
Returned Value's Type | This option, appearing only when Multiselect is checked and Return Full Hierarchical Path is unchecked, is used to set the format of returned values (Array or String) of multi-select drop-down trees. If Return Full Hierarchical Path is checked, the returned value's type is determined. In this case, there is no option Returned Value's Type.  1. Array: Returned value is an array. For example, select three values and returned values are "Value 1", "Value 2", "Value 3". 2. String: Returned value is a string, in which separator, initializer, and terminator need to be defined. That is to say, multiple selected values are concatenated into a single string through the separator. For example, in the English input mode, separately set Separator to Comma and Initializer and Terminator to Quotes. The returned value is 'Value 1, Value 2, Value 3'.  |
Validation | Allow Null | Determines whether options can be unselected. Check (default setting): allows options to be unselected. Uncheck: The following prompt pops up during data entry validation and submission.
If Allow Null is unchecked, the option Clear will not appear when you use widgets on mobile terminals. |
Error Tip | This setting item appears if Allow Null is unchecked, allowing you to customize the prompt message. The message Can not be null is displayed by default. |
Allow Edit | Determines whether users can directly enter values. Check (default setting): Users can enter values directly and perform fuzzy search.
The function is not supported on mobile terminals. |
Allow Custom Value | Determines whether users can enter values not included in the drop-down tree options. Check: allows users to enter values not included in the drop-down tree options. Uncheck: allows users to enter values (compared with actual values) only included in the drop-down tree options. If an invalid value is entered, a prompt box appears "Value is not in the drop-down list".
|
Parameter Widget
The attribute setting page of the drop-down tree widget is shown in the following figure.

The following table introduces the settings of each attribute in detail.
Classification | Settings | Introduction |
Basic | Widget Name | Name (default value as treeComboBoxEditor#) of the widget is manually entered and usually used in conjunction with parameters, such as passing the widget value to the corresponding parameter after the widget is obtained through Widget Name. |
Available | Determines whether the widget is available. Check (default setting): The widget can be edited during data entry. Uncheck: The widget is grayed out and cannot be edited during data entry. |
Visible | Determines whether the widget is visible. Check (default setting): The widget is displayed on the page during data entry. Uncheck: The widget is not displayed on the page during data entry. |
Advanced | Label Name | The label attribute of widgets is used on mobile terminals. Because mobile terminals do not support Label Widget on the parameter panel, but recognize the Label Name attribute of ordinary widgets and thus use label names of the widgets. |
Widget Value | Default value (empty by default) in the widget initialization. It can be the actual value bound to the data dictionary or the displayed value. Three value types are supported: String, Field, and Formula.
In FineReport of versions earlier than V11.0.7, the default value of the view tree must include the complete path of the node actual value. In FineReport V11.0.7 and later versions, the TREEDEFAULTPATH function is added, allowing you to set the default value without entering the complete path. 1. String: character text. For example, to select Peking, you can enter "North China,Peking,Peking".  If there are multiple values, parent nodes are separated with commas and multiple values are separated with semicolons. For example, to select Peking and Shanghai, you can enter North China.Peking,Peking; East China,Shanghai,Shanghai.  2. Field: dataset field (such as the region field of dataset ds1). Datasets includes template datasets and server datasets.
You cannot select all functions through Field in multi-select drop-down trees.  If the field value meets multiple value formats, multiple options can be selected. 3. Formula: formulas supported by the designer, such as the value of cell A1/=[[1,11,111],[1,11,112]].  If the value corresponding to the formula meets multiple value formats, multiple options can be selected. |
Data Dictionary | Allows you to define the actual value and display value of the drop-down tree widget. There are three creation methods: Automatic Creation, Basic Layered Creation, and Fast Layered Creation. 1. Automatic Creation: automatically creates a drop-down tree based on the hierarchical relationship of the tree dataset, with no need to define data layer by layer. 2. Basic Layered Creation: defines the view tree layer by layer through the data dictionary. Some layer parameters are needed to be defined in datasets during the process. That is to say, take the values from the previous layer as parameter values to filter data of the next layer.  If there are no child nodes under a directory after it is checked, the icon + is still displayed, but there is no data after you expand the directory. 
3. Fast Layered Creation: defines the hierarchy of the drop-down tree through datasets. Compared to Basic Layered Creation, it does not need the help of layer parameters. Data is arranged by category, with each layer bound to a data column. |
Watermark | Light gray watermarks are displayed in widgets during data entry. You need to manually enter the watermark content (empty by default) to prompt users for the required information. Watermarks disappear after you click the widget editing area. |
Font Size | Font size (default value as 12) of the selected and displayed font in the widget box options.
1. Text size in the drop-down options does not change with the font size here. 2. This function is not supported on mobile terminals. |
Multiselect | Check: You can select multi-options from the drop-down tree during data entry. Uncheck (default setting): You can select only one option from the drop-down tree during data entry.  |
Asynchronously Expand Tree Node Note: In FineReport of versions earlier than V11.0.6, it was called Async Load. | Node loading logic, which affects performance. It is checked by default. Checked: Only data of parent nodes are loaded and all child nodes remain collapsed by default after you expand options, which is suitable for cases with large amounts of data. If there is a default value for the widget, the default value node is expanded and selected by default, while other nodes are not expanded.  Unchecked: All child nodes are expanded at once after you expand options, which is suitable for cases with small data volume. If there is a default value for the widget, all child nodes are expanded at once and default value nodes are selected.  |
Return Only Leaf Node | Determines whether child nodes can be selected automatically after parent nodes are selected in multiple options. Checked (default setting): Child nodes can be selected automatically when parent nodes are selected.  Unchecked: Child nodes cannot be selected automatically when parent nodes are selected. 
Return Only Leaf Node is a function setting option for multi-select drop-down trees, which does not affect single-select drop-down trees. |
Return Full Hierarchical Path | Drop-down tree is a widget with hierarchical structures. Each leaf node at the bottom level has its full hierarchical path. This option determines whether to return full hierarchical paths after a value is selected, with returned value as array-type data. Checked: Full paths are returned. For example, select Director, and returned values are “Headquarter, Marketing department, and Director”.  Unchecked: Only the leaf node is returned. For example, select Director, and the returned value is “Director”. |
Returned Value's Type Note: This function is added in FineReport V11.0.7. | This option, appearing only when Multiselect is checked and Return Full Hierarchical Path is unchecked, is used to set the format of returned values (Array or String) of multi-select drop-down trees. If Return Full Hierarchical Path is checked, the returned value's type is determined. In this case, there is no option Returned Value's Type.  1. Array: Returned value is an array. For example, select three values and returned values are "Value 1", "Value 2", "Value 3". 2. String: Returned value is a string, in which separator, initializer, and terminator need to be defined. That is to say, multiple selected values are concatenated into a single string through the separator. For example, in the English input mode, separately set Separator to Comma and Initializer and Terminator to Quotes. The returned value is 'Value 1, Value 2, Value 3'.  |
Validation | Allow Null | Determines whether widgets can be unselected. Check (default setting): allows widgets to be unselected. Uncheck: The following prompt pops up during data entry validation and submission. |
Error Tip | This setting item appears if Allow Null is unchecked, allowing you to customize the prompt message. The message Can not be null is displayed by default. |
Allow Edit | Determines whether users can directly enter values. Check (default setting): Users can enter values directly and perform fuzzy search.
This function is not supported on mobile terminals. |
Allow Custom Value | Determines whether users can enter values not included in the drop-down tree options. Check: allows users to enter values not included in the drop-down tree options. Uncheck: allows users to enter values (compared with actual values) only included in the drop-down tree options. If an invalid value is entered, a prompt box appears "Value is not in the drop-down list".
|
Coords & Size | Widget Location | Widget location on the parameter panel. The coordinates of the widget are displayed automatically and you can modify the horizontal and vertical coordinates to adjust the widget location. |
Widget Size | Size of the widget. It can be adjusted by changing its width and height. If the size is adjusted by dragging, the height and width are automatically adjusted accordingly. |
Event
On the event setting page, you can achieve certain effects by adding events such as After Initialization, Before Editing, After Editing, After Exiting Edit, Click, and Node Generation.

After selecting an event, you can add event content. The event response methods supported by the drop-down tree widget include JavaScript, Summit to Database, Send Email, Export Event, and Mobile Pop-up.

Select the corresponding event response method.
Mobile Terminal
No configurable options on Mobile Terminal
Fuzzy Search
If you check Allow Edit on the attribute setting page, you can directly enter values when selecting values from the drop-down tree and perform fuzzy search.

For details about the fuzzy search logic, see Fuzzy Query of Drop-down Box/Drop-drop Checkbox/Drop-down Tree.
Application Example
The following table introduces application scenarios of the drop-down tree widget and corresponding documents.
Application Scenario | Effect |
Scenario: In the drop-down tree, there are region, province, and city indicators. You can achieve the simultaneous selection and query of data for multiple cities. Document: Multi-Value Query Through Drop-down Tree |  |
Scenario: There are 3 levels of data (namely region, city, and customer name) in the database. You can achieve simultaneous selection and query of all companies in the East China region and data of a specific company in Peking. |  |
Scenario: Default value can be set in the drop-down tree widget. Document: Drop-down Tree Default Value Setting |  |
Scenario: All selections by default can be set in the drop-down tree widget. |  |