Commonplace

Card Types

Every card in Commonplace has an associated type that defines its structure and behavior. This document explains what card types are, how they work, and how they help you organize your information effectively.

What is a Card Type?

A card type in Commonplace is a blueprint that defines the structure and behavior of cards. It specifies:

  • What fields a card contains
  • What kinds of data those fields can hold
  • Any constraints or validation rules for the fields
  • How the card's data should be displayed
  • Any custom behavior through attached Commonscript code

Card types work like templates, providing a consistent structure for creating similar cards.

Card Type Features

Field Definitions

The core of a card type is its field definitions, which specify:

  • Field names: Identifiers for each piece of data
  • Field types: What kind of data each field can contain (text, number, date, etc.)
  • Required/optional status: Whether a field must have a value
  • Default values: Initial values for fields when a card is created
  • Validation rules: Constraints on what values are acceptable

For example, a "Task" card type might define fields like:

  • Title (required text)
  • Description (optional text)
  • Due Date (optional date)
  • Priority (number from 1-5, default 3)
  • Status (enumeration: "Not Started", "In Progress", "Complete")

Commonscript Code

Card types can include Commonscript code that defines behavior for cards of that type. This code allows cards to respond to events, validate data, or perform calculations.

For example, a "Task" card type might include code to:

  • Calculate days until the due date
  • Validate that the priority is within the allowed range
  • Change the card's appearance based on its status
  • Send notifications when the due date approaches

Automatic Type Detection

To reduce friction when creating cards, Commonplace can automatically detect appropriate card types based on the data you enter. When you create a new card, the system:

  1. Analyzes the fields and data types you've entered
  2. Looks for existing card types with matching structures
  3. Depending on your preference, assigns an existing card type or prompts you to confirm or choose from existing types

This allows you to start creating cards without explicitly defining types first, while still maintaining structured data.

Type Signature

Behind the scenes, Commonplace identifies type compatibility using a "signature" based on the field types. This signature helps the system:

  • Identify when cards have compatible structures
  • Suggest type merges when appropriate
  • Track type evolution over time

User Control

While automatic detection is convenient, you always have control over card types:

  • You can explicitly assign cards to existing types
  • You can create new card types from scratch
  • You can modify card types as your needs evolve
  • You can maintain separate card types even if they have similar structures

Type Compatibility and Merging

As you work with Commonplace, you may create multiple card types with similar structures. The system helps manage this through compatibility detection and merging.

Compatibility Detection

Card types are considered compatible when they have identical field structures (same field types, regardless of names or order). When the system detects compatible types, it may suggest merging them to maintain consistency.

Guided Merging

When card types have identical structures but different field names, the system offers guided merging:

  1. It shows you the differences between the types
  2. It suggests how fields might map between them
  3. It allows you to choose which field names to keep
  4. It helps you resolve any conflicts in attached code

You can accept the suggested merge, customize it, or keep the card types separate.

Type Evolution

When you need to change a card type that's already in use, the system helps you manage the transition:

  1. It identifies what changes you're making (adding fields, changing types, etc.)
  2. It analyzes the impact on existing cards
  3. It flags changes that might cause data loss
  4. It guides you through updating existing cards

Working with Card Types

As you use Commonplace, you'll interact with card types in various ways:

  • Creating card types: Defining new structures for your cards
  • Modifying card types: Updating field definitions as your needs change
  • Merging card types: Combining similar types for consistency
  • Applying card types: Assigning types to cards
  • Browsing card types: Exploring available types in your system

These operations are covered in detail in the Using Card Types document.

Next Steps

Now that you understand card types, you might want to learn about: