content

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 22, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package content defines the content object at the center of the CMS.

Index

Constants

View Source
const DefaultLocale = "en-US"

DefaultLocale is the language the site answers in when nothing else applies.

View Source
const LocaleSettingKey = "locale.default"

LocaleSettingKey names the stored site default language.

View Source
const MaxDepth = 10

MaxDepth bounds how many levels of content nest under one another.

View Source
const PageWord = "page"

PageWord is the segment a numbered listing hides behind.

View Source
const TypePost = "post"

TypePost is the key of the built-in post type.

Variables

View Source
var ErrConflict = errors.New("content: conflicting update")

ErrConflict reports that the content item changed after the update was prepared.

View Source
var ErrCycle = errors.New("content: the item cannot nest inside itself")

ErrCycle reports that content would nest inside itself.

View Source
var ErrDefaultRequired = errors.New("content: the default type must stay")

ErrDefaultRequired reports that the default content type may not be deactivated or removed.

View Source
var ErrFieldNotFound = errors.New("content: field not found")

ErrFieldNotFound reports that the type declares no field under the key.

View Source
var ErrFieldNotRelational = errors.New("content: only a relation field takes a target or many")

ErrFieldNotRelational reports that only a relation field takes a target or many.

View Source
var ErrFieldRequired = errors.New("content: field is required")

ErrFieldRequired reports that a field must hold a value before publishing.

View Source
var ErrFieldShape = errors.New("content: wrong kind of value")

ErrFieldShape reports that a value is not the kind its field holds.

View Source
var ErrFieldTaken = errors.New("content: field key taken")

ErrFieldTaken reports that the type already declares a field under the key.

View Source
var ErrHoldsChildren = errors.New("content: the item still holds children")

ErrHoldsChildren reports that content still holds content nested under it.

View Source
var ErrInvalidAuthor = errors.New("content: invalid author")

ErrInvalidAuthor reports that a content item carries no author.

View Source
var ErrInvalidFieldKey = errors.New("content: invalid field key")

ErrInvalidFieldKey reports that a field key is not a lowercase word.

View Source
var ErrInvalidFieldKind = errors.New("content: invalid field kind")

ErrInvalidFieldKind reports that a field kind is not one the CMS holds.

View Source
var ErrInvalidFieldLabel = errors.New("content: invalid field label")

ErrInvalidFieldLabel reports that a field carries no label.

View Source
var ErrInvalidKey = errors.New("content: invalid type key")

ErrInvalidKey reports that a type key is not a lowercase word.

View Source
var ErrInvalidLabel = errors.New("content: invalid type label")

ErrInvalidLabel reports that a type carries no label.

View Source
var ErrInvalidOrder = errors.New("content: invalid order")

ErrInvalidOrder reports that a sort direction is not one the CMS sorts in.

View Source
var ErrInvalidOrderBy = errors.New("content: invalid orderby")

ErrInvalidOrderBy reports that a sort column is not one the CMS sorts by.

View Source
var ErrInvalidPageKind = errors.New("content: invalid page kind")

ErrInvalidPageKind reports that a page kind is not one the CMS renders.

View Source
var ErrInvalidRevisionCap = errors.New("content: invalid revision cap")

ErrInvalidRevisionCap reports that a revision cap is not a number of rows.

View Source
var ErrInvalidRouteWord = errors.New("content: invalid route word")

ErrInvalidRouteWord reports that a route word is not a lowercase word.

View Source
var ErrInvalidStatus = errors.New("content: invalid status")

ErrInvalidStatus reports that a status value is not one the CMS stores.

View Source
var ErrInvalidTransition = errors.New("content: invalid status transition")

ErrInvalidTransition reports that a status change is not allowed.

View Source
var ErrInvalidType = errors.New("content: invalid type")

ErrInvalidType reports that a content type is not registered.

View Source
var ErrLocaleUnknown = errors.New("content: locale unknown")

ErrLocaleUnknown reports that a language is not one the site answers in.

View Source
var ErrNotFound = errors.New("content: not found")

ErrNotFound reports that no content item exists for the requested ID.

View Source
var ErrNotHierarchical = errors.New("content: the type does not nest")

ErrNotHierarchical reports that a content type does not nest.

View Source
var ErrParentTrashed = errors.New("content: the parent is in the trash")

ErrParentTrashed reports that a parent is on its way out of the site.

View Source
var ErrParentType = errors.New("content: the parent holds another kind of content")

ErrParentType reports that a parent holds another kind of content.

View Source
var ErrRelationNeedsTarget = errors.New("content: a relation field needs a target type")

ErrRelationNeedsTarget reports that a relation field names no target type.

View Source
var ErrRepeatedTarget = errors.New("content: repeated target")

ErrRepeatedTarget reports that a relation field was given the same target twice.

View Source
var ErrReservedAddress = errors.New("content: the address is reserved")

ErrReservedAddress reports that an address names a place the CMS keeps.

View Source
var ErrRevisionNotFound = errors.New("content: revision not found")

ErrRevisionNotFound reports that no revision exists for the requested ID.

View Source
var ErrRootTaken = errors.New("content: another type holds the root")

ErrRootTaken reports that another content type already lives at the root.

View Source
var ErrRouteWordReserved = errors.New("content: route word reserved")

ErrRouteWordReserved reports that the route word names a place the CMS keeps.

View Source
var ErrRouteWordTaken = errors.New("content: route word taken")

ErrRouteWordTaken reports that another content type answers under the route word.

View Source
var ErrSelfTarget = errors.New("content: an item cannot point at itself")

ErrSelfTarget reports that a relation field points an item at itself.

View Source
var ErrSlugTaken = errors.New("content: slug taken")

ErrSlugTaken reports that a content type already holds the requested slug.

View Source
var ErrTargetNotFound = errors.New("content: target not found")

ErrTargetNotFound reports that a relation names an item nothing holds.

View Source
var ErrTargetType = errors.New("content: target is not the type the field points at")

ErrTargetType reports that a relation names an item of the wrong type.

View Source
var ErrTargetUnknown = errors.New("content: relation target unknown")

ErrTargetUnknown reports that a relation field targets an unregistered type.

View Source
var ErrTooDeep = errors.New("content: the nesting limit is reached")

ErrTooDeep reports that content nests beyond the limit.

View Source
var ErrTooManyTargets = errors.New("content: field holds one target")

ErrTooManyTargets reports that a relation field holding one was given more.

View Source
var ErrTypeInUse = errors.New("content: type still holds content")

ErrTypeInUse reports that the content type still holds content.

View Source
var ErrTypeInactive = errors.New("content: type is not active")

ErrTypeInactive reports that the content type is not active.

View Source
var ErrTypeNotFound = errors.New("content: type not found")

ErrTypeNotFound reports that no content type carries the requested key.

View Source
var ErrTypeTaken = errors.New("content: type key taken")

ErrTypeTaken reports that a content type already carries the requested key.

View Source
var ErrTypeTargeted = errors.New("content: a field still targets the type")

ErrTypeTargeted reports that a relation field of another type still targets the type.

View Source
var ErrUnknownField = errors.New("content: unknown field")

ErrUnknownField reports that the type declares no field under the key.

View Source
var ReservedRouteWords = []string{"admin", "api", "gophenberg", "_gophenberg", "media"}

ReservedRouteWords are the first address segments the CMS keeps for itself.

View Source
var SupportedLocales = []string{DefaultLocale, "es-ES", "fr-FR"}

SupportedLocales are the languages the site answers in, the fallback first.

Functions

func AddressPrefix

func AddressPrefix(path, slug string) string

AddressPrefix returns the address an item's slug hangs from.

func AddressUnder

func AddressUnder(prefix, slug string) string

AddressUnder returns the address of a child carrying slug beneath prefix.

func CodeOf added in v0.6.0

func CodeOf(err error) (string, bool)

CodeOf returns the condition code a refusal names, reporting false when it names none.

func Filled added in v0.5.0

func Filled(values Values, relations Relations, fields []Field) error

Filled reports whether every required field of the type holds a value.

func FirstSegment

func FirstSegment(path string) string

FirstSegment returns the first segment of an address.

func Refuse added in v0.6.0

func Refuse(err error, code, message string, held Details) error

Refuse returns the sentinel carrying its condition code, its message and the details a client reads.

func ReservedRoot

func ReservedRoot(segment string) bool

ReservedRoot reports whether the segment names a place the CMS keeps for itself.

func ResolveLocale added in v0.6.0

func ResolveLocale(asked LocaleAsked) string

ResolveLocale returns the language to answer in, preferring the reader, then the site, then the languages the request accepts.

func Slugify

func Slugify(title string) string

Slugify returns title as a URL slug, or [untitledSlug] when it holds no slug characters.

func SplitValues added in v0.5.0

func SplitValues(patch Values, fields []Field) (Values, Relations, error)

SplitValues divides a patch into the scalar values and the targets its type declares.

func ValidateLocale added in v0.6.0

func ValidateLocale(locale string) error

ValidateLocale reports whether the site answers in the language.

Types

type Address

type Address struct {
	Kind Kind
	Type Type
	Item Content
	Page int
}

Address is what a public address holds.

type AddressReader

type AddressReader interface {
	PublishedByPath(ctx context.Context, path string) (Content, error)
}

AddressReader reads the published content an address holds.

type Content

type Content struct {
	ID          uuid.UUID
	Type        string
	ParentID    *uuid.UUID
	Path        string
	Slug        string
	Title       string
	Content     string
	Excerpt     string
	Status      Status
	AuthorID    uuid.UUID
	Fields      Values
	Relations   Relations
	PublishedAt *time.Time
	CreatedAt   time.Time
	UpdatedAt   time.Time
}

Content is a content item holding Gutenberg-serialized block HTML.

func New

func New(t Type, parent *Content, title string, authorID uuid.UUID) (Content, error)

New returns a draft Content of the given type under parent, slugged after its title.

func Reparent

func Reparent(t Type, c Content, parent *Content, height int) (Content, error)

Reparent returns the item and the height it carries nested under parent, or the reason they may not sit there.

func (Content) Place

func (c Content) Place(prefix, slug string) Content

Place returns the item carrying slug at the address beneath prefix.

func (Content) Rename

func (c Content) Rename(slug string) (Content, error)

Rename returns the item carrying slug where it already answers, or the reason it may not.

func (*Content) Restore

func (c *Content) Restore() error

Restore returns a trashed content item to draft, or reports ErrInvalidTransition.

func (Content) SelfTargeted added in v0.5.0

func (c Content) SelfTargeted() error

SelfTargeted reports whether any relation field of the item points at the item itself.

func (*Content) Transition

func (c *Content) Transition(to Status) error

Transition moves the content item to the given status, stamping PublishedAt on the first publication and returning ErrInvalidTransition when disallowed.

type Details added in v0.6.0

type Details map[string]any

Details holds the parts of a refusal a client reads as data rather than as prose.

func DetailsOf added in v0.6.0

func DetailsOf(err error) (Details, bool)

DetailsOf returns the details a refusal carries, reporting false when it carries none.

type Field added in v0.5.0

type Field struct {
	ID        int
	TypeKey   string
	Key       string
	Label     string
	Kind      FieldKind
	RelatesTo string
	Many      bool
	Required  bool
	CreatedAt time.Time
	UpdatedAt time.Time
}

Field describes one typed field a content type declares.

func NewField added in v0.5.0

func NewField(f Field) (Field, error)

NewField returns a field definition ready to store, or the reason it is not one.

func (Field) Validate added in v0.5.0

func (f Field) Validate() error

Validate reports whether the field definition may be stored.

type FieldKind added in v0.5.0

type FieldKind string

FieldKind is the shape of value a field holds.

const (
	FieldKindText     FieldKind = "text"
	FieldKindNumber   FieldKind = "number"
	FieldKindBoolean  FieldKind = "boolean"
	FieldKindDate     FieldKind = "date"
	FieldKindMedia    FieldKind = "media"
	FieldKindRelation FieldKind = "relation"
)

The field kinds a content type declares.

type Filter

type Filter struct {
	Type    string
	Status  Status
	Search  string
	OrderBy OrderBy
	Order   Order
	Page    int
	PerPage int
}

Filter narrows a content listing.

type Kind

type Kind string

Kind names what an address holds.

const (
	KindItem    Kind = "item"
	KindArchive Kind = "archive"
	KindTerm    Kind = "term"
)

The kinds of thing a public address answers with.

type LocaleAsked added in v0.6.0

type LocaleAsked struct {
	User     string
	Site     string
	Accepted string
}

LocaleAsked carries what each leg of the resolution chain offered.

type Order

type Order string

Order names a sort direction.

const (
	OrderAsc  Order = "asc"
	OrderDesc Order = "desc"
)

The directions a listing can be sorted in.

func ParseOrder

func ParseOrder(raw string) (Order, error)

ParseOrder returns the direction named by raw, or ErrInvalidOrder.

type OrderBy

type OrderBy string

OrderBy names a column a listing can be sorted by.

const (
	OrderByDate  OrderBy = "date"
	OrderByTitle OrderBy = "title"
)

The columns a listing can be sorted by.

func ParseOrderBy

func ParseOrderBy(raw string) (OrderBy, error)

ParseOrderBy returns the column named by raw, or ErrInvalidOrderBy.

type PageKind

type PageKind string

PageKind is what the public page of one content item renders.

const (
	PageKindSingle  PageKind = "single"
	PageKindArchive PageKind = "archive"
)

The page kinds a content type declares.

type Refusal added in v0.6.0

type Refusal struct {
	Err     error
	Code    string
	Message string
	Held    Details
}

Refusal is a sentinel carrying its condition code and the dynamic parts of the refusal.

func (*Refusal) Error added in v0.6.0

func (r *Refusal) Error() string

Error returns the message the refusal reads as.

func (*Refusal) Unwrap added in v0.6.0

func (r *Refusal) Unwrap() error

Unwrap returns the sentinel the refusal stands for.

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry answers which content types the CMS holds, caching what it reads.

func NewRegistry

func NewRegistry(store TypeStore) *Registry

NewRegistry returns a Registry reading through store.

func (*Registry) Active

func (r *Registry) Active(ctx context.Context, key string) (Type, error)

Active returns the type carrying the key when it is active, or the reason it serves nothing.

func (*Registry) All

func (r *Registry) All(ctx context.Context) ([]Type, error)

All returns every registered type, active or not, in registration order.

func (*Registry) ByKey

func (r *Registry) ByKey(ctx context.Context, key string) (Type, error)

ByKey returns the type carrying the key, or ErrTypeNotFound.

func (*Registry) ByRouteWord

func (r *Registry) ByRouteWord(ctx context.Context, word string) (Type, error)

ByRouteWord returns the active type answering under the word, or ErrTypeNotFound.

func (*Registry) Create

func (r *Registry) Create(ctx context.Context, t Type) (Type, error)

Create registers the type, or reports why it may not join the registry.

func (*Registry) CreateField added in v0.5.0

func (r *Registry) CreateField(ctx context.Context, f Field) (Field, error)

CreateField declares the field on its type, or reports why the registry refuses it.

func (*Registry) Default

func (r *Registry) Default(ctx context.Context) (Type, error)

Default returns the type living at the root, or ErrTypeNotFound.

func (*Registry) Delete

func (r *Registry) Delete(ctx context.Context, key string) error

Delete removes the type, or reports why the registry keeps it.

func (*Registry) DeleteField added in v0.5.0

func (r *Registry) DeleteField(ctx context.Context, typeKey, key string) error

DeleteField removes the field and its values, or reports it missing.

func (*Registry) Update

func (r *Registry) Update(ctx context.Context, t Type) (Type, error)

Update stores the edited type, or reports why the registry keeps it as it stands.

func (*Registry) UpdateField added in v0.5.0

func (r *Registry) UpdateField(ctx context.Context, f Field) (Field, error)

UpdateField carries the field's label and required flag, keeping its shape.

type Relations added in v0.5.0

type Relations map[string][]uuid.UUID

Relations holds the items a content item points at, keyed by field key.

func (Relations) Merge added in v0.5.0

func (r Relations) Merge(patch Relations) Relations

Merge returns the stored targets with the patch applied, where a named field replaces its targets.

type Resolver

type Resolver struct {
	// contains filtered or unexported fields
}

Resolver answers what a public address holds.

func NewResolver

func NewResolver(store AddressReader, registry TypeReader) *Resolver

NewResolver returns a Resolver reading content through store and types through registry.

func (*Resolver) Resolve

func (r *Resolver) Resolve(ctx context.Context, raw string) (Address, error)

Resolve returns what the address holds, or ErrNotFound.

type Revision

type Revision struct {
	ID        uuid.UUID
	ContentID uuid.UUID
	Kind      RevisionKind
	AuthorID  uuid.UUID
	Title     string
	Content   string
	Excerpt   string
	Fields    Values
	CreatedAt time.Time
}

Revision is a snapshot of a content item's editable content.

func NewRevision

func NewRevision(c Content, kind RevisionKind, authorID uuid.UUID) (Revision, error)

NewRevision returns a snapshot of the item's editable content, credited to the given author.

type RevisionKind

type RevisionKind string

RevisionKind distinguishes an update snapshot from a per-author autosave.

const (
	RevisionKindRevision RevisionKind = "revision"
	RevisionKindAutosave RevisionKind = "autosave"
)

The kinds of revision a content item carries.

type Status

type Status string

Status is the publication state of a content item.

const (
	StatusDraft     Status = "draft"
	StatusPending   Status = "pending"
	StatusPrivate   Status = "private"
	StatusScheduled Status = "scheduled"
	StatusPublished Status = "published"
	StatusTrash     Status = "trash"
)

The statuses a content item may hold. Scheduled is stored but unreachable until a publish worker exists.

func ParseStatus

func ParseStatus(value string) (Status, error)

ParseStatus returns the Status named by value, or ErrInvalidStatus.

type Store

type Store interface {
	Create(ctx context.Context, c Content) (Content, error)
	ByID(ctx context.Context, id uuid.UUID) (Content, error)
	PublishedByPath(ctx context.Context, path string) (Content, error)
	Children(ctx context.Context, id uuid.UUID) (int, error)
	Depth(ctx context.Context, id uuid.UUID) (int, error)
	List(ctx context.Context, f Filter) ([]Content, int, error)
	RelatedTo(ctx context.Context, target uuid.UUID, page, perPage int) ([]Content, int, error)
	TargetsOf(ctx context.Context, from uuid.UUID) (Targets, error)
	Update(
		ctx context.Context, c Content, expectedUpdatedAt time.Time, snapshot *Revision, revisionCap int,
	) (Content, error)
	Trash(ctx context.Context, id uuid.UUID, updatedAt time.Time) (Content, error)
	Restore(ctx context.Context, id uuid.UUID, updatedAt time.Time) (Content, error)
	Delete(ctx context.Context, id uuid.UUID) error
	Counts(ctx context.Context, contentType string) (map[Status]int, error)
	Revisions(ctx context.Context, contentID uuid.UUID) ([]Revision, error)
	RevisionByID(ctx context.Context, contentID, revisionID uuid.UUID) (Revision, error)
	DeleteRevision(ctx context.Context, contentID, revisionID uuid.UUID) error
	SaveAutosave(ctx context.Context, autosave Revision) (Revision, error)
	Autosave(ctx context.Context, contentID, authorID uuid.UUID) (Revision, error)
	DeleteAutosave(ctx context.Context, contentID, authorID uuid.UUID) error
}

Store persists content items and their revisions.

type Target added in v0.5.0

type Target struct {
	ID    uuid.UUID
	Title string
	Path  string
}

Target names one item a relation field points at, as a public reader sees it.

type Targets added in v0.5.0

type Targets map[string][]Target

Targets holds the items a content item points at, named and addressed, keyed by field key.

type Type

type Type struct {
	Key           string
	SingularLabel string
	PluralLabel   string
	RouteWord     string
	Hierarchical  bool
	Revisions     bool
	RevisionCap   int
	PageKind      PageKind
	Default       bool
	Active        bool
	Fields        []Field
	CreatedAt     time.Time
	UpdatedAt     time.Time
}

Type describes a kind of content the CMS stores.

func NewType

func NewType(key, singular, plural, routeWord string) (Type, error)

NewType returns a content type ready to store, or the reason it is not one.

func (Type) Validate

func (t Type) Validate() error

Validate reports whether the type may be stored.

type TypeReader

type TypeReader interface {
	ByRouteWord(ctx context.Context, word string) (Type, error)
	ByKey(ctx context.Context, key string) (Type, error)
}

TypeReader answers which type answers under a route word and which carries a key.

type TypeStore

type TypeStore interface {
	List(ctx context.Context) ([]Type, error)
	ByKey(ctx context.Context, key string) (Type, error)
	Create(ctx context.Context, t Type) (Type, error)
	Update(ctx context.Context, t Type) (Type, error)
	Delete(ctx context.Context, key string) error
	CreateField(ctx context.Context, f Field) (Field, error)
	UpdateField(ctx context.Context, f Field) (Field, error)
	DeleteField(ctx context.Context, typeKey, key string) error
}

TypeStore persists the content type registry and its field definitions.

type Values added in v0.5.0

type Values map[string]any

Values holds a content item's scalar field values keyed by field key.

func (Values) Merge added in v0.5.0

func (v Values) Merge(patch Values) Values

Merge returns the stored values with the patch applied, where a nil value clears its key.

func (Values) Validate added in v0.5.0

func (v Values) Validate(fields []Field) error

Validate reports whether every value matches the kind its field declares.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL