Models Overview

The heart of the Whoa Excel Addin is the model engine.

The models you create represent real-world things relevant to the problems you’re solving.

A collection of fields

Each model is a collection of fields, each assigned a concrete type such as TextField or DateField. Conceptually, a field corresponds to one column in an Excel table, and the terms field and column are used interchangeably throughout this guide.

Two special field types — ForeignKey and ManyToManyField — allow direct connections between models. This is the core mechanism that makes business rules easier to express in code.

Web vs Local (model-level data source)

Every model declares where its record identities come from.

• Local models create and own their IDs inside Excel.
• Web models treat IDs as externally owned and authoritative.

This distinction determines lifecycle rules: who can create records, when records can be modified, and what “saving” means. The Addin uses this signal to prevent category errors, such as attempting to create records that should only exist as mirrors of an external system.

Declare intent once. The engine enforces it everywhere.

Remote vs Local (field-level writeability)

Fields also declare intent.

• Local fields are freely writable.
• Remote fields are constrained or effectively read-only.

Remote fields typically represent values whose source of truth lives elsewhere or where mutation would be ambiguous. The Addin uses this to gate setters, generic edit UI behavior, and validation paths. Writes that don’t make sense fail fast.

This prevents silent corruption and keeps data flow directional.

Model Sort Fields

A model can define one or more sort fields to establish a default ordering.

Sort fields support multi-level ordering and are applied consistently across lists, dropdowns, and generated views. This avoids each caller inventing its own ordering logic.

Sort configuration is continuously validated. If a field used for sorting is removed or altered, this will be detected by the Addin's built-in validation engine.

Model Index Fields

A model may define a single index field that acts as a human-facing identifier.

The index is not the engine’s primary key. It exists to support: - stable lookups - readable references - meaningful UI selection

Index values are expected to be unique per record.

Think “unit number” or “vendor code”, not an opaque ID. Like sort fields, index fields are validated in the background. If an index becomes invalid, the Addin raises a flag instead of drifting into an inconsistent state.

The engine keeps you on the rails without constant supervision.