Documentation
¶
Overview ¶
Package snippets manages the pre-written HTML blocks editors can insert into rich regions from the in-place editor's palette. Snippets come from two places: the host application's config (per-customer components, versioned with the code) and the database (created by admins in the admin UI). Once inserted, a snippet is ordinary region content — edited in place, sanitized on save, and styled entirely by the host site's CSS.
Index ¶
- Variables
- func CodeKeyFor(name string) string
- func CodeKeyPattern() *regexp.Regexp
- func ValidCodeKey(key string) bool
- type CodeSnippet
- type CodeStore
- func (s *CodeStore) All(ctx context.Context) ([]CodeSnippet, error)
- func (s *CodeStore) ByKey(ctx context.Context, key string) (*CodeSnippet, error)
- func (s *CodeStore) Delete(ctx context.Context, key string) error
- func (s *CodeStore) Insert(ctx context.Context, c *CodeSnippet) (int64, error)
- func (s *CodeStore) Lookup(ctx context.Context, onErr func(key string, err error)) func(string) (string, bool)
- func (s *CodeStore) Update(ctx context.Context, c *CodeSnippet) error
- type Snippet
- type Store
- func (s *Store) All(ctx context.Context) ([]Snippet, error)
- func (s *Store) Count(ctx context.Context) (int, error)
- func (s *Store) Delete(ctx context.Context, id int64) error
- func (s *Store) GetByID(ctx context.Context, id int64) (*Snippet, error)
- func (s *Store) Insert(ctx context.Context, sn *Snippet) (int64, error)
- func (s *Store) Update(ctx context.Context, sn *Snippet) error
Constants ¶
This section is empty.
Variables ¶
var ErrDuplicateCodeKey = errors.New("snippets: code key already exists")
ErrDuplicateCodeKey is returned when a key is already taken.
var ErrNotFound = errors.New("snippets: not found")
ErrNotFound is returned when no snippet matches the query.
Functions ¶
func CodeKeyFor ¶ added in v1.1.9
CodeKeyFor turns a human name into a key candidate: lowercased, runs of anything outside [a-z0-9] collapsed to a single hyphen, trimmed to the column's width. Returns "" when nothing usable survives, which callers treat as "ask for a key instead of guessing one".
func CodeKeyPattern ¶ added in v1.1.9
CodeKeyPattern is the same vocabulary as a pattern, for callers that need the regexp rather than the predicate — the editor's HTML sanitizer bounds the placeholder attribute with it, and having one definition is what keeps the two from drifting apart.
func ValidCodeKey ¶ added in v1.1.9
ValidCodeKey reports whether key is a usable code-snippet key: a lowercase letter or digit followed by up to 63 more of those or hyphens.
Types ¶
type CodeSnippet ¶ added in v1.1.9
type CodeSnippet struct {
ID int64
Key string // referenced by data-cms-code; see ValidCodeKey
Name string // what the editor shows a human
HTML string // markup, script tags and all
CreatedAt time.Time
UpdatedAt time.Time
}
CodeSnippet is one custom-code block: markup that may carry its own <script> (or <style>), stored under a key and referenced from page content rather than pasted into it.
The split matters. Region and section content is sanitized on every non-admin save, so executable markup left inside it would either be stripped — silently deleting an admin's widget the first time an editor fixed a typo in the same section — or have to be safelisted, which would hand every editor a script-injection hole. What a page stores instead is an inert placeholder naming this key (<div class="cms-code" data-cms-code="key"></div>): safe to carry through the sanitizer untouched, meaningless on its own, and swapped for the HTML below on a public render.
type CodeStore ¶ added in v1.1.9
type CodeStore struct {
// contains filtered or unexported fields
}
CodeStore reads and writes the custom-code library.
func NewCodeStore ¶ added in v1.1.9
NewCodeStore returns a CodeStore backed by db.
func (*CodeStore) All ¶ added in v1.1.9
func (s *CodeStore) All(ctx context.Context) ([]CodeSnippet, error)
All returns every code snippet, ordered by name.
func (*CodeStore) Delete ¶ added in v1.1.9
Delete removes a code snippet. Placeholders in pages that named it are left alone and render as nothing, so a delete is recoverable by creating the key again.
func (*CodeStore) Insert ¶ added in v1.1.9
Insert stores a new code snippet and returns its id. A key already in use comes back as ErrDuplicateCodeKey.
func (*CodeStore) Lookup ¶ added in v1.1.9
func (s *CodeStore) Lookup(ctx context.Context, onErr func(key string, err error)) func(string) (string, bool)
Lookup returns a func that resolves keys to markup for one render, remembering what it has already fetched: a page naming the same block twice costs one query, and a page naming none costs none. Errors resolve to "not found" — a failing widget must not take the page down — and are reported to onErr when one is given.
type Snippet ¶
type Snippet struct {
ID int64
Name string
Group string
HTML string
Settings map[string]string
CreatedAt time.Time
UpdatedAt time.Time
}
Snippet is one insertable block. ID is set only for database-stored snippets; config-registered ones have ID zero.
A snippet with a non-nil Settings map is a *section preset*: instead of a block dropped into existing content, it is a starting point for a whole section — the editor offers it only in the "Add a section" chooser, and applies the settings (background, width, height, vertical alignment) to the new section along with the HTML. Keys and values are the section-settings vocabulary: "bg" and "width" name curated SectionStyles option keys, "height" is "50"/"75"/"100", "valign" is "center"/"bottom", "bgcolor" is #rrggbb, "bgimage" is a URL, and "bgposition" anchors that image as a pair of percentages across and down, e.g. "50% 20%" ("50% 50%" is centered, and is the default). Unknown keys or invalid values fall back to the defaults, same as the section settings dialog. Presets come from config or from the admin snippets UI (which offers the curated settings; the free-form bgcolor/bgimage/bgposition are config-only). Group names the category the editor's drawer files the snippet under: the drawer offers a category dropdown when any loaded snippet carries one. Grouping is config-only (like render.EditorStyle.Group) — admin- created snippets and ungrouped config snippets appear under "Custom".
func DefaultSectionPresets ¶
func DefaultSectionPresets() []Snippet
DefaultSectionPresets is the Tailwind-first default library of section presets — snippets with Settings, offered as one-click starting points in the "Add a section" chooser. Two markup strategies, chosen per preset: markup that should adapt when the editor later changes the section background skips not-prose and leans on prose/prose-invert for its colors (Hero, CTA, FAQ); grid layouts that Typography would restyle use not-prose with explicit slate colors and suit light backgrounds (Feature grid, Stats, Testimonials). Like DefaultSnippets, every class must be safelisted in the site's Tailwind build (see the README).
func DefaultSnippets ¶
func DefaultSnippets() []Snippet
DefaultSnippets is the Tailwind-first default library, used when the host does not configure its own. The markup avoids elements the editor sanitizer strips (no SVG, no scripts) and uses `not-prose` so Tailwind Typography doesn't restyle component internals. Like the editor styles, every class here must be safelisted in the site's Tailwind build (see the README). The cms-snippet marker class on each snippet's root makes the block manageable in the in-place editor: a dotted outline while editing, and a floating drag-handle/trash chrome when clicked. Like cms-btn (which marks a link as an editable button), it carries no CSS of its own.
func LibrarySectionPresets ¶ added in v0.9.3
func LibrarySectionPresets() []Snippet
LibrarySectionPresets returns the imported section presets. Like DefaultSectionPresets, each carries Settings so the editor offers it in the "Add a section" chooser. All use not-prose with explicit slate colors, so they suit light backgrounds.
func LibrarySnippets ¶ added in v0.9.3
func LibrarySnippets() []Snippet
LibrarySnippets returns the imported inline blocks. They ship with the defaults when Config.Snippets is nil.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store reads and writes admin-created snippets in Postgres.
func (*Store) Count ¶
Count returns how many stored snippets exist — the admin adds the host-registered ones and shows the total beside its Snippets nav entry.
func (*Store) Delete ¶
Delete removes a stored snippet. Content already inserted into pages is unaffected — inserted snippets are plain region HTML.
Source Files