Teko File History

A library for creating a file history web page used for Teko system.

Installation

yarn

yarn add teko-file-history

npm

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 @nam.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.2List of FPS client IDs, used for getting history for multiple clients | | accessToken | string | false | Deprecated since 1.2.0Access 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.0X-Request-ID header for the [GET] processing-files API | | isUploadedByMe | boolean | false | Since 1.3.5Filter current user's uploaded files | | createdByEmails | string[] | false | Since 1.3.5Filter files by createdByEmails | | processingFileIds | number[] | false | Since 1.3.5Filter files by processingFileIds | | searchFileName | string | false | Since 1.3.5Filter 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.0Append 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 | | checkNumberOfLines | boolean | false | no | Check number of lines in the file |

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:

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.

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

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

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

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 🤷‍♂️
  />
);