README.vue.md

Vue components for the Kloudless Authenticator

This is a thin Vue wrapper for the Kloudless Authenticator. We provide the following components to add the Authenticator to any Vue app:

• AuthButton: A button component that will launch the Authenticator when clicked.
• createAuthButton: A method that accepts your custom component and wraps it in a new one that launches the Authenticator.

Supports Vue v2.

DEMO

Table of contents

• Installation
• How It Works
  • AuthButton
    • Example
  • createAuthButton
    • Example
• Props
• Attributes
• Events
• Set/Get Global Options
• Testing

Installation

npm install @kloudless/authenticator

How It Works

AuthButton

A button component that wraps the Authenticator view and will launch the Authenticator when clicked.

Example

<template>
  <auth-button
    :options="{ 'client_id': 'KLOUDLESS_APP_ID' }"
    class="CUSTOM_CLASS"
    disabled="false"
    title="BUTTON_TITLE"
    @click="onClick"
    @error="onError"
    @success="onSuccess" >
  </auth-button>
</template>

<script>
import { AuthButton } from '@kloudless/authenticator/vue';

export default {
  components: { AuthButton },
  methods: {
    onClick() { console.log('click'); },
    onSuccess(result) { console.log('success', result) },
    onError(error) { console.log('error', error) }
  }
};
</script>

createAuthButton

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

All the properties passed to the new component will be passed to the wrapped component except for the options property. Also, all the events emitted from the wrapped component will be propagated. In addition, the new component will emit the events that are generated by the Authenticator. A click event will be emitted even if the wrapped component doesn't emit one.

Example

First, wrap your custom button:

import { createAuthButton } from '@kloudless/authenticator/vue';
import CustomButton from 'path/to/CustomButton';

const CustomAuthButton = createAuthButton(CustomButton);

export default CustomAuthButton

Usage:

<template>
  <custom-auth-button
    :options="{ 'client_id': 'KLOUDLESS_APP_ID' }"
    @click="onClick"
    @error="onError"
    @success="onSuccess" />
</template>

Props

• options (Required) OAuth config object.
• options.client_id (Required) The Kloudless application ID.
• options.scope (Optional) Used to determine which services the user can choose from to connect. Could either be an Array of different scopes, or a space-delimited string. ex: "any.calendar any.storage", ["any.calendar", "any.storage"]
• options.extra_data (Optional) A URL-encoded JSON object containing data used to pre-fill default values for fields in the Kloudless authentication forms. ex: the domain of a WebDAV server.
• options.oob_loading_delay (Optional) Indicates the number of milliseconds the loading spinner will last on the callback page before revealing the token. Defaults to 2000.
• title (Optional) The text shows on the AuthButton. Defaults to "Connect Account".

Attributes

Here are the DOM element attributes you can set:

• style CSS styles directly set on the AuthButton.
• class CSS class names.
• disabled true to disable AuthButton.

Events

• success Emitted when authentication succeeds. The event parameter object contains the access token obtained via the OAuth flow, as well as the metadata of the connected account :

  {
      'access_token': 'TOKEN123ABC',
      'token_type': 'Bearer',
      'scope': 'box:normal.storage', // Currently, the requested scope is returned
      'state': 'randomstate123',
      'account': {
          'id': 123,
          'service': 'box',
          ...
      }
  }

• error Emitted when authentication fails. The event parameter object contains error information:

  {
    'error': "server_error"
    'error_description': "An error occurred. User did not authorize access to account"
    'state': "7691344675"
  }

• click Emitted when the component is clicked.

Set/Get Global Options

See auth.setGlobalOptions() and auth.getGlobalOptions().

Testing

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

$ npm install --prefix storybook-vue/

Then, start up the testing server:

$ 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:

# YOUR_APP_ID is the App ID
$ STORYBOOK_KLOUDLESS_APP_ID=YOUR_APP_ID npm run storybook:vue