Skip to content

Commit 37b34dc

Browse files
ntachevayordan-mitev
ntacheva
and
yordan-mitev
authored
[4.5] docs(dropdownbutton): Documentation for DropDownButton (#1595)
* docs(dropdownbutton): Documentation for DropDownButton * docs(dropdownbutton): update articles and add component in keyboard navigation and config * Update components/dropdownbutton/overview.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/dropdownbutton/overview.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/dropdownbutton/overview.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/dropdownbutton/overview.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/dropdownbutton/appearance.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/dropdownbutton/appearance.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/dropdownbutton/overview.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/dropdownbutton/overview.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/dropdownbutton/overview.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/dropdownbutton/overview.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/dropdownbutton/overview.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/dropdownbutton/overview.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/dropdownbutton/overview.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/dropdownbutton/overview.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/dropdownbutton/overview.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/dropdownbutton/icons.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/dropdownbutton/icons.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update components/dropdownbutton/appearance.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * chore(dropdownbutton):address some of the feedback * docs(dropdownbutton,splitbutton): address feedback --------- Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com>
1 parent 9b54708 commit 37b34dc

File tree

9 files changed

+554
-25
lines changed

9 files changed

+554
-25
lines changed

‎_config.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -330,6 +330,8 @@ navigation:
330330
title: "DragAndDrop"
331331
"*drawer":
332332
title: "Drawer"
333+
"*dropdownbutton":
334+
title: "DropDownButton"
333335
"*dropdownlist":
334336
title: "DropDownList"
335337
"*dropzone":
@@ -499,6 +501,7 @@ intro_columns:
499501
"Button Group": "buttongroup-overview"
500502
"Toggle Button": "togglebutton-overview"
501503
"Drawer": "drawer-overview"
504+
"DropDownButton": "dropdownbutton-overview"
502505
"Menu": "components/menu/overview"
503506
"Context Menu": "contextmenu-overview"
504507
"PanelBar": "panelbar-overview"

‎_contentTemplates/dropdownbutton/notes.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
#dropdownbutton-splitbutton-comparison
2+
The DropDownButton and SplitButton components are similar. They both consist of a primary button and a dropdown element that holds additional action items. The major difference is the purpose of the primary button.
3+
4+
* [DropDownButton]({%slug dropdownbutton-overview%}) - The main purpose of the primary button is to open the popup with additional actions. The primary button does expose a separate [`OnClick` event]({%slug dropdownbutton-events%}), so you can handle it to invoke a dedicated action but clicking on it always opens the dropdown.
5+
6+
* [SplitButton]({%slug splitbutton-overview%}) - The main element contains a primary button and a separate button for opening the dropdown. The purpose of the primary button is to [invoke a standalone action]({%slug splitbutton-events%}#onclick). Clicking on it does not open the dropdown. To open the popup with the additional actions, the user has to click the dedicated button with `caret-alt-down` icon.
7+
#end

‎accessibility/keyboard-navigation.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,7 @@ The following table lists the available Telerik UI for Blazor components with th
6363
| [DateTimePicker](https://demos.telerik.com/blazor-ui/datetimepicker/keyboard-navigation) | **Enhanced** | |
6464
| [Dialog](https://demos.telerik.com/blazor-ui/dialog/overview) | **Enhanced** | Tab to reach and use its buttons. The Dialog restricts the focus within itself during tabbing. |
6565
| [Drawer](https://demos.telerik.com/blazor-ui/drawer/keyboard-navigation) | **Enhanced** | |
66+
| [DropDownButton](https://demos.telerik.com/blazor-ui/dropdownbutton/keyboard-navigation) | **Enhanced** | |
6667
| [DropDownList](https://demos.telerik.com/blazor-ui/dropdownlist/keyboard-navigation) | **Enhanced** | |
6768
| DropZone | - | |
6869
| [Editor](https://demos.telerik.com/blazor-ui/editor/keyboard-navigation) | **Enhanced** | |

‎components/dropdownbutton/appearance.md

Lines changed: 240 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,240 @@
1+
---
2+
title: Appearance
3+
page_title: DropDownButton - Appearance
4+
description: Explore the appearance settings of the DropDownButton for Blazor. See the supproted built-in options for the primary button - fill mode, roundness, size and color.
5+
slug: dropdownbutton-appearance
6+
tags: telerik,blazor,dropdownbutton,appearance,styling
7+
published: True
8+
position: 10
9+
---
10+
11+
# DropDownButton Appearance
12+
13+
This article describes the declarative settings of the DropDownButton component, which affect the styling and appearance of the primary button.
14+
15+
The DropDownButton provides the same appearance parameters as the regular [Button component]({%slug button-appearance%}):
16+
17+
* [FillMode](#fillmode)
18+
* [Rounded](#rounded)
19+
* [Size](#size)
20+
* [ThemeColor](#themecolor)
21+
22+
23+
## Setting Parameter Values
24+
25+
The examples in this article use reflection to show all possible values of the DropDownButton parameters. In a real-world scenario, you can use two options to set the desired parameter values:
26+
27+
* Use the static class members in the `ThemeConstants.DropDownButton` namespace. This is the easier and recommended approach.
28+
* Set the actual string values directly.
29+
30+
The following two configurations will produce the same result.
31+
32+
>caption Two ways to set DropDownButton appearance parameters
33+
34+
````CSHTML
35+
<TelerikDropDownButton FillMode="@ThemeConstants.DropDownButton.FillMode.Solid"
36+
Rounded="@ThemeConstants.DropDownButton.Rounded.Large"
37+
Size="@ThemeConstants.DropDownButton.Size.Large"
38+
ThemeColor="@ThemeConstants.DropDownButton.ThemeColor.Primary">
39+
<DropDownButtonContent> Foo </DropDownButtonContent>
40+
<DropDownButtonItems>
41+
<DropDownButtonItem> Bar </DropDownButtonItem>
42+
</DropDownButtonItems>
43+
</TelerikDropDownButton>
44+
45+
<TelerikDropDownButton FillMode="solid"
46+
Rounded="lg"
47+
Size="lg"
48+
ThemeColor="primary">
49+
<DropDownButtonContent> Foo </DropDownButtonContent>
50+
<DropDownButtonItems>
51+
<DropDownButtonItem> Bar </DropDownButtonItem>
52+
</DropDownButtonItems>
53+
</TelerikDropDownButton>
54+
````
55+
56+
57+
## FillMode
58+
59+
The `FillMode` parameter controls if the primary button of the DropDownButton component will have a background and borders. The setting also affects the component's hover state. To set the parameter value, use the `string` members of the static class `ThemeConstants.DropDownButton.FillMode`.
60+
61+
| `FillMode` Class Member | String Value |
62+
| --- | --- |
63+
| `Solid` (default) | `"solid"` |
64+
| `Flat` | `"flat"` |
65+
| `Outline` | `"outline"` |
66+
| `Link` | `"link"` |
67+
68+
>caption DropDownButton FillMode example
69+
70+
````CSHTML
71+
<p>DropDownButton FillMode</p>
72+
73+
@foreach (var item in FillModes)
74+
{
75+
var fillMode = item.GetValue(null).ToString();
76+
77+
<TelerikDropDownButton FillMode="@fillMode">
78+
<DropDownButtonContent> @fillMode </DropDownButtonContent>
79+
<DropDownButtonItems>
80+
<DropDownButtonItem> secondary </DropDownButtonItem>
81+
</DropDownButtonItems>
82+
</TelerikDropDownButton>
83+
}
84+
85+
@code {
86+
private List<System.Reflection.FieldInfo> FillModes { get; set; }
87+
88+
protected override void OnInitialized()
89+
{
90+
FillModes = typeof(ThemeConstants.DropDownButton.FillMode)
91+
.GetFields().ToList();
92+
93+
base.OnInitialized();
94+
}
95+
}
96+
````
97+
98+
99+
## Rounded
100+
101+
The `Rounded` parameter affects the `border-radius` CSS styles of the DropDownButton's primary button. To set the parameter value, use the `string` members of the static class `ThemeConstants.DropDownButton.Rounded`.
102+
103+
| `Rounded` Class Member | String Value |
104+
| --- | --- |
105+
| `Small` | `"sm"` |
106+
| `Medium` (default) | `"md"` |
107+
| `Large` | `"lg"` |
108+
| `Full` | `"full"` |
109+
110+
>caption DropDownButton Rounded example
111+
112+
````CSHTML
113+
<p>DropDownButton Rounded</p>
114+
115+
@foreach (var item in RoundedOptions)
116+
{
117+
var rounded = item.GetValue(null).ToString();
118+
119+
<TelerikDropDownButton Rounded="@rounded">
120+
<DropDownButtonContent> @rounded </DropDownButtonContent>
121+
<DropDownButtonItems>
122+
<DropDownButtonItem> secondary </DropDownButtonItem>
123+
</DropDownButtonItems>
124+
</TelerikDropDownButton>
125+
}
126+
127+
@code {
128+
private List<System.Reflection.FieldInfo> RoundedOptions { get; set; }
129+
130+
protected override void OnInitialized()
131+
{
132+
RoundedOptions = typeof(ThemeConstants.DropDownButton.Rounded)
133+
.GetFields().ToList();
134+
135+
base.OnInitialized();
136+
}
137+
}
138+
````
139+
140+
## Size
141+
142+
The `Size` parameter can change some dimensions of the DropDownButton's primary button, such as height, margins, or paddings. Possible values are the `string` members of the static class `ThemeConstants.DropDownButton.Size`.
143+
144+
| `Size` Class Member | String Value |
145+
| --- | --- |
146+
| `Small` | `"sm"` |
147+
| `Medium` (default) | `"md"` |
148+
| `Large` | `"lg"` |
149+
150+
>caption DropDownButton Size example
151+
152+
````CSHTML
153+
<p>DropDownButton Size</p>
154+
155+
@foreach (var item in Sizes)
156+
{
157+
var size = item.GetValue(null).ToString();
158+
159+
<TelerikDropDownButton Size="@size">
160+
<DropDownButtonContent> @size </DropDownButtonContent>
161+
<DropDownButtonItems>
162+
<DropDownButtonItem> secondary </DropDownButtonItem>
163+
</DropDownButtonItems>
164+
</TelerikDropDownButton>
165+
}
166+
167+
@code {
168+
private List<System.Reflection.FieldInfo> Sizes { get; set; }
169+
170+
protected override void OnInitialized()
171+
{
172+
Sizes = typeof(ThemeConstants.DropDownButton.Size)
173+
.GetFields().ToList();
174+
175+
base.OnInitialized();
176+
}
177+
}
178+
````
179+
180+
181+
## ThemeColor
182+
183+
The `ThemeColor` parameter sets the background and text color of the DropDownButton's primary button from a set of predefined options. Use the `string` members of the static class `ThemeConstants.DropDownButton.ThemeColor`.
184+
185+
| `ThemeColor` Class Member | String Value |
186+
| --- | --- |
187+
| `Base` (default) | `"base"` |
188+
| `Primary` | `"primary"` |
189+
| `Secondary` | `"secondary"` |
190+
| `Tertiary` | `"tertiary"` |
191+
| `Info` | `"info"` |
192+
| `Success` | `"success"` |
193+
| `Warning` | `"warning"` |
194+
| `Error` | `"error"` |
195+
| `Dark` | `"dark"` |
196+
| `Light` | `"light"` |
197+
| `Inverse` | `"inverse"` |
198+
199+
>caption DropDownButton ThemeColor example
200+
201+
````CSHTML
202+
<p>DropDownButton ThemeColor</p>
203+
204+
@foreach (var item in ThemeColors)
205+
{
206+
var themeColor = item.GetValue(null).ToString();
207+
208+
<TelerikDropDownButton ThemeColor="@themeColor">
209+
<DropDownButtonContent> @themeColor </DropDownButtonContent>
210+
<DropDownButtonItems>
211+
<DropDownButtonItem> secondary </DropDownButtonItem>
212+
</DropDownButtonItems>
213+
</TelerikDropDownButton>
214+
}
215+
216+
@code {
217+
private List<System.Reflection.FieldInfo> ThemeColors { get; set; }
218+
219+
protected override void OnInitialized()
220+
{
221+
ThemeColors = typeof(ThemeConstants.DropDownButton.ThemeColor)
222+
.GetFields().ToList();
223+
224+
base.OnInitialized();
225+
}
226+
}
227+
````
228+
229+
@[template](/_contentTemplates/common/themebuilder-section.md#appearance-themebuilder)
230+
231+
## Next Steps
232+
233+
* [Handle DropDownButton Events]({%slug dropdownbutton-events%})
234+
* [Add DropDownButton Icons]({%slug dropdownbutton-icons%})
235+
236+
237+
## See Also
238+
239+
* [Live Demo: DropDownButton Appearance](https://demos.telerik.com/blazor-ui/dropdownbutton/appearance)
240+
* [DropDownButton API](/blazor-ui/api/Telerik.Blazor.Components.TelerikDropDownButton)

‎components/dropdownbutton/events.md

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
title: Events
3+
page_title: DropDownButton - Events
4+
description: Explore the events that the DropDownButton for Blazor fires. See how you can handle the OnClick of the primary button and the secondary items to respond to the user action.
5+
slug: dropdownbutton-events
6+
tags: telerik,blazor,dropdownbutton,events
7+
published: True
8+
position: 15
9+
---
10+
11+
# DropDownButton Events
12+
13+
The DropDownButton exposes an `OnClick` event that you can use to initiate an action within the application.
14+
15+
The `OnClick` event fires when the user clicks or taps the primary button or a secondary button. The primary `<TelerikDropDownButton>` and each of its `<DropDownButtonItem>` instances execute a separate `OnClick` handler.
16+
17+
The event argument type is [`MouseEventArgs`](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.components.web.mouseeventargs).
18+
19+
The event handler can be synchronous (`void`) or asynchronous (`async Task`).
20+
21+
>caption Handling the DropDownButton OnClick event
22+
23+
````CSHTML
24+
@clickedItemInfo
25+
<br />
26+
@moreInfo
27+
28+
<br />
29+
<TelerikDropDownButton Icon="@SvgIcon.Clipboard" OnClick="@((args) => OnItemClick("Primary", args))">
30+
<DropDownButtonContent>Paste</DropDownButtonContent>
31+
32+
<DropDownButtonItems>
33+
<DropDownButtonItem Icon="@SvgIcon.ClipboardText" OnClick="@((args) => OnItemClick("Paste Text", args))">Paste Text</DropDownButtonItem>
34+
<DropDownButtonItem Icon="@SvgIcon.ClipboardCode" OnClick="@((args) => OnItemClick("Paste as HTML", args))">Paste as HTML</DropDownButtonItem>
35+
<DropDownButtonItem Icon="@SvgIcon.ClipboardMarkdown" OnClick="@((args) => OnItemClick("Paste Markdown", args))">Paste Markdown</DropDownButtonItem>
36+
<DropDownButtonItem OnClick="@((args) => OnItemClick("Set Default Paste", args))">Set Default Paste</DropDownButtonItem>
37+
</DropDownButtonItems>
38+
39+
</TelerikDropDownButton>
40+
41+
@code {
42+
private string clickedItemInfo;
43+
44+
private string moreInfo;
45+
46+
private void OnItemClick(string item, MouseEventArgs args)
47+
{
48+
clickedItemInfo = $"User clicked the {item} option.";
49+
50+
moreInfo = "Ctrl was pressed when clicking the primary button: " + args.CtrlKey;
51+
}
52+
}
53+
````
54+
55+
56+
## See Also
57+
58+
* [DropDownButton API](/blazor-ui/api/Telerik.Blazor.Components.TelerikDropDownButton)
59+
* [Live Demo: DropDownButton](https://demos.telerik.com/blazor-ui/dropdownbutton/overview)

‎components/dropdownbutton/icons.md

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
title: Icons
3+
page_title: DropDownButton - Icons
4+
description: Explore how to use icons with the DropDownButton for Blazor. See how you can add icons in the primary button and in the secondary action items. Revise the supported icon types that you can use.
5+
slug: dropdownbutton-icons
6+
tags: telerik,blazor,dropdownbutton,icons
7+
published: True
8+
position: 5
9+
---
10+
11+
# DropDownButton Icons
12+
13+
The `<TelerikDropDownButton>` and `<DropDownButtonItem>` provide an `Icon` parameter that allows you to add an icon to the main button and all secondary action items.
14+
15+
The `Icon` parameter type is `object` and it accepts:
16+
17+
* a member of the [`FontIcon` enum]({%slug general-information/font-icons%}#icons-list)
18+
* a property of the static [`SvgIcon` class]({%slug general-information/font-icons%}#icons-list)
19+
* a `string` that is a CSS class for a custom icon
20+
21+
>caption How to use icons in Telerik Blazor DropDownButton
22+
23+
````CSHTML
24+
<TelerikDropDownButton Icon="@FontIcon.User">
25+
<DropDownButtonContent>Telerik Font Icon</DropDownButtonContent>
26+
<DropDownButtonItems>
27+
<DropDownButtonItem Icon="@SvgIcon.Gear">Telerik SVG Icon</DropDownButtonItem>
28+
<DropDownButtonItem Icon="@CustomIconClass">Custom Icon</DropDownButtonItem>
29+
<DropDownButtonItem> <TelerikLoader /> Custom markup </DropDownButtonItem>
30+
</DropDownButtonItems>
31+
</TelerikDropDownButton>
32+
33+
<style>
34+
/* Third-party icon libraries should provide these styles out-of-the-box. */
35+
36+
.my-icon {
37+
width: 1em;
38+
height: 1em;
39+
font-size: 16px;
40+
background: purple;
41+
}
42+
</style>
43+
44+
@code {
45+
private string CustomIconClass { get; set; } = "my-icon";
46+
}
47+
````
48+
49+
## Best Practices for Custom Icons and Images
50+
51+
* You can add custom icons and images through additional markup inside the `<DropDownButtonContent>`, where the text is.
52+
53+
* Images used as icons should generally be small enough to fit in a line of text. The primary button is an inline element and is not designed for large images. If you want to use big icon buttons, consider one of the following options:
54+
55+
* Define a `Class` for the button that provides `height` and `width`. The width and height can be set to `auto` or to a value in `px`. When using a static value, it must be sufficient to accommodate the icon.
56+
* Adding your own HTML inside the `<DropDownButtonContent>`, something like: `<DropDownButtonContent><img style="width: 400px; height: 400px;" src="my-icon.svg" />some text</DropDownButtonContent>`
57+
58+
59+
## See Also
60+
61+
* [Live Demo: DropDownButton Overview](https://demos.telerik.com/blazor-ui/dropdownbutton/overview)
62+
* [DropDownButton API](/blazor-ui/api/Telerik.Blazor.Components.TelerikDropDownButton)

0 commit comments

Comments
 (0)