teko-file-history
Version:
File history component for Teko system
254 lines (201 loc) • 13.4 kB
Markdown
# Teko File History
A library for creating a file history web page used for Teko system.
## Installation
### yarn
```bash
yarn add teko-file-history
```
### npm
```bash
npm install teko-file-history
```
## Contribution
1. Clone the repo at https://git.teko.vn/platform/async-process/fps/teko-file-history
2. Install dependencies by running `yarn install` or `npm install`
3. Link the library to an existing project `yarn link`
4. Link the library to the project you want to use it in `yarn link teko-file-history`
5. Build the library by running `yarn build`
6. Verify the feature and create Merge Request, assign `.nv` as reviewer
7. Update documentation if necessary
## Preview UI
## Usage
Designed for React applications, the library consists of 2 separated Antd v4 - based components: `Table` and `Uploader`
> The library has its own mechanism to `fetch` configs from server. In order to get server config, you need to provide `clientId`, `env` and `getAccessToken` to the library. Configs from server will overwrite client config.
### 1. Props list
#### Base props
| Prop | Type | Required? | Description |
| ------------------- | --------- | --------- | -------------------------------------------------------------------------------------- |
| language | string | true | Current language, accepted values [`vi`, `en`, `fr`, `id`, `km`, `ms`, `zh`] |
| env | string | false | Current environment in uppercase, accept [`DEV`, `STAG`, `PROD`] |
| clientId | number | false | FPS client ID, if undefined, can't get FPS client config |
| clientIds | number[] | false | Since `1.3.2`<br>List of FPS client IDs, used for getting history for multiple clients |
| accessToken | string | false | Deprecated since `1.2.0`<br>Access token with `Bearer` prefix, used for fetching APIs |
| isOverwriteDBConfig | boolean | false | Overwrite the configs from server by the component's props |
| classNames | object | false | Custom classnames for the component, detail below |
| tableProps | object | false | Custom props for the table component, detail below |
| uploaderProps | object | false | Custom props for the uploader component, detail below |
| downloadFile | function | false | Custom download function |
| getAccessToken | function | false | Function to get parent's access token, require prefix `Bearer` in the result |
| extra | ReactNode | false | Extra component rendered below the Uploader |
| filterRequestID | string | false | Since `1.3.0`<br>X-Request-ID header for the [GET] processing-files API |
| isUploadedByMe | boolean | false | Since `1.3.5`<br>Filter current user's uploaded files |
| createdByEmails | string[] | false | Since `1.3.5`<br>Filter files by createdByEmails |
| processingFileIds | number[] | false | Since `1.3.5`<br>Filter files by processingFileIds |
| searchFileName | string | false | Since `1.3.5`<br>Filter files by file name |
#### Table props
The table component wraps Antd Table, so it will inherit Antd Table props, besides that we have:
| Prop | Type | Default | Overwritten by DB | Description |
| -------------------------- | -------- | --------------------- | ----------------- | -------------------------------------------------------------------------------------------------- |
| isShowDebug | boolean | true | yes | Show debug button and modal on dev and stag `require env prop to work` |
| isShowCreatedBy | boolean | true | yes | Show created by column |
| isShowReload | boolean | true | yes | Show reload button |
| tableTitle | string | undefined | no | Title of the table |
| onReload | function | undefined | no | Reload function, required if you use your own BFF for fetching data |
| dateFormat | string | "DD/MM/YYYY HH:mm:ss" | no | Date time format |
| orderColumn | string[] | undefined | no | Customize table's column order, accept [`id`, `name`, `createdAt`, `status`, `progressStatus`] |
| shouldAppendDateToFileName | boolean | false | no | Since `1.3.0`<br>Append date to file name when downloading, default is false. Require `dateFormat` |
#### Uploader props
The uploader component also wraps Antd Upload, similarly, we have these extra props:
| Prop | Type | Default | Overwritten by DB | Description |
| ---------------------- | --------- | --------- | ----------------- | -------------------------------------------------------------------------------------------------------- |
| importFileTemplateUrl | string | undefined | yes | URL to download the import file template, if no value found, the download template button will be hidden |
| maxFileSize | number | 5 | yes | Maximum accepted file size in MB |
| inputFileTypes | string[] | ['xlsx'] | yes | Accepted file types, accepted values [`xlsx`, `xls`, `csv`, `pdf`] |
| isShowUploader | boolean | true | no | Show uploader component |
| uploaderPosition | string | 'right' | no | Uploader position, accepted values [`left`, `right`] |
| onUploadFile | function | undefined | no | Custom upload file function, triggered on confirm upload file |
| downloadTemplateButton | ReactNode | undefined | no | Custom download template button, if no value found, the default button will be shown |
| parameters | object | undefined | no | Additional parameters for the upload API |
| extra | ReactNode | undefined | no | Extra component rendered above the drag and drop section |
### 2. Features and their required props/ alternative usage
#### 1. Fetching import history
- Required props: `env`, `clientId`, `getAccessToken`
- Alternative usage: pass `dataSource` and `reload` to `tableProps`
DB interfaces:
```typescript
type ProcessingFile = {
clientId: number;
processingFileId?: number;
fileDisplayName: string;
errorDisplay?: string;
fileUrl: string; // Uploaded file url
resultFileUrl?: string; // Processed file url
status: string; // INIT, PROCESSING, SUCCESS, FAILED
statsTotalRow: number;
statsTotalSuccess: number;
statsTotalProcessed: number;
createdAt: number;
createdBy: string;
finishedAt?: number;
};
```
#### 2. Download file
- Required props: `env`, `getAccessToken`
- Alternative usage: pass `downloadFile` to `FileImportHistory`
#### 3. Upload file
- Required props: `env`, `clientId`, `getAccessToken`
- Alternative usage: using your own Uploader
#### 4. Debug modal
- Required props: `env`, `getAccessToken`
- Alternative usage: hide it by setting `isShowDebug` to `false`
### 3. Understand about styling
The library does not have its own styling. It adds classnames to the components, and apply the style from the parent application.
You can overwrite the default classnames by passing the `classNames` prop to the component.
```javascript
import { FileImportHistory } from 'teko-file-history';
return <FileImportHistory classNames={{ ...customClassNames }} />;
```
List of classNames in the library:
| ClassName | Type | Default | Description |
| --------------------- | ------ | ------------ | -------------------------------------------------------------------------- |
| displayFlex | string | d-flex | Apply `display: flex` |
| flexColumn | string | flex-column | Apply `flex-direction: column` |
| gapBase | string | gap-base | Apply `gap: x` x based on your application |
| gapHalf | string | gap-half | Apply `gap: x` x based on your application |
| marginBottomZero | string | mb-0 | Apply `margin-bottom: 0` |
| marginTopHalf | string | mt-half | Apply `margin-top: x` x based on your application |
| marginHorizontalBase | string | mx-base | Apply `margin-left: x` and `margin-right: x` x based on your application |
| paddingHorizontalBase | string | px-base | Apply `padding-left: x` and `padding-right: x` x based on your application |
| paddingVerticalBase | string | py-base | Apply `padding-top: x` and `padding-bottom: x` x based on your application |
| textErrorColor | string | text-error | Apply `color: #xxx` text error color |
| textPrimaryColor | string | text-primary | Apply `color: #xxx` primary color of the application |
### 4. Implementation examples
#### 1. Using full FPS flow
```javascript
import { FileImportHistory } from 'teko-file-history';
return (
/**
* Let the component do everything 🤸♂️
* From fetching data to file handling, validation, and download 🤝
*/
<FileImportHistory
env={env}
clientId={clientId}
language={language}
getAccessToken={() => `Bearer ${getAccessToken()}`}
/**
* Customize your component like a pro 🤷♂️
*/
tableProps={{
dateFormat: 'DD/MM/YYYY HH:mm:ss',
orderColumn: ['id', 'name', 'createdAt', 'status', 'progressStatus'],
}}
uploaderProps={{
importFileTemplateUrl: 'https://example.com/import-file-template.xlsx',
maxFileSize: 5,
inputFileTypes: ['xlsx', 'xls', 'csv'],
onUploadFile: (file, setFile) => {
// Your upload file logic, it got triggered when you click submit button
},
}}
/>
);
```
#### 2. You control your own data
```javascript
import { FileImportHistory } from 'teko-file-history';
const [loading, setLoading] = useState(false);
return (
<FileImportHistory
env={env}
language={language}
getAccessToken={() => `Bearer ${getAccessToken()}`}
/**
* Just like that, you don't have to worry about clientId anymore 🦈
* But beware, you can't use our default uploader this way, try using onUploadFile 🤷♂️
*/
tableProps={{
dataSource, // Your data 🤸♂️
pagination, // Your pagination 🤸♂️
loading, // Loading state for table and reload button 🌪
onReload: () => {},
}}
uploaderProps={{
onUploadFile: (file, setFile) => {
// Your upload file logic, it got triggered when you click submit button
},
}}
/>
);
```
#### 3. You only need the table thing, and you control your own data
```javascript
import { FileImportHistory } from 'teko-file-history';
const [loading, setLoading] = useState(false);
return (
<FileImportHistory
language={language}
uploaderProps={{
isShowUploader: false,
}}
tableProps={{
dataSource, // Your data 🤸♂️
pagination, // Your pagination 🤸♂️
loading, // Loading state for table and reload button 🌪
onReload: () => {},
}}
downloadFile={(url: string) => onDownloadFile(url)} // Your download function 🤷♂️
/>
);
```