Skip to content

Latest commit

 

History

History
275 lines (217 loc) · 7.75 KB

README.react.md

File metadata and controls

275 lines (217 loc) · 7.75 KB
Raw

React components for the Kloudless File Picker

This project is a thin React wrapper around the Kloudless File Picker. We provide the following components to add the File Picker to any React app:

  • Chooser: A button component that will launch the Chooser when clicked.
  • createChooser: A higher-order component that accepts your custom component and wraps it in a new one that launches the Chooser.
  • Saver: A button component that will launch the Saver when clicked.
  • createSaver: A higher-order component that accepts your custom component and wraps it in a new one that launches the Saver.
  • Dropzone: A Dropzone component that will launch the Chooser when clicked or launch the Saver when files are dropped into it.

Supports React v15 and v16.

Click here to test out our File Picker React component interactively

Table of contents

Installation

npm install @kloudless/file-picker

How It Works

Click here to test out our File Picker React component interactively

Chooser

A button component that wraps the Chooser view of the File Picker and will launch the Chooser when clicked.

Example

import React from 'react';
import ReactDOM from 'react-dom';
import { Chooser } from '@kloudless/file-picker/react';

ReactDOM.render(
  <Chooser
    className="CSS_CLASS_NAME"
    disabled={false}
    title="Choose a file"
    options={{ app_id: 'YOUR_KLOUDLESS_APP_ID' }}
    onSuccess={(result) => console.log('success', result)} />,
  document.getElementById('root'),
);

createChooser

A higher-order component (HOC) that transforms your custom component into a new one that launches the Chooser. It will add a transparent component layer that will hack the onClick event handler. The hacked one will be passed to the wrapped component and launch the Chooser when being called.

All the properties except options and the event handlers passed to the new component will be passed to the wrapped component.

Example

import React from 'react';
import ReactDOM from 'react-dom';
import { createChooser } from '@kloudless/file-picker/react';
import CustomButton from 'path/to/CustomButton';

// First, wrap you custom component
// Your custom component should accept onClick and call it to launch the Chooser.
const CustomChooser = createChooser(CustomButton);

ReactDOM.render(
  <CustomChooser
    options={{ app_id: 'YOUR_KLOUDLESS_APP_ID' }}
    onSuccess={(result) => console.log('success', result)}
  />,
  document.getElementById('root'),
);

Saver

A button component that wraps the Saver view of the File Picker and will launch the Saver when clicked.

Example

import React from 'react';
import ReactDOM from 'react-dom';
import { Saver } from '@kloudless/file-picker/react';

ReactDOM.render(
  <Saver
    className="CSS_CLASS_NAME"
    disabled={false}
    title="Save a file"
    options={{
      app_id: 'YOUR_KLOUDLESS_APP_ID',
      files: [{ url: 'http://file.url', name: 'filename.jpg' }]
    }}
    onSuccess={(result) => console.log('success', result)} />,
  document.getElementById('root'),
);

createSaver

A higher-order component (HOC) that accepts your custom component and wraps it in a new one that launches the Saver. It will add a transparent component layer that will hack the onClick event handler. The hacked one will be passed to the wrapped component and launch the Saver when being called.

All the properties except options and the event handlers passed to the new component will be passed to the wrapped component.

Example

import React from 'react';
import ReactDOM from 'react-dom';
import { createSaver } from '@kloudless/file-picker/react';
import CustomButton from 'path/to/CustomButton';

// First, wrap your custom component.
// Your custom component should accept onClick and call it to launch the Saver.
const CustomSaver = createSaver(CustomButton);

ReactDOM.render(
  <CustomSaver
    options={{
      app_id: 'YOUR_KLOUDLESS_APP_ID',
      files: [{ url: 'http://file.url', name: 'filename.jpg' }]
    }}
    onSuccess={(result) => console.log('success', result)}
  />,
  document.getElementById('root'),
);

Dropzone

A Dropzone component that will launch the Chooser when clicked or launch the Saver when files are dropped into it.

Example

import React from 'react';
import ReactDOM from 'react-dom';
import { Dropzone } from '@kloudless/file-picker/react';

ReactDOM.render(
  <Dropzone
    options={{ app_id: 'YOUR_KLOUDLESS_APP_ID' }}
    onSuccess={(result) => console.log('success', result)}
    height={100}
    width={600}
  />,
  document.getElementById('root'),
);

Props

  • options (Required) An object used to configure the File Picker. Requires the Kloudless App ID at minimum. Refer to the full File Picker Configuration for more details on all possible configuration parameters.
  • className (Optional) CSS class that apply to Saver or Chooser. Defaults to an empty string.
  • title (Optional) The text shown on the button for Chooser or Saver. Default value: Save a file for Saver; Choose a file for Chooser.
  • disabled (Optional) Set true to disable Saver or Chooser. Defaults to false.
  • height (Optional) Dropzone height. Defaults to 100px.
  • width (Optional) Dropzone width. Defaults to 600px.

Event Handlers

Supports all the events that are listed in Events. The event handler's name is in following format: on{EventName}. For example, onSuccess is the event handler for the success event. onError is the event handler for the error event, etc.

In addition, we support the onClick event handler:

  • onClick Called when either the Saver, Chooser, or Dropzone is clicked.

Set/Get Global Options

import { setGlobalOptions, getGlobalOptions } from '@kloudless/file-picker/react';

setGlobalOptions({...});
getGlobalOptions();

The returned data and parameters are the same as for filePicker.setGlobalOptions() and filePicker.getGlobalOptions(). Please refer to the File Picker Methods for more details.

Testing

First, install dependencies as shown below. This only needs to be done once:

$ npm install --prefix storybook-react/

Then, start up the testing server:

$ npm run storybook:react

The testing server uses a default Kloudless App ID. To connect accounts to your own Kloudless app, you can change the ID either via the interactive storybook UI or via an environment variable as shown below:

# ABC123 is the App ID
$ STORYBOOK_KLOUDLESS_APP_ID=ABC123 npm run storybook:react