Skip to content

Commit 7f010ae

Browse files
marin-bratanovmarin-bratanov
authored
colorPalette initial docs (#256)
* chore(colorPalette): skeleton * chore: cross link, fix article name * docs(colorPalette): meat in the overview article * docs(colorPalette): presets * docs(colorPalette): more meat on overview * docs(colorPalette): custom color lists * docs(colorPalete): events * chore(colorPalete): link from kbd nav * docs(colorPalette): validation example * chore(colorPalette): update screenshots
1 parent 19455c2 commit 7f010ae

File tree

11 files changed

+347
-1
lines changed

11 files changed

+347
-1
lines changed

‎_config.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -219,7 +219,8 @@ navigation:
219219
"*chunkprogressbar":
220220
title: "ChunkProgressBar"
221221
"*colorpalette":
222-
title: "ColorPalette"
222+
title: "Color Palette"
223+
isNew: true
223224
"*colorpicker":
224225
title: "ColorPicker"
225226
"*/multicolumncombobox":
@@ -405,6 +406,7 @@ intro_columns:
405406
"HTML Editor": "editor-overview"
406407
"Slider": "slider-overview"
407408
"RangeSlider": "rangeslider-overview"
409+
"Color Palette": "colorpalette-overview"
408410

409411
-
410412
categories:

‎accessibility/keyboard-navigation.md‎

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

3333
* ChunkProgressBar - not applicable, it is merely a visualization component the user cannot interact with.
3434

35+
* [Color Palette](https://demos.telerik.com/blazor-ui/colorpalette/keyboard-navigation)
36+
3537
* [Context Menu](https://demos.telerik.com/blazor-ui/contextmenu/keyboard-navigation)
3638

3739
* [ComboBox](https://demos.telerik.com/blazor-ui/combobox/keyboard-navigation)

‎common-features/input-validation.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ This article provides examples of validating the Telerik Blazor components. The
3030
* [Editor](#editor)
3131
* [MaskedTextbox](#maskedtextbox)
3232
* [Sliders](#sliders)
33+
* [Color Palette](#color-palette)
3334

3435
>tip Telerik offers the [Form Component]({%slug form-overview%}) that lets you generate and manage forms with predefined layouts and less code.
3536
@@ -712,6 +713,41 @@ The sliders are, effectively, numeric inputs in terms of behavior and what data
712713
````
713714

714715

716+
## Color Palette
717+
718+
The Color Palette component, while not an input, can work with validation so you can, for example, require that the user picks a color. Since it is not an input, it does not have an invalid state, but you can add validation messages around it.
719+
720+
````CSHTML
721+
@using System.ComponentModel.DataAnnotations @* This Using is for the model class attributes only *@
722+
723+
<EditForm Model="@validationModel" OnValidSubmit="@HandleValidSubmit">
724+
<DataAnnotationsValidator />
725+
<ValidationSummary />
726+
727+
<TelerikColorPalette @bind-Value="@validationModel.FavoriteColor" />
728+
729+
<ValidationMessage For="@(() => validationModel.FavoriteColor)" />
730+
731+
<TelerikButton ButtonType="@ButtonType.Submit">Submit</TelerikButton>
732+
733+
</EditForm>
734+
735+
@code {
736+
ColorValidationModel validationModel { get; set; } = new ColorValidationModel();
737+
738+
class ColorValidationModel
739+
{
740+
[Required]
741+
public string FavoriteColor { get; set; }
742+
}
743+
744+
async void HandleValidSubmit()
745+
{
746+
Console.WriteLine("valid submit");
747+
}
748+
}
749+
````
750+
715751

716752
## See Also
717753

‎components/colorpalette/custom-colors.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
title: Custom Colors
3+
page_title: Color Palette - Custom Colors
4+
description: Custom Colors in the Color Palette for Blazor.
5+
slug: colorpalette-custom-colors
6+
tags: telerik,blazor,Color,Palette,Custom,Colors
7+
published: true
8+
position: 15
9+
---
10+
11+
# Custom Colors
12+
13+
You can provide your own set of colors to the Blazor Color Palette component. You can use a <a href="https://css-tricks.com/almanac/properties/b/background-color/" target="_blank">valid CSS color</a>, and pass a `IEnumerable<string>` to the `Colors` parameter.
14+
15+
>caption Custom collection of colors in the Color Palette component
16+
17+
````CSHTML
18+
@MyColor
19+
<br />
20+
21+
<TelerikColorPalette Colors="@MyCustomColorList" @bind-Value="@MyColor">
22+
</TelerikColorPalette>
23+
24+
@code {
25+
string MyColor { get; set; }
26+
List<string> MyCustomColorList { get; set; } = new List<string> { "red", "#0f0", "#0000ff" };
27+
}
28+
````
29+
30+
>caption The result from the code snippet above
31+
32+
![custom color collections](images/custom-color-palette.png)
33+
34+
35+
36+
37+
## See Also
38+
39+
* [Color Paletter Overview]({%slug colorpalette-overview%})
40+
* [Predefined Color Lists]({%slug colorpalette-presets%})

‎components/colorpalette/events.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
---
2+
title: Events
3+
page_title: Color Palette - Events
4+
description: Events in the Color Palette for Blazor.
5+
slug: colorpalette-events
6+
tags: telerik,blazor,Color,Palette,events
7+
published: true
8+
position: 50
9+
---
10+
11+
# Events
12+
13+
This article explains the events available in the Telerik Color Palette for Blazor:
14+
15+
16+
* [OnChange](#onchange)
17+
* [ValueChanged](#valuechanged)
18+
* [OnBlur](#onblur)
19+
20+
## OnChange
21+
22+
The `OnChange` event represents a user action - confirmation of the current value. It fires when the user clicks, taps or presses `Enter` to select a color, or when the component loses focus. It does not prevent you from using two-way binding for the `Value`.
23+
24+
>caption Handle OnChange and use two-way binding for the Value
25+
26+
````CSHTML
27+
@MyColor
28+
<br />
29+
30+
<TelerikColorPalette @bind-Value="@MyColor" OnChange="@OnChangeHandler">
31+
</TelerikColorPalette>
32+
33+
@code {
34+
string MyColor { get; set; }
35+
36+
async Task OnChangeHandler(object color)
37+
{
38+
string selectedColor = (string)color;
39+
Console.WriteLine($"two-way binding: {MyColor}, event argument: {selectedColor}");
40+
}
41+
}
42+
````
43+
44+
@[template](/_contentTemplates/common/general-info.md#event-callback-can-be-async)
45+
46+
>tip The `OnChange` event is a custom event and does not interfere with bindings, so you can use it together with models and forms.
47+
48+
49+
## ValueChanged
50+
51+
The `ValueChanged` event fires upon every change (selection of color) in the component. Its main purpose is to provide two-way biding of the `Value`.
52+
53+
>caption Handle ValueChanged
54+
55+
````CSHTML
56+
@MyColor
57+
<br />
58+
59+
<TelerikColorPalette Value="@MyColor" ValueChanged="@ValueChangedHandler">
60+
</TelerikColorPalette>
61+
62+
@code {
63+
string MyColor { get; set; }
64+
65+
async Task ValueChangedHandler(string color)
66+
{
67+
// make sure to update the view-model. If you don't, you will effectively cancel the event
68+
MyColor = color;
69+
70+
Console.WriteLine($"The user selected the color {MyColor}");
71+
}
72+
}
73+
````
74+
75+
@[template](/_contentTemplates/common/general-info.md#event-callback-can-be-async)
76+
77+
78+
79+
80+
## OnBlur
81+
82+
The `OnBlur` event fires when the component loses focus.
83+
84+
>caption Handle the OnBlur event
85+
86+
````CSHTML
87+
@* You do not have to use OnChange to react to loss of focus *@
88+
89+
@MyColor
90+
<br />
91+
92+
<TelerikColorPalette @bind-Value="@MyColor" OnBlur="@OnBlurHandler">
93+
</TelerikColorPalette>
94+
95+
@code {
96+
string MyColor { get; set; }
97+
98+
async Task OnBlurHandler()
99+
{
100+
Console.WriteLine($"Lost focus. The color is {MyColor}");
101+
}
102+
}
103+
````
104+
105+
## See Also
106+
107+
* [ValueChanged and Validation]({%slug value-changed-validation-model%})
108+
* [Fire OnChange Only Once]({%slug ddl-kb-onchange-fires-twice%})

‎components/colorpalette/images/color-palette-first-look.png‎

5.12 KB
Loading

‎components/colorpalette/images/colorpalette-presets.png‎

34.7 KB
Loading

‎components/colorpalette/images/custom-color-palette.png‎

512 Bytes
Loading

‎components/colorpalette/images/large-size-few-columns.png‎

950 Bytes
Loading

‎components/colorpalette/overview.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
---
2+
title: Overview
3+
page_title: Color Palette Overview
4+
description: Overview of the Color Palette for Blazor.
5+
slug: colorpalette-overview
6+
tags: telerik,blazor,masked,Color,Palette,overview
7+
published: True
8+
position: 0
9+
---
10+
11+
# Color Palette Overview
12+
13+
The <a href = "https://www.telerik.com/blazor-ui/colorpalette" target="_blank">Blazor Color Palette component</a> provides a list of color tiles for the user to pick a color from by clicking or tapping. You can choose a [predefined list of colors]({%slug colorpalette-presets%}), or [create your own]({%slug colorpalette-custom-colors%}). Two-way binding and [events]({%slug colorpalette-events%}) let you react to the user choice.
14+
15+
## Basics
16+
17+
To use a Telerik Color Palette for Blazor:
18+
19+
1. Add the `<TelerikColorPalette>` tag.
20+
1. Bind its `Value` to the `string` you want to get out of it.
21+
1. Optionally, choose a list of `Colors` to show the user (one of the [presets we provide]({%slug colorpalette-presets%}), or a set of [custom colors]({%slug colorpalette-custom-colors%})).
22+
* If you do not provide a value for the `Colors`, it will default to the `Office` [preset]({%slug colorpalette-presets%}).
23+
24+
>caption Basic color palette with two-way value binding and a default predefined palette
25+
26+
````CSHTML
27+
<span style="color: @MyColor">@MyColor</span>
28+
<br />
29+
30+
<TelerikColorPalette @bind-Value="@MyColor">
31+
</TelerikColorPalette>
32+
33+
@code {
34+
public string MyColor { get; set; }
35+
}
36+
````
37+
38+
>caption The result from the code snippet above after selecting a color
39+
40+
![Color Palette first look](images/color-palette-first-look.png)
41+
42+
## Appearance
43+
44+
You can control the appearane of the component not only through the lists of `Colors` you provide to it, but also its size through the `Columns`, `TileWidth` and `TileHeight` parameters.
45+
46+
>caption Make a large color palette with few columns
47+
48+
````CSHTML
49+
@SelectedColor
50+
<TelerikColorPalette Colors="@ColorPalettePresets.Basic" @bind-Value="@SelectedColor"
51+
Columns="5" TileHeight="3em" TileWidth="3em">
52+
</TelerikColorPalette>
53+
@code{
54+
string SelectedColor { get; set; }
55+
}
56+
````
57+
58+
>caption Theresult from the code snippet above
59+
60+
![color palette appearance and size customization](images/large-size-few-columns.png)
61+
62+
63+
64+
## Component Reference
65+
66+
````CSHTML
67+
<TelerikColorPalette @ref="@TheColorPaletteRef"></TelerikColorPalette>
68+
69+
@code{
70+
Telerik.Blazor.Components.TelerikColorPalette TheColorPaletteRef { get; set; }
71+
}
72+
````
73+
74+
## Features
75+
76+
>caption The Color Palette provides the following features:
77+
78+
* `Class` - the CSS class that will be rendered on the wrapping element of the component.
79+
80+
* `Colors` - the collection of colors the user can choose from. Can be one of the [presets that come with the component]({%slug colorpalette-presets%}), or [a custom list]({%slug colorpalette-custom-colors%}).
81+
82+
* `Columns` - the number of columns to use when rendering the Colors list. Determines the size of the component together with the `TileHeight` and `TileWidth`.
83+
84+
* `Enabled` - whether the component is enabled.
85+
86+
* `Id` - renders as the `id` attribute on the wrapping element of the component.
87+
88+
* `TabIndex` - maps to the `tabindex` attribute of the main HTML element. You can use it to customize the order in which the elements in your page focus with the `Tab` key.
89+
90+
* `TileHeight` - the height of each individual color item. Determines the size of the component together with the `Columns` and `TileWidth`. Can take CSS [dimensions]({%slug common-features/dimensions%}) strings
91+
92+
* `TileWidth`- the width of each individual color item. Determines the size of the component together with the `Columns` and `TileHeight`. Can take CSS [dimensions]({%slug common-features/dimensions%}) strings
93+
94+
* `Value` - get/set the value of the input, can be used for binding. Can take any string that can be a [CSS background-color string](https://css-tricks.com/almanac/properties/b/background-color/). The presets we provide use hex format (`#123abc`).
95+
96+
* [Events]({%slug colorpalette-events%}) to let you react to the user actions.
97+
98+
* Validation - see the [Input Validation]({%slug common-features/input-validation%}) article.
99+
100+
101+
102+
103+
104+
## See Also
105+
106+
* [Live Demo: Color Palette](https://demos.telerik.com/blazor-ui/colorpalette/overview)
107+
* [Color Presets]({%slug colorpalette-presets%})
108+
* [Custom Color Collections]({%slug colorpalette-custom-colors%})
109+
* [API Reference](https://docs.telerik.com/blazor-ui/api/Telerik.Blazor.Components.TelerikColorPalette)

0 commit comments

Comments
 (0)