Skip to content

Commit 1492876

Browse files
xristianstefanovdimodi
xristianstefanov
and
dimodi
authored
docs(dialog):documentation for the dialog component (#617)
* docs(dialog):documentation for the dialog component * Update components/dialog/overview.md Co-authored-by: Dimo Dimov <[email protected]> * Update components/dialog/overview.md Co-authored-by: Dimo Dimov <[email protected]> * Update components/dialog/overview.md Co-authored-by: Dimo Dimov <[email protected]> * Update components/dialog/overview.md Co-authored-by: Dimo Dimov <[email protected]> * Update components/dialog/header.md Co-authored-by: Dimo Dimov <[email protected]> * Update components/dialog/header.md Co-authored-by: Dimo Dimov <[email protected]> * Update components/dialog/header.md Co-authored-by: Dimo Dimov <[email protected]> * Update components/dialog/action-buttons.md Co-authored-by: Dimo Dimov <[email protected]> * docs(dialog):added suggestions from the comments * docs(dialog):final changes per comments * docs(dialog):changed some words as per comment Co-authored-by: Dimo Dimov <[email protected]>
1 parent 4337e02 commit 1492876

File tree

9 files changed

+314
-1
lines changed

9 files changed

+314
-1
lines changed

‎components/dialog/action-buttons.md

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
title: Action Buttons
3+
page_title: Dialog Action Buttons
4+
description: Action Buttons of the Dialog for Blazor.
5+
slug: dialog-action-buttons
6+
tags: telerik,blazor,dialog,action,buttons
7+
published: True
8+
position: 7
9+
---
10+
11+
# Dialog Action Buttons
12+
13+
The Dialog provides options for rendering action buttons and customizing their text. The action buttons of the Dialog allow you to provide specific interaction to users. To specify action buttons in the Dialog, use the `DialogButtons` tag. You can customize the layout of the buttons by using the `ButtonsLayout` property.
14+
15+
## Example
16+
17+
The following example demonstrates all supported layout options for the action buttons.
18+
19+
>caption The result from the code snippet.
20+
21+
![](images/dialog-action-buttons.gif)
22+
23+
>caption The supported layouts for the action buttons in the Telerik Dialog.
24+
25+
````CSHTML
26+
@* An example of all the available layout options. *@
27+
28+
<TelerikDialog @ref="dialogRef" @bind-Visible="@Visible"
29+
Title="@Title"
30+
ButtonsLayout="SelectedBtnLayout">
31+
<DialogContent>
32+
<div>------- Please choose a layout: -------</div>
33+
<br/>
34+
<TelerikRadioGroup Data="@LayoutTypes" @bind-Value="@SelectedBtnLayout" OnChange="@OnChangeHandler"></TelerikRadioGroup>
35+
</DialogContent>
36+
<DialogButtons>
37+
<TelerikButton OnClick="@(() => { Visible = false; })">Cancel</TelerikButton>
38+
<TelerikButton OnClick="@(() => { Visible = false; })" Primary="true" >OK</TelerikButton>
39+
</DialogButtons>
40+
</TelerikDialog>
41+
42+
@code {
43+
TelerikDialog dialogRef;
44+
private bool Visible { get; set; } = true;
45+
private string Title { get; set; } = "Title here";
46+
47+
public DialogButtonsLayout SelectedBtnLayout { get; set; } = DialogButtonsLayout.Start;
48+
public List<DialogModel> LayoutTypes { get; set; } = new List<DialogModel>()
49+
{
50+
new DialogModel() { Text = "Start", Value = DialogButtonsLayout.Start },
51+
new DialogModel() { Text = "End", Value = DialogButtonsLayout.End },
52+
new DialogModel() { Text = "Center", Value = DialogButtonsLayout.Center },
53+
new DialogModel() { Text = "Stretched", Value = DialogButtonsLayout.Stretched }
54+
};
55+
56+
public class DialogModel
57+
{
58+
public string Text { get; set; }
59+
public DialogButtonsLayout Value { get; set; }
60+
}
61+
62+
async Task OnChangeHandler(object newValue)
63+
{
64+
dialogRef.Refresh(); // The Refresh() method is needed here to re-render and display the changed position of the buttons.
65+
}
66+
}
67+
````

‎components/dialog/events.md

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
---
2+
title: Events
3+
page_title: Dialog - Events
4+
description: Events of the Dialog for Blazor.
5+
slug: dialog-events
6+
tags: telerik,blazor,dialog,events
7+
published: True
8+
position: 10
9+
---
10+
11+
# Dialog Events
12+
13+
This article explains the events available in the Telerik Dialog for Blazor:
14+
15+
* [VisibleChanged](#visiblechanged)
16+
17+
@[template](/_contentTemplates/common/general-info.md#event-callback-can-be-async)
18+
19+
20+
## VisibleChanged
21+
22+
You can use the `VisibleChanged` event to get notifications when the user tries to close the Dialog. You can effectively cancel the event by *not* propagating the new visibility state to the variable the `Visible` property is bound to. This is the way to cancel the event and keep the dialog open.
23+
24+
>caption React to the user closing the Dialog.
25+
26+
````CSHTML
27+
@* An example with the VisibleChanged event. *@
28+
29+
@result
30+
31+
<TelerikButton OnClick="@ToggleDialog">Toggle the Dialog</TelerikButton>
32+
33+
<TelerikDialog Visible="@Visible" VisibleChanged="@VisibleChangedHandler"
34+
Title="@Title">
35+
<DialogContent>
36+
A new version of <strong>Telerik UI for Blazor</strong> is available. Would you like to download and install it now?
37+
</DialogContent>
38+
<DialogButtons>
39+
<TelerikButton OnClick="@ToggleDialog">Skip this version</TelerikButton>
40+
<TelerikButton OnClick="@ToggleDialog">Remind me later</TelerikButton>
41+
<TelerikButton OnClick="@ToggleDialog" Primary="true">Install update</TelerikButton>
42+
</DialogButtons>
43+
</TelerikDialog>
44+
45+
@code {
46+
private bool Visible { get; set; } = true;
47+
private string Title { get; set; } = "Software Update";
48+
string result { get; set; }
49+
50+
void VisibleChangedHandler(bool currVisible)
51+
{
52+
Visible = currVisible; // If you don't do this, the Dialog won't close because of the user action
53+
54+
result = $"The Dialog is now visible: {Visible}";
55+
56+
Console.WriteLine("The user closed the Dialog with the [x] button on its toolbar");
57+
}
58+
59+
public void ToggleDialog()
60+
{
61+
Visible = !Visible;
62+
63+
result = $"The Dialog is now visible: {Visible}";
64+
}
65+
}
66+
````
67+
68+
>caption Prevent the user from closing the Dialog based on a condition.
69+
70+
````CSHTML
71+
@* Not propagating the visible value from the handler to the model can prevent the user from closing the Dialog.
72+
Using the application code to explicitly set the visibility of the Dialog will still close it as it will not fire the event.*@
73+
74+
<TelerikButton OnClick="@(() => { Visible = true; })">Toggle the Dialog</TelerikButton>
75+
76+
<TelerikDialog Visible="@Visible" VisibleChanged="@VisibleChangedHandler"
77+
Title="@Title">
78+
<DialogContent>
79+
Try closing the Dialog with the [x] button on its toolbar, then toggle the checkbox and try again.
80+
<br />
81+
<label>
82+
The user can close the dialog with the [x] button:
83+
<TelerikCheckBox @bind-Value="@isClosable" />
84+
</label>
85+
</DialogContent>
86+
</TelerikDialog>
87+
88+
@code {
89+
private bool Visible { get; set; } = true;
90+
private string Title { get; set; } = "Closable Dialog";
91+
bool isClosable { get; set; }
92+
93+
void VisibleChangedHandler(bool currVisible)
94+
{
95+
if (isClosable)
96+
{
97+
Visible = currVisible; // If you don't do this, the Dialog won't close because of the user action.
98+
}
99+
else
100+
{
101+
Console.WriteLine("The user tried to close the Dialog but the code didn't let them.");
102+
}
103+
104+
}
105+
}
106+
````

‎components/dialog/header.md

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
title: Header
3+
page_title: Dialog Header
4+
description: Header of the Dialog for Blazor.
5+
slug: dialog-header
6+
tags: telerik,blazor,dialog,header
7+
published: True
8+
position: 5
9+
---
10+
11+
# Dialog Header
12+
13+
The header contains the `Title` and the [`Close Action` button]({%slug dialog-action-buttons%}).
14+
15+
There are two ways to define a Dialog title:
16+
* a string `Title` attribute of the component
17+
* a nested `<DialogTitle>` render fragment.
18+
19+
The default `Title` value is `null`.
20+
21+
You can control the close action via the `ShowCloseButton` parameter. Its default value is `true`.
22+
23+
> If you don't want to render the header, set the `ShowCloseButton` to `false` and don't set a `Title`.
24+
25+
## Example
26+
27+
The following example demonstrates how to set up the title through a template. The close action button is also hidden.
28+
29+
>caption The result from the code snippet.
30+
31+
![](images/dialog-header.png)
32+
33+
>caption Title template and no close button in the Telerik Dialog.
34+
35+
````CSHTML
36+
@* An example of a title template and hidden button for closing. *@
37+
38+
<TelerikDialog @bind-Visible="@Visible" ShowCloseButton="false">
39+
<DialogTitle>
40+
<TelerikIcon IconClass="k-icon k-i-caret-double-alt-up"></TelerikIcon>
41+
<strong>@Title</strong>
42+
<TelerikIcon IconClass="k-icon k-i-caret-double-alt-up"></TelerikIcon>
43+
</DialogTitle>
44+
<DialogContent>
45+
A new version of <strong>Telerik UI for Blazor</strong> is available. Would you like to download and install it now?
46+
</DialogContent>
47+
<DialogButtons>
48+
<TelerikButton OnClick="@(() => { Visible = false; })">Skip this version</TelerikButton>
49+
<TelerikButton OnClick="@(() => { Visible = false; })">Remind me later</TelerikButton>
50+
<TelerikButton OnClick="@(() => { Visible = false; })" Primary="true">Install update</TelerikButton>
51+
</DialogButtons>
52+
</TelerikDialog>
53+
54+
@code {
55+
private bool Visible { get; set; } = true;
56+
private string Title { get; set; } = "Software Update";
57+
}
58+
````

‎components/dialog/images/dialog-action-buttons.gif

109 KB
Loading

‎components/dialog/images/dialog-basic-configuration.PNG

8.9 KB
Loading

‎components/dialog/images/dialog-header.PNG

8.52 KB
Loading

‎components/dialog/images/dialog-visibility.gif

98.9 KB
Loading

‎components/dialog/overview.md

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
title: Overview
3+
page_title: Dialog Overview
4+
description: Overview of the Dialog for Blazor.
5+
slug: dialog-overview
6+
tags: telerik,blazor,dialog,overview
7+
published: True
8+
position: 0
9+
---
10+
11+
# Dialog Overview
12+
13+
The Dialog is a modal popup that brings information to the user. It provides actions through its action buttons to prompt the user for input or to ask for a decision. The component can also contain more complex UI elements that require the attention of the user. The main difference from the Window modal is the functionality for actions and predefined dialogs.
14+
15+
## Basics
16+
17+
To add a Telerik Dialog to your Blazor app:
18+
19+
1. Add the `TelerikDialog` tag.
20+
1. Set the `Visible` parameter via one-way or two-way binding.
21+
1. Set a `Title`.
22+
23+
The following example demonstrates how to set up the Dialog with its default configuration.
24+
25+
>caption A basic configuration of the Telerik Dialog.
26+
27+
````CSHTML
28+
@* An example of the Dialog basic implementation. *@
29+
30+
<TelerikDialog @bind-Visible="@Visible"
31+
Title="@Title">
32+
<DialogContent>
33+
A new version of <strong>Telerik UI for Blazor</strong> is available. Would you like to download and install it now?
34+
</DialogContent>
35+
<DialogButtons>
36+
<TelerikButton OnClick="@(() => { Visible = false; })">Skip this version</TelerikButton>
37+
<TelerikButton OnClick="@(() => { Visible = false; })">Remind me later</TelerikButton>
38+
<TelerikButton OnClick="@(() => { Visible = false; })" Primary="true">Install update</TelerikButton>
39+
</DialogButtons>
40+
</TelerikDialog>
41+
42+
@code {
43+
private bool Visible { get; set; } = true;
44+
private string Title { get; set; } = "Software Update";
45+
}
46+
````
47+
48+
>caption The result from the above code snippet.
49+
50+
![](images/dialog-basic-configuration.png)
51+
52+
## Features
53+
54+
The Dialog provides the following features:
55+
56+
* `Visible` - `bool` - defines the visibility of the Dialog.
57+
58+
* `Title` - `string` - defines the title of the Dialog.
59+
60+
* `DialogTitle` - `RenderFragment` - defines the title template of the component.
61+
62+
* `DialogContent` - `RenderFragment` - defines the content template of the component.
63+
64+
* `DialogButtons` - `RenderFragment` - defines the actions bar template of the component.
65+
66+
* `ButtonsLayout` - `enum`- `DialogButtonsLayout` - defines the layout of the actions button in the footer. The default layout is `DialogButtonsLayout.Stretched`. See more in the [Action Buttons article]({%slug dialog-action-buttons%})).
67+
68+
* `ShowCloseButton` - `bool` - defines the close behavior of the component - whether the component should render close flat button in the titlebar. Its **true** by default. See more in the [Header article]({%slug dialog-header%}).
69+
70+
* `CloseOnOverlayClick` - `bool` - defines whether clicking on the modal overlay should close the Dialog.
71+
72+
* `FocusedElementSelector` - `string` - defines the CSS selector of the initially focused item on open. By default, it is the first focusable item in the dialog.
73+
74+
* `Class` - `string` - defines the class of the component instance.
75+
76+
* `Width` - `string` - defines the width of the Dialog.
77+
78+
* `Height` - `string` - defines the height of the Dialog.
79+
80+
## See Also
81+
82+
* [Live Demo: Dialog](https://demos.telerik.com/blazor-ui/dialog/overview)

‎components/dialog/predefined.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description: Predefined Dialogs (alert, confirm, prompt) for Blazor.
55
slug: dialog-predefined
66
tags: telerik,blazor,dialog,predefined,alert,confirm,prompt
77
published: true
8-
position: 10
8+
position: 2
99
---
1010

1111
# Predefined Dialogs - Alert, Confirm, Prompt

0 commit comments

Comments
 (0)