Documentation
¶
Overview ¶
Package sdui is the kit a module describes its part of every app with: its pages, sections, components, data sources, views, menu entries, settings and theme scope, in the sdui.json that ships in each release (WittyMediaServer docs/SDUI-MODULES.md).
A module built for module API 4 must carry one; the server checks it against its catalogue before the module is used and refuses a version without it. This package writes the file from Go, checks it the way the server will as far as that can be done without a server (Check), and answers the server's calls for the module's sources, pictures and settings (Answers).
Index ¶
- Constants
- Variables
- func Errors(issues []Issue) error
- func ImagePath(module, name string) string
- func Int(n int) *int
- func JSON(m *Module) ([]byte, error)
- func Props(kv ...any) map[string]any
- func Settings() map[string]any
- func Summary(m *Module) wittymodule.CatalogUI
- func WriteFile(m *Module, path string) error
- type Action
- type Answers
- type Condition
- type Control
- type DockEntry
- type EnumOption
- type Issue
- type Item
- type ItemAction
- type ItemsAnswer
- type ItemsRequest
- type Match
- type Module
- func (m *Module) AddComponent(c ModuleComponent) *Module
- func (m *Module) AddInsert(page, after string, s Section) *Module
- func (m *Module) AddNav(n NavItem) *Module
- func (m *Module) AddPage(p Page) *Module
- func (m *Module) AddPreset(p ModulePreset) *Module
- func (m *Module) AddSettings(p SettingsPage) *Module
- func (m *Module) AddSource(s SourceSpec) *Module
- func (m *Module) AddView(v ModuleView) *Module
- func (m *Module) Colours(tokens map[string]string) *Module
- type ModuleComponent
- type ModuleInsert
- type ModulePreset
- type ModuleSource
- type ModuleTheme
- type ModuleView
- type NavItem
- type Page
- type PageRegions
- type PersonalPolicy
- type Programme
- type PropSpec
- type Repeat
- type Section
- type SettingRow
- type SettingsGroup
- type SettingsPage
- type Source
- type SourceSpec
- type StatusItem
- type Titles
- type Variant
- type Viewer
Constants ¶
const ( MethodItems = "sdui.items" MethodImage = "sdui.image" MethodSettingsChanged = "settings.changed" )
The calls a server makes to a module's helper for its SDUI.
const ( Format = "wittymodule-sdui" FormatVersion = 1 )
Format and FormatVersion mark the file.
const CatalogRevision = 8
CatalogRevision is the catalogue revision this kit's copy of the catalogue is.
const File = "sdui.json"
File is the name of a module's SDUI file, beside module.json.
const MaxBytes = 1 << 20
MaxBytes bounds the file.
const SettingsEnv = "WITTYMODULE_SETTINGS"
SettingsEnv names the environment a helper is started with: its server settings, as a JSON object, defaults filled in.
Variables ¶
var ( StatusKinds = core.StatusKinds SettingsSlots = core.SettingsSlots )
The status bar's kinds of item, and the places a settings page may be put into.
var CatalogJSON []byte
CatalogJSON is a copy of the server's catalogue (GET /api/v1/sdui/catalog), revision 8.
var ColorTokens = []string{"accent", "accentFg", "accentHover", "accentLine", "accentSoft", "accentText", "bg", "bg2", "bg3", "bg4", "border", "borderStrong",
"brandAccent", "controlLine", "danger", "dangerSoft", "fg", "fg2", "fg3", "focus", "hover", "ok", "okSoft", "onImage", "overlay", "pressed", "scrim", "warn", "warnSoft"}
ColorTokens are the colour tokens themes have, which a module's theme may set.
var SchemaJSON []byte
SchemaJSON is the JSON Schema of the file, as the server writes it.
Functions ¶
func ImagePath ¶
ImagePath is where a server serves a picture of the module's own, answered by Image.
func JSON ¶
JSON is the file's contents for a module: indented, with a newline at the end, the same bytes every time for the same module.
func Summary ¶
func Summary(m *Module) wittymodule.CatalogUI
Summary sums up what a module's SDUI adds to the apps, as a catalogue lists it for a version (wittymodule.CatalogUI): its pages, its menu entries by label, whether it has settings, and how many sources and inserts it has. A store shows it before anything is installed. It is cut to the catalogue's limits, which a file that passes Check is within.
Types ¶
type Action ¶ added in v0.5.1
Action is what activating an item (or one of its buttons) does: a route, playing a title, or one of the module's own commands.
type Answers ¶
type Answers struct {
Items func(ItemsRequest) (ItemsAnswer, error)
// Image answers a picture by name: PNG, JPEG, WebP or GIF, at most 4 MiB.
Image func(name string) ([]byte, error)
// SettingsChanged hears the server's settings after an administrator saved them.
SettingsChanged func(values map[string]any)
}
Answers are a helper's answers to the server's SDUI calls. Any may be nil.
func (Answers) Handle ¶
func (a Answers) Handle(method string, params json.RawMessage) (result any, blob []byte, err error, handled bool)
Handle answers one call if it is one of these: handled is false for any other method, for the helper's own handler to answer. Use it first in a wittymodule.Handler:
if res, blob, err, ok := answers.Handle(method, params); ok {
return res, blob, err
}
type Condition ¶
type Condition struct {
All []Condition `json:"all,omitempty"`
Any []Condition `json:"any,omitempty"`
Not *Condition `json:"not,omitempty"`
// FormFactor: the device is one of these (tv, phone, tablet, desktop, web).
FormFactor []string `json:"formFactor,omitempty"`
// Platform: the app is one of these (web, tvos, ios, android, androidtv, desktop).
Platform []string `json:"platform,omitempty"`
// ProfileKind: the profile is one of these (adult, kids, guest).
ProfileKind []string `json:"profileKind,omitempty"`
// Admin: the profile is (true) or isn't (false) an administrator.
Admin *bool `json:"admin,omitempty"`
// Feature: the server has this feature (/capabilities features).
Feature string `json:"feature,omitempty"`
// Module: this module is installed and on.
Module string `json:"module,omitempty"`
// Can: the profile may use this (games, recordings, downloads, sharing,
// comments, syncplay, remoteControl, remote, liveTv, editLayout): its
// parental feature switches.
Can string `json:"can,omitempty"`
// HasLibrary: the profile can open at least one library of this kind.
HasLibrary string `json:"hasLibrary,omitempty"`
// LibraryKind: the page's own library is of this kind (library pages).
LibraryKind string `json:"libraryKind,omitempty"`
// Capability: the client said it has this (capabilities=hdr,touch).
Capability string `json:"capability,omitempty"`
// Flag: something the server knows is so: setupIncomplete, scanning,
// librariesEmpty, hasQuery, screenTimeUp.
Flag string `json:"flag,omitempty"`
// MinWidth and MaxWidth bound the window's width in points, inclusive.
// They pass when the client didn't say how wide it is.
MinWidth int `json:"minWidth,omitempty"`
MaxWidth int `json:"maxWidth,omitempty"`
// TimeFrom and TimeTo bound the time of day on the server, "HH:MM",
// from inclusive and to exclusive; a range may pass midnight.
TimeFrom string `json:"timeFrom,omitempty"`
TimeTo string `json:"timeTo,omitempty"`
// Weekday: today is one of these (mon, tue, wed, thu, fri, sat, sun).
Weekday []string `json:"weekday,omitempty"`
// Locale: the client's language is this or a kind of it (en matches en-GB).
Locale string `json:"locale,omitempty"`
}
Condition says when a section, variant or navigation entry is shown. Every field that is set must hold; All, Any and Not combine conditions. The zero Condition always holds.
type DockEntry ¶
DockEntry is one destination of the system dock: a route, shown as a layer when As is "layer".
type EnumOption ¶
EnumOption is one choice of a property or facet.
type Issue ¶
type Issue struct {
Path string `json:"path"`
Severity string `json:"severity"`
Message string `json:"message"`
Fix string `json:"fix,omitempty"`
}
Issue is one thing wrong, where, and what to do about it.
func Check ¶
Check checks a module's SDUI exactly as the server does before it uses a module: it is the server's own validator (internal/core, a copy of WittyMediaServer's pkg/sdui that kit/sync-sdui-core.sh keeps current), so a module that passes here is not refused at install for its SDUI. module is the module's ID ("" to take the file's). What the server adds from outside the file, such as that only a helper may declare sources, is checked by `wittymodule check`, which has the manifest.
type Item ¶
Item is one thing a data source found, in the one shape every card style reads: the server's own (sdui/core), so a module's card can carry everything the server's cards can, a row's switch (Control), what tapping it does (Action), the text at its end (Trailing) and a detail panel's buttons (Actions) included. A source fills what it knows; a card style shows what it has room for (see CardStyles).
type ItemAction ¶ added in v0.5.1
type ItemAction = core.ItemAction
ItemAction is one button of an item's detail panel.
type ItemsAnswer ¶
type ItemsAnswer struct {
Items []Item `json:"items"`
More bool `json:"more,omitempty"`
Total int `json:"total,omitempty"`
}
ItemsAnswer is the module's answer. The server keeps only what a card may carry and the profile may see: give contentRating and genres where they apply, routes in the app, and pictures on the server (the module's own: ImagePath).
type ItemsRequest ¶
type ItemsRequest struct {
// Source is the section's source, with the page's variables filled in.
Source Source `json:"source"`
Filter map[string]string `json:"filter,omitempty"`
Offset int `json:"offset"`
Limit int `json:"limit"`
Viewer Viewer `json:"viewer"`
// Settings are the module's settings for this profile: the server's, then the
// profile's own, defaults filled in.
Settings map[string]any `json:"settings,omitempty"`
}
ItemsRequest is a server asking for one of the module's sources.
type Match ¶
type Match struct {
// Library is one library's ID.
Library int64 `json:"library,omitempty"`
// LibraryKind is a kind of library: movies, shows, anime, music, ...
LibraryKind string `json:"libraryKind,omitempty"`
// MediaKind is a kind of title on a detail page: movie, show, episode,
// album, book, game, collection, ...
MediaKind string `json:"mediaKind,omitempty"`
}
Match narrows a page. Zero fields match anything.
type Module ¶
type Module struct {
// Schema may name the JSON Schema an editor checks the file with
// (docs/sdui-module.schema.json); the server ignores it.
Schema string `json:"$schema,omitempty"`
// Format is ModuleFormat, FormatVersion ModuleFormatVersion.
Format string `json:"format"`
FormatVersion int `json:"formatVersion"`
// Module is the module's ID, the same as its manifest's.
Module string `json:"module"`
// Catalog is the catalogue revision the module was written against. A
// server refuses a file newer than its own catalogue.
Catalog int `json:"catalog"`
// Theme is the module's theme scope. Required.
Theme ModuleTheme `json:"theme"`
// Pages are whole pages the module adds: its own (kind custom, opened at
// /page/{id}), or a page for a kind of library or title (a games library
// page, the detail page of a game), or the page of a kind the module is
// about (games, photos, books, music, livetv).
Pages []Page `json:"pages,omitempty"`
// Inserts put one of the module's sections into a built-in page, such as a
// row on Home. An administrator's own page is never changed by a module.
Inserts []ModuleInsert `json:"inserts,omitempty"`
// Presets are sections offered in the page editor's gallery.
Presets []ModulePreset `json:"presets,omitempty"`
// Components are the module's named sections: a section of catalogue
// components with properties of its own, offered in the editor's palette
// and expanded by the server, so no app needs to know them.
Components []ModuleComponent `json:"components,omitempty"`
// Sources are the data sources the module answers, through its helper.
Sources []ModuleSource `json:"sources,omitempty"`
// Views are views of the module's own that an app may draw in a
// NativeView (the module's web bundle, for one); every other app draws the
// NativeView's sections instead.
Views []ModuleView `json:"views,omitempty"`
Navigation []NavItem `json:"navigation,omitempty"`
// Settings describe the module's settings, which every app's own Settings
// draws in its own style under Settings, Modules. They are never SDUI pages.
Settings []SettingsPage `json:"settings,omitempty"`
}
Module is one module's SDUI file.
func New ¶
New starts a module's SDUI: its ID, the catalogue revision it is written for, and its theme scope with a label for the theme editor.
func (*Module) AddComponent ¶
func (m *Module) AddComponent(c ModuleComponent) *Module
func (*Module) AddPage ¶
AddPage, AddSource, AddComponent, AddView, AddInsert, AddPreset, AddNav and AddSettings add one of each, and answer the module for the next.
func (*Module) AddPreset ¶
func (m *Module) AddPreset(p ModulePreset) *Module
func (*Module) AddSettings ¶
func (m *Module) AddSettings(p SettingsPage) *Module
func (*Module) AddSource ¶
func (m *Module) AddSource(s SourceSpec) *Module
func (*Module) AddView ¶
func (m *Module) AddView(v ModuleView) *Module
type ModuleComponent ¶
type ModuleComponent struct {
// Type is "<module>.<Name>": wittyplay.ConsoleShelf.
Type string `json:"type"`
Label string `json:"label"`
Description string `json:"description,omitempty"`
Icon string `json:"icon,omitempty"`
Props []PropSpec `json:"props,omitempty"`
// PageKinds are the kinds of page it may be used on; empty: any.
PageKinds []string `json:"pageKinds,omitempty"`
Section Section `json:"section"`
}
ModuleComponent is a named section with properties of its own. Its Section is a template: a value written "{{name}}" becomes the property's value, and "{{name}}" inside text is replaced by it.
type ModuleInsert ¶
type ModuleInsert struct {
// Page is the built-in page's ID: home, music, games, ...
Page string `json:"page"`
// After or Before name a section of that page; neither: at the end.
After string `json:"after,omitempty"`
Before string `json:"before,omitempty"`
Section Section `json:"section"`
}
ModuleInsert puts a section into a built-in page.
type ModulePreset ¶
type ModulePreset struct {
ID string `json:"id"`
Label string `json:"label"`
Description string `json:"description,omitempty"`
Section Section `json:"section"`
}
ModulePreset is a section for the editor's gallery.
type ModuleSource ¶
type ModuleSource struct {
SourceSpec
}
ModuleSource is a data source a module answers: the catalogue's description of a source, with Type "<module>.<name>".
type ModuleTheme ¶
type ModuleTheme struct {
Scope string `json:"scope"`
Label string `json:"label,omitempty"`
Tokens map[string]string `json:"tokens,omitempty"`
}
ModuleTheme is a module's theme scope: its ID, a name to show in the theme editor, and the colours the module would like, which an administrator's own overrides for the scope replace token by token.
type ModuleView ¶
type ModuleView struct {
// ID is "<module>.<name>"; it is what a NativeView's view prop names and
// what an app that can draw it sends in views=.
ID string `json:"id"`
Label string `json:"label"`
Description string `json:"description,omitempty"`
// Platforms that can draw it, as a hint for the editor; empty: unknown.
Platforms []string `json:"platforms,omitempty"`
}
ModuleView is a view of the module's own for a NativeView.
type NavItem ¶
type NavItem struct {
// Label and Icon may be left out for a page (its title and icon are used)
// and for the libraries (each library's name and its kind's icon).
// Type is "page" (Page names it), "libraries" (one entry per library the
// profile can open), "library" (Library is its ID), "native" (Screen is a
// screen the app draws itself: settings, guide, profiles, downloads,
// remote) or "route" (Route is a place in the app).
When *Condition `json:"when,omitempty"`
// bar itself), "more" (behind More or in the sidebar's lower group), "end"
// (pinned to the far end) or "hidden". A form factor left out is primary.
Placement map[string]string `json:"placement,omitempty"`
}
NavItem is one entry of the main menu.
type Page ¶
type Page struct {
// ID names the page: lower-case letters, digits, - and _. A page with the
// ID of a built-in page replaces it.
ID string `json:"id"`
// Kind says what the page is for, which decides when the app opens it and
// what its sources may refer to ($library on a library page, $item on a
// detail page). See PageKinds.
Kind string `json:"kind"`
// Title is shown in the page's heading and the window title. It may hold
// placeholders ({library}, {title}, {query}, {user}).
Title string `json:"title"`
// Icon is one of Icons, for a navigation entry made from the page.
Icon string `json:"icon,omitempty"`
// Description is for whoever edits the page; clients never see it.
Description string `json:"description,omitempty"`
// Match narrows a library or detail page to one library, one kind of
// library or one kind of media. The most specific match wins.
Match *Match `json:"match,omitempty"`
// Scope is the theme scope the page belongs to: a module id (wittymusic)
// or another name with colours under theme.modules. The whole page takes
// that scope's colour overrides.
Scope string `json:"scope,omitempty"`
// Sections are the page, top to bottom.
Sections []Section `json:"sections"`
// Variants replace Sections for the first variant whose condition holds:
// a kids home, a television home.
Variants []Variant `json:"variants,omitempty"`
// Personal says what a profile may change about the page for itself. nil:
// everything in PersonalKinds.
Personal *PersonalPolicy `json:"personal,omitempty"`
// TTLSeconds suggests how long a client may show the page before asking
// again. 0: the default for the page's kind.
TTLSeconds int `json:"ttlSeconds,omitempty"`
// Regions are what the page puts into the shell's own regions (the status bar, the system
// dock) while it, or its theme scope, is showing.
Regions *PageRegions `json:"regions,omitempty"`
// Slot puts a custom page into a place of the hand-built Settings, as a settings page's slot
// does: "you.games" (You, Games) or "people.profile" (Settings, People, a profile, for
// administrators; the page is opened about the profile, as item). See SettingsSlots.
Slot string `json:"slot,omitempty"`
}
Page is one page of the app as it is authored: an ordered list of sections, each a component from the catalogue, most of them filled from a data source. A page is rendered for one profile on one device into a Document.
type PageRegions ¶
type PageRegions = core.PageRegions
PageRegions is a page's contribution to the shell's regions.
type PersonalPolicy ¶
type PersonalPolicy struct {
Allow []string `json:"allow"`
}
PersonalPolicy lists what profiles may change: any of PersonalKinds. An empty list means nothing.
type PropSpec ¶
type PropSpec struct {
Name string `json:"name"`
Type string `json:"type"`
Label string `json:"label"`
Help string `json:"help,omitempty"`
// Default is what a renderer and the server assume when it is left out.
Default any `json:"default,omitempty"`
Required bool `json:"required,omitempty"`
// Options are the choices of an enum or enumList.
Options []EnumOption `json:"options,omitempty"`
// Min and Max bound an int; MaxLength a string.
Min *int `json:"min,omitempty"`
Max *int `json:"max,omitempty"`
MaxLength int `json:"maxLength,omitempty"`
// FormFactors lists where the property has an effect; empty means all.
FormFactors []string `json:"formFactors,omitempty"`
// Since is the catalogue revision the property appeared in.
Since int `json:"since"`
}
PropSpec describes one property of a component or parameter of a source, with everything an editor needs to offer it and a validator to check it.
type Repeat ¶
type Repeat struct {
// Over is "libraries", "pinnedViews" or "collections".
Over string `json:"over"`
// Kinds keeps only libraries of these kinds (Over "libraries").
Kinds []string `json:"kinds,omitempty"`
// Limit is the most copies made; 0 is the device's limit.
Limit int `json:"limit,omitempty"`
}
Repeat makes a section once per thing.
type Section ¶
type Section struct {
// ID is unique on the page (across variants too): it is how a profile's
// own order refers to the section and how a client asks for more of it.
ID string `json:"id"`
// Component is a type from the catalogue: Shelf, Hero, Grid, ...
Component string `json:"component"`
// Props are the component's properties, as the catalogue describes them.
Props map[string]any `json:"props,omitempty"`
// Source says where the component's items come from.
Source Source `json:"source,omitempty"`
// When must hold for the section to be shown.
When *Condition `json:"when,omitempty"`
// Repeat makes one copy of the section for each library, pinned view or
// collection, with $each standing for it in Source and {each} in titles.
Repeat *Repeat `json:"repeat,omitempty"`
// Scope is a theme scope for this section alone (see Page.Scope).
Scope string `json:"scope,omitempty"`
// Locked keeps profiles from hiding or moving the section.
Locked bool `json:"locked,omitempty"`
// Children are the sections inside a layout component (Stack, Split, Tab).
Children []Section `json:"children,omitempty"`
}
Section is one component on a page.
func NativeView ¶
NativeView is a view of the module's own where an app has it, and children elsewhere.
type SettingRow ¶
type SettingRow struct {
// Key names the value: lower-case first letter, then letters, digits, . _ -.
Key string `json:"key"`
Kind string `json:"kind"`
Label string `json:"label"`
Help string `json:"help,omitempty"`
// Scope is server (the default) or profile.
Scope string `json:"scope,omitempty"`
Default any `json:"default,omitempty"`
Options []EnumOption `json:"options,omitempty"`
Min *int `json:"min,omitempty"`
Max *int `json:"max,omitempty"`
// Unit follows a number: "MB", "seconds".
Unit string `json:"unit,omitempty"`
MaxLength int `json:"maxLength,omitempty"`
}
SettingRow is one setting.
type SettingsGroup ¶
type SettingsGroup struct {
Title string `json:"title,omitempty"`
Rows []SettingRow `json:"rows"`
}
SettingsGroup is a titled group of rows.
type SettingsPage ¶
type SettingsPage struct {
ID string `json:"id"`
Title string `json:"title"`
Icon string `json:"icon,omitempty"`
// Admin pages are shown only to administrators.
Admin bool `json:"admin,omitempty"`
// Slot puts the page into a place of the hand-built Settings: "you.games" (You, Games) or
// "people.profile" (Settings, People, a profile; administrators only, so the page must be
// Admin). See SettingsSlots.
Slot string `json:"slot,omitempty"`
Groups []SettingsGroup `json:"groups"`
}
SettingsPage is one page of a module's settings, as every app's own Settings draws it: a title, and groups of rows.
type Source ¶
Source is a data source and its parameters, written flat: {"type": "recentlyAdded", "library": 3, "limit": 20}. The catalogue lists every type and its parameters. A string parameter beginning with $ stands for something the page was opened with ($library, $item, $show, $query) or for the thing a repeated section is repeated over ($each).
type SourceSpec ¶
type SourceSpec struct {
Type string `json:"type"`
Label string `json:"label"`
Description string `json:"description"`
Icon string `json:"icon"`
// Category groups the editor's list: personal, library, discover, live,
// music, context, structure.
Category string `json:"category"`
Params []PropSpec `json:"params,omitempty"`
// Yields are the item kinds it gives; CardStyle the style "auto" means.
Yields []string `json:"yields"`
CardStyle string `json:"cardStyle"`
// PageKinds lists the kinds of page it can be used on; empty means any.
PageKinds []string `json:"pageKinds,omitempty"`
// Paged sources give more through a section's cursor URL.
Paged bool `json:"paged"`
// SeeAll is the route "See all" opens, with {param} placeholders; "" when
// the source has no page of its own.
SeeAll string `json:"seeAll,omitempty"`
// Title is a good default title for a section using it.
Title string `json:"title,omitempty"`
Since int `json:"since"`
Example json.RawMessage `json:"example,omitempty"`
// Module is the module that answers the source; "" for the server.
Module string `json:"module,omitempty"`
// TopShelf offers the source for tvOS Top Shelf, as a row of its own: only for a
// source with no required parameters and no PageKinds.
TopShelf bool `json:"topShelf,omitempty"`
}
SourceSpec describes one data source.
type StatusItem ¶
type StatusItem = core.StatusItem
StatusItem is one thing in the status bar: kind profile, server or text.
type Variant ¶
type Variant struct {
ID string `json:"id"`
Label string `json:"label,omitempty"`
When *Condition `json:"when"`
Sections []Section `json:"sections"`
}
Variant is another list of sections for the same page, used when its condition holds. Variants are tried in order; the first that holds wins.
type Viewer ¶
type Viewer struct {
// User is the account the page is for (its id on the server), for a module's own data about
// that person: what they played, their friends, their saves.
User int64 `json:"user,omitempty"`
ProfileKind string `json:"profileKind"`
Admin bool `json:"admin,omitempty"`
Cannot []string `json:"cannot,omitempty"`
FormFactor string `json:"formFactor,omitempty"`
Platform string `json:"platform,omitempty"`
Locale string `json:"locale,omitempty"`
}
Viewer is who the page is for.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package sdui is WittyMediaServer's server-driven UI: the model an administrator writes pages in, the catalogue that describes it, the validator, and the renderer that turns one page into the tree of components one profile's app draws on one device.
|
Package sdui is WittyMediaServer's server-driven UI: the model an administrator writes pages in, the catalogue that describes it, the validator, and the renderer that turns one page into the tree of components one profile's app draws on one device. |
|
Package sduitest keeps a module's sdui.json equal to its Go definition, in the module's own tests:
|
Package sduitest keeps a module's sdui.json equal to its Go definition, in the module's own tests: |