ToggleButton
A ToggleButton control presents a standard button that users can click. It is similar to a Button control, but adds the following functionality:
-
A ToggleButton control has two states, and when users click the ToggleButton control, it toggles the state that it is in. The ToggleButton control remembers what state it is in until the user reloads the page that contains the ToggleButton control. The ToggleButton control uses different visual styles for the two states.
-
The IsOpen and the ShowArrow properties are specific to the ToggleButton control. It shares all other properties with the Button control.
If you set the ShowArrow property to true, the ToggleButton control shows an arrow that points up when IsOpen is true, and points down when IsOpen is false.
If you set the ButtonType property to primary, SPEAK makes it stand out visually. You can set the size of a button to normal or large with the Dimensions property.
You should set ToggleButton controls that users click to carry out the main purpose of a page to primary and use default for other buttons. You can also set the ButtonType to inverse. An inverse button uses the same colors as a default button, but swaps the text and background colors.
ToggleButton controls can display icons as well as text and they can show both at the same time.
You specify icons using the ImageUrl property. You can use the same icons here as when you select an icon for an item in the content tree. ToggleButton controls also support defining the icon as a “sprite,” selected from a sprite sheet. The ImageUrl property stores the URL of the sprite sheet, and the BackgroundPosition property stores the coordinates of the desired sprite (icon/image).
If you use both icon and text, SPEAK positions the icon to the left of the text. You cannot change this position.
When to use
The following is an example of when to use a ToggleButton control.
When you use the FilterControl control to display a panel with facets, you often want to give users the possibility to hide and show the FilterControl. You can use a ToggleButton control for this, by binding the IsVisible property of the FilterControl to the IsOpen property of the ToggleButton control. The default value of the IsOpen property is false, so if you want the FilterControl to be open when the page is loaded, you have to set the IsOpen property to true.
Properties
|
Name |
Description |
Default |
|---|---|---|
|
Appearance | ||
|
BackgroundPosition |
Set the offset of the sprite/icon/image in a sprite sheet file in this format: -<x>px -<y>px Where <x> indicates the horizontal number of pixels from the left edge of the sprite sheet to the left edge of the sprite (represented as a negative number), and <y> indicates the vertical number of pixels from the top edge of the sprite sheet (represented as a negative number) to the top edge of the sprite. |
-0px -0px |
|
ButtonType |
Select Default, Primary, or Inverse. |
Default |
|
Dimension |
Set the size of the button. Select Normal or Large. |
Normal |
|
ImageUrl |
Set the Sitecore path of an icon (for example, | |
|
IsOpen |
If true, the ToggleButton control is in the “open” state. The ToggleButton control toggles the value when users click it. |
False |
|
ShowArrow |
If true, the ToggleButton control displays an arrow that indicates what state it is in. |
False |
|
Text |
Set the text to display on the ToggleButton control. You can enter a static text, set the text from PageCode, or you can bind to a property of another control. | |
Configuration
You can create a configuration item for a ToggleButton control by creating an item based on the ToggleButton Parameters template.
The configuration item has these specific fields:
-
ButtonType
-
Dimension
-
Text – this field corresponds to the Text property, and you use the field to make it easier to translate UI texts.
-
IsOpen
-
ImageUrl
-
BackgroundPosition
-
ShowArrow
It inherits these fields:
-
Click
-
IsEnabled
-
IsVisible
-
AccessKey
-
Tooltip
-
Behaviors
-
Id