Overview of IntegralUI ListScroller for Angular

Created: 20 April 2018

IntegralUI ListScroller is a native Angular component that displays a scrollable item list in horizontal or vertical layout. Only one item is selectable at time that appears at center of the component. In this article, you will find detailed information on what features are included in the List Scroller component.

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

The above demo shows a list scroller component where items are positioned horizontally, displaying an icon. Using arrow buttons, you can navigate among the lists and select specific items. Selected item displays an icon and a title on bottom. By clicking on the check box, you can enable/disable the component.

You can also navigate between items in the list scroller using the mouse-wheel.

How to Use IntegralUI ListScroller in Angular

To use the List Scroller component you need to do the following:

• In app template place the List Scroller component using the iui-listrscroller tag name
• Set values for different properties available
• Use the ngTemplate to create the content for each item, selected and normal
• Connect the component to your data source using the items property

The items property accepts an array of objects that contain data related to each item. The item object can contain any custom fields, which you can use them to display data in the item template. In this example, we will use an icon and title on bottom for selected item only.

The bottom title appears outside the List Scroller component, and its value changes whenever selection changes. For this purpose a variable selectedItem is used to hold a reference to current selection and a handler for selectionChanged event is created.

• Angular
• HTML
• CSS

public ctrlStyle: any = {
    item: {
        general: { 
            normal: 'lscrl-ovw-item-normal',
            hovered: 'lscrl-ovw-item-hovered',
            selected: 'lscrl-ovw-item-selected'
        }
    }
}

public items: Array = [];

public listEnabled: boolean = true;
public selectedItem: any = null;

constructor(){
    this.items = [
        { id: 1, icon: "sci-fi", text: "Sci-Fi" },
        { id: 2, icon: "adventure", text: "Adventure",  },
        { id: 3, icon: "action", text: "Action " },
        { id: 4, icon: "drama", text: "Drama" },
        { id: 5, icon: "music", text: "Music" },
        { id: 6, icon: "comedy", text: "Comedy"  },
        { id: 7, icon: "biography", text: "Biography"  },
        { id: 8, icon: "crime", text: "Crime" },
        { id: 9, icon: "western", text: "Western"  },
        { id: 10, icon: "horror", text: "Horror" },
        { id: 11, icon: "romance", text: "Romance" }
    ];
}

onSelectionChanged(e: any){
    this.selectedItem = e.item;
}
                            

<div class="lscrl-ovw-container">
    <label><input type="checkbox" [(ngModel)]="listEnabled" style="margin-bottom:20px">Movies</label>
    <iui-listscroller [controlStyle]="ctrlStyle" [enabled]="listEnabled" [items]="items" [itemSize]="{ width: 48, height: 36 }" (selectionChanged)="onSelectionChanged($event)" #listscroll>
        <ng-template let-item>
            <div align="center">
                <div class="lscrl-ovw-icons {{item.icon}}"></div>
            </div>
        </ng-template>
    </iui-listscroller>
    <div align="center" *ngIf="selectedItem" style="margin-top:10px">{{selectedItem.text}}</div>
</div>
                            

/* General Settings */
.lscrl-ovw-container
{
    width: 275px;
}
.lscrl-ovw-item-normal
{
    opacity: 0.5;
}
.lscrl-ovw-item-hovered, .lscrl-ovw-item-selected
{
    opacity: 1;
}

/* Item Icons */
.lscrl-ovw-icons
{
    background: url(app/integralui/resources/movie-genres.png) no-repeat 0 0;
    display: inline-block;
    padding: 0;
    margin: 3px 0;
    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;
}                         
                            

Once the data and template for each item is created, you can start using the List Scroller component.

Supported Properties

You can use the following properties to change the appearance and behavior of the List Scroller component:

• controlStyle - specifies an object that contains all style settings for the component
• data - specifies an object that holds data related to the component
• enabled - determines whether the component is enabled or disabled
• items - holds a reference to the list of items defined in your application component
• itemSize - determines the width and height if the item in pixels
• name - uniquely identifies the component
• scrollMode - specifies whether the view is scrolled horizontally or vertically
• selectedItem - an object that points to the currently selected item
• state - specifies the component state: disabled, hovered, etc.

Using the above properties, you can modify the List Scroller component and make it appear and function in a way best suited for your application.

Supported Events

Here is a list of available events:

• afterSelect - occurs after item is selected
• beforeSelect - occurs before item is selected
• change - occurs when item order changes during sorting
• clear - occurs when all items are removed from the ListBox
• itemAdded - occurs when new item is added to the ListBox
• itemAdding - occurs before item is added
• itemRemoved - occurs when item is removed from the ListBox
• itemRemoving - occurs before item is removed
• scrollModeChanged - occurs when scrollMode property changes
• scrollPosChanged - occurs when current scroll position changes
• selectionChanged - occurs when currently selected item has changed
• updateComplete - occurs when updating of component layout is completed

Whenever a new item is added to the list, the itemAdding followed by itemAdded events are fired. By handling these events you can intercept the add operation and if required cancel it within the itemAdding event.

In similar way, you can handle other events are add your code with custom actions. Liek in current example, when a different item is selected the bottom title is updated:

• Angular
• HTML

onSelectionChanged(e: any){
    this.selectedItem = e.item;
}
                            

<iui-listscroller (selectionChanged)="onSelectionChanged($event)" [controlStyle]="ctrlStyle" [enabled]="listEnabled" [items]="items" [itemSize]="{ width: 48, height: 36 }" #listscroll>
    <ng-template let-item>
        <div align="center">
            <div class="lscrl-ovw-icons {{item.icon}}"></div>
        </div>
    </ng-template>
</iui-listscroller>
                            

Supported Methods

Here is a list of available methods:

• addItem - adds a new item to the list
• clearItems - removes all items from the list
• cloneItem - creates a deep copy of specified item
• insertItemAt - inserts a new item a specific position in the list
• insertItemAfter - inserts a new item after specified item
• insertItemBefore - inserts a new item before specified item
• findItemById - searches the list for an item using specified id value
• findItemByText - searches the list for an item using specified text value
• refresh - updates the appearance of the component
• removeItem - removes an item from the list
• removeItemAt - removes an item at specified position from the list
• resumeLayout - resumes and updates the component layout
• sort - sorts the items in ascending or descending order
• suspendLayout - suspends any change to the component layout
• updateLayout - updates the component layout
• updateView - updates the list

Using these methods, you can modify the structure of the List Scroller component from code.

How to Customize the List Scroller Appearance

Several CSS classes govern the appearance of the List Scroller component, located at the component css file. You can override these classes with your own, by adding new class names to the controlStyle property and set these classes in the CSS of your application. You only need to provide classes only for those parts of the component that you want to modify.

In addition, each item has a template where you can add any HTML element or other Angular components and arrange them in custom layouts. For example, instead of displaying only text or icon, each item can have a check box, buttons or any other element.

Conclusion

IntegralUI List Scroller component allows you to display scrollable item list in your Angular applications. You can use this component to present current selection in clear way to the user while allowing navigation between different list items. Using this component you can create multiple horizontal lists aligned vertically, which will allow selection of different items from different lists.

The List Scroller component is part of IntegralUI Web.