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 garunteed to have a the following options:
-
name : string
- the name of the field -
type : string
- the field type -
label : string (optional)
- a display name for the field
Full CustomPluginConfigOptions Type
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;
};
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 field -
allowMultiple : 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 field -
secure : boolean (optional)
- whether to omit input from pre-hydrated configs -
multiline : boolean (optional)
- whether this text input should allow multiple lines -
placeholder : string (optional)
- the placeholder for this input field -
defaultValue : 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 field -
defaultValue : 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 field -
defaultValue : 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 field -
values : string[]
- the options to show for this input field -
singleLine : boolean (optional)
- whether to display options on a single line. Good for (2-3) options -
defaultValue : 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 field -
values : string[]
- the options to show for this input field -
width : string (optional)
- how wide the dropdown should be in pixels -
defaultValue : 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
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(id: string): WorkbookVariable;
/**
* Setter for workbook variable passed in
*/
setVariable(id: string, ...values: unknown[]): void;
/**
* Getter for interaction selection state
*/
getInteraction(id: string): WorkbookSelection[];
/**
* Setter for interaction selection state
*/
setInteraction(
id: string,
elementId: string,
selection: WorkbookSelection[],
): void;
/**
* Overrider function for Config Ready state
*/
setLoadingState(ready: boolean): void;
/**
* Allows users to subscribe to changes in the passed in variable
*/
subscribeToWorkbookVariable(
id: string,
callback: (input: WorkbookVariable) => void,
): Unsubscriber;
/**
* Allows users to subscribe to changes in the passed in interaction ID
*/
subscribeToWorkbookInteraction(
id: string,
callback: (input: WorkbookSelection[]) => void,
): Unsubscriber;
};
elements: {
/**
* Getter for Column Data by parent sheet ID
*/
getElementColumns(id: string): Promise<WbElementColumns>;
/**
* Subscriber to changes in column data by ID
*/
subscribeToElementColumns(
id: string,
callback: (cols: WbElementColumns) => void,
): Unsubscriber;
/**
* Subscriber for the data within a given sheet
*/
subscribeToElementData(
id: 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
function useElementData(elementId: string): WorkbookElementData;
Arguments
-
elementId : string
- A workbook element’s unique identifier.
Returns the row data from the specified element.
interface WorkbookElementData {
[colId: string]: any[];
}
useVariable()
Returns a given variable's value and a setter to update that variable
function useVariable(
variableId: string,
): [WorkbookVariable | undefined, (...values: unknown[]) => void];
Arguments
-
variableId : string
- The ID of the 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 interation
function useInteraction(
interactionId: string,
elementId: string,
): [WorkbookSelection | undefined, (value: WorkbookSelection[]) => void];
Arguments
-
interactionId : string
- The ID of the interaction -
elementId : 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;
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.
-
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
!
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