Commonplace

Extending Commonplace: System Extensions

Commonplace is designed to be extensible, allowing you to add new capabilities to your system as your needs evolve. This document explains how system extensions work and how you can use them to customize your Commonplace experience.

What are System Extensions?

System extensions in Commonplace are special cards that add new functionality to the system. They allow you to:

  • Add new field types beyond the built-in ones
  • Create custom visualization capabilities
  • Integrate with external services and APIs
  • Define new event types and handlers
  • Extend the Commonscript language with new functions

Extensions are implemented as cards with special permissions, placed in designated collections within your Commonplace system.

Extensibility Model

The extensibility model in Commonplace is designed to be transparent and secure:

Extension Cards

  • Extensions are implemented as cards with Commonscript code
  • These cards have special permissions based on their location
  • Extensions have visual indicators to show their privileged status
  • Users can inspect extension code to understand what it does

Permission Inheritance

  • Cards inherit permissions from their containing collections
  • Placing a card in a designated extension collection grants it specific capabilities
  • Moving a card out of an extension collection revokes those capabilities
  • This makes permission management visual and intuitive

System Extension Collections

Commonplace includes several designated collections for different types of extensions:

System Extensions Collection

The primary collection for system extensions, which can include:

  • New field types (location, currency, specialized formats)
  • Custom visualization components
  • System-level event handlers
  • Commonscript language extensions

External Connectors Collection

A collection for cards that connect to external systems:

  • API integrations
  • File system access
  • Network services
  • External databases

UI Extensions Collection

A collection for cards that extend the user interface:

  • Custom card layouts
  • Specialized collection views
  • New interaction patterns
  • Visualization tools

Example: Adding a Location Field Type

Here's how you might add a new field type to your Commonplace system:

  1. Create a card with Commonscript code that implements a location field
  2. The code defines how to:
    • Store and validate location data
    • Display locations on maps
    • Calculate distances between locations
    • Format location information for display
  3. Place this card in the System Extensions collection
  4. The system makes the new "location" field type available in Card Types
  5. You can now add location fields to your cards

Collection Hierarchies

System extensions work within the collection hierarchy of your Commonplace system:

Home Collection

  • The root of your personal Commonplace system
  • Contains your primary working collections
  • May include personal extensions that apply only to your system

System Collection

  • Contains system-level collections including extensions
  • Manages system-wide settings and capabilities
  • Includes the designated extension collections

Additional Top-Level Collections

  • You can create additional top-level collections as needed
  • These can include their own extension collections with scoped permissions
  • Extensions in these collections apply only within their scope

Security Considerations

System extensions involve important security considerations:

Permission Boundaries

  • Extensions have clearly defined permission boundaries
  • The system enforces these boundaries at runtime
  • Users are notified when extensions request sensitive permissions

Code Review

  • Extension code can be reviewed before installation
  • Visual indicators show when cards have special permissions
  • The system can provide information about what extensions are doing

Sandboxing

  • Extensions run in sandboxed environments
  • Resource usage is monitored and limited
  • Extensions can be disabled if they cause problems

Working with Extensions

As you become more familiar with Commonplace, you might:

  • Install extensions created by others
  • Create custom extensions for your specific needs
  • Share extensions with other Commonplace users
  • Manage extension permissions to control what they can do

These operations are covered in detail in the Extending Your System document.

Next Steps

Now that you understand system extensions, you might want to learn about: