Class sap.m.PanelModule: sap/m/Panel

extends Control

A container control which has a header and content.

Overview

The panel is a container for grouping and displaying information. It can be collapsed to save space on the screen.

Guidelines:

  • Nesting two or more panels is not recommended.
  • Do not stack too many panels on one page.

Structure

A panel consists of a title bar with a header text or header toolbar, an info toolbar (optional), and a content area. Using the headerToolbar aggregation, you can add a toolbar with any toolbar content (i.e. custom buttons, spacers, titles) inside the title bar.

There are two types of panels: fixed and expandable. Expendable panels are enabled by the expandable property. Furthermore you can define an expand animation with the property expandAnimation.

Usage

When to use:

  • You need to group or display information and want to give users the option of hiding this information.
  • You want to show additional information on demand (for example, a panel could show optional input fields for an advanced search).
  • You want to create a panel with controls that do not require user interaction and are not part of a form. Depending on the usage, change the accessibleRole property from the default Form to Region or Complementary.

Responsive Behavior

  • If the width of the panel is set to 100% (default), the panel and its children are resized responsively, depending on its parent container.
  • If the panel has a fixed defined height, it will take up the space, even if the panel is collapsed.
  • When the panel is expandable, an arrow icon (pointing to the right) appears in front of the header.
  • When the animation is activated, expand/collapse uses a smooth animation to open or close the content area.
  • When the panel expands/collapses, the arrow icon rotates 90 degrees clockwise/counter-clockwise.
  • When the height uses the default property auto, the height of the content area is automatically adjusted to match the height of its content.
  • When the height of the panel is set to a fixed size, the content area can be scrolled through.

Since: 1.16.
Constructor Summary
new sap.m.Panel(sId?, mSettings?)Constructor for a new Panel.
Event Summary
expand(oControlEvent)Indicates that the panel will expand or collapse.
Events borrowed from class sap.ui.core.Control
Method Summary
sap.m.Panel.extend(sClassName, oClassInfo?, FNMetaImpl?)Creates a new subclass of class sap.m.Panel with name sClassName and enriches it with the information contained in oClassInfo.
sap.m.Panel.getMetadata()Returns a metadata object for class sap.m.Panel.
addContent(oContent)Adds some content to the aggregation content.
attachExpand(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the expand event of this sap.m.Panel.
destroyContent()Destroys all the content in the aggregation content.
destroyHeaderToolbar()Destroys the headerToolbar in the aggregation headerToolbar.
destroyInfoToolbar()Destroys the infoToolbar in the aggregation infoToolbar.
detachExpand(fnFunction, oListener)Detaches event handler fnFunction from the expand event of this sap.m.Panel.
fireExpand(mParameters?)Fires event expand to attached listeners.
getAccessibleRole()Gets current value of property accessibleRole.
getBackgroundDesign()Gets current value of property backgroundDesign.
getContent()Gets content of aggregation content.
getExpandable()Gets current value of property expandable.
getExpandAnimation()Gets current value of property expandAnimation.
getExpanded()Gets current value of property expanded.
getHeaderText()Gets current value of property headerText.
getHeaderToolbar()Gets content of aggregation headerToolbar.
getHeight()Gets current value of property height.
getInfoToolbar()Gets content of aggregation infoToolbar.
getWidth()Gets current value of property width.
indexOfContent(oContent)Checks for the provided sap.ui.core.Control in the aggregation content.
insertContent(oContent, iIndex)Inserts a content into the aggregation content.
removeAllContent()Removes all the controls from the aggregation content.
removeContent(vContent)Removes a content from the aggregation content.
setAccessibleRole(sRole)Sets the accessibleRole property of the control.
setBackgroundDesign(sBackgroundDesign)Sets a new value for property backgroundDesign.
setExpandable(bExpandable)Sets the expandable property of the control.
setExpandAnimation(bExpandAnimation)Sets a new value for property expandAnimation.
setExpanded(bExpanded)Sets the expanded property of the control.
setHeaderText(sHeaderText)Sets a new value for property headerText.
setHeaderToolbar(oHeaderToolbar)Sets the aggregated headerToolbar.
setHeight(sHeight)Sets the height of the panel.
setInfoToolbar(oInfoToolbar)Sets the aggregated infoToolbar.
setWidth(sWidth)Sets the width of the panel.
Constructor Detail
new sap.m.Panel(sId?, mSettings?)

Constructor for a new Panel.

Accepts an object literal mSettings that defines initial property values, aggregated and associated objects as well as event handlers. See sap.ui.base.ManagedObject for a general description of the syntax of the settings object.

The supported settings are:

In addition, all settings applicable to the base type sap.ui.core.Control can be used as well.

Parameters:
stringsId?ID for the new control, generated automatically if no ID is given
objectmSettings?Initial settings for the new control
Event Detail
expand(oControlEvent)
Indicates that the panel will expand or collapse.
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
booleanoControlEvent.getParameters.expandIf the panel will expand, this is true. If the panel will collapse, this is false.
Since:
1.22
Method Detail
sap.m.Panel.extend(sClassName, oClassInfo?, FNMetaImpl?): function

Creates a new subclass of class sap.m.Panel with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.core.Control.extend.

Parameters:
stringsClassNameName of the class being created
objectoClassInfo?Object literal with information about the class
functionFNMetaImpl?Constructor function for the metadata object; if not given, it defaults to sap.ui.core.ElementMetadata
Returns:
functionCreated class / constructor function
sap.m.Panel.getMetadata(): sap.ui.base.Metadata
Returns a metadata object for class sap.m.Panel.
Returns:
sap.ui.base.MetadataMetadata object describing this class
addContent(oContent): sap.m.Panel
Adds some content to the aggregation content.
Parameters:
sap.ui.core.ControloContentthe content to add; if empty, nothing is inserted
Returns:
sap.m.PanelReference to this in order to allow method chaining
attachExpand(oData?, fnFunction, oListener?): sap.m.Panel

Attaches event handler fnFunction to the expand event of this sap.m.Panel.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.Panel itself.

Indicates that the panel will expand or collapse.

Parameters:
objectoData?An application-specific payload object that will be passed to the event handler along with the event object when firing the event
functionfnFunctionThe function to be called when the event occurs
objectoListener?Context object to call the event handler with. Defaults to this sap.m.Panel itself
Returns:
sap.m.PanelReference to this in order to allow method chaining
Since:
1.22
destroyContent(): sap.m.Panel
Destroys all the content in the aggregation content.
Returns:
sap.m.PanelReference to this in order to allow method chaining
destroyHeaderToolbar(): sap.m.Panel
Destroys the headerToolbar in the aggregation headerToolbar.
Returns:
sap.m.PanelReference to this in order to allow method chaining
Since:
1.16
destroyInfoToolbar(): sap.m.Panel
Destroys the infoToolbar in the aggregation infoToolbar.
Returns:
sap.m.PanelReference to this in order to allow method chaining
Since:
1.16
detachExpand(fnFunction, oListener): sap.m.Panel

Detaches event handler fnFunction from the expand event of this sap.m.Panel.

The passed function and listener object must match the ones used for event registration.

Parameters:
functionfnFunctionThe function to be called, when the event occurs
objectoListenerContext object on which the given function had to be called
Returns:
sap.m.PanelReference to this in order to allow method chaining
Since:
1.22
fireExpand(mParameters?): sap.m.Panel
Fires event expand to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
booleanmParameters.expand?If the panel will expand, this is true. If the panel will collapse, this is false.
Returns:
sap.m.PanelReference to this in order to allow method chaining
Since:
1.22
getAccessibleRole(): sap.m.PanelAccessibleRole

Gets current value of property accessibleRole.

This property is used to set the accessible aria role of the Panel. Depending on the usage you can change the role from the default Form to Region or Complementary.

Default value is Form.

Returns:
sap.m.PanelAccessibleRoleValue of property accessibleRole
Since:
1.46
getBackgroundDesign(): sap.m.BackgroundDesign

Gets current value of property backgroundDesign.

This property is used to set the background color of the Panel. Depending on the theme you can change the state of the background from "Solid" over "Translucent" to "Transparent".

Default value is Translucent.

Returns:
sap.m.BackgroundDesignValue of property backgroundDesign
Since:
1.30
getContent(): sap.ui.core.Control[]

Gets content of aggregation content.

Determines the content of the Panel. The content will be visible only when the Panel is expanded.

Returns:
sap.ui.core.Control[]
getExpandable(): boolean

Gets current value of property expandable.

Specifies whether the control is expandable. This allows for collapsing or expanding the infoToolbar (if available) and content of the Panel. Note: If expandable is set to false, the Panel will always be rendered expanded.

Default value is false.

Returns:
booleanValue of property expandable
Since:
1.22
getExpandAnimation(): boolean

Gets current value of property expandAnimation.

Indicates whether the transition between the expanded and the collapsed state of the control is animated. By default the animation is enabled.

Default value is true.

Returns:
booleanValue of property expandAnimation
Since:
1.26
getExpanded(): boolean

Gets current value of property expanded.

Indicates whether the Panel is expanded or not. If expanded is set to true, then both the infoToolbar (if available) and the content are rendered. If expanded is set to false, then only the headerText or headerToolbar is rendered.

Default value is false.

Returns:
booleanValue of property expanded
Since:
1.22
getHeaderText(): string

Gets current value of property headerText.

This property is used to set the header text of the Panel. The "headerText" is visible in both expanded and collapsed state. Note: This property is overwritten by the "headerToolbar" aggregation.

Default value is .

Returns:
stringValue of property headerText
getHeaderToolbar(): sap.m.Toolbar

Gets content of aggregation headerToolbar.

This aggregation allows the use of a custom Toolbar as header for the Panel. The "headerToolbar" is visible in both expanded and collapsed state. Use it when you want to add extra controls for user interactions in the header. Note: This aggregation overwrites "headerText" property.

Returns:
sap.m.Toolbar
Since:
1.16
getHeight(): sap.ui.core.CSSSize

Gets current value of property height.

Determines the Panel height.

Default value is auto.

Returns:
sap.ui.core.CSSSizeValue of property height
getInfoToolbar(): sap.m.Toolbar

Gets content of aggregation infoToolbar.

This aggregation allows the use of a custom Toolbar as information bar for the Panel. The "infoToolbar" is placed below the header and is visible only in expanded state. Use it when you want to show extra information to the user.

Returns:
sap.m.Toolbar
Since:
1.16
getWidth(): sap.ui.core.CSSSize

Gets current value of property width.

Determines the Panel width.

Default value is 100%.

Returns:
sap.ui.core.CSSSizeValue of property width
indexOfContent(oContent): int
Checks for the provided sap.ui.core.Control in the aggregation content. and returns its index if found or -1 otherwise.
Parameters:
sap.ui.core.ControloContentThe content whose index is looked for
Returns:
intThe index of the provided control in the aggregation if found, or -1 otherwise
insertContent(oContent, iIndex): sap.m.Panel
Inserts a content into the aggregation content.
Parameters:
sap.ui.core.ControloContentthe content to insert; if empty, nothing is inserted
intiIndexthe 0-based index the content should be inserted at; for a negative value of iIndex, the content is inserted at position 0; for a value greater than the current size of the aggregation, the content is inserted at the last position
Returns:
sap.m.PanelReference to this in order to allow method chaining
removeAllContent(): sap.ui.core.Control[]

Removes all the controls from the aggregation content.

Additionally, it unregisters them from the hosting UIArea.

Returns:
sap.ui.core.Control[]An array of the removed elements (might be empty)
removeContent(vContent): sap.ui.core.Control
Removes a content from the aggregation content.
Parameters:
int|string|sap.ui.core.ControlvContentThe content to remove or its index or id
Returns:
sap.ui.core.ControlThe removed content or null
setAccessibleRole(sRole): sap.m.Panel
Sets the accessibleRole property of the control.
Parameters:
sap.m.PanelAccessibleRolesRoleDefines the aria role of the control.
Returns:
sap.m.PanelPointer to the control instance to allow method chaining.
setBackgroundDesign(sBackgroundDesign): sap.m.Panel

Sets a new value for property backgroundDesign.

This property is used to set the background color of the Panel. Depending on the theme you can change the state of the background from "Solid" over "Translucent" to "Transparent".

When called with a value of null or undefined, the default value of the property will be restored.

Default value is Translucent.

Parameters:
sap.m.BackgroundDesignsBackgroundDesignNew value for property backgroundDesign
Returns:
sap.m.PanelReference to this in order to allow method chaining
Since:
1.30
setExpandable(bExpandable): sap.m.Panel
Sets the expandable property of the control.
Parameters:
booleanbExpandableDefines whether the control is expandable or not.
Returns:
sap.m.PanelPointer to the control instance to allow method chaining.
setExpandAnimation(bExpandAnimation): sap.m.Panel

Sets a new value for property expandAnimation.

Indicates whether the transition between the expanded and the collapsed state of the control is animated. By default the animation is enabled.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Parameters:
booleanbExpandAnimationNew value for property expandAnimation
Returns:
sap.m.PanelReference to this in order to allow method chaining
Since:
1.26
setExpanded(bExpanded): sap.m.Panel
Sets the expanded property of the control.
Parameters:
booleanbExpandedDefines whether control is expanded or not.
Returns:
sap.m.PanelPointer to the control instance to allow method chaining.
setHeaderText(sHeaderText): sap.m.Panel

Sets a new value for property headerText.

This property is used to set the header text of the Panel. The "headerText" is visible in both expanded and collapsed state. Note: This property is overwritten by the "headerToolbar" aggregation.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is .

Parameters:
stringsHeaderTextNew value for property headerText
Returns:
sap.m.PanelReference to this in order to allow method chaining
setHeaderToolbar(oHeaderToolbar): sap.m.Panel
Sets the aggregated headerToolbar.
Parameters:
sap.m.ToolbaroHeaderToolbarThe headerToolbar to set
Returns:
sap.m.PanelReference to this in order to allow method chaining
Since:
1.16
setHeight(sHeight): sap.m.Panel
Sets the height of the panel.
Parameters:
sap.ui.core.CSSSizesHeightThe height of the panel as CSS size.
Returns:
sap.m.PanelPointer to the control instance to allow method chaining.
setInfoToolbar(oInfoToolbar): sap.m.Panel
Sets the aggregated infoToolbar.
Parameters:
sap.m.ToolbaroInfoToolbarThe infoToolbar to set
Returns:
sap.m.PanelReference to this in order to allow method chaining
Since:
1.16
setWidth(sWidth): sap.m.Panel
Sets the width of the panel.
Parameters:
sap.ui.core.CSSSizesWidthThe width of the Panel as CSS size.
Returns:
sap.m.PanelPointer to the control instance to allow method chaining.