|
| 1 | +# mgt-file |
| 2 | + |
| 3 | +The File component is used to represent an individual file/folder from OneDrive or SharePoint by displaying information such as the file/folder name, an icon indicating the file type, and other properties such as the author, last modified date, or other details selected by the developer. The developer or application provides the identifiers for a file and the component will generate the query to retreive the file based on the identifiers provided. This component can be used on it's own or as part of the [mgt-file-list](./mgt-file-list.md) and [mgt-file-picker](./mgt-file-picker.md) components. |
| 4 | + |
| 5 | +<img src="./images/mgt-file.png" width=400/> |
| 6 | + |
| 7 | +## Supported functionality |
| 8 | + |
| 9 | +| Feature | Priority | Notes | |
| 10 | +| ------- | -------- | ----- | |
| 11 | +| Retreieve a file from Microsoft Graph using the query or identifiers provided | P0 | | |
| 12 | +| Display the name of the file/folder| P0| | |
| 13 | +| Display an icon indicating if it's a folder or file and the file type| P0 | Icons needed include generic folder icon, .docx, .pptx, .xlsx, and generic file icon for other file types | |
| 14 | +| Display relevant details of the file | P0 | Developer should be able to configure what details are being rendered | |
| 15 | + |
| 16 | +## Proposed Solution |
| 17 | + |
| 18 | +### Example 1: Developer provides the full query path for the file |
| 19 | +```<mgt-file file-query="/me/drives/items/123" view="twolines"></mgt-file>``` |
| 20 | + |
| 21 | +The request made: `GET /me/drives/items/123` |
| 22 | + |
| 23 | +### Example 2: Developer provides a site-id and item-id |
| 24 | +```<mgt-file site-id="123" item-id="456"></mgt-file>``` |
| 25 | + |
| 26 | +The request made: `GET /sites/123/drive/items/123` |
| 27 | + |
| 28 | +### Example 3: Developer provides only an item-id |
| 29 | + |
| 30 | +```<mgt-file item-id="123"></mgt-file>``` |
| 31 | + |
| 32 | +The request made: `GET /me/drive/items/123` |
| 33 | + |
| 34 | +## Example 4: The component is used inside of a File List component that uses an insight type. |
| 35 | + |
| 36 | +```<mgt-file insight-type="trending" insight-id="123"></mgt-file>``` |
| 37 | + |
| 38 | +The request made: `GET /me/insights/trending/123/resource` |
| 39 | + |
| 40 | +## Attributes and Properties |
| 41 | + |
| 42 | +| Attribute | Property | Description | |
| 43 | +| --------- | -------- | ----------- | |
| 44 | +| `file-query` | `fileQuery` | The full query or path to the file to be retrieved. | |
| 45 | +| `drive-id` | `driveId` | The Id of the drive the file belongs to. Must also provide either `item-id` or `item-path`. | |
| 46 | +| `group-id` | `groupId` | Id of the group the file belongs to. Must also provide either `item-id` or `item-path`. | |
| 47 | +| `site-id` | `siteId` | Id of the site the file belongs to. Must also provide either `{item-id}` or `{item-path}`. Provide the `{list-id}` too if you’re referencing a file from a specific list. | |
| 48 | +| `list-id` | `listId` | Id of the list the file belongs to. Must also provide `{site-id}` and `{item-id}`. | |
| 49 | +| `item-id` | `itemId` | Id of the file. Default query is `/me/drive/items`. Provide `{drive-id}`, `{group-id}`, `{site-id}`, or `{user-id}` to query a specific location. | |
| 50 | +| `item-path` | `itemPath` | Item path of the file. Default query is `/me/drive/root`. Provide `{drive-id}`, `{group-id}`, `{site-id}`, or `{user-id}` to query a specific location. | |
| 51 | +| `insight-type` | `insightType` | Type of insight the file is retrieved from. Can be `trending`, `used`, or `shared`. | |
| 52 | +| `insight-id` | `insightId` | Id of the insight resource. | |
| 53 | +| `file-details` | `fileDetails` | Set to an object representing a file | |
| 54 | +| `file-icon` | `fileIcon` | Set to an icon to show for the file | |
| 55 | +| `view` | `view` | Set to control how the file is rendered. The default is `name`. <br>`oneline` - show the icon, name and one line of text (`lastModifiedDateTime` by default)<br> `twolines` - show the icon, name, and two lines of text (`displayName` of the author by default) | |
| 56 | +| `line1-property` | `line1Property` | Sets the property of `fileDetails` to use for the first line of text. Default is `lastModifiedDateTime`. | |
| 57 | +| `line2-property` | `line2Property` | Sets the property of `fileDetails` to use for the second line of text. Default is `displayName` of author. | |
| 58 | + |
| 59 | + |
| 60 | +## APIs and Permissions |
| 61 | + |
| 62 | +| Query | Use if | Permission Scopes | |
| 63 | +| ----- | ------ | ----------------- | |
| 64 | +| `GET /drives/{drive-id}/items/{item-id}` | `{drive-id}` AND `{item-id}` | Files.Read, Files.Read.All, Sites.Read.All | |
| 65 | +| `GET /drives/{drive-id}/root:/{item-path}` | `{drive-id}` AND `{item-path}` | " | |
| 66 | +| `GET /groups/{group-id}/drive/items/{item-id}` | `{group-id}` AND `{item-id}` | " | |
| 67 | +| `GET /groups/{group-id}/drive/root:/{item-path}` | `{group-id}` AND `{item-path}` | " | |
| 68 | +| `GET /me/drive/items/{item-id}` | ONLY `{item-id}` | " | |
| 69 | +| `GET /me/drive/root:/{item-path}` | ONLY `{item-path}` | " | |
| 70 | +| `GET /sites/{site-id}/drive/items/{item-id}` | `{site-id}` AND `{item-id}` | " | |
| 71 | +| `GET /sites/{site-id}/drive/root:/{item-path}` | `{site-id}` AND `{item-path}` | " | |
| 72 | +| `GET /sites/{site-id}/lists/{list-id}/items/{item-id}/driveItem` | `{site-id}` AND `{list-id}` AND `{item-id}` | " | |
| 73 | +| `GET /users/{user-id}/drive/items/{item-id}` | `{user-id}` AND `{item-id}` | " | |
| 74 | +| `GET /users/{user-id}/drive/root:/{item-path}` | `{user-id}` AND `{item-path}` | " | |
| 75 | +| `GET /me/insights/trending/{id}/resource` | `insight-type` is `trending` AND `{id}` | Sites.Read.All | |
| 76 | +| `GET /users/{id or userPrincipalName}/insights/trending/{id}/resource` | `{user-id or upn}` AND `insight-type` is `trending` AND `{id}` | " | |
| 77 | +| `GET /me/insights/used/{id}/resource` | `insight-type` is `used` AND `{id}` | " | |
| 78 | +| `GET /users/{id or userPrincipalName}/insights/used/{id}/resource` | `{user-id or upn}` AND `insight-type` is `used` AND `{id}` | " | |
| 79 | +| `GET /me/insights/shared/{id}/resource` | `insight-type` is `shared` AND `{id}` | " | |
| 80 | +| `GET /users/{id or userPrincipalName}/insights/shared/{id}/resource` | `{user-id or upn}` AND `insight-type` is `shared` AND `{id}` | " | |
| 81 | + |
| 82 | +## Templates |
| 83 | + |
| 84 | +| Data Type | Data Context | Description | |
| 85 | +| ----------- | -------------- | ------------- | |
| 86 | +| loading | none | The template to render while the component is in a loading state. | |
| 87 | +| no-data | none | The template to render when no file data is available. | |
| 88 | +| default | file: the file details object | The default template replaces the entire component with your own. | |
0 commit comments