Advanced User Interface Controls and Components
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.
If you have any questions, don't hesitate to contact us at support@lidorsystems.com
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.
In order to use the ListBar component in your app, you need to do the following:
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/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<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" }
]
}
];
}
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.
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:
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.
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.
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:
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.
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:
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.
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.
The ListBar component is part of IntegralUI Web.