Block plugins

caution

The plugin API is under active development and may change. This page documents the current registration interface for block developers.

Plugins let UI components — data tables, graphs, sequence alignments — own their persistent state. The component author packages state management into a plugin; the block developer registers an instance. The plugin handles its own initialization, persistence, and migrations.

Registering a plugin

Use .plugin() on the BlockModelV3 builder:

import { BlockModelV3, DataModelBuilder } from '@platforma-sdk/model';

// Assume `tablePlugin` is provided by a component library
import { tablePlugin } from '@platforma-sdk/ui-vue';

type BlockData = {
  inputRef?: PlRef;
  species: string;
};

const dataModel = new DataModelBuilder()
  .from<BlockData>('v1')
  .init(() => ({ species: 'human' }));

export const platforma = BlockModelV3.create(dataModel)
  .args((data) => {
    if (!data.inputRef) throw new Error('Input is required');
    return { inputRef: data.inputRef, species: data.species };
  })
  .plugin('mainTable', tablePlugin.create({ joinType: 'inner' }), {
    columns: (ctx) => ctx.outputs?.resolve('data')?.getPColumns(),
  })
  .done();

.plugin() takes three arguments:

1. Instance ID — a unique string identifying this plugin within the block (e.g., 'mainTable')
2. Configured plugin — from factory.create(config), provided by the component library
3. Params mapping — an object of lambdas that derive plugin inputs from the block's render context

The params mapping is re-evaluated whenever block data changes, so the plugin always receives current inputs. Multiple plugins can be registered on the same block — each with a distinct instance ID.