Card and Collection Links
links in Commonplace allow you to establish relationships between cards and collections, creating a network of related information. This document explains how links work and how they enable both visual organisation and programmatic interaction.
What are links?
links in Commonplace are links between cards and collections that represent relationships and enable data flow. They serve two main purposes:
- Visual organisation: Showing how different pieces of information relate to each other
- Programmatic interaction: Enabling cards to respond to changes in connected cards
links follow Commonplace's principle of progressive complexity - they start as simple visual links but can evolve into sophisticated event-driven interactions as your needs grow.
Link Components
Inlets
Inlets are named entry points on cards that can receive links and process events:
- Defined in a card's Type
- Named with descriptive identifiers (e.g., "data-source", "approval-workflow")
- Can specify what types of events they accept
- Can have requirements for what types of cards can connect to them
- Enable Commonscript code to respond to events from connected cards
Outlets
Every card and collection can act as an outlet, sending events to connected inlets:
- No explicit configuration needed - all cards can send events
- Events are generated when cards change, when user actions occur, etc.
- Events carry information about what changed and references to the source card
Link Visualisation
In spatial views, links are represented as lines between cards:
- Show the relationship between cards visually
- Can be labeled to indicate the nature of the relationship
- Can have different styles to represent different types of links
- Help users understand the structure of their knowledge network
Progressive Levels of Linking
Commonplace supports different levels of Link complexity:
Level 1: Basic Visual links
The simplest form of links:
- Draw lines between cards to show relationships
- Represent your mental model of how information relates
- No code or complex configuration required
- Pure visual organization
Level 2: Named Inlets and Event Processing
As your needs grow, you can use more structured links:
- Define named inlets on cards
- Write Commonscript to process events received through inlets
- Respond to changes in connected cards
- Build simple automated workflows
Level 3: Type-Constrained Processing
For advanced needs, you can use fully structured links:
- Specify type requirements for cards that connect to inlets
- Create type-safe data processing pipelines
- Build complex workflows with validation
- Develop sophisticated interactive systems
Link Scope
Links in Commonplace have defined scope:
- Links exist within the context of a specific collection
- Cards in different collections can be connected if they appear in the same collection
- links cannot leave the collection they belong to
- Collections can connect to peer collections (collections at the same level)
This scoping ensures that links remain manageable and meaningful within their context.
Working with Links
As you use Commonplace, you'll create and manage links to express relationships between your information:
- Creating links: Drawing links between related cards
- Defining inlets: Specifying how cards can receive links
- Writing event handlers: Adding code to respond to events from connected cards
- Visualising networks: Seeing the structure of your connected information
These operations are covered in detail in the Connecting Cards and Collections document.
Benefits of Links
The link system in Commonplace provides several benefits:
- Express relationships: Show how different pieces of information relate to each other
- Build context: See information in its broader context
- Enable automation: Create automated workflows and data processing
- Support thinking: Visualise your mental models and thought processes
- Facilitate discovery: Find unexpected relationships and insights
Next Steps
TODO