Commonplace

Introduction to Commonscript

Commonscript is the programming language that powers custom behavior in Commonplace. This document introduces the language, its purpose, and how it fits into the Commonplace system.

What is Commonscript?

Commonscript is a purpose-built scripting language designed specifically for Commonplace. It allows you to add custom logic and behavior to your cards and collections, enabling:

  • Automated processing of card data
  • Custom interactions and user interfaces
  • Event-driven responses to changes
  • Data validation and transformation
  • Integration with other parts of your knowledge system

Commonscript follows Commonplace's principle of progressive complexity - you don't need to use it when you're starting with the system, but it's available when you need more sophisticated capabilities.

Why Commonscript?

Commonplace uses a custom language rather than an existing one for several reasons:

  • Security: Commonscript runs in a sandboxed environment with controlled access to system resources
  • Integration: The language is tightly integrated with Commonplace's card and collection model
  • Simplicity: Commonscript focuses on the specific needs of Commonplace users without unnecessary complexity
  • Consistency: The language works the same way across all platforms and implementations
  • Progressive disclosure: Features can be introduced gradually as users become more experienced

When to Use Commonscript

You might use Commonscript when you want to:

  • Automate calculations: Derive values from other fields
  • Validate data: Ensure field values meet specific criteria
  • Create custom views: Design specialized displays for your cards
  • Build workflows: Automate sequences of actions
  • Connect to external systems: Integrate with other tools and services
  • Respond to events: Take action when cards are changed or events occur

Commonscript Basics

Where Commonscript Lives

Commonscript code can be attached to:

  • Card Types: Defining behavior for all cards of a certain type
  • Individual cards: Adding custom behavior to specific cards
  • Collections: Adding behavior to collections
  • System extensions: Adding new capabilities to the system

How Commonscript Executes

Commonscript uses an event-driven execution model:

  1. Events occur in the system (card changes, user actions, etc.)
  2. These events trigger Commonscript code that's registered to handle them
  3. The code executes in the context of specific cards or collections
  4. The code can update card data, trigger other events, or interact with the user

Execution Context

When Commonscript runs, it has access to:

  • self: The current card or collection instance
  • event: Information about the event that triggered the code
  • connected cards: Cards connected through inlets and outlets
  • built-in functions: System-provided functionality
  • user-defined functions: Functions you define in your code

Security Model

Commonscript operates within a secure sandbox:

  • Code can only access data it has permission to see
  • External access requires explicit permissions
  • Cards with special privileges have visual indicators
  • All code runs in isolated environments

This security model allows you to safely use code from different sources while maintaining control over your data.

Learning Path

As you learn Commonscript, you might follow this progression:

  1. Start with simple expressions: Calculate field values based on other fields
  2. Add event handlers: Respond to changes in your cards
  3. Create custom functions: Build reusable pieces of functionality
  4. Work with links: Interact with connected cards
  5. Build custom interfaces: Create specialized views and interactions
  6. Develop extensions: Add new capabilities to your Commonplace system

Example: A Simple Task Card

Here's a simple example of Commonscript attached to a task card schema:

// Calculate days remaining when due date changes
on_field_change("due_date", function() {
  if (!self.due_date) {
    self.days_remaining = null;
    return;
  }
  
  let today = new Date();
  let due = new Date(self.due_date);
  let diff = Math.floor((due - today) / (1000 * 60 * 60 * 24));
  
  self.days_remaining = diff;
  
  // Update status based on days remaining
  if (diff < 0 && self.status !== "Overdue") {
    self.status = "Overdue";
  } else if (diff <= 2 && self.status !== "Urgent") {
    self.status = "Urgent";
  }
});

// Validate that priority is between 1 and 5
on_field_change("priority", function() {
  if (self.priority < 1 || self.priority > 5) {
    throw new Error("Priority must be between 1 and 5");
  }
});

This code:

  1. Calculates days remaining whenever the due date changes
  2. Updates the task status based on the days remaining
  3. Validates that the priority is within an acceptable range

Next Steps

Now that you understand the basics of Commonscript, you might want to explore: