Merge pull request #110 from DejWass/master

File Explorer Documentation

src/.vuepress/config.js

@@ -359,6 +359,16 @@ module.exports = config({
                                     title: 'Controls',
                                     collapsable: true,
                                     children: [
+                                        {
+                                            title: 'File Explorer',
+                                            collapsable: true,
+                                            children: [
+                                                ['/en/developer-guide/applications/controls/FileExplorer/general.md', 'General'],
+                                                ['/en/developer-guide/applications/controls/FileExplorer/actions.md', 'Actions'],
+                                                ['/en/developer-guide/applications/controls/FileExplorer/collaborationworkspaces.md', 'Collaboration Workspaces'],
+                                                ['/en/developer-guide/applications/controls/FileExplorer/documenttemplating.md', 'Templates & Classification'],
+                                            ]
+                                        },
                                         ['/en/developer-guide/applications/controls/general.md', 'General Information'],
                                         ['/en/developer-guide/applications/controls/addresspicker.md', 'Address Picker'],
                                         ['/en/developer-guide/applications/controls/annotations.md', 'Annotations'],
@@ -370,6 +380,7 @@ module.exports = config({
                                         ['/en/developer-guide/applications/controls/emailpicker.md', 'Email Picker'],
                                         ['/en/developer-guide/applications/controls/emaildesigner.md', 'Email Designer'],
                                         ['/en/developer-guide/applications/controls/filepicker.md', 'File Picker'],
+                                        ['/en/developer-guide/applications/controls/FileExplorer/fileexplorer.md', 'File Explorer'],
                                         ['/en/developer-guide/applications/controls/formbutton.md', 'Form Button'],
                                         ['/en/developer-guide/applications/controls/htmlcontentdisplay.md', 'HTML Content Display'],
                                         ['/en/developer-guide/applications/controls/keyfigures.md', 'Key Figures'],

src/en/developer-guide/applications/controls/FileExplorer/actions.md

@@ -0,0 +1,49 @@
+---
+Author: David Wasserbauer
+---
+
+# Capabilities - WIP
+
+In File Explorer, you can do many actions which are available in Sharepoint and even some more. Here is the list.
+
+## Actions
+
+Please keep in mind that by the time this documentation is written only Sharepoint as provider and Path Mode is supported. 
+If no one extended this documentation, then these action are describing behavior with this setup.
+
+### New
+
+![New](/.attachments/applications/Controls/FileExplorer/fileexplorer_actions_new.png)
+
+This button is located in **Header Command Bar**. More than one action is located under that:
+
+#### Folder
+
+Creates new folder. New folder dialog appears for user to enter folder name. After confirmation the folder is created and list of items is refreshed.
+
+#### New document
+
+Creates new document. You can create new Word, Excel or PowerPoint document. After selecting desired document type the dialog to enter document name appears. After entering the name and confirmation the document is created and it opens in new tab.
+
+#### From template
+
+![New template](/.attachments/applications/Controls/FileExplorer/fileexplorer_actions_template.png)
+
+Two options are hidden under this button: 
+- Create new template
+  - Opens Document Template form. User can create one and publish it to be able to use it in File Explorer.
+- Generate document from template
+  - Based on environment setup users can select published matching template and generate a document. More info [here](./documenttemplating.md).
+
+### Upload
+
+Available in Header Command Bar. After triggering the action file selection pops up and you can upload a document from your device. After file selection user is prompted to classify uploaded document but it can be skipped.
+
+![Upload](/.attachments/applications/Controls/FileExplorer/fileexplorer_actions_upload.png)
+
+### Sync to device
+
+Starts synchronizing current folder to local machine via OneDrive.
+
+
+## REST WILL BE ADDED

src/en/developer-guide/applications/controls/FileExplorer/collaborationworkspaces.md

@@ -0,0 +1,107 @@
+---
+Author: David Wasserbauer
+---
+
+# Collaboration Workspaces
+
+The Collaboration Workspace Entities play a crucial role in configuring and fine-tuning the settings of the File Explorer control. File Explorer will not function without them. The entire File Explorer setup is located in the TALXIS Admin App, under the Documents section.
+
+![File Explorer Admin App](/.attachments/applications/Controls/FileExplorer/collabworkspace_talxisadminapp.png)
+
+Let's delve into the key components of these entities.
+
+## Collaboration Workspace Template
+
+![Collaboration Workspace Template Form](/.attachments/applications/Controls/FileExplorer/collabworspace_templateform.png)
+
+This is the place where you set up File Explorer settings. Collaboration Workspace Template records are retrieved from the environment by entity and, if specified, by query as well. The second option is to have a record specified in the control binding. 
+The user is prompted to create a new record if no matching record exists.
+
+![No Collaboration Workspace found](/.attachments/applications/Controls/FileExplorer/collabworkspace_notfound.png)
+
+### Record fetching
+
+Collaboration Template records are matched first by entities and, if present, then by queries.
+
+For example, when creating a setup for File Explorer bound to a form of the Account entity, the Entity Name is specified as 'account'. Additionally, because the Internal ID attribute is used in the Liquid path, a simple query is included to ensure that path creation is triggered only when all values in the path are present. This practice is strongly recommended.
+
+![Record Fetching](/.attachments/applications/Controls/FileExplorer/collabworkspace_recordfetching.png)
+
+By using matching records, we can have multiple settings for one bound File Explorer. For example, you can have one SharePoint site for accounts of type 'Internal' and another for the rest. It can also point to the same site but a different location. You can possibly take it to the extreme and have a specific configuration for each address. Your options are limitless in this case! 🤯
+
+
+### File Explorer Settings
+
+This is where you configure the File Explorer behavior. It's essentially the same configuration as in the File Picker binding. In this case, it has been moved here to allow changes in the target environment. 
+
+Each configuration has an explanation written below it.
+
+![File Explorer Settings](/.attachments/applications/Controls/FileExplorer/collabworkspace_settings.png)
+
+- **Default Opener:** Set the primary way to open documents such as Word, Excel, PowerPoint.
+- **File Explorer Mode:** Path/List. Only Path is currently supported.
+- **File Explorer Provider:** Sharepoint/Environment File System. Only Sharepoint is currently supported.
+- **Root Folder Name:** Use this field if you do not want to display the name of the last folder in the path.
+- **Lock on Disable:** If you wish to disable some functionality, such as recording or deleting, on inactive records, select Yes here.
+- **Columns to be Shown:** Enter the columns you wish to display here. Separate the individual columns with a comma. Currently available column names: author, datemodified, filesize, version.
+- **Event Handlers:** Support for this functionality will be added in future releases.
+- **Expand Query:** The query to get data from associated entities. Contact your administrator for setup help.
+- **Folder Path:** The path to the destination folder in Sharepoint Online. Separate folders with '/'. Path supports the LIQUID markup language. Contact your administrator for setup help.
+- **Graph Filter Query:** A filter used by the File Explorer to correctly find the target site in Sharepoint Online. Contact your administrator for setup help.
+- **Form ID:** Enter the main form ID for the file metadata here. Default value is 357117a8-ac48-ee11-be6d-000d3adc1f33.
+
+Ask WAS for help if needed.
+
+
+
+## Collaboration Workspace Item
+
+You can locate them in the sitemap, but the optimal approach is to navigate directly from the Collaboration Workspace Template form. In the context of File Explorer, these records serve as templates for scaffolding folder structures. If any records are present when File Explorer is initially initialized with a specific record, they are created as folders.
+
+
+![Collab Workspace Items Subgrid](/.attachments/applications/Controls/FileExplorer/collabworkspace_itemssubgrid.png)
+
+
+### Folder Structure Generation
+
+Each record of this entity represents one created folder. 
+
+![Collab Workspace Items Form](/.attachments/applications/Controls/FileExplorer/collabworkspace_itemform.png)
+
+#### Structure
+
+The structure itself is created using the 'Parent Folder' and 'Child Items' attributes. You begin by creating top-level folders, and then you can add the desired number of nested folders.
+
+#### Conditional Creation
+
+You can further adjust the folder structure by using 'Entity Name' and 'Query.' If these are not specified or do not match the current record, the folder does not get created.
+
+#### Folder Name
+
+The folder name is taken from the record name, or you can use the Item Name Template and write Liquid in there. The name is resolved from the data on your record.
+
+
+
+## Collaboration Workspace Instance
+
+Records of this entity are created each time someone loads File Explorer on an entity form, and if no matching Collaboration Workspace Instance exists. This approach makes sense for several reasons:
+- You can have a static path to a SharePoint Site that remains the same even if someone changes settings in the related Collaboration Workspace Template record.
+- Information about finished scaffolding is saved here.
+
+You can view them all in the TALXIS Admin App, and, of course, you can access them from the Collaboration Workspace Template form.
+
+
+![Collab Workspace Items Form](/.attachments/applications/Controls/FileExplorer/collabworkspace_itemform.png)
+
+There is simple form present in TALXIS Admin app where you can see state of instance:
+
+![Collab Workspace Items Form](/.attachments/applications/Controls/FileExplorer/collabworkspace_instanceform.png)
+
+If something went wrong, you can always delete a record here and force File Explorer to initialize a new one. This is particularly handy for correcting issues with the Collaboration Workspace Template record setup.
+
+
+## Summary
+
+- You have to have a Collaboration Workspace Template record created and correctly set up for File Explorer to work.
+- If you wish to generate a folder structure, you need to create Collaboration Workspace Item records.
+- Collaboration Workspace Instance records represent the created folder path for a specific record, and they are generated automatically.

src/en/developer-guide/applications/controls/FileExplorer/documenttemplating.md

@@ -0,0 +1,59 @@
+---
+Author: David Wasserbauer
+---
+
+# Templates & Classification
+
+In File Explorer, you can leverage our [Document Templates](./../../utilities/templates/document-template.md) and on top of that you can categorize them using **Document Type** entity.
+The result looks for example like this:
+
+![File Explorer Template Selection](/.attachments/applications/Controls/FileExplorer/fileexplorer_templateselection.png)
+
+## Document Type
+
+Document Type settings are once again located in the TALXIS Admin App. They operate hierarchically based on the **Parent** attribute. You can create nested categories with up to 3 levels. 
+
+Records of this entity can also be used for the classification of uploaded and existing documents.
+
+This is what root document type looks like:
+
+![Document Type Form Root](/.attachments/applications/Controls/FileExplorer/documenttype_rootform.png)
+
+To use a Document Type record for document classification, you need to have the tag enabled for file classification set to true. It is recommended to set this at the bottom level, but it can be configured at any level.
+
+This is what a child Document Type meant for file classification looks like:
+
+![Document Type Child Root](/.attachments/applications/Controls/FileExplorer/documenttype_childform.png)
+
+You can see that when 'Enabled for File Classification' is set to true, some additional properties are provided for you to set up. Both 'Allowed Paths' and 'Form ID' are optional.
+
+### Allowed Paths
+
+This parameter specifies in which folder(s) this classification is enabled. If it is not specified then it is not filtered out. 
+
+Split folder names by ';' in case you need to add multiple ones.
+
+For example in screenshot above the value "EXTERNAL;INTERNAL;PARTNER" means that you can use any **Document Template** which has this **Document Type** selected only in folders which names equal to "EXTERNAL", "INTERNAL" or "PARTNER".
+
+This serves one purpose, which is to assist users in creating documents in the correct paths.
+
+### Form ID
+
+This parameter can be used to override the default talxis_file form used for opening file details. Enter the form ID, and it will be rendered when opening the details pane. This can be useful when dealing with a specific type of file that has custom attributes.
+
+
+## Document Template
+
+Nothing much differs from standard Document Template behavior, but you get some more options to specify here. If you do not have the Document Type attribute on the Document Template record specified, then it is shown directly in the 'From Template' section of File Explorer. If you have it specified, then it gets further filtered and structured, as shown in the example above.
+
+### Record fetching
+
+Document Template records are once again matched using the Entity Name and Query attributes on the record. The record also needs to be published to be displayed. On top of that, you can create a new one directly from File Explorer using the 'New Template' option in the 'From Template' section.
+
+
+## Summary
+
+- Document Templates needs to be properly setuped and published in order to be used in File Explorer.
+- Use Document Type records to further diversify and specify possibilities for users.
+- Try to enable File Classification for bottom levels of Document Types.
+- If you need help, ask WAS.

src/en/developer-guide/applications/controls/FileExplorer/general.md

@@ -0,0 +1,151 @@
+---
+Author: David Wasserbauer
+---
+
+# File Explorer
+
+Welcome to the documentation for our cutting-edge File Explorer control! 
+
+The File Explorer control is built on the foundations of the File Picker control. This means that you can find similar functionality, but it is essentially a much more powerful version of the File Picker.
+
+## How to setup
+
+### Binding Field
+Control can be binded to any field of type Multiple (Multiline Text).
+
+Example:
+
+```xml
+<controlDescription forControl="{af3dd624-3a7a-4a4a-bde6-68348df49a86}">
+  <customControl id="{E0DECE4B-6FC8-4A8F-A065-082708572369}">
+    <parameters>
+      <datafieldname>talxis_filecontrol</datafieldname>
+    </parameters>
+  </customControl>
+  <customControl formFactor="0" name="talxis_TALXIS.PCF.FileExplorer">
+    <parameters>
+      <bindingField type="Multiple">talxis_filecontrol</bindingField>
+    </parameters>
+  </customControl>
+  <customControl formFactor="1" name="talxis_TALXIS.PCF.FileExplorer">
+    <parameters>
+      <bindingField type="Multiple">talxis_filecontrol</bindingField>
+    </parameters>
+  </customControl>
+  <customControl formFactor="2" name="talxis_TALXIS.PCF.FileExplorer">
+    <parameters>
+      <bindingField type="Multiple">talxis_filecontrol</bindingField>
+    </parameters>
+  </customControl>
+</controlDescription>
+```
+
+If you are accustomed to the File Picker setup, you might be surprised by the absence of certain parameters. They are not missing; rather, they have been relocated to the configuration record.
+
+An existing Collaboration Workspace Template record is necessary for File Explorer to function correctly.
+
+Check [Collaboration Workspaces](./collaborationworkspaces.md) for more info.
+
+## General Overview
+
+![File Explorer Structure](/.attachments/applications/Controls/FileExplorer/fileexplorer_overview.png)
+
+If we simplify the control then we have these general parts:
+- Header Command Bar
+- Breadcrumb
+- File Area
+- Item Command Bar (part of File Area)
+- Details Panel
+
+### Header Command Bar
+
+This is a place for buttons which execute some actions.
+Those actions are done on **selected items**.
+
+By default when nothing is selected or you have only one item selected it looks like this:
+
+![Default Header Command Bar](/.attachments/applications/Controls/FileExplorer/fileexplorer_headercommandbar_default.png)
+
+You can use these actions:
+- New
+- Upload
+- Sync to device
+
+If you have more than one item selected, the Item Command Bar next to the item name disappears, and buttons for supported actions appear in the Header Command Bar.
+It looks like this:
+
+![Multiple Selection Header Command Bar](/.attachments/applications/Controls/FileExplorer/fileexplorer_headercommandbar_multiple.png)
+
+You can use these actions:
+- New
+- Upload
+- Download
+- Delete
+- Move To
+- Copy To
+- ZIP Archive
+- Sync to device
+
+### Breadcrumb
+
+This component is essentially a navigation property. By default, only the root folder's name is displayed (or the overridden name if applicable). If you navigate to a specific folder, you can return to the previous level by clicking on the corresponding folder in the breadcrumb path.
+
+![Breadcrumb](/.attachments/applications/Controls/FileExplorer/fileexplorer_breadcrumb.png)
+
+So for example in the screenshot above by clicking on "Contracts" you will go back to Contracts folder.
+
+### File Area
+
+The general appearance is similar to the File Picker control. You can select items, and by using Drag & Drop, you can upload new files. In addition to the existing features in the File Picker control, a new column is available to display the **Version**.
+
+#### Version
+
+The value is retrieved from SharePoint. Each time it is updated, the change is propagated to the connected talxis_file record where metadata is stored.
+
+### Item Command Bar
+
+Most of the command-related actions are executed through buttons. These buttons are filtered based on compatibility with the type of item. For example, folders have fewer options, such as Downloading as PDF, Printing, and Versioning.
+
+![Item Command Bar](/.attachments/applications/Controls/FileExplorer/fileexplorer_itemheaderbar.png)
+
+This is the full list on actions available there:
+- Open
+  - Document Preview
+  - Desktop application
+  - Web Editor
+  - Sharepoint Folder
+- Sharing
+  - Copy link
+  - Add people and send
+- Delete
+- Rename
+- Move To
+- Copy To
+- Download
+  - File as is
+  - PDF
+- Convert
+  - PDF
+  - ZIP archive
+- Print
+- Versioning
+  - Check Out/In
+  - Show history
+
+
+### Details Panel
+
+This is the area where you can view file metadata. By clicking on the "Info" icon in the upper right corner with the item selected, a panel will appear.
+
+![Details Panel](/.attachments/applications/Controls/FileExplorer/fileexplorer_detailspanel.png)
+
+In this example the default talxis_file form is used. You can change this default form in [Collaboration Workspace Template](./collaborationworkspaces.md).
+
+### What now?
+
+Learn how to properly setup File Explorer via [Collaboration Workspace Template](./collaborationworkspaces.md).
+
+Browse through [capabilities](./actions.md) of this control **(WIP)**.
+
+Check [Document Templating](./documenttemplating.md) to learn how to generate files from the File Explorer.
+