Custom objects

A custom object is a new content type you define. Where a custom attribute, adds an extra field to an existing content type, a custom object creates a new kind of record with its own fields and its own admin area.

Custom objects are useful when:

• You need a record with multiple fields that stands on its own.
• The same record is referenced from many places (events, posts, pages) and managing it centrally avoids duplication.
• You want to build a reusable list or picker over these records in your theme.

Defining a custom object

Open the Custom objects area of Basker. Define a new object. Each object has:

• A label: the human-readable name editors see.
• A handle: the stable identifier used in the public API and theme code. It is generated from the label and cannot be changed after creation.
• An optional icon to identify the object in the admin.
• An optional description explaining what the object is for.
• A list of fields: the structure of each instance.
• An Expose in public API option: whether instances of this object type can be read through the FrontStage API.

Fields can be text, number, date, media, file, choices, relationships, rich text, email, colour, or JSON. A relationship field can link to pages, events, files, people, venues, organisations, seasons, series, smart collections, blogs, posts, or other custom object instances. Fields can also be nested up to two levels deep (group related fields together, or let editors add a repeating set of fields), so an object can hold structured data, not just flat values.

Relationship, media, and file fields also have a Public API response setting. Use it to return the full related record, a compact summary, or only IDs when the object is returned through the FrontStage API.

A definition can optionally be shared with other sites in your group, so the same object type is available to manage across them.

Examples

A few examples to make the idea concrete:

• Sponsor: fields for name, logo, tier, link, and description. Each sponsor is one instance; events reference sponsors by relationship.
• Discount code: fields for code, percentage off, valid-from date, valid-until date, terms.
• Accessibility service: fields for service name, description, providing partner, and the events it applies to.
• Trustee: fields for name, role, biography, photo, year joined.

You define the structure once; you create as many instances as you need. See Custom object instances.

Where custom objects appear

Once defined, a custom object behaves like a built-in content type:

• It has its own admin list and editor.
• Its instances can be referenced from any field that takes relationships, including custom attributes on other content types.
• Compatible theme blocks can select one or more instances.
• Themes can render its instances on the live site if they're set up to.
• The FrontStage API can expose its instances when Expose in public API is enabled.

Versus custom attributes

Use a custom attribute when you need to attach extra information to existing content. Use a custom object when the information itself is the content and deserves its own list, management area, and concept.

Where to go next