├── LICENSE
├── README.md
├── example
├── 1.png
├── 2.png
├── 3.png
└── example.html
└── src
├── select2totree.css
└── select2totree.js
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2017 clivezhg
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 |
This project is not maintained by the author.
2 |
3 |
4 | Select2-to-Tree
5 | =======
6 |
7 | Select2-to-Tree is an extension to Select2, a popular select boxes library: https://github.com/select2/select2.
8 |
9 | Though Select2 is very versatile, it only supports a single level of nesting. See https://select2.github.io/options.html#how-many-levels-of-nesting-are-allowed:
10 |
11 | Because Select2 falls back to an <optgroup> when creating nested options, only a single level of nesting is supported. Any additional levels of nesting is not guarenteed to be displayed properly across all browsers and devices.
12 |
13 | Select2-to-Tree extends Select2 to support arbitrary level of nesting.
14 |
15 | Select2 compatibility
16 | ---------------------
17 | * Select2 4+
18 |
19 | Browser compatibility
20 | ---------------------
21 | * IE 8+
22 | * Chrome 8+
23 | * Firefox 10+
24 | * Safari 3+
25 | * Opera 10.6+
26 |
27 | Usage
28 | -----
29 | Firstly, you need to know the usage of Select2: https://github.com/select2/select2
30 |
31 | Then, in your HTML document, you add the Select2 library (the `*.js` file & `*.css` file, currently the version should be 4.0+), and the Select2-to-Tree library (the `*.js` file & `*.css` file in the "`src`" folder). jQuery is also needed.
32 |
33 | There are 2 ways to use Select2-to-Tree:
34 |
35 |
1. Use data, and empty <select> element(see "Example 1" in "example/example.html"):
36 |
37 | Suppose your HTML is like this:
38 | ```html
39 |
41 | ```
42 | And your data:
43 | ```js
44 | var mydata = [
45 | {id:1, text:"USA", inc:[
46 | {text:"west", inc:[
47 | {id:111, text:"California", inc:[
48 | {id:1111, text:"Los Angeles", inc:[
49 | {id:11111, text:"Hollywood"}
50 | ]},
51 | {id:1112, text:"San Diego", selected:"true"}
52 | ]},
53 | {id:112, text:"Oregon"}
54 | ]}
55 | ]},
56 | {id:2, text:"India"},
57 | {id:3, text:"中国"}
58 | ];
59 | ```
60 | And you call Select2-to-Tree like the following:
61 | ```js
62 | $("#sel_1").select2ToTree({treeData: {dataArr:mydata}, maximumSelectionLength: 3});
63 | ```
64 | "`{treeData: {dataArr:mydata}`" is for Select2-to-Tree, "`maximumSelectionLength: 3`" is for Select2 (and you can set the other Select2 arguments if needed)
65 |
66 | About the data structure: "`id`" will be used as option value, "`text`" will be used as option label, and "`inc`" will be used to specify sub-level options. If your data structure is not like this, you can set arguments in "`treeData`" to change the default behavior, e.g., `treeData: {dataArr: mydata, valFld: "value", labelFld: "name", incFld: "sub"}`:
67 | - `dataArr`, an array containing the data.
68 | - `valFld`, the option value field, it's "`id`" by default. (if the value is empty, the corresponding option will be unselectable, see the "west" option in the example)
69 | - `selFld`, the selected value field, it's "`selected`" by default.
70 | - `labelFld`, the option label field, it's "`text`" by default.
71 | - `incFld`, the sub options field, it's "`inc`" by default.
72 | - `dftVal`, the default value.
73 |
74 | For `valFld` and `labelFld`, you can give a object path (eg: `item.label`. see "Example 4" in "example/example.html").
75 |
76 | The above are all the parameters supported by Select2-to-Tree.
77 |
78 |
2. directly create the <select> element(see "Example 2" in "example/example.html"):
79 |
80 | If it's hard to create the required data structure, you can directly create the <select> element. It's like the following:
81 | ```html
82 |
90 | ```
91 | - the classes `l1`,`l2`,`l3`,`l4`,`l5`..., setting the nesting level.
92 | - the attribute `data-pup`, setting the value of the parent level option.
93 | - the class `non-leaf`, setting whether the option has children or not.
94 |
95 | Then, you call Select2-to-Tree (the "`treeData`" argument of Select-to-Tree is not needed here, but you can set arguments for Select2):
96 | ```js
97 | $("#sel_2").select2ToTree();
98 | ```
99 |
100 | Styling
101 | -----
102 | Select-to-Tree uses CSS rules(in the select2totree.css file) to control the indent & size of each level, e.g.:
103 | ```
104 | .s2-to-tree .select2-results__option.l8 {
105 | margin-left: 6.0em;
106 | font-size: 0.75em;
107 | }
108 | ```
109 | By default, Select-to-Tree defines 8 levels, if you need more than 8 levels, you can add your own CSS rules.
110 | You can also change or override the pre-defined CSS rules to match your requirements.
111 |
112 | Constraints
113 | -----------
114 | - AJAX data source is not supported.
115 | - It is a little slower than plain Select2, because there are extra operations to do. Anyway, according to my test (you can check "Example 3" in "example/example.html", click the "India -> north"), 1500 options is basically acceptable, which is enough in most of the real world cases.
116 |
117 | Illustration
118 | ------------
119 | See "Example 3" in "example/example.html":
120 |
121 |
122 |
123 | Copyright and license
124 | ---------------------
125 | The license is available within the repository in the [LICENSE][license] file.
126 |
--------------------------------------------------------------------------------
/example/1.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/clivezhg/select2-to-tree/7514110fd3d8bc055450ec1609f4c7b5490c55e2/example/1.png
--------------------------------------------------------------------------------
/example/2.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/clivezhg/select2-to-tree/7514110fd3d8bc055450ec1609f4c7b5490c55e2/example/2.png
--------------------------------------------------------------------------------
/example/3.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/clivezhg/select2-to-tree/7514110fd3d8bc055450ec1609f4c7b5490c55e2/example/3.png
--------------------------------------------------------------------------------
/example/example.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 | Select2-to-Tree * example
6 |
7 |
8 |
9 |
10 |
11 |
12 |
13 |