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

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`]
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
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

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`]

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`]
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

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