Skip to content

Commit 9ae9391

Browse files
dimodiDimo Dimov
dimodi
and
Dimo Dimov
authored
Colorpicker and ColorGradient documentation (#533)
* docs(colorgradient): Add ColorGradient documentation * docs(colorpicker): Add ColorPicker documentation draft * docs(colorpicker): Finish ColorPicker documentation * docs: Update ColorGradient and ColorPalette documentation Co-authored-by: Dimo Dimov <[email protected]>
1 parent 612918e commit 9ae9391

File tree

10 files changed

+426
-1
lines changed

10 files changed

+426
-1
lines changed

‎_config.yml

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -270,8 +270,11 @@ navigation:
270270
title: "Checkbox"
271271
"*chunkprogressbar":
272272
title: "ChunkProgressBar"
273+
"*colorgradient":
274+
title: "ColorGradient"
275+
isNew: true
273276
"*colorpalette":
274-
title: "Color Palette"
277+
title: "ColorPalette"
275278
isNew: true
276279
"*colorpicker":
277280
title: "ColorPicker"

‎_contentTemplates/common/coloreditors.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
#value-formats
2+
3+
* Hexadecimal
4+
* 3 digits - `#f00`
5+
* 6 digits - `#ff0000`
6+
* 8 digits, including alpha opacity - `#ff000080`
7+
* RGB or RGBA
8+
* integer color values - `rgb(255, 0, 0)`
9+
* percentage color values - `rgb(100%, 0%, 0%)`
10+
* the alpha opacity must always be a decimal number between 0 and 1 - `rgba(100%, 0%, 0%, 0.5)`. Note the `rgba()` notation, compared to `rgb()` above.
11+
12+
Users can type values in the following formats:
13+
14+
* All hexadecimal
15+
* RGB and RGBA with integer color values
16+
17+
#end

‎components/colorgradient/events.md

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
title: Events
3+
page_title: Events | ColorGradient for Blazor
4+
description: Events in the ColorGradient for Blazor.
5+
slug: colorgradient-events
6+
tags: telerik,blazor,colorgradient,events
7+
published: true
8+
position: 10
9+
---
10+
11+
# ColorGradient Events
12+
13+
This article describes the available events of the Telerik ColorGradient for Blazor.
14+
15+
* [FormatChanged](#formatchanged)
16+
* [ValueChanged](#valuechanged)
17+
18+
19+
## FormatChanged
20+
21+
The `FormatChanged` event fires when the user clicks on the toggle button, which changes the input format. The event can help you persist the selected `Format` at a later stage.
22+
23+
When using this event, make sure to update the component `Format` programmatically in the event handler.
24+
25+
>caption Handle the ColorGradient FormatChanged event
26+
27+
````CSHTML
28+
@* Handle the ColorGradient FormatChanged event *@
29+
30+
<TelerikColorGradient
31+
@bind-Value="@Value"
32+
Format="@Format"
33+
FormatChanged="@FormatChangedHandler" />
34+
35+
@code {
36+
string Value { get; set; }
37+
ColorFormat Format { get; set; }
38+
39+
async Task FormatChangedHandler(ColorFormat newFormat)
40+
{
41+
Format = newFormat;
42+
}
43+
}
44+
````
45+
46+
## ValueChanged
47+
48+
The `ValueChanged` event fires continuously while the user is dragging the component handles, or changing the textbox values.
49+
50+
When using this event, make sure to update the component `Value` programmatically in the event handler.
51+
52+
>caption Handle the ColorGradient ValueChanged event
53+
54+
````CSHTML
55+
@* Handle the ColorGradient ValueChanged event *@
56+
57+
<TelerikColorGradient
58+
Value="@Value"
59+
ValueChanged="@ValueChangedHandler" />
60+
61+
@code {
62+
string Value { get; set; }
63+
64+
async Task ValueChangedHandler(string newValue)
65+
{
66+
Value = newValue;
67+
}
68+
}
69+
70+
````
71+
72+
73+
## See Also
74+
75+
* [ColorGradient Overview]({%slug colorgradient-overview%})
76+
* [ColorGradient Live Demo](https://demos.telerik.com/blazor-ui/colorgradient/overview)

‎components/colorgradient/images/colorgradient-overview.png

122 KB
Loading

‎components/colorgradient/overview.md

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
title: Overview
3+
page_title: Overview | ColorGradient for Blazor
4+
description: Overview of the ColorGradient for Blazor.
5+
slug: colorgradient-overview
6+
tags: telerik,blazor,colorgradient,overview
7+
published: True
8+
position: 0
9+
---
10+
11+
# ColorGradient Overview
12+
13+
The <a href = "https://www.telerik.com/blazor-ui/colorgradient" target="_blank">ColorGradient for Blazor</a> enables users to select a color from an [HSVA](https://en.wikipedia.org/wiki/HSL_and_HSV) canvas, or to type a specific RGB/HEX color value. Compared to our [ColorPalette component]({%slug colorpalette-overview%}), the ColorGradient allows selection from unlimited number of colors. It may also be preferred by advanced users.
14+
15+
#### In this article:
16+
* [Basics](#basics)
17+
* [Example](#example)
18+
* [Features](#features)
19+
* [Using Multiple Input Formats](#using-multiple-input-formats)
20+
* [Supported Value Formats](#supported-value-formats)
21+
22+
## Basics
23+
24+
To use a Telerik ColorGradient for Blazor:
25+
26+
1. Add the `TelerikColorGradient` tag.
27+
1. Set its `Value` attribute to a [HEX/RGB](#supported-value-formats) `string` variable via [one-way]({%slug colorgradient-events%}#valuechanged) or [two-way](#example) binding.
28+
1. (optional) Set the [`ValueFormat` and `Format` attrbutes](#features) to the desired color format.
29+
30+
## Example
31+
32+
Here is a ColorGradient declaration and the resulting UI.
33+
34+
````CSHTML
35+
@* Blazor ColorGradient *@
36+
37+
<TelerikColorGradient @bind-Value="@Value" />
38+
39+
@code {
40+
string Value { get; set; } = "rgb(40, 47, 137)";
41+
}
42+
````
43+
44+
>caption The snippet will produce the following result:
45+
![ColorGradient component](images/colorgradient-overview.png)
46+
47+
## Features
48+
49+
The ColorGradient exposes the following features via its attributes:
50+
51+
* `Value` - `string` - sets the ColorGradient value in a few [different color formats](#supported-value-formats). Supports two-way binding.
52+
* `Formats` - `IEnumerable<ColorFormat>` - defines the available color formats, which the user **can see, toggle and edit** by typing. Both `Hex` and `Rgb` formats are enabled by default and the user can switch between them with a button.
53+
* `Format` - `ColorFormat` - specifies the value format, which the users **sees initially** (`ColorFormat.Rgb` by default). Supports two-way binding. The `Rgb` input format allows changing the textbox values with the Up/Down arrow keys.
54+
* `ValueFormat` - `ColorFormat` - sets the color format, which the **component will return** in the application code (`ColorFormat.Rgb` by default).
55+
* `ShowOpacityEditor` - `bool` - specifies if the user can add opacity (transparency) to the color value (`true` by default).
56+
57+
## Supported Value Formats
58+
59+
The ColorGradient accepts values by the application code in the following formats:
60+
61+
@[template](/_contentTemplates/common/coloreditors.md#value-formats)
62+
63+
Color keywords are not supported. If this is the preferred use case scenario, consider the [ColorPalette component]({%slug colorpalette-overview%}).
64+
65+
## See Also
66+
67+
* [ColorGradient Events]({%slug colorgradient-events%})
68+
* [ColorGradient Live Demo](https://demos.telerik.com/blazor-ui/colorgradient/overview)

‎components/colorpalette/overview.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ position: 0
1212

1313
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.
1414

15+
If unlimited choice of colors is preferred, consider the [ColorGradient component]({%slug colorgradient-overview%}) instead.
16+
1517
## Basics
1618

1719
To use a Telerik Color Palette for Blazor:

‎components/colorpicker/events.md

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
title: Events
3+
page_title: Events | ColorPicker for Blazor
4+
description: Events in the ColorPicker for Blazor.
5+
slug: colorpicker-events
6+
tags: telerik,blazor,colorpicker,events
7+
published: true
8+
position: 20
9+
---
10+
11+
# ColorPicker Events
12+
13+
This article describes the available events of the Telerik ColorPicker for Blazor.
14+
15+
* [OnChange](#onchange)
16+
* [ValueChanged](#valuechanged)
17+
* [ViewChanged](#viewchanged)
18+
19+
## OnChange
20+
21+
The `OnChange` event fires when the user commits their selection with:
22+
23+
* Apply or Cancel button click
24+
* Enter keypress
25+
* Blur action (popup close)
26+
27+
Note that the `OnChange` event may also fire when the actual selected color has not changed.
28+
29+
The event type is `EventCallback<object>`. The `OnChange` event does not prevent two-way binding for the `Value` attribute.
30+
31+
````CSHTML
32+
@* Handle the ColorPicker OnChange event *@
33+
34+
<p>@EventLog</p>
35+
36+
<TelerikColorPicker @bind-Value="@Color" OnChange="@ColorPickerOnChange" />
37+
38+
@code {
39+
string Color { get; set; }
40+
string EventLog { get; set; }
41+
42+
async Task ColorPickerOnChange(object newColor)
43+
{
44+
EventLog = string.Format("The selected color is: {0}", (string)newColor);
45+
}
46+
}
47+
````
48+
49+
## ValueChanged
50+
51+
The `ValueChanged` event fires when the user selects a new color and the component value changes.
52+
53+
The event type is `EventCallback<string>`. Using `ValueChanged` requires one-way binding for the `Value` attribute and manual value update in the event handler.
54+
55+
````CSHTML
56+
@* Handle the ColorPicker ValueChanged event *@
57+
58+
<TelerikColorPicker Value="@Color" ValueChanged="@ColorPickerValueChanged" />
59+
60+
@code {
61+
string Color { get; set; }
62+
63+
async Task ColorPickerValueChanged(string newColor)
64+
{
65+
Color = newColor;
66+
}
67+
}
68+
````
69+
70+
## ViewChanged
71+
72+
The `ViewChanged` event fires when the user toggles between the popup views.
73+
74+
The event type is `EventCallback<ColorPickerView>`. Using `ViewChanged` requires one-way binding for the `View` attribute and manual value update in the event handler.
75+
76+
````CSHTML
77+
@* Handle the ColorPicker ViewChanged event *@
78+
79+
<TelerikColorPicker @bind-Value="@Color" View="@View" ViewChanged="@ColorPickerViewChanged" />
80+
81+
@code {
82+
string Color { get; set; }
83+
ColorPickerView View { get; set; }
84+
85+
async Task ColorPickerViewChanged(ColorPickerView newView)
86+
{
87+
View = newView;
88+
}
89+
}
90+
````
91+
92+
## See Also
93+
94+
* [ColorPicker Overview]({%slug colorpicker-overview%})
95+
* [ColorPicker Views]({%slug colorpicker-views%})

‎components/colorpicker/images/colorpicker-overview.gif

1.03 MB
Loading

‎components/colorpicker/overview.md

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
title: Overview
3+
page_title: Overview | ColorPicker for Blazor
4+
description: Overview of the ColorPicker for Blazor.
5+
slug: colorpicker-overview
6+
tags: telerik,blazor,colorpicker,overview
7+
published: True
8+
position: 0
9+
---
10+
11+
# ColorPicker Overview
12+
13+
The <a href = "https://www.telerik.com/blazor-ui/colorpicker" target="_blank">ColorPicker for Blazor</a> is an interactive component that allows color selection from a popup palette or a [HSVA](https://en.wikipedia.org/wiki/HSL_and_HSV) canvas. Users can also type a specific RGB/HEX color value manually.
14+
15+
#### In this article:
16+
* [Basics](#basics)
17+
* [Example](#example)
18+
* [Interface](#interface)
19+
* [Features](#features)
20+
* [Supported Value Formats](#supported-value-formats)
21+
22+
## Basics
23+
24+
To use a Telerik ColorPicker for Blazor:
25+
26+
1. Add the `TelerikColorPicker` tag.
27+
1. Set its `Value` attribute to any of the [supported HEX/RGB formats](#supported-value-formats). Use a `string` property with [one-way]({%slug colorpicker-events%}#valuechanged) or [two-way](#example) binding.
28+
1. (optional) Set the `ValueFormat` to `ColorFormat.Hex` or `ColorFormat.Rgb` if the app expects a specific color format.
29+
30+
## Example
31+
32+
Here is a simple ColorPicker declaration and the resulting UI.
33+
34+
````CSHTML
35+
@* Blazor ColorPicker *@
36+
37+
<TelerikColorPicker @bind-Value="@Color" />
38+
39+
@code {
40+
string Color { get; set; } = "rgb(40, 47, 137)";
41+
}
42+
````
43+
44+
## Interface
45+
46+
The image below reveals all ColorPicker interface elements:
47+
48+
* Main component button with the current value and a dropdown arrow (outside the popup)
49+
* View selectors (top left)
50+
* Color preview box (top right)
51+
* Current color box (below the color preview)
52+
* Clear button (top)
53+
* Palette tiles or HSV canvas with hue and opacity sliders (middle)
54+
* RGBA or HEX value textboxes (bottom)
55+
* Apply and Cancel buttons (bottom)
56+
57+
Clicking outside the ColorPicker popup acts as an **Apply** action.
58+
59+
![ColorPicker component](images/colorpicker-overview.gif)
60+
61+
## Features
62+
63+
The ColorPicker tag exposes the following features via its attributes:
64+
65+
* `Value` - `string` - sets the ColorPicker value in a few [different color formats](#supported-value-formats). Supports two-way binding.
66+
* `ValueFormat` - `ColorFormat` - sets the color format, which the component will return in the application code. By default, the property is not set and the value format will change depending on the used view: `Rgb` when selecting a color from the GradientView, and `Hex` when selecting a color from the PaletteView.
67+
* `ColorPickerViews` - `RenderFragment` - a nested container to list the [ColorPicker views]({%slug colorpicker-views%}). All views are enabled by default and the user can switch between them with buttons. Each view tag has its own configuration attributes.
68+
* `View` - `ColorPickerView` - sets the default selected [view]({%slug colorpicker-views%}) (`ColorPickerView.Gradient` by default). Supports two-way binding.
69+
* `ShowPreview` - `bool` - toggles the [current color box and the color preview box](#interface) in the popup (`true` by default).
70+
71+
* `Class` - `string` - renders a custom CSS class to the `span.k-colorpicker` element.
72+
* `Enabled` - `bool` - determines if the user can open the popup and change the value (`true` by default).
73+
74+
### Buttons
75+
76+
* `ShowButtons` - `bool` - sets the visibility of the Apply and Cancel buttons (`true` by default).
77+
* `ClearButton` - `bool` - sets the visibility of the Clear button.
78+
79+
### Custom Icon
80+
81+
The ColorPicker provides attributes to render an icon or image inside the [main component button](#interface). This icon can be used to visually distinguish different ColorPickers on the page. In such cases, the selected color is displayed below the icon.
82+
83+
Use one attribute at a time:
84+
85+
* `Icon` - `string` - specifies a [built-in font icon class]({%slug general-information/font-icons%}).
86+
* `ImageUrl` - `string` - specifies an URL for an image.
87+
* `IconClass` - `string` - sets a custom icon class.
88+
89+
90+
## Supported Value Formats
91+
92+
The ColorPicker accepts values by the application code in the following formats:
93+
94+
@[template](/_contentTemplates/common/coloreditors.md#value-formats)
95+
96+
Color keywords are not supported.
97+
98+
## See Also
99+
100+
* [ColorPicker Views]({%slug colorpicker-views%})
101+
* [ColorPicker Events]({%slug colorpicker-events%})
102+
* [ColorPicker Live Demo](https://demos.telerik.com/blazor-ui/colorpicker/overview)

0 commit comments

Comments
 (0)