Commonplace

Cards: The Fundamental Unit

Cards are the basic building blocks of information in Commonplace. This document explains what cards are, how they work, and how you can use them to organize your information.

What is a Card?

A card in Commonplace is a container for a piece of information. Think of it as a digital index card or note card that can hold structured data.

When a card appears in a collection, it includes several key attributes:

  • Logical ID: A unique identifier for the card instance
  • Reference ID: A unique identifier for this specific reference to the card
  • Position: 2D or 3D coordinates indicating where the card appears in the collection
  • Display settings: Visual properties like visibility state and rendering preferences
  • Version information: Tracking for the card's revision history
  • Link points: Inlets and outlets for linking to other cards
  • Metadata: Creation time, modification time, and other tracking information

Cards are designed to be flexible enough to represent many different types of information, from simple notes to complex data structures.

Cards or Card References?

When you work with a card in Commonplace, you're actually working with a reference to that card, not the card itself. This is a crucial distinction:

  • Card instances contain the actual data (fields, content, metadata)
  • Card references are lightweight pointers that appear in collections
  • Multiple references can point to the same card instance
  • When you edit a card through any reference, all other references immediately show the same changes

This means if the same card appears in three different collections, editing it in one collection instantly updates it in all three places - because you're editing the shared card instance, not just a copy. The references only store position and display settings specific to each collection.

Card Components

Card Data (Fields)

The core of a card is its data, organized into fields. Fields can contain various types of information:

  • Markdown: For formatted text with headings, lists, and other styling. This is a first-class cirtizen in Commonplace and empty cards start with a single markdown field by default.
  • Text: For names, descriptions, and other textual content
  • Numbers: For quantities, ratings, or other numeric values
  • Dates: For deadlines, creation dates, or other temporal information
  • Binary objects: For images, files, or other attachments
  • Enumerations: For selecting from predefined options or categories

Card Type

A card may have an associated Card Type that defines what fields it contains and what types of data those fields can hold. The Type acts like a template for the card, ensuring that its data is structured consistently.

Card Layout

The layout controls how a card's fields are displayed. This can vary depending on the device or context where the card is viewed. Layouts can be defined at the schema level or customized for individual cards.

TODO layout at reference vs card instance level?

Card Metadata

Cards include metadata that provides context and tracking information:

  • Creation time: When the card was first created
  • Modification time: When the card was last updated
  • Type ID: Reference to the type that defines the card's structure
  • Layout and Display: Visual properties like visibility state and rendering preferences
  • Link metadata: Information about inlets and outlets for linking to other cards
  • Version information: Tracking for the card's revision history and immutable versioning

Field Metadata

Each field within a card can have its own metadata, including:

  • State information: Current validation status, modification tracking
  • Display hints: How the field should be rendered in different contexts

Card Identity and References

Cards in Commonplace have unique identities, and references to cards can exist in multiple collections. This means:

  • A card exists as an instance with a unique identity
  • The same card can appear in multiple collections through references
  • A card doesn't "belong" to any single collection
  • When you see a card in multiple collections, you're seeing references to the same card instance
  • When the last reference to a card is removed, the card is moved to a "Recently Deleted" collection for recovery (although some kinds of temporarily-created cards might not be moved, to save on system resources.)

This reference-based approach allows you to organize the same information in multiple ways without creating duplicates.

Working with Cards

As you use Commonplace, you'll create, edit, and organize cards to build your knowledge base. The basic operations you can perform with cards include:

  • Creating new cards with appropriate type
  • Editing card content and metadata
  • Organizing cards into collections
  • Connecting cards to establish relationships
  • Searching for cards based on content or metadata
  • Filtering cards to focus on relevant information
  • Sharing cards with others

These operations are covered in detail in the user documentation (TODO: add references)

Card Implementation Levels

Commonplace implements cards at different levels to separate structure from content and context:

Card Type Level

The Card Type defines the structure that applies to all cards using it:

  • Field types and constraints
  • Default layout and display settings
  • Card Type-attached Commonscript code

Instance Level

Each card instance contains:

  • Field data (the actual content values)
  • Instance-specific Commonscript code (if any)
  • Override settings for display or behavior

Reference Level

When a card appears in a collection, the card reference includes:

  • Collection ID
  • Position in the collection (2D/3D coordinates)
  • Links to other cards via inlets/outlets

This separation allows the same card instance to appear in multiple collections with different positioning and connections, while maintaining a single source of truth for the card's content.

Next Steps

TODO