@sigmacomputing/plugin
v1.0.6
Published
Sigma Computing Plugin Client API
Downloads
56,537
Maintainers
Keywords
Readme
Sigma Computing Plugins provides an API for third-party applications add additional functionality into an existing Sigma workbook.
Plugins are built using Sigma’s Plugin API. This API communicates data and interaction events between a Sigma workbook and the plugin. Plugins are hosted by their developer and rendered in an iframe in Sigma.
Warning: Breaking Changes
@sigmacomputing/plugin
has moved to https://github.com/sigmacomputing/plugin and
is now open source. Please read our
CHANGELOG.md
to review any breaking changes that have been made.
Requirements
To test your plugin in Sigma Plugin Dev Playground, you must:
- Have an Admin, Creator or Explorer account type
- Have Can Edit permission on the work
- Be in the workbook’s Edit mode
To test a development version of a registered plugin, you must:
Have either:
- An Admin account type
- A custom account type that supports plugin developer feature permissions
Have "can edit" permission on the workbook
Be in the workbook’s Edit mode
Your plugin must be a Javascript-based project and run in the browser.
Getting Started
Installation
Provided you have already followed the steps to create a plugin and a plugin
development environment, you can install @sigmacomputing/plugin
using one of
the following commands
yarn add @sigmacomputing/plugin
# or
npm install @sigmacomputing/plugin
If you have yet to set up your development environment, follow one of the setup guides below
Create a Development Project
At Sigma, we use React for all of our frontend development. This was taken into consideration when building Sigma’s Plugin feature.
While you are not required to use React for your plugin, it must be written in Javascript and React is recommended. We support both a standard Javascript API and a React Hooks API.
Create a Project with React
Open your terminal and navigate to the directory you want to create your project in.
Create your new project. We recommend using Facebook’s
create-react-app
.npx create-react-app <my-cool-plugin>
Navigate to the project's main directory.
cd <my-cool-plugin>
Use your package manager to install Sigma’s plugin library. We recommend using
yarn
.yarn add @sigmacomputing/plugin
Spin up your local development server.
yarn && yarn start
Start developing:
- Get started with Sigma’s Plugin APIs.
- Test your plugin directly in a Sigma workbook using the Sigma Plugin Dev Playground.
- By default, Create React App dev servers run on http://localhost:3000.
Testing your Plugin
Plugin developers should have access to a special plugin called Sigma Plugin Dev Playground. This plugin is available from any workbook and points to http://localhost:3000, by default.
If you cannot find this plugin, or would like a development playground with an alternative default host, please contact your Organization Admin with a request to Register a Plugin with its production URL set to your preferred development URL.
Using the Development Playground
Before you start:
Set your plugin’s development URL to http://localhost:3000.
Start your plugin locally
Note: If you followed our recommendations under #create-a-development-project, enter the following command in your terminal:
yarn && yarn start
- Create/open a workbook.
- In the workbook header, click Edit.
- Click the + button in the sidebar, to open the workbook’s ADD NEW panel.
- Select the PLUGINS element type, located under UI ELEMENTS.
- The editor panel will show you a list of available plugins. Select Sigma Plugin Dev Playground.
- Your new plugin element will appear on the page.
Note: The editor panel will only display content if you have configured your plugin using Sigma’s plugin Configuration API. Likewise, the element will only display content if your plugin is configured to display content. If you change a plugin's configuration options, input values will need to be re-added in the editor panel.
Now what?
- You can refresh your plugin as you make changes to its code. This option is available from the element’s menu.
- You are responsible for hosting your plugin. Learn more.
- When you’re ready to register your plugin, Add your custom your Plugin with Sigma.
Documentation
CustomPluginConfigOptions
A plugin can be configured with any number of configuration fields. Each field type has its own configuration options. Each field type is also guaranteed to have the following options:
name : string
- the name of the fieldtype : string
- the field typelabel : string (optional)
- a display name for the field
type CustomPluginConfigOptions =
| {
type: 'group';
name: string;
label?: string;
}
| {
type: 'element';
name: string;
label?: string;
}
| {
type: 'column';
name: string;
label?: string;
allowedTypes?: ValueType[];
source: string;
allowMultiple: boolean;
}
| {
type: 'text';
name: string;
label?: string;
source?: string; // can point to a group or element config
secure?: boolean; // if true will omit from prehydrated configs
multiline?: boolean;
placeholder?: string;
defaultValue?: string;
}
| {
type: 'toggle';
name: string;
label?: string;
source?: string;
defaultValue?: boolean;
}
| {
type: 'checkbox';
name: string;
label?: string;
source?: string;
defaultValue?: boolean;
}
| {
type: 'radio';
name: string;
label?: string;
source?: string;
values: string[];
singleLine?: boolean;
defaultValue?: string;
}
| {
type: 'dropdown';
name: string;
label?: string;
source?: string;
width?: string;
values: string[];
defaultValue?: string;
}
| {
type: 'color';
name: string;
label?: string;
source?: string;
}
| {
type: 'variable';
name: string;
label?: string;
allowedTypes?: ControlType[];
}
| {
type: 'interaction';
name: string;
label?: string;
}
| {
type: 'action-trigger';
name: string;
label?: string;
}
| {
type: 'action-effect';
name: string;
label?: string;
};
Group
Can be used to identify a group of related fields
Element
A custom element that is added by your plugin
Column
A custom column configuration that your plugin uses
Additional Fields
allowedTypes : ValueType[] (optional)
- the allowed data types that this column can contain whereValueType
has the following type:type ValueType = | 'boolean' | 'datetime' | 'number' | 'integer' | 'text' | 'variant' | 'link' | 'error';
source : string
- the data source that should be used to supply this fieldallowMultiple : boolean
- whether multiple columns should be allowed as input for this field
Text
A configurable text input for your plugin
Additional Fields
source : string (optional)
- the data source that should be used to supply this fieldsecure : boolean (optional)
- whether to omit input from pre-hydrated configsmultiline : boolean (optional)
- whether this text input should allow multiple linesplaceholder : string (optional)
- the placeholder for this input fielddefaultValue : string (optional)
- the default value for this input field
Toggle
A configurable toggle for your plugin
Additional Fields
source : string (optional)
- the data source that should be used to supply this fielddefaultValue : boolean (optional)
- the default value for this input field
Checkbox
A configurable checkbox for your plugin
Additional Fields
source : string (optional)
- the data source that should be used to supply this fielddefaultValue : boolean (optional)
- the default value for this input field
Radio
A configurable radio button for your plugin
Additional Fields
source : string (optional)
- the data source that should be used to supply this fieldvalues : string[]
- the options to show for this input fieldsingleLine : boolean (optional)
- whether to display options on a single line. Good for (2-3) optionsdefaultValue : boolean (optional)
- the default value for this input field
Dropdown
A configurable dropdown for your plugin
Additional Fields
source : string (optional)
- the data source that should be used to supply this fieldvalues : string[]
- the options to show for this input fieldwidth : string (optional)
- how wide the dropdown should be in pixelsdefaultValue : boolean (optional)
- the default value for this input field
Color
A configurable color picker for your plugin
Additional Fields
source : string (optional)
- the data source that should be used to supply this field
Variable
A configurable workbook variable to control other elements within your workbook
Additional Fields
allowedTypes : ControlType[] (optional)
- the allowed control types that this variable can use whereControlType
has the following type:type ControlType = | 'boolean' | 'date' | 'number' | 'text' | 'text-list' | 'number-list' | 'date-list' | 'number-range' | 'date-range';
Interaction
A configurable workbook interaction to interact with other charts within your workbook
Action Trigger
A configurable action trigger to trigger actions in other elements within your workbook
Action Effect
A configurable action effect that can be triggered by other elements within your workbook
PluginInstance
interface PluginInstance<T> {
sigmaEnv: 'author' | 'viewer' | 'explorer';
config: {
/**
* Getter for entire Plugin Config
*/
get(): Partial<T> | undefined;
/**
* Performs a shallow merge between current config and passed in config
*/
set(config: Partial<T>): void;
/**
* Getter for key within plugin config
*/
getKey<K extends keyof T>(key: K): Pick<T, K>;
/**
* Assigns key value pair within plugin
*/
setKey<K extends keyof T>(key: K, value: Pick<T, K>): void;
/**
* Subscriber for Plugin Config
*/
subscribe(listener: (arg0: T) => void): Unsubscriber;
/**
* Set possible options for plugin config
*/
configureEditorPanel(options: CustomPluginConfigOptions[]): void;
/**
* Gets a static image of a workbook variable
*/
getVariable(configId: string): WorkbookVariable;
/**
* Setter for workbook variable passed in
*/
setVariable(configId: string, ...values: unknown[]): void;
/**
* Getter for interaction selection state
*/
getInteraction(configId: string): WorkbookSelection[];
/**
* Setter for interaction selection state
*/
setInteraction(
configId: string,
elementId: string,
selection: WorkbookSelection[],
): void;
/**
* Triggers an action based on the provided action trigger ID
*/
triggerAction(configId: string): void;
/**
* Registers an effect with the provided action effect ID
*/
registerEffect(configId: string, effect: Function): void;
/**
* Overrider function for Config Ready state
*/
setLoadingState(ready: boolean): void;
/**
* Allows users to subscribe to changes in the passed in variable
*/
subscribeToWorkbookVariable(
configId: string,
callback: (input: WorkbookVariable) => void,
): Unsubscriber;
/**
* @deprecated Use Action API instead
* Allows users to subscribe to changes in the passed in interaction ID
*/
subscribeToWorkbookInteraction(
configId: string,
callback: (input: WorkbookSelection[]) => void,
): Unsubscriber;
};
elements: {
/**
* Getter for Column Data by parent sheet ID
*/
getElementColumns(configId: string): Promise<WbElementColumns>;
/**
* Subscriber to changes in column data by ID
*/
subscribeToElementColumns(
configId: string,
callback: (cols: WbElementColumns) => void,
): Unsubscriber;
/**
* Subscriber for the data within a given sheet
*/
subscribeToElementData(
configId: string,
callback: (data: WbElementData) => void,
): Unsubscriber;
};
/**
* Destroys plugin instance and removes all subscribers
*/
destroy(): void;
}
Framework Agnostic API
client
The client is a pre-initialized plugin instance. You can use this instance
directly or create your own instance using initialize
const client: PluginInstance = initialize();
Usage
import { client } from '@sigmacomputing/plugin';
client.config.configureEditorPanel([
{ name: 'source', type: 'element' },
{ name: 'dimension', type: 'column', source: 'source', allowMultiple: true },
]);
initialize()
Instead of using the pre-initialized plugin instance, you can create your own plugin instance.
function initialize<T = {}>(): PluginInstance<T>;
Usage
import { initialize } from '@sigmacomputing/plugin';
const myClient: PluginInstance = initialize();
myClient.config.configureEditorPanel([
{ name: 'source', type: 'element' },
{ name: 'dimension', type: 'column', source: 'source', allowMultiple: true },
]);
React API
A context provider your plugin that enables all of the other React API hooks. You should wrap your plugin with this provider if your want to use the plugin hook API.
interface SigmaClientProviderProps {
client: PluginInstance;
children?: ReactNode;
}
function SigmaClientProvider(props: SigmaClientProviderProps): ReactNode;
usePlugin()
Gets the entire plugin instance
function usePlugin(): PluginInstance;
useEditorPanelConfig()
Provides a setter for the plugin's configuration options
function useEditorPanelConfig(nextOptions: CustomPluginConfigOptions[]): void;
Provides a setter for the Plugin's Config Options
Arguments
nextOptions : CustomPluginConfigOptions[]
- Updated possible Config Options
useLoadingState()
Gets the current plugin's loading stat. Returns a value and a setter allowing you to update the plugin's loading state
function useLoadingState(
initialState: boolean,
): [boolean, (nextState: boolean) => void];
Arguments
initialState : boolean
- Initial value to set loading state to
useElementColumns()
Provides the latest column values from corresponding sheet
function useElementColumns(elementId: string): WorkbookElementColumns;
Arguments
elementId : string
- A workbook element’s unique identifier.
Returns the column information from the specified element.
interface WorkbookElementColumn {
id: string;
name: string;
columnType: ValueType;
}
interface WorkbookElementColumns {
[colId: string]: WbElementColumn;
}
useElementData()
Provides the latest data values from corresponding sheet, up to 25000 values.
function useElementData(configId: string): WorkbookElementData;
Arguments
configId : string
- A workbook element’s unique identifier from the plugin config.
Returns the row data from the specified element.
interface WorkbookElementData {
[colId: string]: any[];
}
usePaginatedElementData()
Provides the latest data values from the corresponding sheet (initially 25000), and provides a callback for fetching more data in chunks of 25000 values.
function useElementData(configId: string): [WorkbookElementData, () => void];
Arguments
configId : string
- A workbook element’s unique identifier from the plugin config.
Returns the row data from the specified element, and a callback for fetching more data.
interface WorkbookElementData {
[colId: string]: any[];
}
useVariable()
Returns a given variable's value and a setter to update that variable
function useVariable(
configId: string,
): [WorkbookVariable | undefined, (...values: unknown[]) => void];
Arguments
configId : string
- The config ID corresponding to the workbook control variable
The returned setter function accepts 1 or more variable values expressed as an array or multiple parameters
function setVariableCallback(...values: unknown[]): void;
useInteraction()
Returns a given interaction's selection state and a setter to update that interaction
function useInteraction(
configId: string,
elementId: string,
): [WorkbookSelection | undefined, (value: WorkbookSelection[]) => void];
Arguments
configId : string
- The config ID corresponding to the workbook interactionelementId : string
- The ID of the element that this interaction is associated with
The returned setter function accepts an array of workbook selection elements
function setVariableCallback(value: WorkbookSelection[]): void;
useActionTrigger()
configId : string
- The config ID corresponding to the action trigger
Returns a callback function to trigger one or more action effects for a given action trigger
function useActionTrigger(configId: string): () => void;
triggerActionCallback();
Arguments
configId : string
- The config ID corresponding to the action trigger
The function that can be called to asynchronously trigger the action
function triggerActionCallback(configId: string): void;
useActionEffect()
Registers and unregisters an action effect within the plugin
function useActionEffect(configId: string, effect: () => void);
Arguments
configId : string
- The config ID corresponding to the action effecteffect : Function
- The function to be called when the effect is triggered
useConfig()
Returns the workbook element’s current configuration. If a key is provided, only the associated configuration is returned.
function useConfig(key?: string): any;
Arguments
key : string (optional)
- The name of a key within the associatedPluginConfigOptions
object
Examples
Sigma’s development team has created a set of example plugins, listed below.
All of our example plugins are hosted and can be added to your organization. To view / add an example plugin to your organization, follow the steps to register a plugin using its Production URL, listed below.
You can also visit Sigma’s Sample Plugin repository directly on Github.
Available Plugins
Recharts Bar Chart - A basic bar chart built with the Recharts library.
- Source Code
- Production URL: https://sigma-sample-bar-chart-54049.netlify.app/
D3 Candlestick - A candlestick visualization built with D3.
- Source Code
- Production URL: https://sigma-sample-candlestick-chart-1664e5.netlify.app/
Narrative Science Quill - Demonstrates secure text entry.
- Source Code
- Production URL: https://narrativescience-quill-3ee312.netlify.app/
D3 Graph - Demonstrates usage of multiple data sources and in-memory joins.
- Source Code
- Production URL: https://d3-graph-3a0d0f.netlify.app/
D3 Sunburst - A sunburst visualization built with D3.
- Source Code
- Production URL: https://d3-sunburst-b97c7c.netlify.app/
Frappe Heatmap - A basic Frappe visualization example.
- Source Code
- Production URL: https://frappe-heatmap-9a4163.netlify.app/
Use an Example in Your Organization
To add an example plugin to your organization, follow the steps to register a plugin using its Production URL, listed in the examples above.
Run an Example Locally
Open your terminal, and navigate to the directory you want to save the example’s in.
Clone Sigma’s Sample Plugin repository.
git clone https://github.com/sigmacomputing/sigma-sample-plugins.git
Navigate to the plugin you would like to try.
cd sigma-sample-plugins/<plugin-name>
Run the plugin.
yarn && yarn start
Note: For additional instructions, visit the README file located in the main directory of any given example plugin.
Host Your Plugin
As a plugin developer, you are responsible for hosting your plugin(s). If you’re new to hosting your own projects, here are a few popular hosting platforms you can get started with:
Contributing
We welcome contributions to @sigmacomputing/plugin
!
🐛 Issues, 📥 Pull requests and 🌟 Stars are always welcome. Read our contributing guide to get started.
yarn format
Format your code to match the sigmacomputing style guide
yarn test
Check if the unit tests all pass
You can also run the tests in
--watch
mode with yarn test:watch