NavigationBar

Namespace: Wisej.Web.Ext.NavigationBar

Assembly: Wisej.Web.Ext.NavigationBar (4.1.0.0)

Control
- ScrollableControl
  - Panel
    - FlexLayoutPanel
      - NavigationBar

Represents a responsive vertical navigation bar that displays an application header with logo, child items, and a user panel with gravatar and other user information.

C#
VB.NET

public class NavigationBar : FlexLayoutPanel, IWisejDesignTarget

Public Class NavigationBar
    Inherits FlexLayoutPanel
    Implements IWisejDesignTarget

Items are NavigationBarItem instances added to the Items collection; each item can contain child items in its own Items collection. When CompactView is true, the bar shrinks to show only the icons and the child items of a top-level item are displayed in a popup NavigationBarMenu.

Example:

Building a navigation bar in code and reacting to item clicks:

var navBar = new NavigationBar
{
    Dock = DockStyle.Left,
    Text = "My Application",
    Logo = "Images/logo.svg",
    UserName = "Jane Doe",
    UserStatus = "Online",
    UserStatusColor = Color.LimeGreen
};
navBar.UserAvatar = navBar.GetGravatarUrl("jane.doe@example.com");

navBar.Items.Add("dashboard", "Dashboard", "Images/dashboard.svg");
navBar.Items.Add("reports", "Reports", "icon-file");
navBar.Items["reports"].Items.Add("sales", "Sales");
navBar.Items["reports"].Items.Add("inventory", "Inventory");

navBar.ItemClick += (s, e) => AlertBox.Show("Clicked: " + e.Item.Text);
this.Controls.Add(navBar);

Constructors

NavigationBar()

Initializes a new instance of NavigationBar.

Properties

CompactView

Boolean: Returns or sets the compact view mode. (Default: False)

When set to true, the title, user name and user information are hidden, the width of the NavigationBar is reduced to fit the logo (the current width is saved), the avatar is resized to the size of the logo and all top-level items are collapsed. While in compact view, the width cannot be changed, items show their text as a tooltip, and expanding a top-level item with child items shows its children in a popup NavigationBarMenu instead. When set back to false, the saved width and avatar size are restored and the parents of the SelectedItem are expanded. Fires the CompactViewChanged event.

Example:

Toggling the compact view when the user clicks the title, and switching it automatically on small screens:

private void navigationBar1_TitleClick(object sender, EventArgs e)
{
    this.navigationBar1.CompactView = !this.navigationBar1.CompactView;
}

private void Page1_Resize(object sender, EventArgs e)
{
    this.navigationBar1.CompactView = this.Width < 800;
}

EnableKeyboardNavigation

Boolean: Returns or sets whether the user can change the SelectedItem using the keyboard. (Default: False)

When enabled, the NavigationBar becomes focusable and handles these keys: Up and Down move to the previous or next visible item; Right selects the first child item; Left selects the parent item; Home and End select the first and last top-level item; Space and Enter toggle Expanded; "+" expands and "-" collapses the selected item. Keyboard navigation changes the SelectedItem without firing the ItemClick event.

Indentation

Int32: Returns or sets the indentation in pixels for child items. (Default: 0)

The value is multiplied by the nesting level of each child item and applied as the left margin of the child item's icon: with an indentation of 16, first-level children are indented by 16 pixels, second-level children by 32 pixels, and so on. Top-level items are not indented.

ItemHeight

Int32: Returns or sets the height of the child NavigationBarItem elements. (Default: 45)

The height, in pixels, is applied to the header of all the items at every level, including items added later.

Throws:

ArgumentOutOfRangeException The value is less than 0 or greater than 32000.

Items

NavigationBarItemCollection: Returns the collection of items to display in the NavigationBar.

This collection contains only the top-level items. Child items are added to the Items collection of their parent item.

Example:

Creating a two-level menu:

var customers = new NavigationBarItem { Name = "customers", Text = "Customers", Icon = "Images/customers.svg" };
customers.Items.Add("customerList", "All Customers");
customers.Items.Add("customerNew", "New Customer");

this.navigationBar1.Items.Add(customers);
this.navigationBar1.Items.Add("settings", "Settings", "Images/settings.svg");

Logo

String: Returns or sets the logo to display in the title. (Default: "")

The value can be a URL, a relative path to an image file, or the name of a theme icon. The logo remains visible in CompactView and its size determines the width of the compact NavigationBar.

SelectedItem

NavigationBarItem: Returns or sets the selected item.

The item can be at any level (top-level or child item) but it must belong to this NavigationBar. Setting this property updates Selected on the previous and new item, expands all the parent items of the new item (unless CompactView is true) and fires the SelectedItemChanged event. It doesn't fire the ItemClick event. Clicking an item sets this property automatically after the ItemClick event. Set it to null to clear the selection.

Throws:

ArgumentException The NavigationBarItem doesn't belong to this NavigationBar.

Example:

Selecting a child item in code, which also expands its parent:

this.navigationBar1.SelectedItem = this.navigationBar1.Items["reports"].Items["sales"];

private void navigationBar1_SelectedItemChanged(object sender, EventArgs e)
{
    var item = this.navigationBar1.SelectedItem;
    if (item != null)
        this.labelTitle.Text = item.Text;
}

ShowHeader

Boolean: Returns or sets whether the header panel is visible. (Default: True)

The header panel displays the Logo and the title (Text). Clicking it fires the TitleClick event.

ShowUser

Boolean: Returns or sets whether the user panel is visible. (Default: True)

The user panel displays UserAvatar, UserName, UserStatus and UserStatusColor. Clicking it fires the UserClick event.

Text

String: Returns or sets the text to display in the title. (Default: "")

The title is displayed in the header panel next to the Logo and it's hidden when CompactView is true.

UserAvatar

String: Returns or sets the user avatar to display in the user panel.

The value can be a URL, a relative path to an image file, or the name of a theme icon. Use GetGravatarUrl to show the gravatar associated with the user's email address.

Example:

Showing the gravatar of the current user:

this.navigationBar1.UserName = "Jane Doe";
this.navigationBar1.UserAvatar = this.navigationBar1.GetGravatarUrl("jane.doe@example.com");

UserName

String: Returns or sets the user name to display in the user panel. (Default: "")

The user name is hidden when CompactView is true.

UserStatus

String: Returns or sets the status text to display in the user panel. (Default: "")

UserStatusColor

Color: Returns or sets the status color to display in the user panel. (Default: Color [Empty])

Methods

Dispose(disposing)

Clean up any resources being used.

Parameter	Type	Description
disposing	Boolean	true if managed resources should be disposed; otherwise, false.

GetGravatarUrl(email)

Returns the URL of the gravatar image associated with the specified email address.

Parameter	Type	Description
email	String	Email address for which to retrieve the gravatar URL.

Returns: String. The gravatar URL in the format https://gravatar.com/avatar/{md5 hash}.

The email address is trimmed and converted to lower case before computing its MD5 hash. The URL is computed locally and it's not validated: if the email is not registered with gravatar, the service returns its default image. This method doesn't change UserAvatar.

Throws:

ArgumentNullException email is null.

Example:

Setting the avatar of the logged-in user:

this.navigationBar1.UserAvatar = this.navigationBar1.GetGravatarUrl("jane.doe@example.com");

OnCompactViewChanged(e)

Fires the CompactViewChanged event.

Parameter	Type	Description
e	EventArgs	Not used.

OnItemClick(e)

Fires the ItemClick event.

Parameter	Type	Description
e	NavigationBarItemClickEventArgs	A NavigationBarItemClickEventArgs containing the event data.

OnItemInfoClick(e)

Fires the ItemInfoClick event.

Parameter	Type	Description
e	NavigationBarItemClickEventArgs	A NavigationBarItemClickEventArgs containing the event data.

OnItemShortcutClick(e)

Fires the ItemShortcutClick event.

Parameter	Type	Description
e	NavigationBarItemClickEventArgs	A NavigationBarItemClickEventArgs containing the event data.

OnSelectedItemChanged(e)

Fires the SelectedItemChanged event.

Parameter	Type	Description
e	EventArgs	Not used.

OnTitleClick(e)

Fires the TitleClick event.

Parameter	Type	Description
e	EventArgs	Not used.

OnUserClick(e)

Fires the UserClick event.

Parameter	Type	Description
e	EventArgs	Not used.

SetBoundsCore(x, y, width, height, specified)

Parameter	Type	Description
x	Int32
y	Int32
width	Int32
height	Int32
specified	BoundsSpecified

Events

CompactViewChanged

EventHandler Fired when the value of the property CompactView changes.

SelectedItemChanged

EventHandler Fired when the value of the property SelectedItem changes.

TitleClick

EventHandler Fired when the user clicks the title header.

UserClick

EventHandler Fired when the user clicks the user information panel.

Implements

Name	Description
IWisejDesignTarget
IUserData
IBindableComponent
IDropTarget
IImage
IWisejComponent
IWisejControl
IWisejSerializable

Constructors​

NavigationBar()​

Properties​

CompactView​

EnableKeyboardNavigation​

Indentation​

ItemHeight​

Items​

Logo​

SelectedItem​

ShowHeader​

ShowUser​

Text​

UserAvatar​

UserName​

UserStatus​

UserStatusColor​

Methods​

Dispose(disposing)​

GetGravatarUrl(email)​

OnCompactViewChanged(e)​

OnItemClick(e)​

OnItemInfoClick(e)​

OnItemShortcutClick(e)​

OnSelectedItemChanged(e)​

OnTitleClick(e)​

OnUserClick(e)​

SetBoundsCore(x, y, width, height, specified)​

Events​

CompactViewChanged​

ItemClick​

ItemInfoClick​

ItemShortcutClick​

SelectedItemChanged​

TitleClick​

UserClick​

Implements​

Constructors

NavigationBar()

Properties

CompactView

EnableKeyboardNavigation

Indentation

ItemHeight

Items

Logo

SelectedItem

ShowHeader

ShowUser

Text

UserAvatar

UserName

UserStatus

UserStatusColor

Methods

Dispose(disposing)

GetGravatarUrl(email)

OnCompactViewChanged(e)

OnItemClick(e)

OnItemInfoClick(e)

OnItemShortcutClick(e)

OnSelectedItemChanged(e)

OnTitleClick(e)

OnUserClick(e)

SetBoundsCore(x, y, width, height, specified)

Events

CompactViewChanged

ItemClick

ItemInfoClick

ItemShortcutClick

SelectedItemChanged

TitleClick

UserClick

Implements