docs(fileselect, upload): add initial files documentation (#1531)

* docs(fileselect, upload): add initial files documentation

Author: yanisslav

components/fileselect/initial-files.md

@@ -0,0 +1,85 @@
+---
+title: Initial Files
+page_title: FileSelect Initial Files
+description: The FileSelect allows you to define a collection of pre-selected files, which will be initially shown in the selected file list.
+slug: fileselect-initial-files
+tags: telerik,blazor,fileselect,initial, files
+published: True
+position: 40
+---
+
+# FileSelect Initial Files
+
+The Blazor FileSelect component enables you to display specific files in the file list when the component loads for the first time. This is a convenient way to show previously uploaded files.
+
+To configure the initially displayed files, use the `Files` parameter of the FileSelect—it accepts an `IEnumerable<FileSelectFileInfo>` collection that stores a set of pre-selected files.
+
+>caption Display initial files in FileSelect's list.
+
+```CSHTML
+
+<TelerikFileSelect Files="@InitialFiles" />
+
+@code {
+    private List<FileSelectFileInfo> InitialFiles { get; set; } = new List<FileSelectFileInfo>()
+    {
+        new FileSelectFileInfo(){ Id="1", Name="Report", Extension=".pdf", Size = 1024 * 1024 * 2 },
+        new FileSelectFileInfo(){ Id="2", Name="Image", Extension=".jpg", Size = 1024 * 1024 * 4 },
+        new FileSelectFileInfo(){ Id="3", Name="Picture", Extension=".png", Size = 1024 * 1024 * 3 },
+    };
+}
+
+```
+
+## Persist Selected Files
+
+The Initial Files feature of the FileSelect allows you to save a list of files that the user has selected. Then, you can display them again when the page is reloaded. To achieve this:
+1. Store the [`FileSelectFileInfo`]({%slug fileselect-events%}#fileselectfileinfo) records received during the [`OnSelect`]({%slug fileselect-events%}#onselect) event.
+1. Load the [`FileSelectFileInfo`]({%slug fileselect-events%}#fileselectfileinfo) records in the FileSelect when the page is loaded.
+
+>caption How to load files and display them initially in the FileSelect
+
+```CSHTML
+
+@using System.IO;
+
+@if (InitialFiles != null)
+{
+    <TelerikFileSelect Files="@InitialFiles"
+                       OnSelect="@OnSelect" />
+}
+
+@code {
+    private List<FileSelectFileInfo> InitialFiles { get; set; }
+
+    private void OnSelect(FileSelectEventArgs args)
+    {
+        foreach (var file in args.Files)
+        {
+            //await SaveFileInfo(file); Here, you can store the file information it in a database, text file, or any other desired storage
+        }
+    }
+
+    protected override async Task OnInitializedAsync()
+    {
+        await LoadFiles();
+    }
+
+    private async Task LoadFiles()
+    {
+        //Simulate files information loading
+        await Task.Delay(1000);
+        InitialFiles = new List<FileSelectFileInfo>()
+        {
+            new FileSelectFileInfo(){ Id="1", Name="Report", Extension=".pdf", Size = 1024 * 1024 * 2 }
+        };
+    }
+}
+
+```
+
+
+## See Also
+
+* [FileSelect API](/blazor-ui/api/Telerik.Blazor.Components.TelerikFileSelect)
+* [FileSelect Overview]({%slug fileselect-overview%})

components/fileselect/overview.md

@@ -69,6 +69,10 @@ Additionally, you may define an external drop zone by using the [Telerik UI for
 
 The FileSelect includes [built-in client-side validation]({%slug fileselect-validation%}) for the file size and type (extension). Additional custom validation can take place in the [OnSelect event]({%slug fileselect-events%}#onselect).
 
+## Initial Files
+
+The Initial Files feature allows you to display a set of pre-selected files in the FileSelect when the component loads. This functionality is helpful when you want to show files that were previously provided by the user. [Read more about the FileSelect Initial Files feature...]({%slug fileselect-initial-files%})
+
 ## Templates
 
 You can use the functionality of the built-in template and modify the appearance of the **Select files...** button. [Read more about the Telerik FileSelect templates...]({%slug fileselect-templates%})
@@ -91,6 +95,7 @@ The following table lists the FileSelect parameters. Also check the [FileSelect
 | `MinFileSize` | `int?` | Sets the minimum allowed file size in bytes. Read more at [Validation]({%slug fileselect-validation%}). |
 | `MaxFileSize`| `int?` | Sets the maximum allowed file size in bytes. Read more at [Validation]({%slug fileselect-validation%}). |
 | `Multiple` | `bool`<br />(`true`) | Sets if the user can select several files at the same time. |
+| `Files` | `IEnumerable<FileSelectFileInfo>` | Collection of files that will be initially displayed in the FileSelect file list. |
 
 
 ## FileSelect Reference and Methods

components/upload/initial-files.md

@@ -0,0 +1,86 @@
+---
+title: Initial Files
+page_title: Upload Initial Files
+description: The Upload allows you to define a collection of pre-selected files, which will be initially shown in the selected file list.
+slug: upload-initial-files
+tags: telerik,blazor,upload,initial, files
+published: True
+position: 40
+---
+
+# Upload Initial Files
+
+The Blazor Upload component enables you to display specific files in the file list when the component loads for the first time. This is a convenient way to show previously uploaded files.
+
+To configure the initially displayed files, use the `Files` parameter of the Upload—it accepts an `IEnumerable<UploadFileInfo>` collection that stores a set of pre-selected files.
+
+>caption Display initial files in Upload's list.
+
+```CSHTML
+
+<TelerikUpload Files="@InitialFiles" />
+
+@code {
+    private List<UploadFileInfo> InitialFiles { get; set; } = new List<UploadFileInfo>()
+    {
+        new UploadFileInfo(){ Id="1", Name="Report", Extension=".pdf", Size = 1024 * 1024 * 2 },
+        new UploadFileInfo(){ Id="2", Name="Image", Extension=".jpg", Size = 1024 * 1024 * 4 },
+        new UploadFileInfo(){ Id="3", Name="Picture", Extension=".png", Size = 1024 * 1024 * 3 },
+    };
+}
+
+```
+
+## Persist Selected Files
+
+The Initial Files feature of the Upload allows you to save a list of files that the user has selected. Then, you can display them again when the page is reloaded. To achieve this:
+1. Store the [`UploadFileInfo`]({%slug upload-events%}#uploadfileinfo) records received during the [`OnSelect`]({%slug upload-events%}#onselect) event.
+1. Load the [`UploadFileInfo`]({%slug upload-events%}#uploadfileinfo) records in the Upload when the page is loaded.
+
+>caption How to load files and display them initially in the Upload
+
+```CSHTML
+
+@using System.IO;
+
+
+@if (InitialFiles != null)
+{
+    <TelerikUpload Files="@InitialFiles"
+                   OnSelect="@OnSelect" />
+}
+
+@code {
+    private List<UploadFileInfo> InitialFiles { get; set; }
+
+    private void OnSelect(UploadSelectEventArgs args)
+    {
+        foreach (var file in args.Files)
+        {
+            //await SaveFileInfo(file); Here, you can store the file information it in a database, text file, or any other desired storage
+        }
+    }
+
+    protected override async Task OnInitializedAsync()
+    {
+        await LoadFiles();
+    }
+
+    private async Task LoadFiles()
+    {
+        //Simulate files information loading
+        await Task.Delay(1000);
+        InitialFiles = new List<UploadFileInfo>()
+        {
+            new UploadFileInfo(){ Id="1", Name="Report", Extension=".pdf", Size = 1024 * 1024 * 2 }
+        };
+    }
+}
+
+```
+
+
+## See Also
+
+* [Upload API](/blazor-ui/api/Telerik.Blazor.Components.TelerikUpload)
+* [Upload Overview]({%slug upload-overview%})

components/upload/overview.md

@@ -175,6 +175,10 @@ Authentication and authorization depends on the application.
 
 The Upload includes [built-in client-side validation]({%slug upload-validation%}) for the file size and type (extension). Additional custom validation can take place in the [OnSelect event]({%slug upload-events%}#onselect).
 
+## Initial Files
+
+The Initial Files feature allows you to display a set of pre-selected files in the Upload when the component loads. This functionality is helpful when you want to show files that were previously provided by the user. [Read more about the Upload Initial Files feature...]({%slug upload-initial-files%})
+
 ## Templates
 
 You can use the functionality of the built-in template and modify the appearance of the **Select files...** button. [Read more about the Telerik Upload templates...]({%slug upload-templates%})
@@ -215,6 +219,7 @@ The following table lists the Upload parameters. Also check the [Upload API Refe
 | `SaveField` | `string`<br />(`"files"`) | Sets the `FormData` key, which contains the file submitted to the [`SaveUrl` endpoint](#implement-controller-methods). The `SaveField` value must match the save controller method's argument name. |
 | `SaveUrl` | `string` | The URL which receives the uploaded files. `SaveUrl` and `RemoveUrl` **cannot change** between file selection and file upload, because the component will be recreated and the selected files will be lost. |
 | `WithCredentials` | `bool` | Controls if the Upload will send credentials such as cookies or HTTP headers for [**cross-site** requests](#cross-origin-requests). See [XMLHttpRequest.withCredentials](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/withCredentials). On the other hand, use the [`OnUpload` and `OnRemove` events]({%slug upload-events%}) to add authentication tokens and other metadata to the component requests. |
+| `Files` | `IEnumerable<UploadFileInfo>` | Collection of files that will be initially displayed in the Upload file list. |
 
 
 ## Upload Reference and Methods