# Kloudless File Picker with Vue

Kloudless File Picker for your Vue App. We provide:
- `Chooser`:
  A button component that will launch the Chooser when clicked.
- `createChooser`:
  A method 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 method 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 Vue v2.

<!-- STORY -->

<!-- STORY HIDE START -->

[**Click here to test out our File Picker Vue component interactively**](https://kloudless.github.io/file-picker/vue)

<!-- STORY HIDE END -->

## Table of contents

* [Installation](#installation)
* [How It Works](#how-it-works)
  * [Chooser](#chooser)
    * [Example](#example)
  * [createChooser](#createchooser)
    * [Example](#example-1)
  * [Saver](#saver)
    * [Example](#example-2)
  * [createSaver](#createsaver)
    * [Example](#example-3)
  * [Dropzone](#dropzone)
    * [Example](#example-4)
* [Props](#props)
* [Attributes](#attributes)
* [Events](#events)
* [Set/Get Global Options](#setget-global-options)
* [Custom CSS/style](#custom-cssstyle)
* [Testing](#testing)

## Installation

```shell
npm install @kloudless/file-picker
```

## How It Works

<!-- STORY HIDE START -->

[**Click here to test out our File Picker Vue component interactively**](https://kloudless.github.io/file-picker/vue)

<!-- STORY HIDE END -->

### Chooser

A button component that wraps the [Chooser](https://github.com/kloudless/file-picker#chooser)
view of the File Picker and will launch the Chooser when clicked.

#### Example

```html
<template>
  <chooser
    :options="{ 'app_id': 'KLOUDLESS_APP_ID' }"
    title="Click Chooser"
    @success="success"
    @addAccount="addAccount"
    @logout="logout" />
</template>

<script>
import { Chooser } from '@kloudless/file-picker/vue';

export default {
  name: 'app',
  components: { Chooser },
  methods: {
    success(result) { console.log('"success" received', result) },
    addAccount(account) { console.log('"addAccount" received', account) },
    logout() { console.log('"logout" received') },
  },
}
</script>
```

### createChooser

A method that accepts your custom component and wraps it in a new one that
launches the Chooser.
It will add a transparent component layer that will catch the click event from
the wrapped component and then launch the Chooser.

All the properties except `options` passed to the new component will be passed
to the wrapped component.  
Also, all the events emitted from the wrapped component will be propagated.  
In addition, the new component will emit the [events](#events) that
are generated by the Chooser.  
A `click` event will be emitted even if the wrapped component doesn't emit one.

#### Example

First, wrap your custom button:
```javascript
import { createChooser } from '@kloudless/file-picker/vue';
import MyButton from 'path/to/MyButton';

const MyChooserButton = createChooser(MyButton);

export default MyChooserButton;
```

Usage:
```html
<template>
  <my-chooser-button
    :options="{ 'app_id': 'KLOUDLESS_APP_ID' }"
    @click="click"
    @error="error"
    @success="success" />
</template>
```

### Saver

A button component that wraps the [Saver](https://github.com/kloudless/file-picker#saver)
view of the File Picker and will launch the Saver when clicked.

#### Example

```html
<template>
  <saver
    :options="{ \
      'app_id': 'KLOUDLESS_APP_ID' \
      'files': [{ \
          'url': 'https://www.app.com/logo.png', \
          'name': 'logo.png' \
        }, \
      }"
    title="Click Saver"
    @success="success"
    @addAccount="addAccount"
    @logout="logout" />
</template>

<script>
import { Saver } from '@kloudless/file-picker/vue';

export default {
  name: 'app',
  components: { Saver },
  methods: {
    success(result) { console.log('"success" received', result) },
    addAccount(account) { console.log('"addAccount" received', account) },
    logout() { console.log('"logout" received') },
  },
}
</script>
```

### createSaver

A method 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 catch the click event from
the wrapped component and then launch the Saver.

All the properties except `options` passed to the new component will be passed
to the wrapped component.  
Also, all the events emitted from the wrapped component will be propagated.  
In addition, the new component will emit the [events](#events) that
are generated by the Saver.  
A `click` event will be emitted even if the wrapped component doesn't emit one.

#### Example

First, wrap your custom button:
```javascript
import { createSaver } from '@kloudless/file-picker/vue';
import MyButton from 'path/to/MyButton';

const MySaverButton = createSaver(MyButton);

export default MySaverButton
```

Usage:
```html
<template>
  <my-saver-button
    :options="{ \
      'app_id': 'KLOUDLESS_APP_ID' \
      'files': [{ \
          'url': 'https://www.app.com/logo.png', \
          'name': 'logo.png' \
        }, \
      }"
    title="Click Saver"
    @success="success"
    @addAccount="addAccount"
    @logout="logout" />
</template>
```

### Dropzone

A [Dropzone](https://github.com/kloudless/file-picker#dropzone) component that
will launch the Chooser when clicked or launch the Saver when files are dropped.

#### Example

```html
<template>
  <dropzone
    :options="{ 'app_id': 'KLOUDLESS_APP_ID' }"
    @success="success"
    @addAccount="addAccount"
    @logout="logout" />
</template>

<script>
import { Dropzone } from '@kloudless/file-picker/vue';

export default {
  name: 'app',
  components: { Dropzone },
  methods: {
    success(result) { console.log('"success" received', result) },
    addAccount(account) { console.log('"addAccount" received', account) },
    logout() { console.log('"logout" received') },
  },
}
</script>
```

## 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](https://github.com/kloudless/file-picker#configuration)
  for more details on all possible configuration parameters.
- `title` _(Optional)_   
  The text shown on the button for `Chooser` or `Saver`.
  Default value: `Save a file` for `Saver`; `Choose a file` for `Chooser`.

## Attributes

Here are the DOM element attributes you can set:

- `class`
  CSS class names.
- `style`
  CSS styles directly set on the element.
- `disabled`
  `true` to disable the component.

## Events

Supports all of the events listed in [Events](https://github.com/kloudless/file-picker#events).

In addition, we support the `click` event:
- `click`
  Emitted when the component is clicked.

## Set/Get Global Options

```javascript
import { setGlobalOptions, getGlobalOptions } from '@kloudless/file-picker/vue';

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

The returned data and parameters are the same as for
`filePicker.setGlobalOptions()` and `filePicker.getGlobalOptions()`.
Please refer to the
[File Picker Methods](https://github.com/kloudless/file-picker#methods)
for more details.

## Custom CSS/style

By default, we don't apply any CSS styles to the components.
You have to include CSS files and set `class` or `style` props on your own.

## Testing

First, install dependencies as shown below. This only needs to be
done once:
```shell
$ npm ci --prefix storybook-vue/
```

Then, start up the testing server:
```shell
$ npm run storybook:vue
```

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:

```shell
# ABC123 is the App ID
$ STORYBOOK_KLOUDLESS_APP_ID=ABC123 npm run storybook:vue
```