Component extensions: add features to a component without touching it

Extensions add namespaced fields, functions, workflows, templates and config to an existing component, can be switched off without losing data, and are how marketplace apps add features to components you already have.

A component holds your data model and the logic that belongs to it. Sometimes you want to add to a component you didn't write, or one that is shared: a tracking number on every order, an SEO block on every product, a status lookup against a carrier. Editing the core settings for each of those makes the component harder to reason about, and it makes the additions hard to remove.

An extension is the answer. It is a self-contained package that attaches to a component and adds capabilities without modifying the component's core settings. This post covers what an extension contributes, how its names stay separate from the component's own, how to switch it on and off, how to type it, and how marketplace apps use extensions. For the component itself, see our post on components.

You build and manage extensions in the dashboard under Developer › Extension Builder, and through the API and SDK.

What an extension contributes

An extension can add any of these:

Part What it is
Fields Extra data fields stored alongside the component's native fields
Functions Custom functions scoped to the extension
Workflows Workflow nodes that react to the component's create, update and delete events
Templates UI templates for rendering extension-specific views
Config Extension-specific key-value configuration

Extensions are versioned and can be activated or deactivated independently. While an extension is active, its fields, functions and workflows take part in all component operations automatically.

Here is a shipping_tracker extension that adds two fields, a function and some config to an orders component:

{
  "name": "shipping_tracker",
  "is_active": true,
  "version": "1.0.0",
  "fields": [
    {
      "key": "tracking_number",
      "name": "Tracking Number",
      "type": "string",
      "module": "input",
      "visible": true,
      "constraints": { "required": true }
    },
    {
      "key": "carrier",
      "name": "Carrier",
      "type": "string",
      "module": "select",
      "visible": true,
      "constraints": { "selectables": { "items": ["DHL", "FedEx", "UPS", "USPS"] } }
    }
  ],
  "functions": [
    {
      "name": "get_tracking_status",
      "expr": "return await Http.get(`https://api.carrier.com/track/${input.tracking_number}`)"
    }
  ],
  "workflows": [],
  "config": { "default_carrier": "DHL" }
}

Keep API keys and URLs in the extension's config rather than hard-coding them in functions.

Namespacing

Everything an extension adds lives under its own name, so it can't collide with the component or with other extensions.

Fields are stored at extensions.{extension_name}.{field_key}. Use that full path to update, filter, sort and project:

const component = new Component("orders")

await component.create({
  order_id: "ORD-001",
  extensions: {
    shipping_tracker: { tracking_number: "1234567890", carrier: "DHL" }
  }
})

await component.update(uuid, { "extensions.shipping_tracker.carrier": "FedEx" })

const results = await component.find({
  $adv: { "extensions.shipping_tracker.carrier": "DHL" }
})

Extension fields are ordinary fields under a prefix. They carry the same module and type as any other field and follow the same rules. For example, you can sort on one that stores a scalar, but not on one that stores an array or object. Because of the prefix, extensions is a reserved field key on a component, and field keys can't contain a dot.

Functions use dot notation: shipping_tracker.get_tracking_status.

Calling extension functions

Extension functions have the same structure and execution context as component functions. Call them as extensionName.functionName, over the API or from the SDK:

POST /v4/system/component/orders/function/shipping_tracker.get_status
import { Component } from "@ptkl/sdk"

const orders = new Component("orders")
await orders.function("shipping_tracker.get_status", {
  tracking_number: "1234567890"
})

If you don't care which extension provides a function, prefix the name with $.. The platform then looks at the component's own functions first, then at active extensions in install order. If several extensions define the same name, the last one installed wins:

await orders.function("$.calculate", { amount: 100 })

Extension functions exist only while the extension is active. When it is deactivated, calling one returns a not-found error. Who may run them is a permission: functions for all of a component's functions, or function::{name} for one.

Workflows

When a record event happens, the platform runs the component's own workflows and then each active extension's workflows, in order. Extension workflows get the same event context as the component's, plus the extension's name and config:

{
  "context": {
    "event": "Before::Create",
    "component": "orders",
    "extension": { "name": "shipping_tracker", "config": { } },
    "schema": "default"
  }
}

A component's code, including its extension functions and extension workflows, runs as the component's run identity.

Activation and deactivation

Set is_active to false to switch an extension off:

  • its fields stay in the data but are no longer validated or enforced;
  • its functions become unavailable;
  • its workflows stop running on record events;
  • the data it stored is preserved.

Deleting an extension removes its definition from the component. The data in its fields is preserved, but nothing manages it any more. Write your workflows so they cope with the extension being off.

The SDK mirrors the API: getExtension, installExtension, updateExtension and deleteExtension. Each takes the component version, such as "0.1.0":

await component.updateExtension("shipping_tracker", "0.1.0", {
  is_active: false
})

Typed extensions with IDL

An extension can declare its own IDL next to its fields and functions. The structure mirrors the component's IDL: global functions and a schemas map with per-schema types and fields.

{
  "name": "premium",
  "is_active": true,
  "idl": {
    "version": "1.0",
    "functions": [
      {
        "name": "flag_item",
        "input":  { "sku": { "type": "string", "required": true } },
        "output": { "type": "boolean" }
      }
    ],
    "schemas": {
      "default": {
        "types": {},
        "fields": {
          "flagged_items": { "type": "array", "items": { "type": "OrderItem" } }
        }
      }
    }
  }
}

Type names in an extension IDL resolve like this:

Reference Resolves to
"OrderItem" The extension's own types first, then the component's
"$.OrderItem" The component's types only
"otherExtension.OrderItem" Rejected: no references between extensions

The one-way rule

Extensions can reference the component's types. The component's IDL cannot reference extension types, because the component is written without knowing which extensions will be installed.

Install-time guards

When you install an extension, the platform checks its IDL against the component's for every schema it declares. Installation is blocked if an extension type name, field key or function name already exists in the component. So each name belongs to exactly one source.

To validate a value against an extension's IDL from the command line, use ptkl validate-idl.

How marketplace apps use extensions

An app (see our post on Forge) that adds a feature to a component the customer already has can do it with an extension. The app's install script adds the extension to the target component, and its uninstall script removes it. The install script first checks whether the extension exists, so running it twice is safe:

const { settings } = await platform.component("products").settings();
const existing = settings.extensions?.find(ext => ext.name === "my_app_tracking");

if (!existing) {
  await platform.component("products").installExtension({
    name: "my_app_tracking",
    is_active: true,
    fields: [ /* ... */ ]
  }, settings.version);
}

Because the extension is namespaced, the app's fields and functions can't overwrite the customer's own. Because it can be deactivated, the customer's data survives. Uninstall scripts should remove or deactivate what install created, and deactivate rather than delete user data where possible.

When to use an extension

  • A feature you want to add to a component you don't own.
  • Optional behaviour that should be switchable without losing data.
  • A package of fields, functions and workflows that you ship together and version.

If the change belongs to the component's core model, edit the component instead.

Worked example

Your orders component needs shipment tracking.

  1. Install shipping_tracker with a tracking_number field, a carrier field and a get_tracking_status function.
  2. Create orders with extensions.shipping_tracker.tracking_number set.
  3. Call orders.function("shipping_tracker.get_tracking_status", { tracking_number }) to look up status.
  4. Filter orders with $adv: { "extensions.shipping_tracker.carrier": "DHL" }.
  5. Switch it off with is_active: false. The tracking numbers stay in the records.

Learn more