Skip to content

Commit 3aa4ec7

Browse files
ntachevantacheva
authored
Fileselect docs (#707)
* docs(fileselect):draft docs * docs(fileselect):updates * docs(fileselect):final * docs(fileselect):updates
1 parent 7bcf731 commit 3aa4ec7

File tree

5 files changed

+287
-1
lines changed

5 files changed

+287
-1
lines changed

‎_config.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -306,6 +306,8 @@ navigation:
306306
title: "DropDownTree"
307307
"*editor":
308308
title: "Editor"
309+
"*fileselect":
310+
title: "FileSelect"
309311
"*form":
310312
title: "Form"
311313
"*flatcolorpicker":

‎components/fileselect/events.md‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
---
2+
title: Events
3+
page_title: FileSelect - Events
4+
description: Events in the FileSelect for Blazor.
5+
slug: fileselect-events
6+
tags: telerik,blazor,upload,async,events
7+
published: true
8+
position: 20
9+
---
10+
11+
# FileSelect Events
12+
13+
This article explains the events available in the Telerik FileSelect for Blazor:
14+
15+
* [OnSelect](#onselect)
16+
* [OnRemove](#onremove)
17+
18+
## OnSelect
19+
20+
The `OnSelect` fires when one or multiple files have been selected through the `Select files` button. Contains a list of fileInfo objects, allowing processing of the files.
21+
22+
The event handler receives a `FileSelectEventArgs` object. Its `Files` field is a collection of `FileSelectFileInfo` objects. They describe each selected file and allow its processing.
23+
24+
The `FileSelectFileInfo` object contains the following properties:
25+
26+
Property | Type | Description
27+
---------|----------|---------
28+
`Id` | `string` | the unique identifier of the file.
29+
`Name`|`string` | the file name.
30+
`Size` |`long` | the file size in bytes.
31+
`Extension` |`string` | the file extension.
32+
`InvalidExtension` | `bool` | a boolean flag indicating whether the file has an extension that is not within the specified ones.
33+
`InvalidMinFileSize` | `bool` | a boolean flag indicating whether the file has a size below the minimum.
34+
`InvalidMaxFileSize` | `bool` | a boolean flag indicating whether the file exceeds the max file size.
35+
`Stream`| `FileInfoStream` | a stream that can be used to upload the file to memory, file system or other. It's used to asynchronously get the byte array data of the file.
36+
37+
>caption Handle the OnSelect event of the FileSelect
38+
39+
````CSHTML
40+
*Handle the OnSelect event of the FileSelect to access the selected files and upload them*@
41+
42+
@using System.IO
43+
@using Microsoft.AspNetCore.Hosting
44+
@using System.Threading
45+
@using Telerik.Blazor.Components.FileSelect
46+
47+
@inject IWebHostEnvironment HostingEnvironment
48+
49+
<div style="width:300px">
50+
<TelerikFileSelect OnSelect=@HandleFiles
51+
AllowedExtensions="@AllowedExtensions">
52+
</TelerikFileSelect>
53+
<div class="k-form-hint">
54+
Expected files: <strong>JPG, PNG, GIF</strong>
55+
</div>
56+
</div>
57+
58+
@code {
59+
public List<string> AllowedExtensions { get; set; } = new List<string>() { ".jpg", ".png", ".gif" };
60+
public Dictionary<string, CancellationTokenSource> Tokens { get; set; } = new Dictionary<string, CancellationTokenSource>();
61+
62+
private void HandleFiles(FileSelectEventArgs args)
63+
{
64+
foreach (var file in args.Files)
65+
{
66+
if (!file.InvalidExtension)
67+
{
68+
_ = UploadFile(file);
69+
}
70+
}
71+
}
72+
73+
private async Task UploadFile(FileSelectFileInfo file)
74+
{
75+
Tokens.Add(file.Id, new CancellationTokenSource());
76+
var path = Path.Combine(HostingEnvironment?.WebRootPath, file.Name);
77+
await using FileStream fs = new FileStream(path, FileMode.Create);
78+
await file.Stream.CopyToAsync(fs, Tokens[file.Id].Token);
79+
}
80+
}
81+
````
82+
83+
@[template](/_contentTemplates/common/general-info.md#event-callback-can-be-async)
84+
85+
86+
## OnRemove
87+
88+
The `OnRemove` fires when a file has been removed from the list of selected files (by clicking the `x` icon or pressing `Del` key). Contains the removed fileInfo object.
89+
90+
The event handler receives a `FileSelectEventArgs` object. Its `Files` field is a collection of `FileSelectFileInfo` objects. As the FileSelect component allows deleting one item at a time, the collection contains only one `FileSelectFileInfo` object (the deleted one) and it has the following fields:
91+
92+
Property | Type | Description
93+
---------|----------|---------
94+
`Id`| `string` | the unique identifier of the file.
95+
`Name` | `string` | the file name.
96+
`Size` | `long` | the file size in bytes.
97+
`Extension` | `string` | the file extension.
98+
`InvalidExtension` | `bool` | a boolean flag indicating whether the file has an extension that is not within the specified ones.
99+
`InvalidMinFileSize` | `bool` | a boolean flag indicating whether the file has a size below the minimum.
100+
`InvalidMaxFileSize` | `bool` | a boolean flag indicating whether the file exceeds the max file size.
101+
`Stream` | `FileInfoStream` | a stream that can be used to upload the file to memory, file system or other. It's used to asynchronously get the byte array data of the file.
102+
103+
>caption Handle the OnRemove event of the FileSelect
104+
105+
````CSHTML
106+
@*Handle the OnRemove event of the FileSelect to access and delete the uploaded files*@
107+
108+
@using System.IO
109+
@using Microsoft.AspNetCore.Hosting
110+
@using System.Threading
111+
@using Telerik.Blazor.Components.FileSelect
112+
113+
@inject IWebHostEnvironment HostingEnvironment
114+
115+
<div style="width:300px">
116+
<TelerikFileSelect OnRemove=@HandleRemoveFiles
117+
AllowedExtensions="@AllowedExtensions">
118+
</TelerikFileSelect>
119+
<div class="k-form-hint">
120+
Expected files: <strong>JPG, PNG, GIF</strong>
121+
</div>
122+
</div>
123+
124+
@code {
125+
public List<string> AllowedExtensions { get; set; } = new List<string>() { ".jpg", ".png", ".gif" };
126+
public Dictionary<string, CancellationTokenSource> Tokens { get; set; } = new Dictionary<string, CancellationTokenSource>();
127+
128+
private async Task HandleRemoveFiles(FileSelectEventArgs args)
129+
{
130+
foreach (var file in args.Files)
131+
{
132+
// If you're still uploading the file, cancel the process first.
133+
Tokens[file.Id].Cancel();
134+
Tokens.Remove(file.Id);
135+
136+
await Task.Delay(1);
137+
138+
var path = Path.Combine(HostingEnvironment?.WebRootPath, file.Name);
139+
140+
// Remove the file from the file system
141+
File.Delete(path);
142+
}
143+
144+
}
145+
}
146+
````
147+
148+
@[template](/_contentTemplates/common/general-info.md#event-callback-can-be-async)
149+
150+
151+
## See Also
152+
153+
* [Live Demo: FileSelect Events](https://demos.telerik.com/blazor-ui/fileselect/events)
154+
* [FileSelect Overview]({%slug fileselect-overview%})
155+
* [FileSelect Validation]({%slug fileselect-validation%})

‎components/fileselect/overview.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
---
2+
title: Overview
3+
page_title: FileSelect Overview
4+
description: Overview of the FileSelect for Blazor.
5+
slug: fileselect-overview
6+
tags: telerik,blazor,fileselect,async,overview
7+
published: True
8+
position: 0
9+
---
10+
11+
# FileSelect Overview
12+
13+
The <a href = "https://www.telerik.com/blazor-ui/fileselect" target="_blank">Blazor FileSelect component</a> helps users select single or multiple files from their local file systems. It provides UI for selecting the files and allows the application logic to handle the actual upload as desired. The component is especially useful when you want full control over the process of creating the server requests and sent forms.
14+
15+
The Telerik FileSelect for Blazor provides a [Stream](https://docs.microsoft.com/en-us/dotnet/api/system.io.stream?view=net-6.0) for each selected file, so that you can manipulate the file in-memory, save it to the file system or send it to another destination.
16+
17+
>tip The maximum file size supported by the framework up till .NET 5 is 2 GB and as of .NET 6 [this limit is removed](https://github.com/dotnet/aspnetcore/pull/33900). At the time of introducing the component, Telerik UI for Blazor supports .NET versions 3.1.x - 6 and for multi-targeting purposes the FileSelect component allows maximum file size of 2 GB.
18+
19+
#### To use a Telerik FileSelect for Blazor
20+
21+
1. Add the `TelerikFileSelect` tag
22+
1. Configure the desired settings through the corresponding [parameters it exposes](#features)
23+
24+
````CSHTML
25+
@* Basic FileSelect that accepts DOCX and PDF files.
26+
This sample does not showcase actual upload of these files for brevity
27+
For such an example see https://docs.telerik.com/blazor-ui/components/fileselect/events
28+
*@
29+
30+
<div style="width:300px">
31+
<TelerikFileSelect AllowedExtensions="@AllowedExtensions">
32+
</TelerikFileSelect>
33+
<div class="k-form-hint">
34+
Expected files: <strong> DOCX and PDF </strong>
35+
</div>
36+
</div>
37+
38+
@code {
39+
public List<string> AllowedExtensions { get; set; } = new List<string>() { ".docx", ".pdf"};
40+
}
41+
````
42+
43+
>caption Component namespace and reference
44+
45+
````CSHTML
46+
<TelerikFileSelect @ref="@FileSelectRef" />
47+
48+
@code{
49+
Telerik.Blazor.Components.TelerikFileSelect FileSelectRef { get; set; }
50+
}
51+
````
52+
53+
54+
## Features
55+
56+
The FileSelect component provides the following key features:
57+
58+
Parameter | Type | Description
59+
---------|----------|---------
60+
`Class` | `string` | the CSS class that will be rendered on the main wrapping element of the FileSelect component.
61+
`Enabled` | `bool` | enables or disables the component.
62+
`Multiple` | `bool` | controls whether selection of multiple files at once is allowed. Default value is `true`.
63+
`AllowedExtensions` | `List<string>` | a list of allowed file extensions. Read more in [Validation article]({%slug fileselect-validation%}).
64+
`MinFileSize` | `int?` | the minimum file size in bytes allowed for upload. Default is null. Read more in [Validation article]({%slug fileselect-validation%}).
65+
`MaxFileSize`| `int?` | the maximum file size in bytes. Default is null. Read more in [Validation article]({%slug fileselect-validation%}).
66+
67+
## See Also
68+
69+
* [Live Demo: FileSelect Overview](https://demos.telerik.com/blazor-ui/fileselect/overview)
70+
* [FileSelect Validation]({%slug fileselect-validation%})
71+
* [FileSelect Events]({%slug fileselect-events%})

‎components/fileselect/validation.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
title: Validation
3+
page_title: FileSelect - Validation
4+
description: Validate the selected files in the FileSelect for Blazor.
5+
slug: fileselect-validation
6+
tags: telerik,blazor,fileselect,async,validate,validation
7+
published: true
8+
position: 10
9+
---
10+
11+
# FileSelect - Selected Files Validation
12+
13+
If you want to validate the files when uploading, you should implement the validation in two parts:
14+
15+
* client validation - performed by the Telerik FileSelect component
16+
* server validation - must be implemented in the application endpoints
17+
18+
The Telerik FileSelect component offers parameters to validate the file selection on the client:
19+
20+
* `AllowedExtensions` - `List<string>` - a list of extensions that the user can select. Choosing different files will mark them as invalid in the UI. Its default is an empty list, which allows all extensions.
21+
* `MinFileSize`- `int?` - the minimum size of a file in bytes. Files with a smaller size will be marked as invalid in the UI.
22+
* `MaxFileSize`- `int?` - the maximum size of a file in bytes. Files with a larger size will be marked as invalid in the UI.
23+
24+
>caption Client validation in the Telerik FileSelect component
25+
26+
For brevity, this sample does not showcase actual upload of the files. You can find an example in the [FileSelect Events article]({%slug fileselect-events%}).
27+
28+
````CSHTML
29+
@* Some images are only allowed, min size 1KB, max size 4MB *@
30+
31+
<div style="width:300px">
32+
<TelerikFileSelect AllowedExtensions="@AllowedExtensions"
33+
MinFileSize="@MinSize"
34+
MaxFileSize="@MaxSize">
35+
</TelerikFileSelect>
36+
<div class="k-form-hint">
37+
Expected files: <strong> JPG, PNG, JPEG </strong> between <strong>1KB</strong> and <strong>4MB</strong>.
38+
</div>
39+
</div>
40+
41+
@code {
42+
public List<string> AllowedExtensions { get; set; } = new List<string>() { ".jpg", ".png", ".jpeg" };
43+
44+
public int MinSize { get; set; } = 1024;
45+
46+
public int MaxSize { get; set; } = 4 * 1024 * 1024;
47+
}
48+
````
49+
50+
@[template](/_contentTemplates/upload/notes.md#server-security-note)
51+
52+
53+
## See Also
54+
55+
* [Live Demo: FileSelect Validation](https://demos.telerik.com/blazor-ui/fileselect/validation)
56+
* [FileSelect Overview]({%slug fileselect-overview%})
57+
* [FileSelect Events]({%slug fileselect-events%})
58+

‎components/upload/validation.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ position: 2
1010

1111
# Validate Uploaded Files
1212

13-
Files must be validated when uploading, and the process has two parts:
13+
If you want to validate the files when uploading, you should implement the validation in two parts:
1414

1515
* client validation - performed by the Telerik Upload component
1616
* server validation - must be implemented in the application endpoints

0 commit comments

Comments
 (0)