Skip to content

Commit 8ee0ad2

Browse files
svdimitrmarin-bratanov
svdimitr
and
marin-bratanov
authored
Docs toolbar component (#175)
* feat(toolbar): initial docs * chore(toolbar): add templated article * chore(toolbar): separte overview article to different ones * chore(toolbar): setup for events article * chore(toolbar): add example to toolbarbutton * chore(toolbar): fix the slug of the separators article * chore(toolbar): add examples for the built-in buttons * chore(toolbar): more explanations in the tepmplated item * chore(toolbar); events article * chore(toolbar): add namespace and ref * chore(toolbar); add the component to kbnav list * chore(toolbar): add to intro article * chore(toolbar): fix typo * chore(toolbar): overview improvements * chore(toolbar): built-in tools improvements * chore(toolbar): separators improvement * chore(toolbar): events improvements Co-authored-by: Marin Bratanov <[email protected]>
1 parent 81dd341 commit 8ee0ad2

13 files changed

+488
-0
lines changed

‎_config.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -347,6 +347,7 @@ intro_columns:
347347
"Tab Strip": "components/tabstrip/overview"
348348
"TreeView": "components/treeview/overview"
349349
"Pager": "pager-overview"
350+
"ToolBar": "toolbar-overview"
350351

351352
-
352353
title: "Interactivity and UX"

‎accessibility/keyboard-navigation.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,8 @@ The following list shows the Telerik components that support specific keyboard c
8686

8787
* [TimePicker](https://demos.telerik.com/blazor-ui/timepicker/keyboard-navigation)
8888

89+
* [ToolBar](https://demos.telerik.com/blazor-ui/toolbar/keyboard-navigation)
90+
8991
* [ToggleButton](https://demos.telerik.com/blazor-ui/togglebutton/keyboard-navigation)
9092

9193
* TreeList - will have keyboard navigation in an upcoming release.

‎components/toolbar/built-in-tools.md

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
---
2+
title: Built-in Tools
3+
page_title: ToolBar - Built-in Tools
4+
description: Built-in Tools in the Telerik ToolBar for Blazor
5+
slug: toolbar-built-in-tools
6+
tags: telerik,blazor,toolbar,builtin,tools,button,buttons
7+
published: True
8+
position: 1
9+
---
10+
11+
# Built-in Tools
12+
13+
The Telerik ToolBar for Blazor allows you to use built-in buttons and button groups or to add a [custom tool]({%slug toolbar-templated-item%}). The available built-in tools are:
14+
15+
* [ToolBarButton](#toolbarbutton)
16+
* [ToolBarToggleButton](#toolbartogglebutton)
17+
* [ToolbarButtonGroup](#toolbarbuttongroup)
18+
19+
## ToolBarButton
20+
21+
A toolbar button is a plain button that you can click and it raises an event so the application can respond to that.
22+
23+
You can add multiple buttons to the Telerik Toolbar. To do that you should add the `<ToolBarButton>` to the `<TelerikToolBar>`.
24+
25+
You can customize the buttons using the following features:
26+
27+
* `Enabled` - `bool`, defaults to `true` - specifies if the button is clickable.
28+
29+
* `Visible` - `bool`, defaults to `true` - specifies if the button will be visible in the toolbar.
30+
31+
* `Title` - `string` - maps to the `title` HTML attribute for the `<button>`.
32+
33+
* `Class` - `string` - the CSS class that will be rendered on the main wrapping element of the ToolbarButton. You could use that class to cascade styles.
34+
35+
* `OnClick` - `EventCallback` - allows you to execute a method upon the click of the button. For more information see the [Events]({%slug toolbar-events%}) article.
36+
37+
* `Icon` - `string` - adds a font icon to the button. You can find more information on adding a font icon to a Telerik Component in [Telerik Font Icons article]({%slug general-information/font-icons%}#icon-in-telerik-component).
38+
39+
* `ImageURL` - `string` - adds an image to the button. You can provide an image url to this parameter.
40+
41+
* `SpriteClass` - `string` - add a sprite class image to the button. Set this attribute to `k-icon MySpriteClass` where `MySpriteClass` defines the CSS rules for the sprite.
42+
43+
* `IconClass` - `string` - allows you to set a CSS class that provides the required font name, font size and content for the `::before` pseudo-element.
44+
45+
>caption The Telerik ToolBar with ToolBarButtons
46+
47+
![](images/toolbar-toolbarbutton-example.png)
48+
49+
````CSHTML
50+
@*This example shows the TelerikToolBar with ToolBarButtons and their features*@
51+
52+
<TelerikToolBar>
53+
<ToolBarButton Icon="@IconName.Bold" Class="myBoldButton" Enabled="@true" Visible="true" Title="Bold Button" OnClick="@OnBold">Bold</ToolBarButton>
54+
<ToolBarButton Icon="@IconName.Italic" Class="myItalicButton" Enabled="@false" Visible="true" Title="Italic Button" OnClick="@OnItalic">Italic</ToolBarButton>
55+
<ToolBarButton Icon="@IconName.Underline" Class="myUnderlineButton" Enabled="@true" Visible="true" Title="Underline Button" OnClick="@OnUnderline">Underline</ToolBarButton>
56+
</TelerikToolBar>
57+
58+
@code {
59+
public void OnBold()
60+
{
61+
Console.WriteLine("The user clicked on the bold button");
62+
}
63+
64+
public void OnItalic()
65+
{
66+
Console.WriteLine("The user clicked on the italic button");
67+
}
68+
69+
public void OnUnderline()
70+
{
71+
Console.WriteLine("The user clicked on the underline button");
72+
}
73+
}
74+
````
75+
76+
## ToolBarToggleButton
77+
78+
A toolbar toggle button has two states - normal and selected - and clicking it can toggle between them through two-way binding or an event.
79+
80+
You can add multiple toggle buttons to the Telerik Toolbar. To do that you should add the `<ToolBarToggleButton>` to the `<TelerikToolBar>`.
81+
82+
You can customize the toggle buttons using the following features:
83+
84+
* `Selected` - `bool` - specifies whether the button is in selected state. You can use it with one and two-way data binding with the `SelectedChanged` event. For more information on how to handle the `SelectedChanged` event see the [Events]({%slug toolbar-events%}) article.
85+
86+
* `Enabled` - `bool`, defaults to `true` - specifies if the button is clickable.
87+
88+
* `Visible` - `bool`, defaults to `true` - specifies if the button will be visible in the toolbar.
89+
90+
* `Title` - `string` - maps to the `title` HTML attribute for the `<button>`.
91+
92+
* `Class` - `string` - the CSS class that will be rendered on the main wrapping element of the ToolbarButton. You could use that class to cascade styles.
93+
94+
* `OnClick` - `EventCallback` - allows you to execute an method upon the click of the button. For more information read the [Events]({%slug toolbar-events%}) article.
95+
96+
* `Icon` - `string` - adds a font icon to the button. You can find more information on adding a font icon to a Telerik Component in [Telerik Font Icons article]({%slug general-information/font-icons%}#icon-in-telerik-component).
97+
98+
* `ImageURL` - `string` - adds an image to the button. You can provide an image url to this parameter.
99+
100+
* `SpriteClass` - `string` - add a sprite class image to the button. Set this attribute to `k-icon MySpriteClass` where `MySpriteClass` defines the CSS rules for the sprite.
101+
102+
* `IconClass` - `string` - allows you to set a CSS class that provides the required font name, font size and content for the `::before` pseudo-element.
103+
104+
>caption The Telerik ToolBar with ToolBarToggleButtons
105+
106+
![](images/toolbar-togglebutton-example.png)
107+
108+
````CSHTML
109+
@*This example shows the TelerikToolBar with ToolBarToggleButton and its available features*@
110+
111+
<TelerikToolBar>
112+
<ToolBarToggleButton @bind-Selected="@Selected"
113+
Enabled="true"
114+
Class="myToggleFullScreenButton"
115+
Icon="@IconName.ToggleFullScreenMode"
116+
OnClick="@ToggleFullScreen">
117+
Toggle Fullscreen
118+
</ToolBarToggleButton>
119+
</TelerikToolBar>
120+
121+
@code {
122+
public bool Selected { get; set; } = true;
123+
124+
public void ToggleFullScreen()
125+
{
126+
if (Selected)
127+
{
128+
Console.WriteLine("The user is in full screen");
129+
}
130+
else
131+
{
132+
Console.WriteLine("The user exited full screen");
133+
}
134+
}
135+
}
136+
````
137+
138+
## ToolBarButtonGroup
139+
140+
The button group is a container for one or more buttons that renders them together and spaces them out from the adacent buttons or groups.
141+
142+
You can add one or more group of buttons to the Toolbar. To do that you should add the `<ToolBarButtonGroup>` to the `<TelerikToolBar>`. In the button group you can place either the `ToolBarButton` or the `ToolBarToggleButton`.
143+
144+
You can customize the groups using the following features:
145+
146+
* `Visible` - `bool`, defaults to `true` - specifies if the group will be visible in the toolbar.
147+
148+
* `SelectionMode` - `enum` - specifies whether you can select one or multiple buttons from the group at the same time (applicable for `ToolBarToggleButton` instances inside it). It takes a member of the `ButtonGroupSelectionMode` enum:
149+
150+
* Single - this is the default value
151+
* Multiple
152+
153+
* `Enabled` - `bool`, defaults to `true` - specifies if the group is clickable.
154+
155+
* `Class` - `string` - the CSS class that will be rendered on the main wrapping element of the ToolBarButtonGroup. You could use that class to cascade styles.
156+
157+
* `Width` - `string` - allows you to control the width of the group.
158+
159+
>caption The Telerik ToolBar with grouped buttons
160+
161+
![](images/toolbar-grouped-buttons.png)
162+
163+
````CSHTML
164+
@*This example shows the TelerikToolBar with grouped ToolBarButtons*@
165+
166+
<TelerikToolBar>
167+
<ToolBarButtonGroup Visible="true"
168+
SelectionMode="@ButtonGroupSelectionMode.Multiple"
169+
Class="formattingButtons"
170+
Enabled="true">
171+
<ToolBarButton Icon="@IconName.Bold">Bold</ToolBarButton>
172+
<ToolBarButton Icon="@IconName.Italic">Italic</ToolBarButton>
173+
<ToolBarButton Icon="@IconName.Underline">Underline</ToolBarButton>
174+
</ToolBarButtonGroup>
175+
</TelerikToolBar>
176+
````
177+
178+
## See Also
179+
180+
* [Live Demo: ToolBar Overview](https://demos.telerik.com/blazor-ui/toolbar/overview)
181+
* [ToolBar Overview]({%slug toolbar-overview%})

‎components/toolbar/events.md

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
title: Events
3+
page_title: ToolBar - Events
4+
description: Events in the Telerik ToolBar for Blazor
5+
slug: toolbar-events
6+
tags: telerik,blazor,toolbar,events
7+
published: True
8+
position: 25
9+
---
10+
11+
# Events
12+
13+
The ToolBar exposes events for its [built-in buttons]({%slug toolbar-built-in-tools%}) which allow you to react when the user perform actions on them. Such actions would be a click event or changing the selected state for the toggle button. The available events are:
14+
15+
* [OnClick](#onclick)
16+
* [SelectedChanged](#selectedchanged)
17+
18+
For [custom (templated) items]({%slug toolbar-templated-item%}), handle the corresponding events exposed by the components/elements you place inside them.
19+
20+
## OnClick
21+
22+
The `OnClick` event fires when the user clicks on a button in the ToolBar (also applicable to toggle buttons).
23+
24+
>caption The OnClick event for the ToolBar buttons
25+
26+
````CSHTML
27+
@*When clicking on the button a message will be printed in your console*@
28+
29+
<TelerikToolBar>
30+
<ToolBarButton Icon="@IconName.HyperlinkEmail" OnClick="@OnHyperlinkClick">Hyperlink</ToolBarButton>
31+
</TelerikToolBar>
32+
33+
34+
@code {
35+
public void OnHyperlinkClick()
36+
{
37+
Console.WriteLine("The user clicked on the hyperlink button");
38+
}
39+
}
40+
````
41+
42+
## SelectedChanged
43+
44+
The `SelectedChanged` event will fire when the user changes the state of the [`ToolBarToggleButton`]({%slug toolbar-built-in-tools%}#toolbartogglebutton). It is used for one-way data binding of the `Selected` parameter and will prevent you from using two-way data binding (`@bind-Selected`)
45+
46+
>caption The SelectedChanged event for the ToolBarToggleButton
47+
48+
````CSHTML
49+
@*Handle the SelectedChangedEvent*@
50+
51+
<TelerikToolBar>
52+
<TelerikToggleButton Selected="@Selected" SelectedChanged="@SelectedChangedHandler"></TelerikToggleButton>
53+
54+
</TelerikToolBar>
55+
56+
57+
@code {
58+
public bool Selected { get; set; }
59+
60+
public void SelectedChangedHandler(bool value)
61+
{
62+
Selected = value;
63+
64+
//your application logic regarding the change of the value
65+
}
66+
}
67+
````
68+
69+
## See Also
70+
71+
* [Live Demo: ToolBar Overview](https://demos.telerik.com/blazor-ui/toolbar/overview)
72+
* [ToolBar Overview]({%slug toolbar-overview%})

‎components/toolbar/images/basic-toolbar-screenshot.png

5.6 KB
Loading

‎components/toolbar/images/toolbar-grouped-buttons.png

3.4 KB
Loading

‎components/toolbar/images/toolbar-separators.png

21.1 KB
Loading

‎components/toolbar/images/toolbar-templated-item.png

4.24 KB
Loading

‎components/toolbar/images/toolbar-togglebutton-example.png

2.53 KB
Loading

‎components/toolbar/images/toolbar-toolbarbutton-example.png

3.44 KB
Loading

‎components/toolbar/overview.md

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
---
2+
title: Overview
3+
page_title: ToolBar Overview
4+
description: Overview of the ToolBar component for Blazor.
5+
slug: toolbar-overview
6+
tags: telerik,blazor,toolbar,tools,buttoncontainer
7+
published: True
8+
position: 0
9+
---
10+
11+
# ToolBar Overview
12+
13+
The ToolBar component is a container for buttons or other application-specifc tools. This article explains the available features.
14+
15+
#### In This Article
16+
17+
* [Basics](#basics)
18+
* [Features](#features)
19+
20+
## Basics
21+
22+
To use the Telerik Toolbar component:
23+
24+
1. Add the `<TelerikToolBar>` tag to your page.
25+
1. Populate it with [Built-In Tools]({%slug toolbar-built-in-tools%}) or [Custom Tools]({%slug toolbar-templated-item%}).
26+
1. Handle their respective events so your application can respond to the user actions.
27+
28+
>caption Basic Telerik Toolbar
29+
30+
![basic toolbar screenshot](images/basic-toolbar-screenshot.png)
31+
32+
````CSHTML
33+
@*Add a basic Telerik ToolBar to your page with a few built-in buttons.*@
34+
35+
<TelerikToolBar>
36+
<ToolBarButtonGroup>
37+
<ToolBarButton Icon="@IconName.Bold" OnClick="@OnBold">Bold</ToolBarButton>
38+
<ToolBarButton Icon="@IconName.Italic" OnClick="@OnItalic">Italic</ToolBarButton>
39+
<ToolBarButton Icon="@IconName.Underline" OnClick="@OnUnderline">Underline</ToolBarButton>
40+
</ToolBarButtonGroup>
41+
42+
<ToolBarToggleButton @bind-Selected="@Selected">Toggle Button</ToolBarToggleButton>
43+
44+
<ToolBarButton Icon="@IconName.Undo">Undo</ToolBarButton>
45+
</TelerikToolBar>
46+
47+
<br />
48+
49+
@Result
50+
51+
@code {
52+
public bool Selected { get; set; } = true;
53+
54+
public string Result { get; set; }
55+
56+
public void OnBold()
57+
{
58+
Result = "The user clicked on the bold button";
59+
}
60+
61+
public void OnItalic()
62+
{
63+
Result = "The user clicked on the italic button";
64+
}
65+
66+
public void OnUnderline()
67+
{
68+
Result = "The user clicked on the underline button";
69+
}
70+
}
71+
````
72+
73+
74+
>caption Components namespace and reference
75+
76+
````CSHTML
77+
@*Component namespace and reference*@
78+
79+
<TelerikToolBar @ref="@ToolbarReference">
80+
<ToolBarToggleButton @bind-Selected="@Selected">Toggle Button</ToolBarToggleButton>
81+
82+
<ToolBarButton Icon="@IconName.Undo">Undo</ToolBarButton>
83+
</TelerikToolBar>
84+
85+
@code {
86+
public Telerik.Blazor.Components.TelerikToolBar ToolbarReference { get; set; }
87+
88+
public bool Selected { get; set; } = true;
89+
}
90+
````
91+
92+
## Features
93+
94+
>caption The ToolBar provides the following features:
95+
96+
* `Class` - `string` - the CSS class that will be rendered on the main wrapping element of the ToolBar component. You could use that class to control the size of the component through CSS.
97+
98+
* `ToolBarButton` - renders a button in the ToolBar. You can find more information and examples in the [Built-In Tools]({%slug toolbar-built-in-tools%}#toolbarbutton) article.
99+
100+
* `ToolBarToggleButton` - renders a toggle button in the ToolBar. You can find more information and examples in the [Built-In Tools]({%slug toolbar-built-in-tools%}#toolbartogglebutton) article.
101+
102+
* `ToolBarButtonGroup` - creates a group of buttons in the component. You can find more information and examples in the [Built-In Tools]({%slug toolbar-built-in-tools%}#toolbarbuttongroup) article.
103+
104+
* `ToolBarTemplateItem` - allows you to create a custom item for the ToolBar. You can read more about this in the [Templated Item]({%slug toolbar-templated-item%}) article.
105+
106+
* `ToolBarSeparator` - adds a line that separates items in the ToolBar. You can find more information in the [Separators]({%slug toolbar-separators%}) article.
107+
108+
* `ToolBarSpacer` - adds empty space that separates the items into different groups. You can find more information in the [Separators]({%slug toolbar-separators%}) article.
109+
110+
111+
112+
## See Also
113+
114+
* [Live Demo: ToolBar Overview](https://demos.telerik.com/blazor-ui/toolbar/overview)
115+
* [Live Demo: ToolBar Tools](https://demos.telerik.com/blazor-ui/toolbar/tools)

0 commit comments

Comments
 (0)