Skip to content

Commit

Permalink
Merge branch 'main' of https://github.com/mar10/wunderbaum
Browse files Browse the repository at this point in the history
  • Loading branch information
@mar10
mar10 committed Jun 22, 2024
2 parents 468e857 + 6c1d857 commit 9a302d5
Show file tree
Hide file tree
Showing 4 changed files with 272 additions and 252 deletions.
26 changes: 14 additions & 12 deletions docs/_sidebar.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,21 +5,23 @@
- User Guide
- [Quick start](tutorial/quick_start)
- [Initialization](tutorial/tutorial_initialize)
- [Events](tutorial/tutorial_events)
- [Render](tutorial/tutorial_render)
- [Styling](tutorial/tutorial_styling)
- [Grid](tutorial/tutorial_grid)
- [Edit](tutorial/tutorial_edit)
- [API](tutorial/tutorial_api)
- [Drag'n'Drop](tutorial/tutorial_dnd)
- [Filter](tutorial/tutorial_filter)
- [Keyboard](tutorial/tutorial_keyboard)
- [Select](tutorial/tutorial_select)
- [Data Formats](tutorial/tutorial_source)
- Features
- [Render](tutorial/tutorial_render)
- [Styling](tutorial/tutorial_styling)
- [Grid](tutorial/tutorial_grid)
- [Edit](tutorial/tutorial_edit)
- [Drag'n'Drop](tutorial/tutorial_dnd)
- [Select](tutorial/tutorial_select)
- [Events](tutorial/tutorial_events)
- [Filter](tutorial/tutorial_filter)
- [Keyboard](tutorial/tutorial_keyboard)
- [API](tutorial/tutorial_api)
- [Concepts](tutorial/concepts)
- [Migration](tutorial/migrate)
- [Contribute](tutorial/contribute)
- [API Reference](https://mar10.github.io/wunderbaum/api/index.html ":ignore")
- [Online Demo](https://mar10.github.io/wunderbaum/demo/)
- [Code Reference](https://mar10.github.io/wunderbaum/api/index.html ":ignore")
- [Online Demos](https://mar10.github.io/wunderbaum/demo/)
- [Changelog](https://github.com/mar10/wunderbaum/blob/main/CHANGELOG.md)

<!-- - [GitHub Project](https://github.com/mar10/wunderbaum) -->
55 changes: 33 additions & 22 deletions docs/tutorial/quick_start.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,6 @@ A Wunderbaum control is added to a web page by defining a `<div>` tag and
then create a new _Wunderbaum_ class instance, passing the tag and configuration
options.

<kbd>index.html</kbd>:

```html
<!DOCTYPE html>
<html>
Expand All @@ -25,10 +23,41 @@ options.
/>
<script
defer
src="ttps://cdn.jsdelivr.net/npm/wunderbaum@0/dist/wunderbaum.umd.min.js"
src="https://cdn.jsdelivr.net/npm/wunderbaum@0/dist/wunderbaum.umd.min.js"
></script>
<!-- Your application code -->
<script defer src="main.js"></script>
<script>
data = [
{
"title": "Node 1",
"expanded": true,
"children": [
{
"title": "Node 1.1"
},
{
"title": "Node 1.2"
}
]
},
{
"title": "Node 2",
}
]
document.addEventListener("DOMContentLoaded", (event) => {
const tree = new mar10.Wunderbaum({
element: document.getElementById("demo-tree"),
source: data,
init: (e) => {
e.tree.setFocus();
},
activate: (e) => {
alert(`Thank you for activating ${e.node}.`);
},
});
});
</script>
</head>

<body>
Expand All @@ -42,24 +71,6 @@ options.
</html>
```

Once the page is loaded, initialize the tree control:

<kbd>main.js</kbd>:

```js
document.addEventListener("DOMContentLoaded", (event) => {
const tree = new mar10.Wunderbaum({
element: document.getElementById("demo-tree"),
source: "get/root/nodes",
init: (e) => {
e.tree.setFocus();
},
activate: (e) => {
alert(`Thank you for activating ${e.node}.`);
},
});
});
```

ESM modules are also supported:

Expand Down
223 changes: 5 additions & 218 deletions docs/tutorial/tutorial_initialize.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -132,7 +132,10 @@ and more.
?> Event Handlers are described in detail in the [Events chapter](/tutorial/tutorial_events.md).
## Source Format and API
## Data Source
?> See examples of JSON data and learn more in the next section, [Data Formats](/tutorial/tutorial_source.md)
Typically we load the tree nodes in a separate Ajax request like so:
Expand Down Expand Up @@ -177,222 +180,6 @@ Note that
converted to `&lt;script&gt;...`, which is rendered by the browser as
`<script>...`, but not interpreted as HTML element.
### Nested List Format
All node are transferred as a list of top-level nodes, with optional nested
lists of child nodes.
```js
[
{
title: "Books",
expanded: true,
children: [
{
title: "Art of War",
author: "Sun Tzu",
},
{
title: "The Hobbit",
author: "J.R.R. Tolkien",
},
],
},
{
title: "Music",
children: [
{
title: "Nevermind",
author: "Nirvana",
},
],
},
];
```
### Object Format
This is the most commonly used format. Here we pass an object that contains
one `children` element, but also additional information.
```js
{
"types": {...},
"columns": [...],
"_keyMap": {...},
"children": [
{
"title": "Books",
"expanded": true,
"children": [
{
"title": "Art of War",
"author": "Sun Tzu"
},
]
},
...
]
}
```
### Type Information
A tree often contains multiple nodes that share attributes.
We can extract type information to a separate block, in order to make the
data model more concise:
```js
{
"types": {
"folder": { "icon": "bi bi-folder", "classes": "bold-style" },
"book": { "icon": "bi bi-book" },
"music": { "icon": "bi bi-disk" }
},
"children": [
{
"title": "Books",
"type": "folder",
"expanded": true,
"children": [
{
"title": "Art of War",
"type": "book",
"author": "Sun Tzu"
},
...
]
},
{
"title": "Music",
"type": "folder",
"children": [
{
"title": "Nevermind",
"type": "music",
"author": "Nirvana"
}
]
}
]
}
```
Type definitions can also be passed directly to the tree constructor:
```js
const tree = new mar10.Wunderbaum({
id: "demo",
element: document.getElementById("demo-tree"),
source: "get/root/nodes",
types: {
folder: { icon: "bi bi-folder", classes: "bold-style" },
book: { icon: "bi bi-book" },
music: { icon: "bi bi-disk" }
},
...
```
### Compact Formats
Load time of data is an important aspect of the user experience. <br>
We can reduce the size of the JSON data by eliminating redundancy:
- Remove whitespace from the JSON (the listings in this chapter are formatted
for readability).
- Don't pass default values, e.g. `expanded: false` is not required.
- Use `node.type` declarations, to extract shared properties (see above).
```js
{
"_format": "nested",
"types": {"person": {...}, ...},
"children": [
{"title": "Node 1", "key": "id123", "type": "folder", "expanded": true, "children": [
{"title": "Node 1.1", "key": "id234", "type": "person"},
{"title": "Node 1.2", "key": "id345", "type": "person", "age": 32}
]}
]
}
```
The example above can still be optimized:
- Pass `1` instead of `true` and `0` instead of `false`
(or don't pass it at all if it is the default).
- Use `_keyMap` and shorten the key names, e.g. send `{"t": "foo"}` instead of
`{"title": "foo"}` (see below).
- Use a `_valueMap` to define a global list of potential string values for a distinct property type. Nodes can then pass a numeric index instead of the string, which will save space.
!> The syntax of `_keyMap` and `_valueMap` has changed with v0.7.0.
```js
{
"_format": "nested", // Optional
"types": {"person": {...}, ...},
"columns": [...],
// Map from short key to final key (if a key is not found here it will
// be used literally):
"_keyMap": {"title": "t", "key": "k", "type": "y", "children": "c", "expanded": "e"},
// Optional: if a 'type' entry has a numeric value, use it as index into this
// list (string values are still used literally):
"_valueMap": {
"type": ["folder", "person"]
},
"children": [
{"t": "Node 1", "k": "id123", "y": 0, "e": 1, "c": [
{"t": "Node 1.1", "k": "id234", "y": 1},
{"t": "Node 1.2", "k": "id345", "y": 1, "age": 32}
]}
]
}
```
### Flat, Parent-Referencing List
The flat format is even a few percent smaller than the nested format.
It may also be more apropropriate for sending patches for existing trees, since
parent keys can be passed.
Here all nodes are passed as a flat list, without nesting. <br>
A node entry has the following structure:
`[PARENT_ID, [POSITIONAL_ARGS]]`<br>
or <br>
`[PARENT_ID, [POSITIONAL_ARGS], {KEY_VALUE_ARGS}]`
`PARENT_ID` is either a string that references an existing `node.key`
or the numeric the index of a node that appeared before in the list.
`POSITIONAL_ARGS` define property values in the order defined by `_positional`.
`KEY_VALUE_ARGS` define other properties as key/value pairs (optional).
```js
{
"_format": "flat",
"types": {...}, // Optional, but likely if `_valueMap` is used
"columns": [...], // Optional
// Map from short key to final key (if a key is not found here it will
// be used literally):
"_keyMap": {"expanded": "e"},
// Values for these keys are appended as list items.
// Other items - if any - are collected into one dict that is also appended:
"_positional": ["title", "key", "type"],
// Optional: if a 'type' entry has a numeric value, use it as index into this
// list (string values are still used literally):
"_valueMap": {
"type": ["folder", "person"]
},
// List index is 0-based, parent index null means 'top-node'.
// If parent index is a string, parent is searched by `node.key` (slower)
"children": [
[0, "Node 1", "id123", 0, {"e": true}], // index=0
[1, "Node 1.1", "id234", 1], // index=1
[1, "Node 1.2", "id345", 1, {"age": 32}] // index=2
]
}
```
### Handling External Data Formats
Expand All @@ -415,4 +202,4 @@ const tree = new Wunderbaum({
});
},
});
```
```
Loading

0 comments on commit 9a302d5

Please sign in to comment.