8000 [CHORE] Update readme · SortableJS/ember-sortablejs@61dcc26 · GitHub
[go: up one dir, main page]
Skip to content 8000

Commit 61dcc26

Browse files
lvegeranolvegerano
committed
[CHORE] Update readme
1 parent a2abb4c commit 61dcc26

File tree

1 file changed

+78
-51
lines changed

1 file changed

+78
-51
lines changed

‎README.md

Lines changed: 78 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -5,82 +5,109 @@ ember-sortablejs
55

66
This addon allows you to use drag and drop in your ember application using [SortableJS/Sortable](https://github.com/SortableJS/Sortable)
77

8-
98
Compatibility
109
------------------------------------------------------------------------------
1110

1211
* Ember.js v3.13 or above
1312
* Ember CLI v3.13 or above
14-
* Node.js v8 or above
15-
13+
* Node.js v10 or above
1614

1715
Installation
1816
------------------------------------------------------------------------------
19-
17+
> **NOTE**: The beta version is out. Please give me a hand and test it out.
2018
```
21-
ember install ember-sortablejs
19+
ember install ember-sortablejs@beta
2220
```
2321

22+
This addon has a peer dependency on `sortablejs` that will be installed with the addon
23+
24+
Still to do
25+
------------------------------------------------------------------------------
26+
Refer to the upcoming [project](https://github.com/SortableJS/ember-sortablejs/projects/2)
27+
28+
Library support
29+
------------------------------------------------------------------------------
30+
Currently supported:
31+
- [x] Drag from one list to another
32+
- [x] Sort
33+
- [x] Clone
34+
- [ ] Swap
35+
- [ ] Multi Drag
36+
- [ ] Nested List
2437

2538
Usage
2639
------------------------------------------------------------------------------
2740

28-
```html
41+
```hbs
2942
<SortableJs
43+
@items={{array "one" "two" "three" "four" "five"}}
3044
@options={{hash animation=150 ghostClass="ghost-class" group="shared-list"}}
31-
@onChoose={{fn this.onChoose}}
32-
@onUnchoose={{fn this.onUnchoose}}
33-
@onStart={{fn this.onStart}}
34-
@onEnd={{fn this.onEnd}}
35-
@onAdd={{fn this.onAdd}}
36-
@onUpdate={{fn this.onUpdate}}
37-
@onRemove={{fn this.onRemove}}
38-
@onMove={{fn this.onMove}}
39-
@onClone={{fn this.onClone}}
40-
@onChange={{fn this.onChange}}
41-
as |sortable|
45+
@onStart={{this.onStart}}
46+
@onEnd={{this.onEnd}}
47+
as |list|
4248
>
43-
<div class="list-group-item bg-yellow">Item 1</div>
44-
<div class="list-group-item bg-yellow">Item 2</div>
45-
<div class="list-group-item bg-yellow">Item 3</div>
46-
<div class="list-group-item bg-yellow">Item 4</div>
47-
<div class="list-group-item bg-yellow">Item 5</div>
49+
{{#each list as |item|}}
50+
<div class="list-group-item bg-yellow">{{item.value}}</div>
51+
{{/each}}
4852
</SortableJs>
4953
```
5054

55+
How it works
56+
------------------------------------------------------------------------------
57+
SortableJs works by manipulating the DOM directly this is very compatible with
58+
the Glimmer VM. To mitigate this we need tu use SortableJs as a middle and use
59+
the events it emits to update state and prevent the DOM manipulation the lib does.
60+
61+
This is accomplished by maintaining an internal list. This list is a copy of the
62+
array supplied via `@items`. The events `onStart`, `onEnd`, `onUpdate`, `onAdd`,
63+
`onRemove` are intercepted to prevent DOM manipulation and maintaining the internal
64+
list.
65+
66+
I you have ideas on how to approach this better. Please open an issue 😄
67+
68+
Caveats
69+
------------------------------------------------------------------------------
70+
- Not SortableJS plugins work.
71+
- While you could bypass `@items` I highly discourage since the library manipulates the DOM directly.
72+
5173
Options
5274
------------------------------------------------------------------------------
5375
The addon supports all the options that sortable accepts, see: https://github.com/SortableJS/Sortable#options
5476

55-
The events:
56-
- `onChoose`
57-
- `onUnchoose`
58-
- `onStart`
59-
- `onEnd`
60-
- `onAdd`
61-
- `onUpdate`
62-
- `onSort`
63-
- `onRemove`
64-
- `onMove`
65-
- `onClone`
66-
- `onChange`
67-
- `scrollFn`
68-
- `setData`
69-
- `onFilter`
70-
- `onSpill`
71-
72-
Should be in the component signature as closure actions.
73-
All actions get the events as described in the SortableJS docs as well as the sortable instance.
74-
```js
75-
onChoose(evt, sortable) {...}
76-
```
77+
Component API
78+
------------------------------------------------------------------------------
79+
|arg|type|description|
80+
|:---|:---:|:---|
81+
| `@items`| Array | A list of the items to be managed by the addon|
82+
| `@onChoose` | Function | (SortablejsEvent) => {...}
83+
| `@onUnchoose` | Function | (SortablejsEvent) => {...}
84+
| `@onStart` | Function | (SortablejsEvent) => {...}
85+
| `@onEnd` | Function | (SortablejsEvent, cancelDnD) => {...}
86+
| `@onAdd` | Function | (SortablejsEvent) => {...}
87+
| `@onUpdate` | Function | (SortablejsEvent) => {...}
88+
| `@onSort` | Function | (SortablejsEvent) => {...}
89+
| `@onRemove` | Function | (SortablejsEvent) => {...}
90+
| `@onMove` | Function | (SortablejsMoveEvent) => {...}
91+
| `@onClone` | Function | (SortablejsEvent) => {...}
92+
| `@onChange` | Function | (SortablejsEvent) => {...}
93+
| `@scrollFn` | Function | (SortablejsEvent) => {...}
94+
| `@setData` | Function | (SortablejsEvent) => {...}
95+
| `@onFilter` | Function | (SortablejsEvent) => {...}
96+
| `@onSpill` | Function | (SortablejsEvent) => {...}
97+
98+
`SortablejsEvent` - A [`CustomEvent`](https://github.com/SortableJS/Sortable#event-object-demo) provided by SortableJS
99+
100+
`SortablejsMoveEvent` - A [`CustomEvent`](https://github.com/SortableJS/Sortable#move-event-object) provided by SortableJS
101+
102+
`cancelDnD` - A callback provided by the ember addon to basically undo you last drag and drop or sort;
103+
77104
Migrating from 1.x
78105
------------------------------------------------------------------------------
79106
- `onSetData` is no longer suported. Rename argument to `setData`.
80107
- `<SortableJs>` no longer expects a wrapped list. Instead the addon itself will act as the sortable list container.
81108

82109
v1
83-
```html
110+
```hbs
84111
<SortableJs
85112
@options={{hash animation=150 ghostClass="ghost-class" group="shared-list"}}
86113
>
@@ -95,16 +122,16 @@ v1
95122
```
96123

97124
v2
98-
```html
125+
```hbs
99126
<SortableJs
100127
class="list-group"
128+
@items={{array "Item 1" "Item 2" "Item 3" "Item 4" "Item 5"}}
101129
@options={{hash animation=150 ghostClass="ghost-class" group="shared-list"}}
130+
as |list|
102131
>
103-
<div class="list-group-item">Item 1</div>
104-
<div class="list-group-item">Item 2</div>
105-
<div class="list-group-item">Item 3</div>
106-
<div class="list-group-item">Item 4</div>
107-
<div class="list-group-item">Item 5</div>
132+
{{#each list as |item|}}
133+
<div class="list-group-item">Item 1</div>
134+
{{/each}}
108135
</SortableJs>
109136
```
110137
License

0 commit comments

Comments
 (0)
0