Skip to content

Commit f12f6d7

Browse files
author
Cleverson Nascimento
committed
New contextMenuBuilder api to help users build the menu with ease.
Several additions: * Issues: - Templarian#22 Adding a context menu class name to dropdown: Class ng-bootstrap-contextmenu is now appended to the holding div; * Pull Requests - Templarian#17 Added a event for opening: Added event for opening, after open and after closed; - Templarian#21 Allow icons (as HTML) in menu item: Not as html, but the new builder api handles the icon submission; - Templarian#25 Added support for item text promise: The text is now wrapped inside a $q.when function.
1 parent b71da75 commit f12f6d7

File tree

2 files changed

+493
-87
lines changed

2 files changed

+493
-87
lines changed

‎README.md

+283-41
Original file line numberDiff line numberDiff line change
@@ -28,55 +28,256 @@ $scope.items = [
2828
{ name: 'Joe', otherProperty: 'Bar' }
2929
};
3030

31-
$scope.menuOptions = [
32-
['Select', function ($itemScope) {
33-
$scope.selected = $itemScope.item.name;
34-
}],
35-
null, // Dividier
36-
['Remove', function ($itemScope) {
37-
$scope.items.splice($itemScope.$index, 1);
38-
}]
39-
];
31+
var builder = contextMenuBuilder();
32+
builder.newMenuItem('Select', function ($itemScope) {
33+
$scope.selected = $itemScope.item.name;
34+
});
35+
builder.addSeparator();
36+
builder.newMenuItem('Remove', function ($itemScope) {
37+
$scope.items.splice($itemScope.$index, 1);
38+
});
39+
40+
$scope.menuOptions = builder;
4041
```
4142

4243
## Menu Options
4344

44-
Every menu option has an array with 2-3 indexs. Most items will use the `[String, Function]` format. If you need a dynamic item in your context menu you can also use the `[Function, Function]` format.
45+
A menu options model can be a `contextMenuBuilder`, an `Array`, or a `Function` returning one of those.
46+
An empty `contextMenuBuilder` or `Array` will not display a context menu.
4547

46-
The third optional index is a function used to enable/disable the item. If the functtion returns true, the item is enabled (default). If no function is provided, the item will be enabled by default.
47-
48-
```js
49-
$scope.menuOptions = [
50-
[function ($itemScope, $event) {
51-
return $itemScope.item.name;
52-
}, function ($itemScope, $event) {
53-
// Action
54-
}, function($itemScope, $event) {
55-
// Enable or Disable
56-
return true; // enabled = true, disabled = false
57-
}]
58-
];
59-
```
60-
61-
The menuOptions can also be defined as a function returning an array. An empty array will not display a context menu.
48+
### Menu Options as `Function`
6249

6350
```html
6451
<div ng-repeat="item in items" context-menu="menuOptions(item)">Right Click: {{item.name}}</div>
6552
```
6653

54+
Returning an `Array`:
6755
```js
6856
$scope.menuOptions = function (item) {
6957
if (item.name == 'John') { return []; }
70-
return [
71-
[function ($itemScope) {
58+
return [{
59+
text: function ($itemScope) {
7260
return $itemScope.item.name;
73-
}, function ($itemScope) {
61+
},
62+
click: function ($itemScope) {
7463
// Action
75-
}]
76-
];
64+
}
65+
}];
7766
};
7867
```
7968

69+
Returning a `contextMenuBuilder`:
70+
```js
71+
$scope.menuOptions = function (item) {
72+
var builder = contextMenuBuilder();
73+
if (item.name != 'John') {
74+
builder.newMenuItem(function ($itemScope) {
75+
return $itemScope.item.name;
76+
},
77+
function ($itemScope) {
78+
// Action
79+
});
80+
}
81+
return builder;
82+
};
83+
```
84+
85+
### Menu Options as `Array`
86+
87+
Using an `Array` to build your options, every item is an object with the properties below.
88+
To add a separator, leave the item as `null`;
89+
90+
```js
91+
[{
92+
text: "item name",
93+
icon: "icon class",
94+
enabled: true,
95+
click: function($itemScope, $event, $model){}
96+
},
97+
...
98+
]
99+
```
100+
101+
The properties definitions are:
102+
103+
Property | Type | Details
104+
---------|------|--------
105+
text | `String`, `Function`, `Promise` | The text property will define the text that will appear for the menu item. If `String`, the literal will be put in the item. If `Function`, the function will be called with params `$itemScope`, `$event`, `$model`. The result of it will be put in the item. If `Promise`, the resolve of the promise will be put in the item.
106+
icon (optional) | `String`, `Function` | The icon property is the class that will be appended to `<i>` in the menu item. If this property is not present, no icon will be inserted. If `String`, the literal will be added as class. If `Function`, the function will be called with params `$itemScope`, `$event`, `$model`. The result of it will be added as class.
107+
enabled (optional) | `Boolean`, `Function` | The enabled property will define if the item will be clickable or disabled. Defaults to `true`. If `Boolean`, the item will ALWAYS be enabled (when true) or disabled (when false). If `Function`, the function will be called with params `$itemScope`, `$event`, `$model`. The `Boolean` result of it will determine if the item is clickable or not.
108+
click | `Function` | The click property is the action that will be called when the item is clicked. The function will be called with params `$itemScope`, `$event`, `$model`.
109+
110+
### Menu Options as `contextMenuBuilder`
111+
112+
Using a builder to construct your context menu is the recommended approach.
113+
114+
#### `contextMenuBuilder`
115+
116+
The `contextMenuBuilder` has the following methods:
117+
118+
##### newMenuItem([text],[fnAction]);
119+
120+
Create and add a new item to the context menu at the current position.
121+
122+
Param | Type | Details
123+
------|------|--------
124+
text (optional) | `String`, `Function`, `Promise` | The text param will define the text that will appear for the menu item. If `String`, the literal will be put in the item. If `Function`, the function will be called with params `$itemScope`, `$event`, `$model`. The result of it will be put in the item. If `Promise`, the resolve of the promise will be put in the item.
125+
fnAction (optional) | `Function` | The fnAction param is the action that will be called when the item is clicked. The function will be called with params `$itemScope`, `$event`, `$model`.
126+
127+
###### Returns
128+
129+
`contextMenuItem` The return is an instance of a `contextMenuItem` containing functions to help setup the item.
130+
131+
##### newMenuItemAt(index, [text],[fnAction]);
132+
133+
Create and add a new item to the context menu at the given position.
134+
135+
Param | Type | Details
136+
------|------|--------
137+
index | `Number` | The index to insert the new menu item at.
138+
text (optional) | `String`, `Function`, `Promise` | The `text` param will define the text that will appear for the menu item. If `String`, the literal will be put in the item. If `Function`, the function will be called with params `$itemScope`, `$event`, `$model`. The result of it will be put in the item. If `Promise`, the resolve of the promise will be put in the item.
139+
fnAction (optional) | `Function` | The fnAction param is the action that will be called when the item is clicked. The function will be called with params `$itemScope`, `$event`, `$model`.
140+
141+
###### Returns
142+
143+
`contextMenuItem` The return is an instance of a `contextMenuItem` containing functions to help setup the item.
144+
145+
##### addSeparator();
146+
147+
Add a separator to the context menu at the current position.
148+
149+
##### addSeparatorAt(index);
150+
151+
Add a separator to the context menu at the given position.
152+
153+
Param | Type | Details
154+
------|------|--------
155+
index | `Number` | The index to insert the separator at.
156+
157+
##### removeLast();
158+
159+
Remove the last menu item.
160+
161+
##### removeAt(index);
162+
163+
Remove the menu item at the given position.
164+
165+
Param | Type | Details
166+
------|------|--------
167+
index | `Number` | The index to remove the item from
168+
169+
##### clear();
170+
171+
Remove all menu items.
172+
173+
#### `contextMenuItem`
174+
175+
The `contextMenuItem` is an object that holds the whole item definition and contains various functions to help you set it up.
176+
It contains the followig properties and methods:
177+
178+
Property | Type | Details
179+
---------|------|--------
180+
text | `String`, `Function`, `Promise` | The text property will define the text that will appear for the menu item. If `String`, the literal will be put in the item. If `Function`, the function will be called with params `$itemScope`, `$event`, `$model`. The result of it will be put in the item. If `Promise`, the resolve of the promise will be put in the item.
181+
icon | `String`, `Function` | The icon property is the class that will be appended to `<i>` in the menu item. If this property is left undefined, no icon will be inserted. If `String`, the literal will be added as class. If `Function`, the function will be called with params `$itemScope`, `$event`, `$model`. The result of it will be added as class.
182+
enabled | `Boolean`, `Function` | The enabled property will define if the item will be clickable or disabled. Defaults to `true`. If `Boolean`, the item will ALWAYS be enabled (when true) or disabled (when false). If `Function`, the function will be called with params `$itemScope`, `$event`, `$model`. The `Boolean` result of it will determine if the item is clickable or not.
183+
click | `Function` | The click property is the action that will be called when the item is clicked. The function will be called with params `$itemScope`, `$event`, `$model`.
184+
185+
##### setText(text)
186+
187+
Set the text property of the menu item.
188+
189+
Param | Type | Details
190+
------|------|--------
191+
text | `String`, `Function`, `Promise` | If `String`, the literal will be put in the item. If `Function`, the function will be called with params `$itemScope`, `$event`, `$model`. The result of it will be put in the item. If `Promise`, the resolve of the promise will be put in the item.
192+
193+
###### Returns
194+
195+
`contextMenuItem` Returns the self instance to enable chain calls.
196+
197+
##### setTextFunction(fn)
198+
199+
Wrapper for the `setText` function that accepts only function.
200+
201+
Param | Type | Details
202+
------|------|--------
203+
fn | `Function` | The function will be called with params `$itemScope`, `$event`, `$model`. The result of it will be put in the item.
204+
205+
###### Returns
206+
207+
`contextMenuItem` Returns the self instance to enable chain calls.
208+
209+
##### setTextPromise(promise)
210+
211+
Wrapper for the `setText` function that accepts only promises.
212+
213+
Param | Type | Details
214+
------|------|--------
215+
promise | `Promise` | The resolve of the promise will be put in the item.
216+
217+
###### Returns
218+
219+
`contextMenuItem` Returns the self instance to enable chain calls.
220+
221+
##### setIcon(icon)
222+
223+
Set the icon property of the menu item.
224+
225+
Param | Type | Details
226+
------|------|--------
227+
icon | `String`, `Function` | If `String`, the literal will be added as class. If `Function`, the function will be called with params `$itemScope`, `$event`, `$model`. The result of it will be added as class.
228+
229+
###### Returns
230+
231+
`contextMenuItem` Returns the self instance to enable chain calls.
232+
233+
##### setIconFunction(fn)
234+
235+
Wrapper for the `setIcon` function that accepts only functions.
236+
237+
Param | Type | Details
238+
------|------|--------
239+
icon | `Function` | The function will be called with params `$itemScope`, `$event`, `$model`. The result of it will be added as class.
240+
241+
###### Returns
242+
243+
`contextMenuItem` Returns the self instance to enable chain calls.
244+
245+
##### setEnabled(enabled)
246+
247+
Set the enabled property of the menu item.
248+
249+
Param | Type | Details
250+
------|------|--------
251+
enabled | `Boolean`, `Function` | If `Boolean`, the item will ALWAYS be enabled (when true) or disabled (when false). If `Function`, the function will be called with params `$itemScope`, `$event`, `$model`. The `Boolean` result of it will determine if the item is clickable or not.
252+
253+
###### Returns
254+
255+
`contextMenuItem` Returns the self instance to enable chain calls.
256+
257+
##### setEnabledFunction(fn)
258+
259+
Wrapper for the `setEnabled` function that accepts only functions.
260+
261+
Param | Type | Details
262+
------|------|--------
263+
enabled | `Function` | The function will be called with params `$itemScope`, `$event`, `$model`. The `Boolean` result of it will determine if the item is clickable or not.
264+
265+
###### Returns
266+
267+
`contextMenuItem` Returns the self instance to enable chain calls.
268+
269+
##### setClick(fn)
270+
271+
Set the click property of the menu item.
272+
273+
Param | Type | Details
274+
------|------|--------
275+
click | `Function` | The function will be called with params `$itemScope`, `$event`, `$model`.
276+
277+
###### Returns
278+
279+
`contextMenuItem` Returns the self instance to enable chain calls.
280+
80281
## Model Attribute (optional)
81282

82283
In instances where a reference is not passed through the `$itemScope` (i.e. not using `ngRepeat`), there is a `model` attribute that can pass a value.
@@ -88,21 +289,62 @@ In instances where a reference is not passed through the `$itemScope` (i.e. not
88289
The `model` is evaluated as an expression using `$scope.$eval` and passed as the third argument.
89290

90291
```js
91-
$scope.menuOptions = [
92-
[function ($itemScope, $event, model) {
93-
return $itemScope.item.name;
94-
}, function ($itemScope, $event, model) {
95-
// Action
96-
}, function($itemScope, $event, model) {
97-
// Enable or Disable
292+
var builder = contextMenuBuilder();
293+
builder.newMenuItem(function ($itemScope, $event, $model) {
294+
return $itemScope.item.name;
295+
},
296+
function ($itemScope, $event, $model) {
297+
// Action
298+
})
299+
.setEnabled(function($itemScope, $event, text, $model){
300+
// Enable or Disable
98301
return true; // enabled = true, disabled = false
99-
}]
100-
];
302+
});
303+
$scope.menuOptions = builder;
304+
```
305+
306+
## Context Menu Events
307+
308+
The context menu supports these three events:
309+
310+
Event | Details
311+
------|--------
312+
opening | This event happens before the context menu is open and it must return a `Boolean`. If the return is false, the context will not be shown.
313+
open | This event happens after the context menu is open. Its return is irrelevant.
314+
close | This event happens after the context menu is closed. Its return is irrelevant.
315+
316+
### Adding handlers
317+
318+
To handle any of these events, add a tag with the same name to the context menu tag.
319+
320+
```html
321+
<div>
322+
<div ng-repeat="item in items" context-menu="menuOptions" opening="willOpen(item)" open="onOpen(item)" close="onClose(item)">Right Click: {{item.name}}</div>
323+
</div>
324+
```
325+
326+
The expression on the events will be evaluated using `$scope.$eval`.
327+
328+
```js
329+
$scope.willOpen = function(item) {
330+
//Do something
331+
return true; // true will show the context, false will not
332+
};
333+
334+
$scope.onOpen = function(item) {
335+
//Do something
336+
};
337+
338+
$scope.onClose = function(item) {
339+
//Do something
340+
};
101341
```
102342

103343
## Style Overlay
104344

105-
To give a light darker disabled tint while the menu is open add the style below.
345+
The `<div>` holding the menu item list is decorated with the class `ng-bootstrap-contextmenu`.
346+
347+
Also to give a light darker disabled tint while the menu is open add the style below.
106348

107349
```css
108350
body > .dropdown {

0 commit comments

Comments
 (0)