Save and load icons

  • Blockly icons can optionally save their state for persistence, requiring the implementation of the ISerializable interface and registration.

  • Icon state is stored within the icons property of a block's state in JSON format, utilizing the saveState and loadState methods.

  • The saveState method includes an optional doFullSerialization parameter to handle cases where the referenced data model isn't available during deserialization, for instance when loading or copying blocks.

  • To load saved icon state, implement the loadState method which receives the JSON data previously saved by saveState.

  • For the serialization system to instantiate your custom icon, register it using its corresponding IconType, ensuring consistency with the getType method's return value.

Some icons have state that needs to be saved, while others are instantiated based on existing state. For example, comment icons need to save their text, while warning icons don't because they are instantiated based on how blocks are connected.

If your icon needs to save its state, you need to implement the ISerializable interface and register your icon.

The state returned by your icon gets included in the icons property of your block's state:

{
  'blocks': {
    'languageVersion': 0,
    'blocks': [
      {
        'type': 'my_block',
        'icons': {
          // Your state goes here!
          'my_icon': 'some state',
        }
      }
    ]
  }
}

Save state

To save the state of your icon, you need to implement the saveState method of the ISerializable interface. This method can return arbitrary json, which gets passed to your loadState method.

saveState() {
  return this.state;  // Some arbirtary JSON-compatible data.
}

Full serialization and backing data

saveState also receives an optional doFullSerialization parameter. This is used by icons that reference state serialized by a different serializer (like backing data models). The parameter signals that the referenced state won't be available when the block is deserialized, so the icon should serialize all of the backing state itself. For example, this is true when an individual block is serialized, or when a block is copy-pasted.

Two common use cases for this are:

  • When an individual block is loaded into a workspace where the backing data model doesn't exist, the icon has enough information in its own state to create a new data model.
  • When a block is copy-pasted, the icon always creates a new backing data model instead of referencing an existing one.

Load state

To save the state of your icon, you need to implement the loadState method of the ISerializable interface. This method takes in the JSON returned by your saveState method.

loadState(state) {
  this.state = state;
}

Register icon classes

Finally you need to register your icon so that the serialization system can instantiate it. Remember that the IconType used to register your icon needs to have the same string as the one returned by its getType method.

class myIcon extends Blockly.icons.Icon {
  getType() {
    return new Blockly.icons.IconType('my_icon');
  }
}

Blockly.icons.registry.register(
    new Blockly.icons.IconType('my_icon'), myIcon);