Overview of IntegralUI ListBar for Angular 2

Created: 18 August 2016

Updated: 24 March 2017

IntegralUI ListBar is a native Angular 2 component that displays a list of expandable groups, in 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.

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:

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

publicgroups: Array<any>;

// 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" }

]

}

];

}

privateitemStyle = {

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:

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.

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:

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

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.