Overview of IntegralUI ListBox for Angular

IntegralUI ListBox is a native Angular 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.

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

If you have any questions, don't hesitate to contact us at support@lidorsystems.com

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.

You can change the movie rating by mouse left-click and move over the Rating component.

How to Use IntegralUI ListBox in Angular

To use the ListBox component 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:

public items: Array;

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 },

        // . . . 
        // 
        // The full data set is available at https://stackblitz.com/edit/integralui-listbox-overview
        //
        
    ];
}
                            
<iui-listbox [items]="items">
    <iui-listitem *ngFor="let item of items">  
        <!-- Place Item Content Here -->
    </iui-listitem>
</iui-listbox>
                            

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

public listStyle: any = {
    general: {
        normal: 'lbox-ovw-normal'
    }
}

public itemStyle: any = {
    general: {
        normal: 'lbox-ovw-item-normal'
    }
}

public lboxOverviewRatingStyleStars: any = {
    general: { normal: 'lbox-ovw-rating' },
    content: { normal: 'lbox-ovw-rating-stars-content'}
}

getRating(value: any){
    return Math.floor(value / 2);
}
                            
<iui-listbox [items]="items" [controlStyle]="listStyle" #listbox>
    <iui-listitem *ngFor="let item of items" [controlStyle]="itemStyle"> 
        <div class="lbox-ovw-item-content">
            <span class="lbox-ovw-icons {{item.icon}}"></span>
            <span class="lbox-ovw-title">{{item.text}}</span>
            <span class="lbox-ovw-year">{{item.year}}</span>
            <iui-rating [controlStyle]="lboxOverviewRatingStyleStars" [value]="getRating(item.rating)" [max]="5"></iui-rating>
        </div>
    </iui-listitem>
</iui-listbox> 
                            
.lbox-ovw-normal
{
    width: 500px;
    height: 400px;
}
.lbox-ovw-item-content
{
    padding: 3px;
    margin: 1px 0;
}
.lbox-ovw-item-normal .iui-item-hovered
{
    background: #f5f5f5 !important;
    border-color: #e5e5e5 !important;
}
.lbox-ovw-item-normal .iui-item-selected
{
    background-color: #e9e9e9 !important;
    border-color: #d9d9d9 !important;
    color: black !important;
}
.lbox-ovw-title
{
    display: inline-block;
    margin-left: 5px;
    overflow: hidden;
    text-overflow: ellipsis;
    vertical-align: middle;
    white-space: nowrap;
    width: 40%;
}
.lbox-ovw-year
{
    display: inline-block;
    text-align: center;
    width: 30%;
}
.lbox-ovw-normal img
{
    display: inline-block;
    text-align: center;
    vertical-align: middle;
}     
.lbox-ovw-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;
}
.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;
}
.lbox-ovw-rating
{
    background: transparent;
    border: 0;
    cursor: pointer;
    display: inline-block;
    margin: auto;
}
.lbox-ovw-rating
{
    display: inline-block;
    vertical-align: middle;
}
.lbox-ovw-rating-stars-content
{
    background-image: url(resources/rating/star-empty-white.png);
}
                            

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

Using data binding, different values are 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.

IntegralUI ListBox - Properties, Events and Methods

A detailed list of each property, event and method is available here: ListBox online help.

Data Binding in ListBox

For advanced settings, for example when you have a custom data source which may differ from internal data settings of the list box, you 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. By using the loadData method, you can accomplish this and change the layout of the list box on the fly.

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:

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

// . . . 

// 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', { static: false }) listbox: IntegralUIListBox;
 

// Initialize data set 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);
}
                            
<iui-listbox [items]="data" (itemAdded)="itemAddedEvent($event)" #listbox>
    <iui-listitem *ngFor="let item of data">  
       {{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

Drag and Drop in Angular ListBox

If drag and drop is enabled, you can reorder one or more items in ListBox component. This process is accompanied with events that you can handle in your code and provide conditions and addition custom functionality.

A detailed information is available here: Overview of Drag and Drop in Angular ListBox

ListBox Multi Selection

By default, you can select only one item the ListBox. To enable selection of multiple items, set the selectionMode property to either MultiSimple or MultiExtended value. This allows you to select multiple items using mouse and CTRL or SHIFT keys.

You can find more information here: Selection Options in ListBox Component.

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.

Furthermore, you can add your own CSS classes and override the default ones within your application code. For this purpose, the controlStyle property is used, which holds an object with names of CSS classes for each control part. By changing this object value, you can add the names of new classes and replace the default ones.

dialogStyle = {
    general: {
        disabled: 'iui-listbox-disabled',
        focused: 'iui-listbox-focused',
        normal: 'iui-listbox',
        hovered: 'iui-listbox-hovered',
        selected: 'iui-listbox-selected'
    },
    item: {
        general: {
            disabled: 'iui-listitem-disabled',
            focused: 'iui-listitem-focused',
            normal: 'iui-listitem',
            hovered: 'iui-listitem-hovered',
            selected: 'iui-listitem-selected'
        },
        content: {
            disabled: 'iui-listitem-content-disabled',
            focused: 'iui-listitem-content-focused',
            normal: 'iui-listitem-content',
            hovered: 'iui-listitem-content-hovered',
            selected: 'iui-listitem-content-selected'
        }
    }
}
                    

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

IntegralUI ListBox component allows you to present list of custom elements and arrange them dynamically using advanced drag drop operations.

Using item templates, you can add any custom HTML elements or Angular components, like icons, checkboxes, editors etc. To customize the ListBox appearance, you can override the default CSS classes with your own or choose a different theme.

The ListBox component is part of IntegralUI Web.

Newsletter


Sign-up to our newsletter and you will receive news on upcoming events, latest articles, samples and special offers.
Name: Email: *
*By checking this box, I agree to receive a newsletter from Lidor Systems in accordance with the Privacy Policy. I understand that I can unsubscribe from these communications at any time by clicking on the unsubscribe link in all emails.