A package is a set of elements to be used in WebWriter, implemented by a developer. It contains several parts with a package.json file serving as the entrypoint. It should follow NPM's conventions to provide metadata for the widget package. Specifically, these rules apply:
A field name MUST be present. The name MUST be scoped (in the form @{SCOPE}/{NAME}).
A field version MUST be present. It MUST follow the syntax of SemVer and SHOULD follow the conventions laid out with SemVer.
A field exports MUST be present. It MUST contain a record mapping identifiers of the pattern {TYPE}/{ID} to relative paths of source files.
{TYPE} MUST be one of themes, utilities, snippets or widgets.
{ID} MUST be a sequence of lowercase, URL-safe characters.
If {TYPE} is widgets, {ID} MUST follow the form {SCOPE}-{ELEMENT}, where {SCOPE} is the package scope and {ELEMENT} is a string such that {SCOPE}-{ELEMENT} is a valid custom element identifier. The file referenced MUST be a JavaScript or TypeScript file that registers a custom element of the same name {SCOPE}-{ELEMENT} with window.customElements.define
If {TYPE} is snippets, {ID} MAY be a string such that widgets/{ID} is also defined in exports.
If {TYPE} is themes, the file referenced MUST be a CSS file.
A field editingConfig MAY be present. It MUST be an object where each key is also present in exports, and each value is an object providing editing settings depending on {TYPE}
Elements
Widgets
Widgets are interactive elements visible to both authors and users.
Attributes represent the permanent state of the widget. WebWriter tracks changes in attributes and is able to undo/redo them. For non-permanent state, properties should be used.
Attributes of the widget and events that may be emitted can be annotated for purposes of documentation.
Supported attributes & events
class - State of the editor
ww-beforeprint: Before printing, this class is set, allowing widgets to change their presentation to be print-ready.
contenteditable - Differentiate author and user behavior
The value contenteditable="true" is set when editing, allowing widgets to provide affordances to authors change their state.
lang - Language for localization
WebWriter sets the user's chosen document language on each widget during editing as the lang attribute. The widget should process the set locale and change its presentation accordingly.
@experience - Custom events for xAPI statements
Widget may emit custom experience events that report interactions with the widget.
Slots
Slots are elements inside the widget's shadow tree in which content can be placed. This allows for a nesting of elements in WebWriter. Developers can specify the the allowed content of the slot with a content expression. The content expression is added as a custom JSDoc annotation on the component.
Parts & CSS variables
Parts and CSS variables enable styling the internals of the widget by WebWriter or developed stylesheets. Developers can annotate CSS variables with a CSS type that enables WebWriter to generate a widget allowing the user to manipulate the CSS variable. For example, the widget may have a --canvas-color variable that is of the CSS type <color>, allowing authors to use a color picker to choose a color.
Themes
Themes are stylesheets intended to be applied to the whole explorable.
Snippets
Snippets are arbitrary HTML fragments to be inserted into the explorable.
Package & Widget Concept
Phases
Structure
A package is a set of elements to be used in WebWriter, implemented by a developer. It contains several parts with a
package.jsonfile serving as the entrypoint. It should follow NPM's conventions to provide metadata for the widget package. Specifically, these rules apply:nameMUST be present. The name MUST be scoped (in the form@{SCOPE}/{NAME}).versionMUST be present. It MUST follow the syntax of SemVer and SHOULD follow the conventions laid out with SemVer.exportsMUST be present. It MUST contain a record mapping identifiers of the pattern{TYPE}/{ID}to relative paths of source files.{TYPE}MUST be one ofthemes,utilities,snippetsorwidgets.{ID}MUST be a sequence of lowercase, URL-safe characters.{TYPE}iswidgets,{ID}MUST follow the form{SCOPE}-{ELEMENT}, where{SCOPE}is the package scope and{ELEMENT}is a string such that{SCOPE}-{ELEMENT}is a valid custom element identifier. The file referenced MUST be a JavaScript or TypeScript file that registers a custom element of the same name{SCOPE}-{ELEMENT}withwindow.customElements.define{TYPE}issnippets,{ID}MAY be a string such thatwidgets/{ID}is also defined inexports.{TYPE}isthemes, the file referenced MUST be a CSS file.editingConfigMAY be present. It MUST be an object where each key is also present inexports, and each value is an object providing editing settings depending on{TYPE}Elements
Widgets
Widgets are interactive elements visible to both authors and users.
Custom Elements Manifest (CEM) is a way to describe custom elements, adding metadata. For WebWriter, this could serve several functions.The
@custom-elements-manifest/analyzerlibrary is useful for this - During widget development, this can be run when neccessary.Attributes & Events
Attributes represent the permanent state of the widget. WebWriter tracks changes in attributes and is able to undo/redo them. For non-permanent state, properties should be used. Attributes of the widget and events that may be emitted can be annotated for purposes of documentation.
Supported attributes & events
class- State of the editorww-beforeprint: Before printing, this class is set, allowing widgets to change their presentation to be print-ready.contenteditable- Differentiate author and user behaviorThe value
contenteditable="true"is set when editing, allowing widgets to provide affordances to authors change their state.lang- Language for localizationWebWriter sets the user's chosen document language on each widget during editing as the
langattribute. The widget should process the set locale and change its presentation accordingly.@experience- Custom events for xAPI statementsWidget may emit custom
experienceevents that report interactions with the widget.Slots
Slots are elements inside the widget's shadow tree in which content can be placed. This allows for a nesting of elements in WebWriter. Developers can specify the the allowed content of the slot with a content expression. The content expression is added as a custom JSDoc annotation on the component.
Parts & CSS variables
Parts and CSS variables enable styling the internals of the widget by WebWriter or developed stylesheets. Developers can annotate CSS variables with a CSS type that enables WebWriter to generate a widget allowing the user to manipulate the CSS variable. For example, the widget may have a
--canvas-colorvariable that is of the CSS type<color>, allowing authors to use a color picker to choose a color.Themes
Themes are stylesheets intended to be applied to the whole explorable.
Snippets
Snippets are arbitrary HTML fragments to be inserted into the explorable.