RadPanelBar
The RadPanelBar control is used to display a list of items in a Web Forms page and is often used control for building collapsible side-menu interfaces. The RadPanelBar control supports the following features:
- Databinding that allows the control to be populated from various datasources
- Programmatic access to the RadPanelBar object model which allows to dynamic creation of panelbars, populate items, set properties.
- Customizable appearance through built-in or user-defined skins.
Items
The RadPanelBar control is made up of tree of items represented by RadPanelItem objects. Items at the first level (level 0) are called root items. A items that has a parent item is called a child item. All root items are stored in the Items collection. Child items are stored in a parent item's Items collection.
Each item has a Text and a Value property. The value of the Text property is displayed in the RadPanelBar control, while the Value property is used to store any additional data about the item, such as data passed to the postback event associated with the item. When clicked, a item can navigate to another Web page indicated by the NavigateUrl property.
Definition
Namespace:Telerik.Web.UI
Assembly:Telerik.Web.UI.dll
Syntax:
[EmbeddedSkin("PanelBar", typeof(RadPanelBar))]
[EmbeddedSkin("PanelBar", "Default", typeof(RadPanelBar))]
[RequiredCss("Telerik.Web.UI.Skins.Common.fonticons.css", RenderMode.Lightweight, typeof(RadPanelBar))]
[RequiredCss("Telerik.Web.UI.Skins.Common.MaterialRipple.css", RenderMode.Lightweight, typeof(RadButton))]
[RequiredScript(typeof(Core))]
[RequiredScript(typeof(jQueryPlugins))]
[ClientScriptResource("Telerik.Web.UI.RadPanelBar", "Telerik.Web.UI.PanelBar.RadPanelBarScripts.js")]
[RequiredScript(typeof(jSlide))]
[RequiredScript(typeof(TouchScrollExtender))]
[RequiredScript(typeof(MaterialRipple))]
[TelerikToolboxCategory("Navigation")]
[ToolboxBitmap(typeof(RadPanelBar), "Toolbox.Icons.PanelBar.png")]
public class RadPanelBar : HierarchicalControlItemContainer, IComponent, IDisposable, IParserAccessor, IUrlResolutionService, IDataBindingsAccessor, IControlBuilderAccessor, IControlDesignerAccessor, IExpressionsAccessor, IAttributeAccessor, IScriptControl, IControlResolver, IPostBackDataHandler, ISkinnableControl, IControl, IFeatureGroup, INamingContainer, IXmlSerializable, IControlItemContainer, IRadPanelItemContainer, IPostBackEventHandlerInheritance: objectControlWebControlBaseDataBoundControlDataBoundControlRadDataBoundControlControlItemContainerHierarchicalControlItemContainerRadPanelBar...
Implements:
Inherited Members
Constructors
Initializes a new instance of the RadPanelBar class.
public RadPanelBar()Use this constructor to create and initialize a new instance of the RadPanelBar control.
Properties
Gets or sets a value indicating whether all items can be collapsed. This allows all the items to be collapsed even if the panelbar's ExpandMode is set to SingleExpandedItem or FullExpandedItem mode.
[ClientControlProperty]
public bool AllowCollapseAllItems { get; set; }Gets the object that controls the Wai-Aria settings applied on the control's input element.
[PersistenceMode(PersistenceMode.InnerProperty)]
public WaiAriaSettings AriaSettings { get; }Gets a list of all client-side changes (adding an item, removing an item, changing an item's property) which have occurred.
[Browsable(false)]
public IList<ClientOperation<RadPanelItem>> ClientChanges { get; }A list of ClientOperation<T> objects which represent all client-side changes the user has performed. By default the ClientChanges property returns empty list. Client-changes are recorded if and only if the client-side methods trackChanges()/commitChanges() have been invoked.
You can use the ClientChanges property to respond to client-side modifications such as
- adding a new item
- removing existing item
- clearing the children of an item or the control itself
- changing a property of the item
The ClientChanges property is available in the first postback (ajax) request after the client-side modifications have taken place. After this moment the property will return empty list.
Gets the settings for the animation played when an item closes.
[PersistenceMode(PersistenceMode.InnerProperty)]
public AnimationSettings CollapseAnimation { get; }An AnimationSettings that represents the collapse animation.
Use the CollapseAnimation property to customize the expand animation of RadPanelBar. You can specify the Type, Duration and the items are collapsed.
To disable expand animation effects you should set the Type to AnimationType.None. To customize the expand animation you can use the ExpandAnimation property.
Gets or sets a value indicating the timeout after which a panel item starts to close.
[ClientControlProperty]
[ClientPropertyName("collapseDelay")]
public int CollapseDelay { get; set; }An integer specifying the timeout measured in milliseconds. The default value is 0 milliseconds.
To customize the timeout prior to item closing use the ExpandDelay property.
Specifies the name of the cookie which should be used when PersistStateInCookie is set to true.
[ClientControlProperty]
public string CookieName { get; set; }If this property is not set the ClientID property will be used as the name of the cookie.
The CssClass property will now be used instead of the former Skin and will be modified in AddAttributesToRender()
protected override string CssClassFormatString { get; }Overrides:
Gets the data bindings for panel items in the panelbar.
[PersistenceMode(PersistenceMode.InnerProperty)]
public RadPanelItemBindingCollection DataBindings { get; }The data bindings.
When set to true enables support for WAI-ARIA.
[ClientControlProperty]
[ClientPropertyName("enableAriaSupport")]
public bool EnableAriaSupport { get; set; }Gets or sets a value indicating whether RadPanelBar should HTML encode the text of its items.
[ClientControlProperty]
[ClientPropertyName("_enableItemTextHtmlEncoding")]
public bool EnableItemTextHtmlEncoding { get; set; }true if the text should be encoded; otherwise, false. The default value is
false.
Gets the settings for the animation played when an item opens.
[PersistenceMode(PersistenceMode.InnerProperty)]
public AnimationSettings ExpandAnimation { get; }An AnimationSettings that represents the expand animation.
Use the ExpandAnimation property to customize the expand animation of RadPanelBar. You can specify the Type, Duration and the To disable expand animation effects you should set the Type to AnimationType.None.
To customize the collapse animation you can use the CollapseAnimation property.
Gets or sets a value indicating the timeout after which a panel item starts to open.
[ClientControlProperty]
[ClientPropertyName("expandDelay")]
public int ExpandDelay { get; set; }An integer specifying the timeout measured in milliseconds. The default value is 0 milliseconds.
Use the ExpandDelay property to delay item opening.
To customize the timeout prior to item closing use the CollapseDelay property.
Gets of sets a value indicating the behavior of RadPanelbar when an item is expanded.
[ClientControlProperty]
public PanelBarExpandMode ExpandMode { get; set; }One of the PanelBarExpandMode values. The default value is MultipleExpandedItems.
Use the ExpandMode property to specify the way RadPanelbar should behave after an item is expanded. The available options are:
- MultipleExpandedItems (default) - More than one item can be expanded at a time.
- SingleExpandedItem - Only one item can be expanded at a time. Expanding another item collapses the previously expanded one.
- FullExpandedItem - Only one item can be expanded at a time. The expanded area occupies the entire height of the RadPanelbar. The Height property should be set in order RadPanelbar to operate correctly in this mode.
Gets a RadPanelItemCollection object that contains the root items of the current RadPanelBar control.
[PersistenceMode(PersistenceMode.InnerProperty)]
public RadPanelItemCollection Items { get; }A RadPanelItemCollection that contains the root items of the current RadPanelBar control. By default the collection is empty (RadPanelBar has no children).
Implements:
Use the Items property to access the child items of RadPanelBar. You can also use the Items property to manage the root items. You can add, remove or modify items from the Items collection.
Gets or sets the template for displaying the items in RadPanelBar.
[TemplateContainer(typeof(RadPanelItem))]
[PersistenceMode(PersistenceMode.InnerProperty)]
[Browsable(false)]
[Bindable(false)]
public ITemplate ItemTemplate { get; set; }A ITemplate implemented object that contains the template for displaying panel items. The default value is a null reference (Nothing in Visual Basic), which indicates that this property is not set.
The ItemTemplate property sets a template that will be used for all panel items.
To specify unique display for individual items use the ItemTemplate property of the RadPanelItem class.
Gets or sets the maximum number of levels to bind to the RadPanelBar control.
public override int MaxDataBindDepth { get; set; }The maximum number of levels to bind to the RadPanelBar control. The default is -1, which binds all the levels in the data source to the control.
Overrides:
When binding the RadPanelBar control to a data source, use the MaxDataBindDepth property to limit the number of levels to bind to the control. For example, setting this property to 2 binds only the root panel items and their immediate children. All remaining records in the data source are ignored.
Gets or sets a value indicating the client-side event handler that is called before the browser context panel shows (after right-clicking an item).
[ClientControlEvent]
[ClientPropertyName("contextMenu")]
public string OnClientContextMenu { get; set; }A string specifying the name of the JavaScript function that will handle the event. The default value is empty string.
Use the OnClientContextMenu property to specify a JavaScript function that will be executed before the context menu shows after right clicking an item.
Two parameters are passed to the handler
- sender (the client-side RadPanelbar object)
- eventArgs with two properties
- Item - the instance of the selected item
- EventObject - the browser DOM event
Gets or sets the name of the JavaScript function called when an item's expand/collapse animation finishes
[ClientControlEvent]
[ClientPropertyName("itemAnimationEnd")]
public string OnClientItemAnimationEnd { get; set; }Gets or sets a value indicating the client-side event handler that is called after an item loses focus.
[ClientControlEvent]
[ClientPropertyName("itemBlur")]
public string OnClientItemBlur { get; set; }A string specifying the name of the JavaScript function that will handle the event. The default value is empty string.
If specified, the OnClientItemBlur client-side event handler is called when a panel item loses focus as a result of the user pressing a key or clicking elsewhere on the page. Two parameters are passed to the handler:
- sender, the panelbar client object;
- eventArgs with one property, Item (the instance of the panel item).
This event cannot be cancelled.
Gets or sets a value indicating the client-side event handler that is called after a panel item is clicked.
[ClientControlEvent]
[ClientPropertyName("itemClicked")]
public string OnClientItemClicked { get; set; }A string specifying the name of the JavaScript function that will handle the event. The default value is empty string.
This event is similar to OnClientItemFocus but fires only on mouse click.
If specified, the OnClientItemClicked client-side event handler is called after a panel item is clicked upon. Two parameters are passed to the handler:
- sender, the panelbar client object;
- eventArgs with one property, Item (the instance of the panel item).
This event cannot be cancelled.
Gets or sets a value indicating the client-side event handler that is called when a panel item is clicked.
[ClientControlEvent]
[ClientPropertyName("itemClicking")]
public string OnClientItemClicking { get; set; }A string specifying the name of the JavaScript function that will handle the event. The default value is empty string.
This event is similar to OnClientItemFocus but fires only on mouse click.
If specified, the OnClientItemClicking client-side event handler is called before a panel item is clicked upon. Two parameters are passed to the handler:
- sender, the panelbar client object;
- eventArgs with one property, Item (the instance of the panel item).
The OnClientItemClicking event can be cancelled. To do so, return False from the event handler.
Gets or sets a value indicating the client-side event handler that is called when a group of child items collapses.
[ClientControlEvent]
[ClientPropertyName("itemCollapse")]
public string OnClientItemCollapse { get; set; }A string specifying the name of the JavaScript function that will handle the event. The default value is empty string.
If specified, the OnClientItemClose client-side event handler is called when a group of child items closes. Two parameters are passed to the handler:
- sender, the panelbar client object;
- eventArgs with one property, Item (the instance of the panel item).
This event cannot be cancelled.
Gets or sets a value indicating the client-side event handler that is called when a group of child items expands.
[ClientControlEvent]
[ClientPropertyName("itemExpand")]
public string OnClientItemExpand { get; set; }A string specifying the name of the JavaScript function that will handle the event. The default value is empty string.
Gets or sets a value indicating the client-side event handler that is called when a panel item gets focus.
[ClientControlEvent]
[ClientPropertyName("itemFocus")]
public string OnClientItemFocus { get; set; }A string specifying the name of the JavaScript function that will handle the event. The default value is empty string.
If specified, the OnClientItemFocus client-side event handler is called when a panel item is selected using either the keyboard (the [TAB] or arrow keys) or by clicking it. Two parameters are passed to the handler:
- sender, the panelbar client object;
- eventArgs with one property, Item (the instance of the panel item).
This event cannot be cancelled.
Gets or sets a value indicating the client-side event handler that is called after the RadPanelbar client-side object is initialized.
[ClientControlEvent]
[ClientPropertyName("load")]
public string OnClientLoad { get; set; }A string specifying the name of the JavaScript function that will handle the event. The default value is empty string.
If specified, the OnClienLoad client-side event handler is called after the panelbar is fully initialized on the client.
A single parameter - the panelbar client object - is passed to the handler.
This event cannot be cancelled.
Gets or sets a value indicating the client-side event handler that is called when the mouse moves out of a panel item in the RadPanelbar control.
[ClientControlEvent]
[ClientPropertyName("mouseOut")]
public string OnClientMouseOut { get; set; }A string specifying the name of the JavaScript function that will handle the event. The default value is empty string.
If specified, the OnClientMouseOut client-side event handler is called when the mouse moves out of a panel item. Two parameters are passed to the handler:
- sender, the panelbar client object;
- eventArgs with one property, Item (the instance of the panel item).
This event cannot be cancelled.
Gets or sets a value indicating the client-side event handler that is called when the mouse moves over a panel item in the RadPanelbar control.
[ClientControlEvent]
[ClientPropertyName("mouseOver")]
public string OnClientMouseOver { get; set; }A string specifying the name of the JavaScript function that will handle the event. The default value is empty string.
If specified, the OnClientMouseOverclient-side event handler is called when the mouse moves over a panel item. Two parameters are passed to the handler:
- sender, the panelbar client object;
- eventArgs with one property, Item (the instance of the panel item).
This event cannot be cancelled.
Gets or sets a value indicating whether the control would persists its state between pages (expanded and selected items).
[ClientControlProperty]
public bool PersistStateInCookie { get; set; }true if the control would persist its state; false otherwise. The default value is false.
Use the PersistStateInCookie property to make RadPanelbar persist its state between pages. This feature requires browser cookies to be enabled. Also the ClientID and ID properties of the RadPanelbar control must be the same in all pages accessible via the control (and containing it).
Page1.aspx:
<radP:RadPanelbar ID="RadPanelbar1" > ... </radP:RadPanelbar>
Page2.aspx
<radP:RadPanelbar ID="RadPanelbar1" > ... </radP:RadPanelbar>
Gets or sets the URL of the page to post to from the current page when an item from the panel is clicked.
[Themeable(false)]
public override string PostBackUrl { get; set; }The URL of the Web page to post to from the current page when an item from the panel control is clicked. The default value is an empty string (""), which causes the page to post back to itself.
Overrides:
Gets the selected panel item.
[Browsable(false)]
public RadPanelItem SelectedItem { get; }Returns the panel item which is currently selected. If no item is selected the SelectedItem property will return null (Nothing in VB.NET).
protected override bool SupportsRenderingMode { get; }Overrides:
Methods
protected override void AddAttributesToRender(HtmlTextWriter writer)Overrides:
This methods clears the selected items of the current RadPanelBar instance. Useful when you need to clear item selection after postback.
public void ClearSelectedItems()This methods collapses all expanded panel items
public void CollapseAllItems()protected override ControlItemCollection CreateChildItemCollection()Overrides:
protected override NavigationItemBindingCollection CreateDataBindings()Overrides:
protected override void DescribeClientEvents(IScriptDescriptor descriptor)Overrides:
protected override void DescribeClientProperties(IScriptDescriptor descriptor)Overrides:
protected override void DescribeComponent(IScriptDescriptor descriptor)Overrides:
Returns the first RadPanelItem that matches the conditions defined by the specified predicate. The predicate should returns a boolean value.
public RadPanelItem FindItem(Predicate<RadPanelItem> match)The Predicate <> that defines the conditions of the element to search for.
Returns:Searches the RadPanelbar control for the first RadPanelItem with a Text property equal to the specified value.
public RadPanelItem FindItemByText(string text, bool ignoreCase)The value to search for.
ignoreCaseboolA Boolean indicating a case-sensitive or insensitive comparison (true indicates a case-insensitive comparison).
Returns:A RadPanelItem whose Text property is equal to the specified value.
The method returns the first item matching the search criteria. If no item is matching then null (Nothing in VB.NET) is returned.
Searches the RadPanelbar control for the first RadPanelItem with a Text property equal to the specified value.
public RadPanelItem FindItemByText(string text)The value to search for.
Returns:A RadPanelItem whose Text property is equal to the specified value.
The method returns the first item matching the search criteria. If no item is matching then null (Nothing in VB.NET) is returned.
Searches the RadPanelbar control for the first RadPanelItem with a NavigateUrl property equal to the specified value.
public RadPanelItem FindItemByUrl(string url)The value to search for.
Returns:A RadPanelItem whose NavigateUrl property is equal to the specified value.
The method returns the first Item matching the search criteria. If no Item is matching then null (Nothing in VB.NET) is returned.
Searches the RadPanelbar control for the first RadPanelItem with a Value property equal to the specified value.
public RadPanelItem FindItemByValue(string value, bool ignoreCase)The value to search for.
ignoreCaseboolA Boolean indicating a case-sensitive or insensitive comparison (true indicates a case-insensitive comparison).
Returns:A RadPanelItem whose Value property is equal to the specified value.
The method returns the first item matching the search criteria. If no item is matching then null (Nothing in VB.NET) is returned.
Searches the RadPanelbar control for the first RadPanelItem with a Value property equal to the specified value.
public RadPanelItem FindItemByValue(string value)The value to search for.
Returns:A RadPanelItem whose Value property is equal to the specified value.
The method returns the first item matching the search criteria. If no item is matching then null (Nothing in VB.NET) is returned.
Gets a linear list of all items in the RadPanelBar control.
public IList<RadPanelItem> GetAllItems()An IList<RadPanelBarItem> containing all items (from all hierarchy levels).
Use the GetAllItems method to obtain a linear collection of all items regardless their place in the hierarchy.
Populates the RadPanelBar control from external XML file.
public override void LoadContentFile(string xmlFileName)The name of the XML file.
Overrides:
The newly added items will be appended after any existing ones.
Executed when post data is loaded from the request
protected override bool LoadPostData(string postDataKey, NameValueCollection postCollection)Overrides:
Raises the ItemClick event.
Raises the ItematCreated event.
Raises the ItemDataBound event.
protected override void RaiseItemDataBound(ControlItem item)Overrides:
protected override void RaiseTemplateNeeded(ControlItem item)Overrides:
protected override void RenderContents(HtmlTextWriter writer)Overrides:
Events
Occurs on the server when a panel item in the RadPanelBar control is clicked.
public virtual event RadPanelBarEventHandler ItemClickThe panel will also postback if you navigate to a panel item using the [panel item] key and then press [enter] on the panel item that is focused. The instance of the clicked panel item is passed to the ItemClick event handler - you can obtain a reference to it using the eventArgs.RadPanelBarItem property.
Occurs on the server when an item in the RadPanelBar control is created.
public event RadPanelBarEventHandler ItemCreatedThe ItemCreated event is raised every time a new item is added.
The ItemCreated event is not related to data binding and you cannot retrieve the DataItem of the item in the event handler.
The ItemCreated event is often useful in scenarios where you want to initialize all items - for example setting the ToolTip of each RadPanelBarItem to be equal to the Text property.
Occurs after a panel item is data bound.
public event RadPanelBarEventHandler ItemDataBoundThe ItemDataBound event is raised for each panel item upon databinding. You can retrieve the item being bound using the event arguments. The DataItem associated with the item can be retrieved using the DataItem property.
The ItemDataBound event is often used in scenarios when you want to perform additional mapping of fields from the DataItem to their respective properties in the RadPanelBarItem class.
Occurs before template is being applied to the panel item.
public event RadPanelBarEventHandler TemplateNeededThe TemplateNeeded event is raised before a template is been applied on the panel item, both during round-trips (postbacks) and at the time data is bound to the control. The TemplateNeeded event is not raised for items which are defined inline in the page or user control.
The TemplateNeeded event is commonly used for dynamic templating.