Commonplace

Commonscript: Programmable Behavior

Commonscript is the scripting language that powers custom behavior in Commonplace. This document explains what Commonscript is, how it works, and how you can use it to extend your Commonplace system.

What is Commonscript?

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

  • 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 the principle of progressive complexity - you don't need to use it when you're starting with Commonplace, but it's available when you need more sophisticated capabilities.

Language Features

Commonscript includes standard programming language features:

Variables

Variables in Commonscript can be used to store temporary data or persist information as hidden card fields:

let count = 0;  // Temporary variable
self.hidden_count = 0;  // Persistent hidden field

Expressions and Conditionals

Commonscript supports standard expressions and conditional logic:

if (self.priority > 3) {
  self.status = "High Priority";
} else {
  self.status = "Normal";
}

Loops

You can use loops to process collections of data:

while (index < items.length) {
  process(items[index]);
  index = index + 1;
}

Event-Driven Execution

Commonscript uses an event-driven model where code executes in response to specific triggers:

on_event("card_changed", function(event) {
  // Code to run when the card changes
});

Execution Context

Commonscript code is attached to Card Types but executes in the context of specific card references:

Card Type Attachment

Code is defined at the Type level, similar to class methods in object-oriented programming:

// In the "Task" Card Type definition
on_field_change("due_date", function() {
  self.days_remaining = calculate_days(self.due_date);
});

Instance Context

At runtime, the code executes in the context of specific card instances:

  • The self keyword refers to the current card instance
  • Each card instance maintains its own state
  • Multiple cards can share the same code but have independent execution

This approach allows for consistent behavior across cards while maintaining instance-specific state.

Event Triggers

Commonscript code can be triggered by various events:

Card Lifecycle Events

  • card_created: When a new card is created
  • card_loaded: When a card is loaded from storage
  • card_saved: When a card is saved to storage
  • card_deleted: When a card is deleted

User Actions

  • field_changed: When a user edits a field
  • button_clicked: When a user clicks a button
  • card_selected: When a user selects a card
  • import_data: When data is imported into a card

Field or Object Events

  • field_validated: When a field's value is validated
  • calculation_needed: When a calculated field needs updating
  • display_refresh: When the card's display needs refreshing

Custom Events

  • User-defined events for specific workflows
  • Events from connected cards via inlets
  • Scheduled or time-based events

External Access

Commonscript operates within a secure sandbox with controlled access to external resources:

Function Scope

  • Commonscript can only call functions defined within its instance by default
  • External access requires explicit permissions

System Extensions

  • External functionality is provided through cards in the System Extensions collection
  • Cards with special privileges have visual indicators to alert users
  • This approach makes network access and external API calls transparent

Sandboxing

  • All code runs in secure, sandboxed environments
  • The permission system controls access scope
  • This allows for safe execution of code from distributed cards and collections

Working with Commonscript

As you become more familiar with Commonplace, you might use Commonscript 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

More detailed information about Commonscript is available in Part 2: Commonscript Language.

Next Steps

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