LogoLogo
FeaturesHelp & ResourcesShowcasePricingLogin
Squirrel Addon Documentation
Squirrel Addon Documentation
  • README
  • Table of contents
  • Building an addon
    • Communication
    • Property Panel
      • Property Panel Elements
        • Accordion
        • Checkbox
        • Color Input
        • Conditional Logic
        • Dropdown
        • Font
        • Horizontal Line
        • Input Box
        • Radio Button
        • Series
        • Sub Accordion
        • Text Label
    • Publishing an addon
      • Restricting private addons
      • The review process
      • Add-on submission
        • Icon guidelines
        • Image guidelines
  • introduction
    • Joining the Developer Program
  • past-events
    • Building your first add-on
  • squirrel-helper-library
    • Dot notation
    • Angular
      • Classes
        • SquirrelCanvas
        • SquirrelColor
        • SquirrelMessage
        • SquirrelPosition
        • SquirrelSize
      • Events
        • onInitState
        • onPropertyChange
        • onPropertyChangesComplete
        • onSetCanvas
        • onSetPosition
        • onSetRuntimeMode
        • onSetSize
      • Getting Started
        • Building your first addon
        • Debugging
        • Sending and Receiving Data
        • The JSON files
      • Methods
        • getBindingDimension
        • getCanvas
        • getCopyOfState
        • getGenericProperty
        • getPosition
        • getRuntimeMode
        • getSize
        • initWithSquirrel
        • parseColor
        • sendToSquirrel
        • setPosition
        • setSize
        • shadeColor
        • tintColor
    • JavaScript
      • Classes
        • SquirrelCanvas
        • SquirrelColor
        • SquirrelMessage
        • SquirrelPosition
        • SquirrelSize
      • Events
        • onInitState
        • onPropertyChange
        • onPropertyChangesComplete
        • onSetCanvas
        • onSetPosition
        • onSetRuntimeMode
        • onSetSize
      • Getting Started
        • Building your first add-on
        • Debugging
        • Sending and Receiving Data
        • The JSON files
      • Methods
        • getBindingDimension
        • getCanvas
        • getCopyOfState
        • getGenericProperty
        • getPosition
        • getRuntimeMode
        • getSize
        • initWithSquirrel
        • parseColor
        • sendToSquirrel
        • setPosition
        • setSize
        • shadeColor
        • tintColor
    • React
      • Coming Soon
Powered by GitBook
LogoLogo

Explore

  • Home
  • Features
  • Pricing
  • Download Squirrel

Help

  • Learn
  • Community
  • Support
  • FAQ's

Updates

  • Blog
  • Events
  • Release Notes

Company

  • Contact Us
  • Privacy Policy
  • Terms of Use

Copyright © 2019 - 2024 InfoSol Ltd. All rights reserved.

On this page
  • Communication overview
  • Handshaking
  • Binding Dimensions
  • Example data structure
  • Sending Data to Squirrel
  • Blocking interactions in Squirrel
  • Resizing and repositioning in Squirrel

Was this helpful?

  1. Building an addon

Communication

PreviousBuilding an addonNextProperty Panel

Last updated 3 years ago

Was this helpful?

Communication overview

Squirrel embeds an addon in an iframe and communicates back and forth with it via JavaScript . As Squirrel could have multiple addons in the same project Squirrel needs a way to identify which addon to send data to, and which addon has sent data back. This is handled in the Squirrel helper library for you, but for background here is a summary of what it’s doing:

  1. When Squirrel embeds an instance of your addon in a project it generates a unique ID for that instance.

  2. This ID is added to the URL string for your addon as a query parameter

  3. The addon framework gets this ID and this is included in all messages to Squirrel.

  4. Squirrel uses this unique ID when sending messages to ensure the message gets sent to the correct addon.

Handshaking

Before Squirrel can send data to an addon it needs to know when the addon is ready to receive data. This is achieved via a handshake.

Once you have done any setup and initialization on your addon and you’re ready to process messages from Squirrel. You need to call the method, from the Squirrel helper library. This sends a message to Squirrel to advise it the addon is ready and waiting. Squirrel then responds with the message, which the Squirrel helper library validates and then calls a number of corresponding callback methods in your addon. By overriding these callback methods you can then process the data being sent.

Binding Dimensions

When binding a property to cell(s) in Squirrel it is useful to know the size of the range of cells selected. For example

  • Has a property only been bound to a single cell e.g. 1 column by 1 row.

  • Has it been bound to a range of cells. e.g. 2 columns by 3 rows etc

Knowing the dimensions of the binding means that you can ensure the data you send to Squirrel matches the correct structure.

  • For single cells

    • Squirrel expects a primitive values (eg string, bool, number etc)

  • For multiple cells

    • Squirrel expects a multi dimensional array for the row and columns.

      • Rows are made up of arrays of primitive values. Each value represents the column

      • The data is then made up of an array of rows.

Example data structure

single cell
"Hello"
3 rows of 2 columns
[
 ['cell A1', 'cell B1'],
 ['cell A2', 'cell B2'],
 ['cell A3', 'cell B3'],
]
1 row of 2 columns
[
 ['cell A1', 'cell B1']
]

Sending Data to Squirrel

Padding the data is where the helper library will check the binding dimensions of the property you are sending, and ensure the data you’re passing is the correct size. This is accomplished by either adding extra rows or columns in to the array with nulls. Passing a padded data structure means that Squirrel will always overwrite all cells in the binding range ensure there are no erroneous values left over from a previous message.

Blocking interactions in Squirrel

The no interaction setting will prevent any events from triggering in your addon.

Resizing and repositioning in Squirrel

Sometimes you may want to resize or change the location of your addon component in Squirrel. For example if your addon needs to expand or shrink to show / hide additional content. This can be achieved by calling setter methods:

Once your addon is setup and has processed the incoming state from Squirrel, you may need to send information back for Squirrel to insert the data into cells in the spreadsheet. This is handled by calling the method in the Squirrel helper library.

Passing the variable name (matching a variable in ) and the data to send to Squirrel. This method constructs the message body and sends the data off to Squirrel. An optional parameter to include at the end of the method call is a bool to advise whether to pad the data. This is set to true by default.

Addons in Squirrel block mouse events from passing through to underlying components. So for example a button behind your addon will not be clickable. It is possible to globally tell Squirrel that your addon does not require interaction (thereby allowing all events to pass through). This is done when you

Calling either of these methods will update the size / position on the Squirrel canvas, and will trigger an event.

sendToSquirrel
publish the addon
setSize()
setPosition()
onPropertyChange
post messaging
initState
initWithSquirrel
default state