Develop Sigma Plugins

Plugins are third-party applications built to add additional functionality into an existing product. Sigma supports plugins for workbooks.

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.

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 (a) an Admin account type or (b) a custom account type that supports plugin developer feature permissions 
  • have Can Edit permission on the work
  • be in the workbook’s Edit mode
• Your plugin must be a JavaScript-based project and run in the browser.
  
  

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

1. Open your terminal and navigate to the directory you want to create your project in.
2. Create your new project. We recommend using Facebook’s Create React App.
   

   npx create-react-app <my-cool-plugin>

3. Navigate to the project's main directory.
   

   cd <my-cool-plugin>

4. Use your package manager to install Sigma’s plugin library. We recommend yarn.
   

   yarn add @sigmacomputing/plugin

5. Spin up your local host.
   

   yarn && yarn start

6. 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.

The Plugin Development API

To view documentation for API documentation for this feature, visit Plugin Development API.

The Plugin Development Playground

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.

Use the Development Playground

Before you start:

• Set your plugin’s development URL to http://localhost:3000.
• Run your plugin remotely.
  Note: If you followed our recommendations under Create a Development Project, enter the following command in your terminal:
  

   yarn && yarn start

1. Create/open a workbook.
2. In the workbook header, click Edit.
3. Click the + button in the sidebar, to open the workbook’s ADD NEW panel.
4. Select the PLUGINS element type, located under UI ELEMENTS.
   
   
5. 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.
   Notes:
   • 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, visit Register a Plugin with your Sigma.
  
  

Test a Development Version of a Plugin

1. Start up your development server.
   Note: If you followed our recommendations under Create a Development Project, enter the following command in your terminal:
   

    yarn && yarn start

2. Create/open a workbook.
3. If you want to work with an existing element using the plugin, select that element.
   Otherwise, create a new plugin-based element.
4. Hover over the element and click the vertical ••• icon button in its top right corner.
5. Select Point to Development URL.
   
   This will open the Configure Dev Server modal.
6. Enter your development URL.
   
   
7. Click Confirm.
   

Now what?

• Your Sigma plugin element will automatically update to reflect saved changes to your code. There is no need to refresh the Sigma page. 
• You can switch back to the production URL at any time, from the same element menu you used to set your temporary development URL (see steps above).

Note: If you change a plugin's configuration options, input values will need to be re-added in the editor panel.

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:

• Heroku
• Netlify 
  
  

Related Resources

Get Started with Custom Plugins
Plugin Development API
Register a Plugin with your Sigma Organization