teko-file-history

Teko File History

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

Installation

yarn add teko-file-history

Contribution

1. Clone the repo here
2. Install dependencies by running yarn install or npm install
3. In this project, run yarn link
4. Build the library by running yarn build
5. In the project you want to use it, run yarn link teko-file-history
6. Verify the feature and create Merge Request, assign @nam.nv as reviewer
7. Update documentation if necessary
8. Run yarn release to bump version and publish to npm

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 List of FPS client IDs, used for getting history for multiple clients
accessToken	string	false	Deprecated since 1.2.0 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 X-Request-ID header for the [GET] processing-files API
isUploadedByMe	boolean	false	Since 1.3.5 Filter current user's uploaded files
createdByEmails	string[]	false	Since 1.3.5 Filter files by createdByEmails
processingFileIds	number[]	false	Since 1.3.5 Filter files by processingFileIds
searchFileName	string	false	Since 1.3.5 Filter files by file name
isMultipleFiles	boolean	false	Since 1.5.0 Show file info using fileRequests & allow upload multiple files

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 HHss"	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 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. It can receive (file, setFile) or (files, setFiles)
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, sent together with fileRequests
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;
  fileRequests?: FileRequest[]; // Uploaded file infos for multiple file requests
};

type FileRequest = {
  url: string;
  displayName?: string;
  metadata?: string;
};

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
• Default submit payload uses multipart/form-data with fileRequests (JSON string)

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: (files, setFiles) => {
        // 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: (files, setFiles) => {
        // 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 🤷‍♂️
  />
);