The Plugin Client is the main API that your custom plugin will use to communicate with Dashibase. It allows developers to access information within a table such as column IDs and per-row values, as well as control specific details of the plugin block such as its dimensions.

Installation

To get started, install the plugin client into your javascript project with a package manager:

Via NPM

npm install @dashibase/plugin-client

Via Yarn

yarn add @dashibase/plugin-client

And import it into your project:

import PluginClient from '@dashibase/plugin-client'

Quick Start

Initialization

The initialization of a plugin is a two-step process. Your plugin has to first send a message to Dashibase to begin the process, and once ready, Dashibase will reply with a message to finish the initialization.

All messages are sent and received through the Plugin Client. You may create a new Plugin Client by calling its constructor.

const client = new PluginClient()

Every plugin must register a callback function with the client’s onSetup method. This callback function will be invoked once the initialization process is completed.

client.onSetup((data) => {  console.log('Plugin has initialized')})

When ready, you can begin the initialization process by calling the client’s init method.

client.init()

After the initialization is completed, the callback function that you registered in the onSetup method will be invoked.

Minimal Example

Here is a minimal code snippet that demonstrates the typical setup.

const client = new PluginClient()client.onSetup((data) => {  console.log('Plugin has initialized')  // Do something here with the data provided from Dashibase})// Tell Dashibase we are readyclient.init()

API Reference

init()

Required for all plugins.

Sends a message to Dashibase to begin the initialization process.

Example

const client = new PluginClient()client.init()

onSetup()

Required for all plugins.

Registers a callback function that will be invoked when the plugin is initialized.

Parameters

func: (payload: SetupMessage) => void (required)

The callback function to be invoked upon initialization.

The callback function will have access to a SetupMessage object with the following properties:

• store: { [string] : any } : An object containing all key-value pairs that were previously stored by the store() method
• columnIds: string[] : An array of strings representing all the column IDs of the current table
• foreignColumnIds: string[] : An array of strings representing the column IDs of all foreign attributes from joined tables. This feature is still in development and is currently unavailable.

Examples

Check if store contains a key-value pair

client.onSetup((data) => {  if (data.store[key]) {    console.log(`${key} is present`)  }})

Retrieve available column IDs

Suppose we want to populate a dropdown in the plugin with the column IDs of the table. We can do so with the data in the SetupMessage object:

import { useState } from 'react'const [dropdownOptions, setDropdownOptions] = useState([])client.onSetup((data) => {  setDropdownOptions([...data.columnIds])}) 

request()

Requests the value of the specified attribute in the current row of the table.

Parameters

key: string (required)

The column ID / attribute name whose value is requested.

Returns

Promise <RespondMessage>

Notes

The key provided must correspond to one of the column IDs of the table. These can be accessed from SetupMessage.columnIds in the onSetup method.

The function returns a promise that resolves to a RespondMessage object, which contains the requested value in its value field.

Examples

Requesting the value of the first column in the table

A common design pattern is to request for certain values in the table once the plugin has been set up. This is typically achieved by calling the request method in the callback function passed to onSetup.

client.onSetup((data) => {  const key = data.columnIds[0]  client.request(key).then((response) => {    console.log(`The value of ${key} is ${response.value}`)  })})

Requesting the value of the id column on click

async function onClick() {  const response = await client.request('id')  const value = response.value  // ...}

store()

Stores a key-value pair on Dashibase that persists between page loads & initializations.

Parameters

key: string (required)

The key of the key-value pair being stored.

value: any (required)

The value of the key-value pair being stored.

Returns

Promise <StoreMessage>

Notes

All key-value pairs stored using this function will be returned in the SetupMessage.store object in the onSetup method in future initializations. This allows some form of state persistence.

For example, if we are building a Stripe plugin, we might first have the user tell us which column contains the Stripe user ID during the initial setup. But after that, we can persist this column via store so that we do not have to ask the user again in the future.

Examples

Storing a value

client.store('key', 'value')

Performing initial setup

client.onSetup((data) => {  if (!data.store['myKey']) {    // If `myKey` is not found in the store, this is probably    // the first time we are loading the plugin    // Do some setup here e.g. ask user for column ID    client.store('myKey', 'myValue')  } else {    // `myKey` is found, so we don't need the user to go over the setup again  }})

setBlockDimensions()

Sets the height, width and resize directions of the plugin block in the Dashibase dashboard.

Parameters

height: number

The new height of the plugin block, in pixels. If value is not provided or undefined, the height of the block will remain unchanged.

width: number

The new width of the plugin block, in pixels. If value is not provided or undefined, the width of the block will remain unchanged.

resizable: boolean | "height" | "width"

Value representing how the user can resize the plugin. If value is not provided, it will default to false.

This can take four possible values:

• true: The user can resize the height & width of the plugin
• false: The user cannot resize the plugin
• "height": The user can resize the height of the plugin
• "width": The user can resize the width of the plugin

Returns

Promise <SetDimensionsMessage>

Examples

Setting the height and width of the plugin

client.setBlockDimensions(100, 100)

Setting resizable value

if (resizable) {    client.setBlockDimensions(undefined, undefined, true)} else {    client.setBlockDimensions(undefined, undefined, false)}

Types

SetupMessage

• id: string
• messageType: MessageType
• store: { [string] : any }
• columnIds: string[]
• foreignColumnIds: string[]

RespondMessage

• id: string
• messageType: MessageType
• key: string
• value: any

StoreMessage

• id: string
• messageType: MessageType
• key: string
• value: any

SetDimensionsMessage

• id: string
• messageType: MessageType
• height: number | undefined
• width: number | undefined
• resizable: boolean | "height" | "width"