diff --git a/_config.yml b/_config.yml index be82a353a0..1e6e61f0ac 100644 --- a/_config.yml +++ b/_config.yml @@ -219,7 +219,8 @@ navigation: "*chunkprogressbar": title: "ChunkProgressBar" "*colorpalette": - title: "ColorPalette" + title: "Color Palette" + isNew: true "*colorpicker": title: "ColorPicker" "*/multicolumncombobox": @@ -405,6 +406,7 @@ intro_columns: "HTML Editor": "editor-overview" "Slider": "slider-overview" "RangeSlider": "rangeslider-overview" + "Color Palette": "colorpalette-overview" - categories: diff --git a/accessibility/keyboard-navigation.md b/accessibility/keyboard-navigation.md index 2417045671..c4adbc7f93 100644 --- a/accessibility/keyboard-navigation.md +++ b/accessibility/keyboard-navigation.md @@ -32,6 +32,8 @@ The following list shows the Telerik components that support specific keyboard c * ChunkProgressBar - not applicable, it is merely a visualization component the user cannot interact with. +* [Color Palette](https://demos.telerik.com/blazor-ui/colorpalette/keyboard-navigation) + * [Context Menu](https://demos.telerik.com/blazor-ui/contextmenu/keyboard-navigation) * [ComboBox](https://demos.telerik.com/blazor-ui/combobox/keyboard-navigation) diff --git a/common-features/input-validation.md b/common-features/input-validation.md index eade14bb80..ae4bdfeee3 100644 --- a/common-features/input-validation.md +++ b/common-features/input-validation.md @@ -30,6 +30,7 @@ This article provides examples of validating the Telerik Blazor components. The * [Editor](#editor) * [MaskedTextbox](#maskedtextbox) * [Sliders](#sliders) +* [Color Palette](#color-palette) >tip Telerik offers the [Form Component]({%slug form-overview%}) that lets you generate and manage forms with predefined layouts and less code. @@ -712,6 +713,41 @@ The sliders are, effectively, numeric inputs in terms of behavior and what data ```` +## Color Palette + +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. + +````CSHTML +@using System.ComponentModel.DataAnnotations @* This Using is for the model class attributes only *@ + + + + + + + + + + Submit + + + +@code { + ColorValidationModel validationModel { get; set; } = new ColorValidationModel(); + + class ColorValidationModel + { + [Required] + public string FavoriteColor { get; set; } + } + + async void HandleValidSubmit() + { + Console.WriteLine("valid submit"); + } +} +```` + ## See Also diff --git a/components/colorpalette/custom-colors.md b/components/colorpalette/custom-colors.md new file mode 100644 index 0000000000..3ef2a50151 --- /dev/null +++ b/components/colorpalette/custom-colors.md @@ -0,0 +1,40 @@ +--- +title: Custom Colors +page_title: Color Palette - Custom Colors +description: Custom Colors in the Color Palette for Blazor. +slug: colorpalette-custom-colors +tags: telerik,blazor,Color,Palette,Custom,Colors +published: true +position: 15 +--- + +# Custom Colors + +You can provide your own set of colors to the Blazor Color Palette component. You can use a valid CSS color, and pass a `IEnumerable` to the `Colors` parameter. + +>caption Custom collection of colors in the Color Palette component + +````CSHTML +@MyColor +
+ + + + +@code { + string MyColor { get; set; } + List MyCustomColorList { get; set; } = new List { "red", "#0f0", "#0000ff" }; +} +```` + +>caption The result from the code snippet above + +![custom color collections](images/custom-color-palette.png) + + + + +## See Also + +* [Color Paletter Overview]({%slug colorpalette-overview%}) +* [Predefined Color Lists]({%slug colorpalette-presets%}) diff --git a/components/colorpalette/events.md b/components/colorpalette/events.md new file mode 100644 index 0000000000..09208c94be --- /dev/null +++ b/components/colorpalette/events.md @@ -0,0 +1,108 @@ +--- +title: Events +page_title: Color Palette - Events +description: Events in the Color Palette for Blazor. +slug: colorpalette-events +tags: telerik,blazor,Color,Palette,events +published: true +position: 50 +--- + +# Events + +This article explains the events available in the Telerik Color Palette for Blazor: + + +* [OnChange](#onchange) +* [ValueChanged](#valuechanged) +* [OnBlur](#onblur) + +## OnChange + +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`. + +>caption Handle OnChange and use two-way binding for the Value + +````CSHTML +@MyColor +
+ + + + +@code { + string MyColor { get; set; } + + async Task OnChangeHandler(object color) + { + string selectedColor = (string)color; + Console.WriteLine($"two-way binding: {MyColor}, event argument: {selectedColor}"); + } +} +```` + +@[template](/_contentTemplates/common/general-info.md#event-callback-can-be-async) + +>tip The `OnChange` event is a custom event and does not interfere with bindings, so you can use it together with models and forms. + + +## ValueChanged + +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`. + +>caption Handle ValueChanged + +````CSHTML +@MyColor +
+ + + + +@code { + string MyColor { get; set; } + + async Task ValueChangedHandler(string color) + { + // make sure to update the view-model. If you don't, you will effectively cancel the event + MyColor = color; + + Console.WriteLine($"The user selected the color {MyColor}"); + } +} +```` + +@[template](/_contentTemplates/common/general-info.md#event-callback-can-be-async) + + + + +## OnBlur + +The `OnBlur` event fires when the component loses focus. + +>caption Handle the OnBlur event + +````CSHTML +@* You do not have to use OnChange to react to loss of focus *@ + +@MyColor +
+ + + + +@code { + string MyColor { get; set; } + + async Task OnBlurHandler() + { + Console.WriteLine($"Lost focus. The color is {MyColor}"); + } +} +```` + +## See Also + +* [ValueChanged and Validation]({%slug value-changed-validation-model%}) +* [Fire OnChange Only Once]({%slug ddl-kb-onchange-fires-twice%}) diff --git a/components/colorpalette/images/color-palette-first-look.png b/components/colorpalette/images/color-palette-first-look.png new file mode 100644 index 0000000000..c3b53444f9 Binary files /dev/null and b/components/colorpalette/images/color-palette-first-look.png differ diff --git a/components/colorpalette/images/colorpalette-presets.png b/components/colorpalette/images/colorpalette-presets.png new file mode 100644 index 0000000000..44b5033dca Binary files /dev/null and b/components/colorpalette/images/colorpalette-presets.png differ diff --git a/components/colorpalette/images/custom-color-palette.png b/components/colorpalette/images/custom-color-palette.png new file mode 100644 index 0000000000..85a070e9a0 Binary files /dev/null and b/components/colorpalette/images/custom-color-palette.png differ diff --git a/components/colorpalette/images/large-size-few-columns.png b/components/colorpalette/images/large-size-few-columns.png new file mode 100644 index 0000000000..344b2e1319 Binary files /dev/null and b/components/colorpalette/images/large-size-few-columns.png differ diff --git a/components/colorpalette/overview.md b/components/colorpalette/overview.md new file mode 100644 index 0000000000..50c1ec1a71 --- /dev/null +++ b/components/colorpalette/overview.md @@ -0,0 +1,109 @@ +--- +title: Overview +page_title: Color Palette Overview +description: Overview of the Color Palette for Blazor. +slug: colorpalette-overview +tags: telerik,blazor,masked,Color,Palette,overview +published: True +position: 0 +--- + +# Color Palette Overview + +The Blazor Color Palette component 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. + +## Basics + +To use a Telerik Color Palette for Blazor: + +1. Add the `` tag. +1. Bind its `Value` to the `string` you want to get out of it. +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%})). + * If you do not provide a value for the `Colors`, it will default to the `Office` [preset]({%slug colorpalette-presets%}). + +>caption Basic color palette with two-way value binding and a default predefined palette + +````CSHTML +@MyColor +
+ + + + +@code { + public string MyColor { get; set; } +} +```` + +>caption The result from the code snippet above after selecting a color + +![Color Palette first look](images/color-palette-first-look.png) + +## Appearance + +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. + +>caption Make a large color palette with few columns + +````CSHTML +@SelectedColor + + +@code{ + string SelectedColor { get; set; } +} +```` + +>caption Theresult from the code snippet above + +![color palette appearance and size customization](images/large-size-few-columns.png) + + + +## Component Reference + +````CSHTML + + +@code{ + Telerik.Blazor.Components.TelerikColorPalette TheColorPaletteRef { get; set; } +} +```` + +## Features + +>caption The Color Palette provides the following features: + +* `Class` - the CSS class that will be rendered on the wrapping element of the component. + +* `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%}). + +* `Columns` - the number of columns to use when rendering the Colors list. Determines the size of the component together with the `TileHeight` and `TileWidth`. + +* `Enabled` - whether the component is enabled. + +* `Id` - renders as the `id` attribute on the wrapping element of the component. + +* `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. + +* `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 + +* `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 + +* `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`). + +* [Events]({%slug colorpalette-events%}) to let you react to the user actions. + +* Validation - see the [Input Validation]({%slug common-features/input-validation%}) article. + + + + + +## See Also + + * [Live Demo: Color Palette](https://demos.telerik.com/blazor-ui/colorpalette/overview) + * [Color Presets]({%slug colorpalette-presets%}) + * [Custom Color Collections]({%slug colorpalette-custom-colors%}) + * [API Reference](https://docs.telerik.com/blazor-ui/api/Telerik.Blazor.Components.TelerikColorPalette) diff --git a/components/colorpalette/presets.md b/components/colorpalette/presets.md new file mode 100644 index 0000000000..a0be4a226b --- /dev/null +++ b/components/colorpalette/presets.md @@ -0,0 +1,49 @@ +--- +title: Presets +page_title: Color Palette - Presets +description: Predefined Color Presets in the Color Palette for Blazor. +slug: colorpalette-presets +tags: telerik,blazor,Color,Palette,Predefined,Colors,Presets +published: true +position: 14 +--- + +# Predefined Colors + +The Telerik Blazor Color Palette component comes with a set of predefined color sets that you can show your users. To use them, set its `Colors` parameter to one of the members of the `Telerik.Blazor.Components.ColorPalettePresets` static class. + +>caption Example of using a predefined color list + +````CSHTML +@SelectedColor + +@code{ + string SelectedColor { get; set; } +} +```` + +>caption List of the built-in color presets in the Telerik Color Palette + +![Color Palette component Presets](images/colorpalette-presets.png) + +>caption Explore the predefined color presets - generates the image above + +````CSHTML +
+ @foreach (System.Reflection.FieldInfo item in typeof(ColorPalettePresets).GetFields()) + { + List currPreset = (List)item.GetValue(null); + string presetName = item.Name; +
+
@presetName
+ +
+ } +
+```` + + +## See Also + +* [Color Paletter Overview]({%slug colorpalette-overview%}) +* [Custom Color Lists]({%slug colorpalette-custom-colors%})