Listview
Basic usage
angular
.module('demoApp', ['mobiscroll-listview'])
.controller('demoController', ['$scope', function ($scope) {
$scope.data = [
{ name: 'Apples' },
{ name: 'Cakes' },
{ name: 'Bottles of Juice' }
];
$scope.settings = {
stages: [
{ percent: -20, color: 'red', icon: 'remove', text: 'Remove', action: function (event, inst) {
// Remove the swiped list item
inst.remove(event.target);
return false;
} },
{ percent: 20, color: 'green', icon: 'plus', text: 'Add', action: function (event, inst) {
// Add a new list item without id
inst.add(null, 'New Item', event.index);
} }
]
};
}]);
<div ng-app="demoApp" ng-controller="demoController">
<ul mobiscroll-listview="settings" mobiscroll-data="data" style="display:none">
<li>{{item.name}}</li>
</<ul>
</<div>
Using the listview
The listview directive has to be associated with an array. The array can hold any data type. On the ui the attribute has to be applied to an unordered list. This directive will behave like the 'ng-repeat' directive, and the markup it will repeat has to be placed inside the 'ul' tag. The markup contained inside the 'ul' tag will be removed upon compile, and will be placed inside a list item tag ('li').
When using array of objects, inside the list, you can access one item with the 'item' keyword inside your expressions and you can also use the ng-repeat directives $index, $last, $first, $middle, $even and $odd special properties.
Here is another example of using the listview directive:
// inside our controller first we initialize our array
$scope.orders = [
{
orderId: 1,
itemName: 'Apples',
count: 5
},
{
orderId: 4,
itemName: 'Cakes',
count: 2
},
{
orderId: 5,
itemName: 'Bottles of Juice',
count: 3
}
];
We will also create properties for adding a new item to the list
$scope.orderId = 6; // this will be the order items id
$scope.orderItemName = 'Chocolates'; // the order items name - starting value 'chocolates'
$scope.count = 1; // how many we would like to order from a particular item
We need a function which creates a new order item and adds it to the array
$scope.addOrder = function () {
// get the id for the order
var oId = $scope.orderId;
$scope.orderId++; // increase the id every time
// ensure the count is a positive integer othervise default to 1
var oCount = parseInt($scope.count);
if (oCount == Number.NaN || oCount < 1) {
oCount = 1;
}
// add the new order to the list
$scope.orders.push({
orderId: oId ,
itemName: $scope.orderItemName,
count: oCount
});
};
After this all we have to do is to create the markup with the correct attributes
<!-- The listview initialized with the orders -->
<div>
<ul mobiscroll-listview mobiscroll-data="orders">
<li data-id="{{item.orderId}}">order #{{item.orderId}}: {{item.count + ' ' + item.itemName}}</li>
</ul>
</div>
<!-- The section for the add order -->
<div>
<label for="iName">Item Name:</label>
<input id="iName" type="text" ng-model="orderItemName" />
<br />
<label for="iCount">Item Count</label>
<input id="iCount" type="text" ng-model="count" />
<button type="button" ng-click="addOrder()">add</button>
</div>
This way when you click the add button a new item will be added to the array, and the listview will update.
Nested ng-repeats
When using additional `ng-repeat`s inside the listview, the directives should be prefixed with `mbsc-`.
<li>{{item.name}} <span mbsc-ng-repeat="star in item.stars">*</span></li>
Hierarchical listview
The listview directive is also capable of creating a hierarchical listview, based on the data provided. In the following example the listview directive will render a list of places grouped by countries and continents.
Here is the hierarchical data. Each list item can have a list of children, which are also list items.
$scope.places = [
{
name: 'North America',
children: [
{
name: 'USA',
children: [
{
name: 'Washington'
},
{
name: 'Florida'
},
{
name: 'Los Angeles'
},
{
name: 'San Francisco'
}
]
},
{
name: 'Canada',
children: [
{
name: 'Vancouver'
},
{
name: 'Winnipeg'
},
{
name: 'Calgary'
}
]
}
]
},
{
name: 'South America',
children: [
{
name: 'Argentina',
children: [
{
name: 'Buenos Aires'
},
// and so on...
];
The initialization of the hierarchical listview is the same as the simple listview.
<ul mobiscroll-data="places" mobiscroll-listview="{ swipe: false }">
<div class="place-cont">{{item.name}}</div>
</ul>
There is a live demo of the hierarchical listview here!
In the next section will be an example on how to initialize the listview with actions properly.
Actions
The same rules apply to the listviews action property. Here is an example on how to implement a remove action for the listview. This example is continued from the listview module.
// logic that is called inside angular
$scope.removeOrder = function (index) {
$scope.orders.splice(index, 1);
};
// the action which is called from mobiscroll
$scope.removeOrderAction = function (li, inst, index) {
$scope.$apply(function () { $scope.removeOrder(index); });
};
The initialization should be like this:
<ul mobiscroll-data="orders"
mobiscroll-listview="{ stages: [ { percent: -20, color: 'red', icon: 'remove', action: removeOrderAction }] }">{{item.itemName}}</ul>
Directives
To use the directives of this module you have to set a dependency in you app to 'mobiscroll-listview'. With Angular.JS version 1.0.8 there is no animation module yet, so the listviews remove animation will not be shown when removing an item from the array. The animations are available though from Angular.JS version 1.1.5, and need the animation module included to work.
For many more examples - simple and complex use-cases - check out the listview demos for angularjs.
Options
Name | Type | Default value | Description |
---|---|---|---|
actionable | boolean | true |
If set to false, hover effects on the listview items will be turned off. This option can be defined inside the itemGroups setting as well for specific items. |
actions | Array, Object | undefined |
An array or an object which defines an icon list whit different actions. If an array, the same icon list will be displayed on both left and right swipe.
An action object has the following properties:
A sample action array:
If an object, a different icon list can be defined to both sides, swipe will be allowed just for the defined side. A sample action object:
|
actionsWidth | Number | 90 |
Specifies the width in percentage of the actions container. |
animateAddRemove | Boolean | true |
If set to false, item add and remove will not be animated. |
animateIcons | Boolean | true |
If false the icon won't be animated when a list item is swiped. |
context | String, HTMLElement | 'body' |
The scrollable DOM element containing the listview. Can be a selector string or a DOM element. |
display | String | 'inline' |
Controls the position of the listview. Possible values:
|
fillAnimation | Boolean | true |
If true the sortable item will be highlighted with a fill animation. |
fixedHeader | Boolean | false |
If true, the group headers will be positioned as fixed (will stay on top, if it's scrolled out of view, until the next group header is reached). |
hover | String, Object | undefined |
On a list item mouse pointer hover shows the underlying action menu. The direction of the reveal can be specified by passing 'left' or 'right' parameter, or with the hover objects direction property. The hover object can have a time and a timeout property to define the reveal animation time and the hover start timeout in milliseconds. Sample hover object:
|
iconSlide | Boolean | false |
If true, the icon and text of an action is slided along the edge of the slided item. |
itemGroups | Object | undefined |
It can be used to define different actions and settings for a group of items. The items can be grouped using the data-type attribute of the list element.
If an item has no data-type attribute, the settings defined outside itemGroups will be used.
Markup
|
loadingIcon | String | 'loop2' |
Specifies the icon inside the loading content. |
navigateOnDrop | Boolean | false |
If the list is sortable and multiLevel flag is set, if an element is dropped on a parent element, or back button, the element will be appended to the sublist / parent list. The navigateOnDrop is true, after the element is dropped, the list will be navigated to the sub list or parent list. |
quickSwipe | Boolean | true |
If true, a quick swipe (duration is less than 300ms and movement is more than 50px) executes the action of the first stage in the swipe direction, even if the stage's percent is not reached. |
select | String | 'off' |
Defines the selection of the items. Possible values:
|
sortable | Boolean Object |
undefined |
If true, or an object the list will be sortable. By passing an object, you can set additional sort options:
|
sortDelay | Number | 200 |
Delay after tap in milliseconds until sort mode is activated on the item. |
stages | Array , Object | [] |
An array of objects which defines the different stages when swiping a list item.
Or it can be an object with 'left' and 'right' property with which different stages can be defined for both sides.
A stage object has the following properties:
See the full list of available icons here. The default icon pack contains the following icons: You can use the icons anywhere in your app using thembsc-ic mbsc-ic-{iconName} classes, e.g.:
A sample stage array:
A sample stage object:
|
striped | Boolean | false |
If true, the list items will have alternate (striped) styling. |
swipe | Boolean, String, or Function | true |
If false, swipe is not allowed. If 'left' or 'right' , swipe is allowed only in the given direction.If a function, the returned value will be used, which can be any of the above. Receives an argument object and the Listview instance as parameters. The arguments object has the following properties:
|
swipeleft | Function | undefined |
Action to execute when a list item is swiped left.
Receives an argument object and the Listview instance as parameters.
The arguments object has the following properties:
|
swiperight | Function | undefined |
Action to execute when a list item is swiped right.
Receives an argument object and the Listview instance as parameters.
The arguments object has the following properties:
|
theme | String | undefined |
Sets the visual appearance of the component.
If it is If the theme for the specific platform is not present, it will default to the Mobiscroll theme. Supplied themes:
Starting from v4.9.0 setting directly the dark version of the theme is deprecated.
Use the themeVariant option instead to control the light / dark appearance of the theme.
Make sure that the theme you set is included in the downloaded package.
|
themeVariant | String | undefined |
Controls which variant of the theme will be used (light or dark). Possible values:
If not set, only the theme setting will determine which theme to use.
To use the option with custom themes, make sure to create two custom themes,
where the dark version has the same name as the light one, suffixed with
The option will not have any effect if the theme option explicitly
sets the dark version of a theme, e.g.
theme: 'ios-dark' .
|
vibrate | Boolean | true |
Turn vibration on/off on sort start and sort end. |
Setting options dynamically
There are two ways to modify options after initalization
-
Using the option method.
The option method always triggers reinitialization. Most of the settings can be updated only this way, updating without initialization has no effect, because the markup is already generated. If the scroller was visible, the reinitialization hides it and it's not shown again automatically (except in inline display mode).
Here is an example for the dynamic option changeangular .module('demoApp', ['mobiscroll-listview']) .controller('demoController', ['$scope', function ($scope) { // Modify options $scope.changeOptions = function () { $scope.myInstance.option({ theme: 'mobiscroll', lang: 'de' }); }; }]);
The markup for the controller<div ng-app="demoApp" ng-controller="demoController"> <input mobiscroll-listview mobiscroll-instance="myInstance"/> <button ng-click="changeOptions()">Change options</button> </div>
-
Modify directly the
settings
object.
Useful when changing dynamic settings, which do not need redraw (e.g. vibrate, calendar marked days).
// Get instance and modify a setting $scope.myInstance.settings.vibrate = true; // Modify settings in an event $scope.settings = { onItemTap: function (event, inst) { inst.settings.vibrate = true; } };
Events
Name | Description | |
---|---|---|
onInit(event, inst) |
Triggered when the component is initialized.
Parameters
Example
|
|
onItemAdd(event, inst) | This event is triggered when an item is added.
Parameters
Example
|
|
onItemRemove(event, inst) | This event is triggered when an item is removed.
Parameters
Example
|
|
onItemTap(event, inst) |
Triggered when an item is tapped.
In case of parent items or back items hierarchical navigation can be prevented by returning false from this event.
Parameters
Example
|
|
onListEnd(event, inst) |
Triggered when scrolling reaches to the end of the listview.
Parameters
Example
|
|
onNavEnd(event, inst) | This event is triggered when hierarchical navigation ends.
Parameters
Example
|
|
onNavStart(event, inst) | This event is triggered when hierarchical navigation starts.
Parameters
Example
|
|
onSlideEnd(event, inst) | This event is triggered when a slide ended.
Parameters
Example
|
|
onSlideStart(event, inst) | This event is triggered when a slide started.
Parameters
Example
|
|
onSort(event, inst) |
Triggered during sorting, is being fired continuosly when the item is dragged.
Parameters
Example
|
|
onSortChange(event, inst) |
Triggered during sorting, but only when the DOM position has changed.
It also has the visual feedback that the items in the background are moving to make place for the dragged item.
Parameters
Example
|
|
onSortEnd(event, inst) |
Triggered when sorting has stopped.
Parameters
Example
|
|
onSortStart(event, inst) |
Triggered when sorting starts.
Parameters
Example
|
|
onSortUpdate(event, inst) |
Triggered when the user stopped sorting and the DOM position has changed.
Parameters
Example
|
|
onStageChange(event, inst) | This event is triggered during sliding when the stage changes.
Parameters
Example
|
Methods
Name | Parameters | Description |
---|---|---|
add(id, markup [, index ] [, callback ] [, parent ]) | Adds a new list item to the list with the given id and markup at the specified index.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods
|
|
addUndoAction(func) |
Push an undo action into the undo stack. Accepts a function as parameter. If it's called multiple times between
startActionTrack and endActionTrack calls, all actions will be added to one action group, and will be undone by one single undo call (like a transaction).
Parameters
ExampleMethods can be called on an instance. For more details see calling methods
|
|
close(item [, time ]) |
Closes the given item, if it's actions or stages are opened.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods
|
|
deselect(item) | Deselects the specified item.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods
|
|
destroy() |
Destroys the component. This will return the element back to its pre-init state.
Returns: Object
ExampleMethods can be called on an instance. For more details see calling methods
|
|
endActionTrack() | All actions between startActionTrack and endActionTrack calls will be handled as one action group, and will be undone by one single undo call (like a transaction).
ExampleMethods can be called on an instance. For more details see calling methods
|
|
getInst() |
Returns the object instance.
Returns: Object
ExampleMethods can be called on an instance. For more details see calling methods
|
|
hideLoading() |
Hides the loading content. By default the loading content is hidden.
ExampleMethods can be called on an instance. For more details see calling methods
|
|
move(item, index [, direction ][, callback ]) | Moves a list item to another position in the list.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods
|
|
navigate(item) |
Brings the specified item into view. If the listview is hierarchical and the item is not in the currently visible level, the listview will slide to the item's level.
If the listview is not currently in the viewport, the viewport will be scrolled to the item.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods
|
|
openActions(item, direction [, time ] [, demo ]) | Opens the actions of a list item.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods
|
|
openStage(item, stage [, time ] [, demo ]) | Opens the specified stage of a list item.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods
|
|
option(options) |
Sets one or more options for the component.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods
|
|
remove(item [, direction ] [, callback ]) | Removes a list item from the list.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods
|
|
select(item) |
Selects the specified item.
Parameters
ExampleMethods can be called on an instance. For more details see calling methods
|
|
showLoading() |
Shows the loading content. By default the loading content is hidden.
ExampleMethods can be called on an instance. For more details see calling methods
|
|
startActionTrack() | All actions between startActionTrack and endActionTrack calls will be handled as one action group, and will be undone by one single undo call (like a transaction).
ExampleMethods can be called on an instance. For more details see calling methods
|
|
tap(el, handler) |
Attaches the handler function to the tap event of element el .
Parameters
ExampleMethods can be called on an instance. For more details see calling methods
|
|
undo() | Last action will be undone.
ExampleMethods can be called on an instance. For more details see calling methods
|
Data attributes
Name | Description |
---|---|
data-icon |
Display an icon inside the list item. It needs a font-icon name.
Only works if the enhance option is true .
|
data-icon-align |
Specify icon alignment. It can be "left" or "right" , it defaults to "left" if not specified.
Only works if the enhance option is true .
|
data-selected | Sets the initially selected listview items. |
data-role | If the list item contains a data-role="list-divider" attribute, than that item will be displayed as a list divider. |
data-type | The items can be grouped using the data-type attribute of the list element. More about groups: itemGroups. |
Localization
Name | Type | Default value | Description |
---|---|---|---|
backText | String | 'Back' |
Text for the back button, in case of hierarchical lists. |
lang | String | 'en-US' |
Language of the component. Based on the language string the component loads the language based default settings from the
language modules.
Supported languages:
|
rtl | Boolean | false |
Right to left display. |
undoText | String | 'Undo' |
Text for the undo action. |
Customizing the appearance
While the provided pre-built themes are enough in many use cases, most of the times on top of adapting to a specific platform, you'd also like to match a brand or color scheme. Mobiscroll provides various ways to achieve this:
- Create custom themes using the theme builder - the custom themes can be also built using out theme builder, on a graphical user interface, without any coding, or the need for Sass support in your project.
- Create custom themes using Sass - use this, if you need multiple themes with different color variatons, in case you have pages with different colors, or you'd like to users to customize the colors of your app.
- Override the Sass color variables - the straightforward way to change the colors in one place throughout the application.
Override the Sass Color Variables
A convenient way to customize the colors of the Mobiscroll components is to override the Sass color variables.
Let's say your branding uses a nice red accent color, and you'd like that color to appear on the Mobiscroll components as well,
while still using platform specific themes (e.g. ios
on iOS devices, material
on Android devices, and mobiscroll
on desktop).
You can override the accent color for every theme:
$mbsc-ios-accent: #e61d2a;
$mbsc-material-accent: #e61d2a;
$mbsc-mobiscroll-accent: #e61d2a;
@import "~@mobiscroll/AngularJS/dist/css/mobiscroll.angularjs.scss"
You can also customize the colors on many levels:
- Theme specific variables (ex.
$mbsc-material-background
,$mbsc-ios-dark-text
) are applied to all components in a theme. Complete list of variables here. - Component specific global variables (ex.
$mbsc-card-background-light
,$mbsc-listview-text-dark
) are applied to all themes for a specific component. - Component and theme specific variables (ex.
$mbsc-ios-dark-form-background
,$mbsc-material-input-text
) are applied to a specific theme and a specific component.
Global variables
These variables are applied to all base themes: iOS, material, windows and mobiscroll.
They all come in pairs. One for the light and one for the dark variant in each theme.
Variable name | Description |
---|---|
$mbsc-listview-background-light | Sets the background color of the listview |
$mbsc-listview-background-dark | |
$mbsc-listview-text-light | Sets the text color of the listview |
$mbsc-listview-text-dark | |
$mbsc-listview-accent-light | Sets the accent color of the listview |
$mbsc-listview-accent-dark | |
$mbsc-listview-header-background-light | Sets the group header background color |
$mbsc-listview-header-background-dark | |
$mbsc-listview-header-text-light | Sets the group header text color |
$mbsc-listview-header-text-dark |
If you really want to get sophisticated or if a color doesn't look good on a specific theme and you want to overwrite it,
you can fine tune all of the above variables individually for each theme.
Below are the complete list of variables broken down to themes:
iOS theme
Variable name | Default value | Description |
---|---|---|
$mbsc-ios-listview-background | #ffffff | The listview background color |
$mbsc-ios-listview-text | #000000 | The listview text color |
$mbsc-ios-listview-accent | #007bff | The listview accent color |
$mbsc-ios-listview-header-background | #efeff4 | The group header background color |
$mbsc-ios-listview-header-text | #707070 | The group header text color |
iOS Dark theme
Variable name | Default value | Description |
---|---|---|
$mbsc-ios-dark-listview-background | #0f0f0f | The listview background color |
$mbsc-ios-dark-listview-text | #ffffff | The listview text color |
$mbsc-ios-dark-listview-accent | #ff8400 | The listview accent color |
$mbsc-ios-dark-listview-header-background | #1a1a1a | The group header background color |
$mbsc-ios-dark-listview-header-text | #8f8f8f | The group header text color |
Windows theme
Variable name | Default value | Description |
---|---|---|
$mbsc-windows-listview-background | #f2f2f2 | The listview background color |
$mbsc-windows-listview-text | #262626 | The listview text color |
$mbsc-windows-listview-accent | #0078d7 | The listview accent color |
$mbsc-windows-listview-header-background | #ffffff | The group header background color |
$mbsc-windows-listview-header-text | #262626 | The group header text color |
Windows Dark theme
Variable name | Default value | Description |
---|---|---|
$mbsc-windows-dark-listview-background | #191919 | The listview background color |
$mbsc-windows-dark-listview-text | #ffffff | The listview text color |
$mbsc-windows-dark-listview-accent | #0078d7 | The listview accent color |
$mbsc-windows-dark-listview-header-background | #000000 | The group header background color |
$mbsc-windows-dark-listview-header-text | #ffffff | The group header text color |
Material theme
Variable name | Default value | Description |
---|---|---|
$mbsc-material-listview-background | #eeeeee | The listview background color |
$mbsc-material-listview-text | #5b5b5b | The listview text color |
$mbsc-material-listview-accent | #000000 | The listview accent color |
$mbsc-material-listview-header-background | #eeeeee | The group header background color |
$mbsc-material-listview-header-text | #009688 | The group header text color |
Material Dark theme
Variable name | Default value | Description |
---|---|---|
$mbsc-material-dark-listview-background | #303030 | The listview background color |
$mbsc-material-dark-listview-text | #c2c2c2 | The listview text color |
$mbsc-material-dark-listview-accent | #ffffff | The listview accent color |
$mbsc-material-dark-listview-header-background | #303030 | The group header background color |
$mbsc-material-dark-listview-header-text | #81ccc4 | The group header text color |
Mobiscroll theme
Variable name | Default value | Description |
---|---|---|
$mbsc-mobiscroll-listview-background | #f7f7f7 | The listview background color |
$mbsc-mobiscroll-listview-text | #454545 | The listview text color |
$mbsc-mobiscroll-listview-accent | #4eccc4 | The listview accent color |
$mbsc-mobiscroll-listview-header-background | #f7f7f7 | The group header background color |
$mbsc-mobiscroll-listview-header-text | #4eccc4 | The group header text color |
Mobiscroll Dark theme
Variable name | Default value | Description |
---|---|---|
$mbsc-mobiscroll-dark-listview-background | #263238 | The listview background color |
$mbsc-mobiscroll-dark-listview-text | #f7f7f7 | The listview text color |
$mbsc-mobiscroll-dark-listview-accent | #4fccc4 | The listview accent color |
$mbsc-mobiscroll-dark-listview-header-background | #263238 | The group header background color |
$mbsc-mobiscroll-dark-listview-header-text | #4fccc4 | The group header text color |