Fileselect docs

_config.yml

@@ -306,6 +306,8 @@ navigation:
         title: "DropDownTree"
      "*editor":
         title: "Editor"
+     "*fileselect":
+        title: "FileSelect"
      "*form":
         title: "Form"
      "*flatcolorpicker":

components/fileselect/events.md

@@ -0,0 +1,155 @@
+---
+title: Events
+page_title: FileSelect - Events
+description: Events in the FileSelect for Blazor.
+slug: fileselect-events
+tags: telerik,blazor,upload,async,events
+published: true
+position: 20
+---
+
+# FileSelect Events
+
+This article explains the events available in the Telerik FileSelect for Blazor:
+
+* [OnSelect](#onselect)
+* [OnRemove](#onremove)
+
+## OnSelect
+
+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.
+
+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.
+
+The `FileSelectFileInfo` object contains the following properties:
+
+Property | Type | Description
+---------|----------|---------
+`Id` | `string` | the unique identifier of the file.
+`Name`|`string` | the file name.
+`Size` |`long` | the file size in bytes.
+`Extension` |`string` | the file extension.
+`InvalidExtension` | `bool` | a boolean flag indicating whether the file has an extension that is not within the specified ones.
+`InvalidMinFileSize` | `bool` | a boolean flag indicating whether the file has a size below the minimum.
+`InvalidMaxFileSize` | `bool` | a boolean flag indicating whether the file exceeds the max file size.
+`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.
+
+>caption Handle the OnSelect event of the FileSelect
+
+````CSHTML
+*Handle the OnSelect event of the FileSelect to access the selected files and upload them*@
+
+@using System.IO
+@using Microsoft.AspNetCore.Hosting
+@using System.Threading
+@using Telerik.Blazor.Components.FileSelect
+
+@inject IWebHostEnvironment HostingEnvironment
+
+<div style="width:300px">
+	<TelerikFileSelect OnSelect=@HandleFiles
+					   AllowedExtensions="@AllowedExtensions">
+	</TelerikFileSelect>
+	<div class="k-form-hint">
+		Expected files: <strong>JPG, PNG, GIF</strong>		
+	</div>
+</div>
+
+@code {
+	public List<string> AllowedExtensions { get; set; } = new List<string>() { ".jpg", ".png", ".gif" };
+	public Dictionary<string, CancellationTokenSource> Tokens { get; set; } = new Dictionary<string, CancellationTokenSource>();
+
+	private void HandleFiles(FileSelectEventArgs args)
+	{
+		foreach (var file in args.Files)
+		{
+			if (!file.InvalidExtension)
+			{
+				_ = UploadFile(file);
+			}
+		}
+	}
+
+	private async Task UploadFile(FileSelectFileInfo file)
+	{
+		Tokens.Add(file.Id, new CancellationTokenSource());
+		var path = Path.Combine(HostingEnvironment?.WebRootPath, file.Name);
+		await using FileStream fs = new FileStream(path, FileMode.Create);
+		await file.Stream.CopyToAsync(fs, Tokens[file.Id].Token);
+	}
+}
+````
+
+@[template](/_contentTemplates/common/general-info.md#event-callback-can-be-async)
+
+
+## OnRemove
+
+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.
+
+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:
+
+Property | Type | Description
+---------|----------|---------
+`Id`| `string` | the unique identifier of the file.
+`Name` | `string` | the file name.
+`Size` | `long`  | the file size in bytes.
+`Extension` | `string` | the file extension.
+`InvalidExtension` | `bool` | a boolean flag indicating whether the file has an extension that is not within the specified ones.
+`InvalidMinFileSize` | `bool` | a boolean flag indicating whether the file has a size below the minimum.
+`InvalidMaxFileSize` | `bool` | a boolean flag indicating whether the file exceeds the max file size.
+`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.
+
+>caption Handle the OnRemove event of the FileSelect
+
+````CSHTML
+@*Handle the OnRemove event of the FileSelect to access and delete the uploaded files*@
+
+@using System.IO
+@using Microsoft.AspNetCore.Hosting
+@using System.Threading
+@using Telerik.Blazor.Components.FileSelect
+
+@inject IWebHostEnvironment HostingEnvironment
+
+<div style="width:300px">
+	<TelerikFileSelect OnRemove=@HandleRemoveFiles
+					   AllowedExtensions="@AllowedExtensions">
+	</TelerikFileSelect>
+	<div class="k-form-hint">
+		Expected files: <strong>JPG, PNG, GIF</strong>		
+	</div>
+</div>
+
+@code {
+	public List<string> AllowedExtensions { get; set; } = new List<string>() { ".jpg", ".png", ".gif" };
+	public Dictionary<string, CancellationTokenSource> Tokens { get; set; } = new Dictionary<string, CancellationTokenSource>();
+
+	private async Task HandleRemoveFiles(FileSelectEventArgs args)
+    {
+        foreach (var file in args.Files)
+        {
+            // If you're still uploading the file, cancel the process first.
+            Tokens[file.Id].Cancel();
+            Tokens.Remove(file.Id);
+
+            await Task.Delay(1);
+
+            var path = Path.Combine(HostingEnvironment?.WebRootPath, file.Name);
+
+            // Remove the file from the file system
+            File.Delete(path);
+        }
+
+    }
+}
+````
+
+@[template](/_contentTemplates/common/general-info.md#event-callback-can-be-async)
+
+
+## See Also
+
+* [Live Demo: FileSelect Events](https://demos.telerik.com/blazor-ui/fileselect/events)
+* [FileSelect Overview]({%slug fileselect-overview%})
+* [FileSelect Validation]({%slug fileselect-validation%})

components/fileselect/overview.md

@@ -0,0 +1,71 @@
+---
+title: Overview
+page_title: FileSelect Overview
+description: Overview of the FileSelect for Blazor.
+slug: fileselect-overview
+tags: telerik,blazor,fileselect,async,overview
+published: True
+position: 0
+---
+
+# FileSelect Overview
+
+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.
+
+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.
+
+>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.
+
+#### To use a Telerik FileSelect for Blazor
+
+1. Add the `TelerikFileSelect` tag
+1. Configure the desired settings through the corresponding [parameters it exposes](#features)
+
+````CSHTML
+@* Basic FileSelect that accepts DOCX and PDF files.
+    This sample does not showcase actual upload of these files for brevity
+    For such an example see https://docs.telerik.com/blazor-ui/components/fileselect/events
+*@
+
+<div style="width:300px">
+    <TelerikFileSelect AllowedExtensions="@AllowedExtensions">
+    </TelerikFileSelect>
+    <div class="k-form-hint">
+        Expected files: <strong> DOCX and PDF </strong>
+    </div>
+</div>
+
+@code {
+    public List<string> AllowedExtensions { get; set; } = new List<string>() { ".docx", ".pdf"};
+}
+````
+
+>caption Component namespace and reference
+
+````CSHTML
+<TelerikFileSelect @ref="@FileSelectRef" />
+
+@code{
+    Telerik.Blazor.Components.TelerikFileSelect FileSelectRef { get; set; }
+}
+````
+
+
+## Features
+
+The FileSelect component provides the following key features:
+
+Parameter | Type | Description
+---------|----------|---------
+`Class` | `string` | the CSS class that will be rendered on the main wrapping element of the FileSelect component.
+`Enabled` | `bool` | enables or disables the component.
+`Multiple` | `bool` | controls whether selection of multiple files at once is allowed. Default value is `true`.
+`AllowedExtensions` | `List<string>` | a list of allowed file extensions. Read more in [Validation article]({%slug fileselect-validation%}).
+`MinFileSize` | `int?` | the minimum file size in bytes allowed for upload. Default is null. Read more in [Validation article]({%slug fileselect-validation%}).
+`MaxFileSize`| `int?` | the maximum file size in bytes. Default is null. Read more in [Validation article]({%slug fileselect-validation%}).
+
+## See Also
+
+* [Live Demo: FileSelect Overview](https://demos.telerik.com/blazor-ui/fileselect/overview)
+* [FileSelect Validation]({%slug fileselect-validation%})
+* [FileSelect Events]({%slug fileselect-events%})

components/fileselect/validation.md

@@ -0,0 +1,58 @@
+---
+title: Validation
+page_title: FileSelect - Validation
+description: Validate the selected files in the FileSelect for Blazor.
+slug: fileselect-validation
+tags: telerik,blazor,fileselect,async,validate,validation
+published: true
+position: 10
+---
+
+# FileSelect - Selected Files Validation
+
+If you want to validate the files when uploading, you should implement the validation in two parts:
+
+* client validation - performed by the Telerik FileSelect component
+* server validation - must be implemented in the application endpoints
+
+The Telerik FileSelect component offers parameters to validate the file selection on the client:
+
+* `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.
+* `MinFileSize`- `int?` - the minimum size of a file in bytes. Files with a smaller size will be marked as invalid in the UI.
+* `MaxFileSize`- `int?` - the maximum size of a file in bytes. Files with a larger size will be marked as invalid in the UI.
+
+>caption Client validation in the Telerik FileSelect component
+
+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%}).
+
+````CSHTML
+@* Some images are only allowed, min size 1KB, max size 4MB *@
+
+<div style="width:300px">
+	<TelerikFileSelect AllowedExtensions="@AllowedExtensions"
+					   MinFileSize="@MinSize"
+					   MaxFileSize="@MaxSize">
+	</TelerikFileSelect>
+	<div class="k-form-hint">
+		Expected files: <strong> JPG, PNG, JPEG </strong> between <strong>1KB</strong> and <strong>4MB</strong>.
+	</div>
+</div>
+
+@code {
+	public List<string> AllowedExtensions { get; set; } = new List<string>() { ".jpg", ".png", ".jpeg" };
+
+	public int MinSize { get; set; } = 1024;
+
+	public int MaxSize { get; set; } = 4 * 1024 * 1024;
+}
+````
+
+@[template](/_contentTemplates/upload/notes.md#server-security-note)
+
+
+## See Also
+
+* [Live Demo: FileSelect Validation](https://demos.telerik.com/blazor-ui/fileselect/validation)
+* [FileSelect Overview]({%slug fileselect-overview%})
+* [FileSelect Events]({%slug fileselect-events%})
+

components/upload/validation.md

@@ -10,7 +10,7 @@ position: 2
 
 # Validate Uploaded Files
 
-Files must be validated when uploading, and the process has two parts:
+If you want to validate the files when uploading, you should implement the validation in two parts:
 
 * client validation - performed by the Telerik Upload component
 * server validation - must be implemented in the application endpoints