LIDOR SYSTEMS

Advanced User Interface Controls and Components

Overview of IntegralUI ListBox for Angular 2

Created: 25 July 2016

IntegralUI ListBox is a native Angular 2 component that represents a list of custom HTML elements that you can reorder dynamically during run-time using drag drop operations. In following sections of this article, you will find information about general features that are included in the ListBox component.

* Icons used in this sample are provided by icons8.com

ListBox component is part of IntegralUI Studio for Web
a suite of UI Components for development of web apps

In above demo we have a list of movies represented by some general info about each movie: genre, title, rating and year when it is released. By left-click and hold of the mouse button, you can drag and drop each item from the list over other items. During this operation, an empty space will appear showing the position at which dragged item can be dropped. Animations during drag and drop are built using only CSS.

How to Use IntegralUI ListBox in Angular 2

In order to use the ListBox component in your app, you need to do the following:

  • Place the ListBox using the iui-listbox tag name
  • Set values for different properties available
  • Add the iui-listitem tag name as a child to create an item with custom HTML content
  • Use the ngFor directive to cycle through each item
  • Connect the ListBox to your data source

At first, you need to add the ListBox component in your app template. For example:

//

// app.component.ts file

//

 

import { bootstrap } from '@angular/platform-browser-dynamic';

import { Component, enableProdMode } from '@angular/core';

import { IntegralUIListItem } from './components/integralui.listitem';

import { IntegralUIListBox } from './components/integralui.listbox';

 

enableProdMode();

 

@Component({

selector: 'iui-app',

templateUrl: 'app.template.html',

directives: [IntegralUIListBox, IntegralUIListItem]

})

export class AppComponent {

// An Array object that holds all item objects shown in ListBox

// It is set as a list of any custom objects, you can use any custom fields and data bind them with ListBox using its properties

public items: Array;

 

// Initialize items in component constructor

constructor(){

this.items = [

{ id: 1, icon: "sci-fi", text: "Star Trek", year: "2009", rating: 8.0 },

{ id: 2, icon: "adventure", text: "Cast Away", year: "2000", rating: 7.7 },

{ id: 3, icon: "action", text: "Gladiator", year: "2000", rating: 8.5 },

{ id: 4, icon: "drama", text: "Malèna", year: "2000", rating: 7.5 },

{ id: 5, icon: "music", text: "Moulin Rouge", year: "2001", rating: 7.6 },

{ id: 6, icon: "comedy", text: "Snatch", year: "2000", rating: 8.3 },

{ id: 7, icon: "biography", text: "A Beautiful Mind", year: "2001", rating: 8.2 },

{ id: 8, icon: "crime", text: "Black Hawk Down", year: "2001", rating: 7.7 },

{ id: 9, icon: "western", text: "Django Unchained", year: "2012", rating: 8.5 },

{ id: 10, icon: "sci-fi", text: "Man of Steel", year: "2013", rating: 7.2 },

{ id: 11, icon: "horror", text: "The Ring", year: "2002", rating: 7.1 },

{ id: 12, icon: "romance", text: "40 Days and 40 Nights", year: "2002", rating: 5.6 },

{ id: 13, icon: "sci-fi", text: "Minority Report", year: "2002", rating: 7.7 },

{ id: 14, icon: "comedy", text: "Scary Movie 3", year: "2003", rating: 5.5 },

{ id: 15, icon: "music", text: "Walk the Line", year: "2005", rating: 7.9 },

{ id: 16, icon: "romance", text: "How to Lose a Guy in 10 Days", year: "2003", rating: 6.4 },

{ id: 17, icon: "crime", text: "The Dark Knight", year: "2008", rating: 9.0 },

{ id: 18, icon: "horror", text: "American Psycho", year: "2000", rating: 7.6 },

{ id: 19, icon: "drama", text: "The Grand Budapest Hotel", year: "2014", rating: 8.1 },

{ id: 20, icon: "comedy", text: "The Wolf of Wall Street", year: "2013", rating: 8.2 }

];

}

 

// Get an image that corresponds with the rating

getRating(value){

let stars = Math.floor(value / 2);

return "../resources/stars-small-" + stars + ".png";

}

}

 

bootstrap(AppComponent);

//

// app.template.html file

//

 

<iui-listbox #listbox [items]="items">

<iui-listitem *ngFor="let item of items">

<span class="icons {{item.icon}}"></span>

<span class="title">{{item.text}}</span>

<span class="year">{{item.year}}</span>

<img src="{{getRating(item.rating)}}" />

</iui-listitem>

</iui-listbox>

/*

listbox-overview.css file

*/

 

.iui-listbox

{

width: 500px !important;

}

.iui-listitem .iui-item

{

padding: 3px;

margin: 1px 0;

}

.iui-listitem .iui-item-label

{

display: none;

}

.iui-listitem .iui-item-hovered

{

background: #f5f5f5 !important;

border-color: #e5e5e5 !important;

}

.iui-listitem .iui-item-selected

{

background-color: #e9e9e9 !important;

border-color: #d9d9d9 !important;

color: black !important;

}

.title

{

display: inline-block;

width: 42%;

}

.year

{

display: inline-block;

text-align: center;

width: 30%;

}

img

{

display: inline-block;

text-align: center;

vertical-align: middle;

}

.icons

{

background: url(../resources/movie-genres.png) no-repeat 0 0;

display: inline-block;

padding: 0;

margin: 3px;

width: 24px;

height: 24px;

vertical-align: middle;

}

.action

{

background-position: 0 0;

}

.adventure

{

background-position: -24px 0;

}

.comedy

{

background-position: -48px 0;

}

.action

{

background-position: -72px 0;

}

.sci-fi

{

background-position: -120px 0;

}

.biography

{

background-position: 0 -24px;

}

.horror

{

background-position: -24px -24px;

}

.drama

{

background-position: -48px -24px;

}

.music

{

background-position: -72px -24px;

}

.romance

{

background-position: -96px -24px;

}

.western

{

background-position: -120px -24px;

}

For items, you can create any custom content using different HTML elements or other Angular components. In our example, item contains three <span> elements and one <img> element, all set to appear inline. In this way, each item will show an image and different information about a movie.

Note If you want to show some item with different content then other items, you can use the directive and set condition by which a different content will appear.

Using data binding, different values will be displayed for each item, based on object field values set in your application code.

In cases where you want to handle events for items, you can do it by using standard Angular event handlers, like (click) event.

You can create different kinds of custom content in the ListBox component. For example, you can create a list box where each item has a checkbox on left and a button on the right side with an editable label in between.

Supported Properties

All properties of the ListBox component can be set using a separate attribute that is linked to an object in your application scope or a specified value.

Here is a list of available properties:

  • dataFields - specifies an object that map the fields names from data source to the ones used by the ListBox
  • items - holds a reference to the list of items defined in your application component
  • options - holds an object that defines all properties of the ListBox
  • selectedItem - an object that points to the currently selected item

By specifying the selectedItem property, you can set an item that will appear as selected during initialization. This property value will change whenever an item is selected either by user click or through code.

Data Binding in ListBox

For advanced settings, for example when we have a custom data source which may differ from internal data settings of the list box, we can use data binding which will match the names of data fields in your data source with those used by the list box.

By specifying the items property to point to your data object, along with dataFields property that holds an object that maps the names of fields in the data object, you can populate the ListBox using any kind of custom data source.

This feature is also usable when you need to populate the ListBox dynamically on demand, by loading additional items from a remote data source when required.

Supported Events

Most of actions in ListBox are accompanied by events. For example, whenever an item is selected, the selection events are thrown, or when an item is added or removed, add or remove events are fired, etc.

Here is a list of available events:

  • afterSelect - occurs after item is selected
  • beforeSelect - occurs before item is selected
  • clear - occurs when all items are removed from the ListBox
  • dragDrop - occurs when item is dropped over target item or empty space
  • dragEnter - occurs when dragged item enters the ListBox space
  • dragLeave - occurs when dragged item leaves the ListBox space
  • dragOver - occurs when item is dragged
  • itemAdded - occurs when item is added to the ListBox
  • itemAdding - occurs before item is added
  • itemClick - occurs when item is clicked
  • itemDblClick - occurs when item is double-clicked
  • itemRemoved - occurs when item is removed from the ListBox
  • itemRemoving - occurs before item is removed
  • selectionChanged - occurs when currently selected item has changed

How to Add/Remove Items Dynamically

In some cases, you may need to add new items or remove existing items in the ListBox during run-time. For this purpose, there are built-in methods available that allow you to change the structure of the ListBox:

//

// app.component.ts file

//

 

export class AppComponent {

// An Array object that holds all item objects shown in ListBox

// It is set as a list of any custom objects, you can use any custom fields and data bind them with ListBox using its properties

public data: Array;

 

// Get a reference to the ListBox component using a variable set in HTML

@ViewChild('listbox') listbox: IntegralUIListBox;

 

// Initialize items in component constructor

constructor(){

this.data = [];

}

 

// Adds a new item to the end of the ListBox

addItem(){

this.listbox.addItem({ text: "Item " + (this.data.length+1).toString() });

}

 

// Fired whenever a new item is added to the ListBox

itemAddedEvent(e){

if (e.item)

console.log("itemAdded: " + e.item.text);

}

}

 

bootstrap(AppComponent);

//

// app.template.html file

//

 

<iui-listbox #listbox [items]="data" (itemAdded)="itemAddedEvent($event)">

<iui-listitem *ngFor="let item of items" [text]="{{item.text}}"></iui-listitem>

</iui-listbox>

In above code, we are adding a new item using the addItem method. To access this method, at first we need to get a reference to the ListBox component. In HTML we are adding the #listbox variable, which is used to locate the ListBox within your application component.

After we have a reference to the ListBox component, we can get access to all public methods available:

  • addItem - inserts a new item at the end of ListBox
  • clearItems - removes all items from the ListBox
  • insertItemAfter - inserts a new item in a position after specified item
  • insertItemBefore - inserts a new item in a position before specified item
  • insertItemAt - inserts a new item at specified position
  • removeItem - removes the specified item from the ListBox

How to Customize the ListBox Appearance

Apart from adding custom content to the ListBox, each part it is fully customizable. Various CSS classes manage the appearance of each part in the ListBox. By changing the attributes of these classes on your code, you can modify the list box in total, and make it more suitable for your application requirements.

ListBox appearance can be changed using a set of CSS classes for all parts, or a specific class for a specific part. For example, you can create a list box where even/odd items appear in different color.

Conclusion

This is a brief introduction to the IntegralUI ListBox for Angular 2, showing mainly drag drop functionality. Currently this component is in BETA. The more advanced features are in work like: context menus, tooltips, drag drop events, custom appearance, etc, which will be available as part of the initial release.

The ListBox component will be part of IntegralUI Studio for Web. Here you can check out different features of existing components.

Did you Like this Article?


Enter your e-mail address below and you will receive latest articles as well as news on upcoming events and special offers.