LIDOR SYSTEMS

Advanced User Interface Controls and Components

Overview of IntegralUI ListBar for Angular 2

Created: 18 August 2016

Updated: 21 December 2016

IntegralUI ListBar is a native Angular 2 component that displays a list of expandable groups, in horizontal or vertical layout. Each group contains a list of items created using custom HTML elements or Angular 2 components. When the current view cannot display all groups in whole, scroll buttons will appear on each side that will allow you to navigate among groups.

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

Above demonstration shows several groups with different number of items. Each group can expand/collapse, but only one group can become selected. Whenever more groups are expanded and they overflow the ListBar current view, a set of scroll buttons will appear on top and bottom side. By pressing these buttons, you can scroll the current view and navigate among presented groups.

How to Use IntegralUI ListBar in Angular 2

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

  • Place the ListBar using the iui-listbar tag name
  • Create a loop of ListGroup components using the iui-listgroup tag name
  • Add items using the iui-item tag name to each group
  • Add custom HTML elements as item content
  • Connect the ListBar to your data source

At first, you need to place the ListBar component in your application template. As a content, ListBar accepts any ListGroup component. In this case, because there are multiple groups in sample data source, we are using the ngFor directive to create a loop:

//

// main.ts file

//

 

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

import { AppModule } from './app.module';

 

const platform = platformBrowserDynamic();

platform.bootstrapModule(AppModule);

 

 

 

//

// app.module.ts file

//

 

import { NgModule } from '@angular/core';

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

import { AppComponent } from './app.component';

import { IntegralUIModule } from 'integralui-web/integralui.module';

 

@NgModule({

imports: [ BrowserModule, IntegralUIModule ],

declarations: [ AppComponent ],

bootstrap: [ AppComponent ]

})

export class AppModule { }

 

 

 

//

// app.component.ts file

//

 

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

 

@Component({

selector: 'iui-app',

templateUrl: 'app.template.html',

styleUrls: ['listbar-overview.css'],

encapsulation: ViewEncapsulation.None

})

export class AppComponent {

// An Array object that holds all group objects shown in ListBar

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

public groups: Array;

 

// Initialize groups in component constructor

constructor(){

this.groups = [

{

id: 1,

text: "Common Controls",

expanded: false,

items: [

{ id: 11, pid: 1, text: "Button" },

{ id: 12, pid: 1, text: "CheckBox" },

{ id: 13, pid: 1, text: "ComboBox" },

{ id: 14, pid: 1, text: "DateTime Picker" },

{ id: 15, pid: 1, text: "Label" },

{ id: 16, pid: 1, text: "ProgressBar" },

{ id: 17, pid: 1, text: "TextBox" }

]

},

{

id: 2,

text: "Containers",

items: [

{ id: 21, pid: 2, text: "GroupBox" },

{ id: 22, pid: 2, text: "Panel" },

{ id: 23, pid: 2, text: "SplitContainer" },

{ id: 24, pid: 2, text: "TabControl" }

]

},

{

id: 3,

text: "Menus & Toolbars",

items: [

{ id: 31, pid: 3, text: "ContextMenu" },

{ id: 32, pid: 3, text: "Menu" },

{ id: 33, pid: 3, text: "ToolStrip" }

]

},

{

id: 4,

text: "Data",

expanded: false,

items: [

{ id: 41, pid: 4, text: "DataGrid" },

{ id: 42, pid: 4, text: "DataSet" },

{ id: 43, pid: 4, text: "ReportViewer" }

]

},

{

id: 5,

text: "Dialogs",

expanded: false,

items: [

{ id: 51, pid: 5, text: "ColorDialog" },

{ id: 52, pid: 5, text: "FontDialog" }

]

},

{

id: 6,

text: "Printing",

expanded: false,

items: [

{ id: 61, pid: 6, text: "PrintDialog" },

{ id: 62, pid: 6, text: "PrintDocument" }

]

},

{

id: 7,

text: "IntegralUI",

items: [

{ id: 71, pid: 7, text: "Accordion" },

{ id: 72, pid: 7, text: "CheckBox" },

{ id: 73, pid: 7, text: "ComboBox" },

{ id: 74, pid: 7, text: "ContextMenu" },

{ id: 75, pid: 7, text: "Menu" },

{ id: 76, pid: 7, text: "SlideBar" },

{ id: 77, pid: 7, text: "TabStrip" },

{ id: 78, pid: 7, text: "TreeGrid" },

{ id: 79, pid: 7, text: "TreeView" }

]

}

];

}

 

private itemStyle = {

general: {

normal: 'item',

hovered: 'item-hovered',

selected: 'item-selected'

}

}

}

 

bootstrap(AppComponent);

//

// app.template.html file

//

 

<iui-listbar [groups]="groups">

<iui-listgroup *ngFor="let group of groups" [text]="group.text" [items]="group.items" [headerAnimation]="'arrow'">

<iui-item *ngFor="let item of group.items" [controlStyle]="itemStyle">

<span>{{item.text}}</span>

</iui-item>

</iui-listgroup>

</iui-listbar>

/*

listbar-overview.css file

*/

 

.iui-listbar

{

width: 300px;

height: 400px;

}

/* Item General */

.item

{

margin: 1px;

padding: 3px;

}

/* Item Hover State */

.item-hovered

{

background-color: #a6c9e6;

border: thin solid #97c0e1;

}

/* Item Selected State */

.item-selected

{

background-color: #428bca;

border: thin solid #357ebd;

color: white;

}

Note Although it is not required, by specifying the groups property you can use different methods like add/remove of groups dynamically through code on run-time.

Each group is represented by a header and item list. You can create custom header by specifying a template, but in this case, only a header title is shown by setting the text property. Depending on animations available, you can choose how the expand/collapse process is handled. In this example, a arrow animation is used.

Note ListGroup component is an extension of GroupBox component. It inherits all functionality available from the GroupBox and extending it further to appear more like a list. Instead acting as a container, the ListGroup shows a list of items as its content.

To create an item list, the iui-item tag is used that relates to the basic IntegralUIItem component. This component by default display an item that has an icon and label, which you can override with custom HTML elements, by simply adding custom content:

<iui-item *ngFor="let item of group.items" [controlStyle]="itemStyle">

<span>{{item.text}}</span>

</iui-item>

To keep this example simple, we are only showing a single text line for each item. However, you can add any custom HTML elements of other Angular 2 components are arrange them in custom layouts.

When you have a template ready, you need to link the data source with the ListBar using corresponding object fields. We have two loops: one will display all groups from your data source, while second loop will display all items for each group respectively.

At the end, the ListBar will show all specified groups with items from your data source. If groups cannot appear in whole, a set of scroll buttons will pop-up in the ListBar. In this way, you can scroll the current view and navigate among presented groups and their items.

Supported Properties

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

Here is a list of available properties:

  • controlStyle - specifies an object that holds names for custom CSS classes
  • dataFields - specifies an object that map the fields names from data source to the ones used by the ListBar
  • groups - holds a reference to the array of group objects defined in your application component
  • selectedGroup - an object that points to the currently selected group
  • selectedItem - an object that points to the currently selected item

By specifying the selectedGroup property, you can set a group that will appear as selected during initialization. You can also set whether a group will appear as expanded initially, by specifying the expanded field in group object in your data source.

Data Binding in ListBar

If you have a data source that uses different names for object fields, you can use dataFields property to match the names of fields in your data source with those used by the ListBar. In this way, you can populate the ListBar using any kind of custom data source. For example, you can load data on demand in the ListBar, from a remote data source.

Supported Events

When interacting with the ListBar component, depending on different action, a corresponding event is fired. For example expanding a group will fire the beforeExpand and afterExpand events, selecting a group or an item will fire beforeSelect, afterSelect and selectionChanged events, etc. Here is a list of available events:

  • afterCollapse - occurs after group is collapsed
  • afterExpand - occurs after group is expanded
  • afterSelect - occurs after group or item is selected
  • beforeCollapse - occurs before group is collapsed
  • beforeExpand - occurs before group is expanded
  • beforeSelect - occurs before group or item is selected
  • clear - occurs when all groups are removed from the Accordion
  • groupAdded - occurs when new group is added to the Accordion
  • groupAdding - occurs before group is added
  • groupClick - occurs when group header is clicked
  • groupDblClick - occurs when group header is double-clicked
  • groupRemoved - occurs when group is removed from the Accordion
  • groupRemoving - occurs before group is removed
  • scrollPosChanged - occurs when scroll position has changed
  • selectionChanged - occurs when currently selected group or item has changed

By handling these events in your code, you can add custom actions that may alter the default behavior of the ListBar component. For example, by handling the beforeExpand event, you can cancel the expansion of specified group, or set different conditions that must pass prior expanding.

How to Add/Remove Groups Dynamically

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

//

// app.component.ts file

//

 

export class AppComponent {

// An Array object that holds all group objects shown in ListBar

private data: Array;

 

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

@ViewChild('listbar') listbar: IntegralUIListBar;

 

// Initialize groups in component constructor

constructor(){

this.data = [];

}

 

// Adds a new group to the end of the ListBar

addGroup(){

this.listbar.addGroup({ text: "Group " + (this.data.length+1).toString() });

}

 

// Fired whenever a new group is added to the ListBar

groupAddedEvent(e){

if (e.group)

console.log("groupAdded: " + e.group.text);

}

}

 

bootstrap(AppComponent);

//

// app.template.html file

//

 

<iui-listbar [groups]="data" (groupAdded)="groupAddedEvent($event)" #listbar>

<iui-listgroup *ngFor="let group of groups" [text]="group.text"></iui-listgroup>

</iui-listbar>

In above code, we are adding a new group with some items using the addGroup method. To access this method, at first we need to get a reference to the ListBar component. In HTML we are adding the #listbar variable, which is used to locate the ListBar within your application component.

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

  • addGroup - inserts a new group at the end of ListBar
  • clearGroups - removes all groups from the ListBar
  • insertGroupAfter - inserts a new group in a position after specified group
  • insertGroupBefore - inserts a new group in a position before specified group
  • insertGroupAt - inserts a new group at specified position
  • removeGroup - removes the specified group from the ListBar

How to Customize the ListBar Appearance

Each part of IntegralUI ListBar component is fully customizable. There are different CSS classes for each component part. Although changing the attributes of built-in classes is possible, you can completely override them using the controlStyle property.

The controlStyle property accpets an object that holds all or partial list of CSS class names that will override the default CSS class names. For each component part, a different CSS class governs its appearance. This allows you to specify a set of different CSS classes for each component part and alter the appearance of the ListBar in whole. In this way, you can make it more suitable for your application requirements.

Conclusion

IntegralUI ListBar component represents a list of expandable groups, displayed either horizontally or vertically. Each group represents a list of items that as a content can display a single text line or custom HTML content. You can navigate among the groups using scroll buttons, which will appear as required, whenever groups overflow the current view of the ListBar component.

Currently this component is in BETA. More advanced features are in work like: context menus, tooltips, custom themes, etc, which will be available as part of the initial release.

The ListBar 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.