Reference → Custom Objects — Reference

Custom Objects — Reference

The Custom Objects surface is the user-defined content-type layer — the place where an operator defines a record type that the platform does not ship with, configures the fields on it, and then drives that type through the same list / edit / publish / soft-delete lifecycle that Posts, Pages, and Events use. Case studies, team members, recipes, real-estate listings, glossary terms — anything that wants the editorial chrome of a Post without being a blog post lives here.

This page is a reference for platform engineers and integrators who need to understand the schema-definition layer, how custom object records route through the shared write surface, and how the per-object archive pages render on the front-end.

Overview

Custom Objects lives under the Custom module group in SG-Admin, paired with the design-system siblings Custom CSS and Custom Codes and the operator-data siblings Custom Fields and Custom Fonts.

The module is paired by convention: one half renders the list, create, edit, manage-form, and view-object-pages views; the other half handles writes — save, table refresh, soft delete, restore. There is also a per-object category management surface — each custom object type can carry its own taxonomy distinct from the blog's Categories.

A Custom Object definition carries a slug, a display name (singular and plural), a field schema, a URL pattern for individual records and the archive, an editor mode (classic or SG-Builder), and a permission-map override. Once defined, the platform exposes a new sidebar entry under the operator's Custom area for managing records of that type. Each record routes through the shared post-record action layer for save, publish, duplicate, soft delete, restore, and revision history.

Where it lives in SG-Admin:

Sidebar: SG-Admin → Custom → Objects
URL prefix: /sg-admin/custom-objects/
Per-object sidebar entry: dynamic, added once the operator publishes a definition
View templates: application/views/Admin/CustomObjects/

Distinct from Custom Fields. Custom Fields adds fields to an existing record type (extra columns on Posts, Pages, Users). Custom Objects defines a whole new record type with its own fields, archive, URL pattern, and lifecycle. Different problem, different surface — use Fields to extend, use Objects to define.

Shared write surface. Custom Object records do not have their own write controller. They route through the same action layer that Posts uses (the layer that serves the post-record actions for Blog, Pages, Events, and Custom Objects). The Custom Objects definition is the schema; the actual record CRUD borrows the Posts pipeline. This is why the Posts data model carries a type field and a polymorphic shape — Custom Objects is one of the consumers.

┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Custom → Objects [+ Add type] │├──────────────────────────────────────────────────────────────────────┤│ Type (singular / plural) Fields Records URL pattern ││ ────────────────────────────── ─────── ──────── ──────────── ││ Case Study / Case Studies 9 14 /work/<slug> ││ Team Member / Team 7 22 /team/<slug> ││ Recipe / Recipes 12 43 /recipe/<slug>││ Glossary Term / Glossary 4 180 /glossary/<s>││ Old Demo / Old Demos (trashed) 3 0 — ││ ││ [⋯ Manage type] [⋯ Manage categories] [⋯ View records] [⋯ Delete] │└──────────────────────────────────────────────────────────────────────┘

Actions

The Custom Objects surface exposes two operation tiers — definition-level (managing the object type itself) and record-level (managing records of a defined type, which routes through the shared post-record action layer).

List object types (definition tier)

Returns the operator-defined object types, with type slug, singular/plural name, field count, current record count, URL pattern, and status. Supports sort and free-text filter on name.

Create object type

Opens an empty definition form. Required: type slug (unique), singular and plural display name, URL pattern. Required minimum field set: title and slug. Optional and common: additional field definitions (text, number, date, select, image, rich text, repeater), editor mode (classic body, SG-Builder canvas, or both), per-object category support, archive layout, SEO defaults, and a permission-map override.

Edit object type

Loads an existing definition into the same form shape used for create, pre-populated. Field additions are non-destructive — existing records inherit a null value for new fields. Field removals soft-delete the field metadata; the underlying record data is retained for a configurable grace window before purge.

Manage form (per-type field editor)

A focused field-schema editor. Drag-orderable list of fields, per-field configuration (label, type, required, default value, validation rule, help text, conditional visibility), and a per-field destination flag (show in list view, show in archive card, expose in SEO meta).

View object pages (record tier)

Routes to the per-type record list view — the page that the dynamic sidebar entry leads to. From there, record-level actions apply: create record, edit record, duplicate, soft delete, restore, revision history. These actions inherit the Posts surface's behavior; see the Posts reference for the operational shape.

Manage object categories

Each object type can carry its own taxonomy distinct from the blog's Categories. The category manager exposes list, create, edit, merge, and delete for that type's category set. Records reference categories by ID; renaming a category preserves the references.

Soft delete object type (definition)

Marks the entire type definition as trashed. Records of the type stop rendering on the front-end immediately. Existing records are retained in the database, marked inherited-trash, and become visible again on restore.

Restore object type

Returns a trashed definition to active. Records that were marked inherited-trash become visible again with their original status.

Permanent delete object type

Hard-removes the definition and all records of the type. Irreversible. Categories scoped to the type are also removed. Use the export utility first if there is any chance the data should be retained.

Data model

A Custom Object definition carries the following fields. Records of a defined type carry the standard post-record shape extended with the type's custom fields.

Definition record:

Field	Type	Notes
`id`	integer	Primary key. Stable across edits.
`type_slug`	string	Unique. Used as the `type` value on records.
`singular_name`	string	Display in singular ("Case Study").
`plural_name`	string	Display in plural ("Case Studies"). Drives sidebar label.
`url_pattern`	string	Tokenized — `/work/` resolves at render.
`archive_url`	string	The collection-view URL — `/work` for case studies.
`field_schema`	array	Ordered list of field definitions. See below.
`editor_mode`	enum	`classic`, `sg-builder`, or `both`.
`category_support`	boolean	`true` enables the per-type category surface.
`seo_defaults`	JSON	Default title pattern, description pattern, schema type.
`permission_overrides`	JSON	Optional capability map override for this type only.
`archive_layout_slug`	string	Foreign key to a list of platform-shipped archive templates.
`status`	enum	`active` or `trash`.
`created_at`	timestamp	Immutable.
`updated_at`	timestamp	Touched on edit.
`created_by`	integer	Foreign key to Users.

Field-schema entry (nested under field_schema[]):

Field	Type	Notes
`slug`	string	Stable identifier. Used in templates and exports.
`label`	string	Editor-visible label.
`type`	enum	`text`, `textarea`, `rich-text`, `number`, `date`, `select`, `image`, `gallery`, `repeater`.
`required`	boolean	Validation rule on save.
`default`	any	Type-appropriate default.
`validation_rule`	string	Optional. Length, range, regex.
`help_text`	string	Optional. Shown beneath the field in the editor.
`conditional_visibility`	JSON	Optional. Show this field only when another field has a given value.
`surface_flags`	object	`list_view`, `archive_card`, `seo_meta` booleans.

Record shape. A record of a defined type is a standard post-record (see the Posts reference) with type = and a custom_fields object keyed by the field schema. The shared post-record lifecycle (draft, scheduled, published, trash, revisions) applies unchanged.

Reference tracking. Records reference media (by media_id), categories (by category_id), and users (by author_id). The platform tracks these references for cascade rules — soft-deleting a media record warns about Custom Object records that reference it; permanent-deleting a category warns about records that point to it. References are not auto-rewritten; the operator decides per-case.

DEFINITION (per type, one record) RECORDS (per type, many)┌─────────────────────────────────┐ ┌────────────────────────────┐│ Case Study │ │ post-record │├─────────────────────────────────┤ ├────────────────────────────┤│ type_slug: case_study │ ───► │ type: case_study ││ url_pattern: /work/<slug> │ │ title, slug, status, body ││ archive_url: /work │ │ author_id, categories ││ editor_mode: sg-builder │ │ custom_fields: ││ field_schema: │ ───► │ ├── client_name ││ client_name (text, req) │ │ ├── industry ││ industry (select, req) │ │ ├── outcome_summary ││ outcome_summary (rich-text) │ │ ├── results_metrics ││ results_metrics (repeater) │ │ ├── hero_image ││ hero_image (image, req) │ │ └── related_services ││ related_services (repeater) │ │ ││ category_support: true │ │ revisions, timestamps ││ seo_defaults: {... } │ └────────────────────────────┘│ permission_overrides: {... } ││ archive_layout_slug: grid-3 │ shared post-record└─────────────────────────────────┘ action layer:save, publish, dup,soft delete, restore,revision history

Permissions

Access to the Custom Objects surface is gated at two layers, with a per-type override capability that lets each defined type carry its own capability map.

Layer 1 — admin gate. Standard admin access check at request entry.

Layer 2 — per-action capability. The default capability map for the Custom Objects surface itself ships as:

Capability	Administrator	Editor	Author	Viewer
List object types	✔	✔	✔	✔
Create object type	✔	—	—	—
Edit object type	✔	—	—	—
Manage form / fields	✔	—	—	—
Manage categories	✔	✔	—	—
View object pages (records)	✔	✔	✔	✔
Soft delete object type	✔	—	—	—
Restore	✔	—	—	—
Permanent delete	✔	—	—	—

Definition-level actions are administrator-only by default — defining a new type changes the platform's data shape, and on customer sites this is typically a one-off setup task held by the same operator that holds theme activation and database-tier capabilities.

Record-tier capabilities route through the shared post-record action layer. The default map there matches the Posts surface (Administrator / Editor / Author / Viewer). A type definition can override this per-type — for example, a Glossary type might allow Editor-tier write but lock revisions to Administrator only.

Self-protection rules. The surface returns a structured rejection on duplicate type slug, on URL pattern collision with an existing type or built-in route, on a permanent delete attempt while records of the type still exist (use the export utility first), and on a field-schema change that violates referential integrity for records already published.

Audit. Every definition-level write — create, edit, schema change, category management, soft delete, restore, permanent delete — emits an Activity Log entry. Record-level writes are logged through the shared post-record action layer's audit path.

ACCESS → /sg-admin/custom-objects/...│▼┌──────────────────────┐│ Admin gate │ unauth → reject└──────────┬───────────┘│ authed▼┌──────────────────────┐│ Capability check ││ definition tier: │ default — administrator only│ record tier: │ per-type override → fallback Posts map└──────────┬───────────┘│ allowed▼┌──────────────────────┐│ Slug / URL uniqueness│ collision → reject│ Referential checks │ schema-change breaks records → reject└──────────┬───────────┘│ passes▼write executes│▼Activity Log entry│▼dynamic sidebar entry refreshes on next requestper-type archive route registers on next render

Related references

Posts — Reference. Custom Object records route through the same write surface and revision system as posts. The behavior of save / publish / duplicate / soft delete / restore / revision-restore is documented there.
Pages — Reference. Same shared write surface. Custom Objects share Pages' SG-Builder integration.
Custom Fields — Reference. The companion surface for extending an existing type. Use Fields to add columns to Posts; use Objects to define a new type entirely.
Custom CSS — Reference. Per-type archive layouts often carry their own Custom CSS rules scoped to the archive URL.
Media — Reference. Image and gallery fields on a Custom Object schema reference Media records by ID.
Users — Reference. Author attribution on a Custom Object record points to the user id.
SEO — Reference. Per-type SEO defaults — title pattern, description pattern, schema type — resolve against the SEO module's defaults.
Settings — Reference. Field-removal grace window, archive-template registry, audit retention.

For the corresponding customer-facing walkthrough — defining a Case Studies type, adding fields, building the archive page — see the Custom Objects section of the customer docs at /docs/custom-objects.

On this page

Guides

Reference

Changelog

Roadmap