In order for your element to talk to the HAX editor, you need to implement static get haxProperties()
on your element. This callback either returns a String
based location of where the HAXSchema lives OR the JSON blob directly. The appstore documentation page also describes how you can integrate without defining this directly on your element.
HAXSchema is the name of our standard for expressing the way HAX can communicate with and implement your web component. This is broken into two major groupings of settings and some basic Boolean
.
// can this item be scaled in the UI, will it have a slider for % width
canScale: true,
// can you position the item left or center justified
canPosition: true,
// can you edit the raw source of this element (future)
canEditSource: false
// design system integration including colors, spacing, font, other treatments
designSystem: {
accent: true,
primary: true,
card: true,
text: true,
designTreatment: true
}
After these Booleans we get into the "Gizmo" section. A Gizmo is what internal to the code base we're calling a custom element as it is represented in HAX interfaces like the Make
area. The reason for this is so that the word element isn't everywhere or else it would get too confusing. A Gizmo describes the way HAX should reference this item in interfaces.
gizmo: {
// title to display
title: "Example hax-element",
// description
description:
"Provide an example to pick apart of a working HAX element",
// icon to represent this in selection displays
icon: "icons:android",
// color to tint this when in displays
color: "green",
// grouping data for filtering in displays (future)
groups: ["Hax"],
// handlers allow HAX to stitch together sources of information with gizmos to render that information
// example: Youtube supplies a source value that points to a url of the video
// if the user picks a video from youtube, things that match
// 'video' as a type and then match on any 1 additional field
// will be presented to the user as the way to render the video
// in the case of YouTube this presents a video-player or QR code
// in default implementations with these tags.
// This is because the match is on source, which the key of source
// in the handles block => points to the property to insert into
// it is an array of objects so you can map to multiple types
// type is a reserved key and can be anything so long as
// a source of data is looking for something matching that "type"
handles: [
{
// what it can present
type: "video",
// the property coming from the app on the left => property in the element on the right
source: "source",
// this pulls the title off the API and sticks it in the caption field of the element
title: "caption",
// fallback matches
caption: "caption",
description: "caption",
// ability to pull color across though this would be rare from an API
color: "primaryColor"
}
],
// any metadata you wish to ship along
meta: {
author: "You",
owner: "Your Company"
}
},
Settings forms for HAX capable elements are grouped into three different areas. The quick
settings segment of the schema provides quick edit, singular properties on the UI as icons. This is present when you select an item in HAX (see screenshot).
settings: {
quick: [
{
property: "accentColor",
title: "Accent color",
description: "Select the accent color for the player.",
inputMethod: "colorpicker"
},
{
attribute: "dark",
title: "Dark theme",
description: "Enable dark theme for the player.",
inputMethod: "boolean"
}
],
The configure section shows up when moving on to the settings manager
After hitting settings, you'll see the manager open up defaulted to the configure settings display.
configure: [
{
property: "source",
title: "Source",
description: "The URL for this video.",
inputMethod: "textfield",
required: true,
validationType: "url"
},
{
property: "track",
title: "Closed captions",
description: "The URL for the captions file.",
inputMethod: "textfield",
required: true,
validationType: "url"
},
{
property: "thumbnailSrc",
title: "Thumbnail image",
description: "Optional. The URL for a thumbnail/poster image.",
inputMethod: "textfield",
required: true,
validationType: "url"
},
{
property: "mediaTitle",
title: "Title",
description: "Simple title for under video",
inputMethod: "textfield",
required: false,
validationType: "text"
},
{
property: "accentColor",
title: "Accent color",
description: "Select the accent color for the player.",
inputMethod: "colorpicker"
},
{
attribute: "dark",
title: "Dark theme",
description: "Enable dark theme for the player.",
inputMethod: "boolean"
}
],
The advanced section shows up when in the configuration manager is open and the user selects Advanced
advanced: [
{
property: "darkTranscript",
title: "Dark theme for transcript",
description: "Enable dark theme for the transcript.",
inputMethod: "boolean"
},
{
property: "hideTimestamps",
title: "Hide timestamps",
description: "Hide the time stamps on the transcript.",
inputMethod: "boolean"
},
{
property: "preload",
title: "Preload source(s).",
description:
"How the sources should be preloaded, i.e. auto, metadata (default), or none.",
inputMethod: "select",
options: {
preload: "Preload all media",
metadata: "Preload media metadata only",
none: "Don't preload anything"
}
},
{
property: "stickyCorner",
title: "Sticky Corner",
description:
"Set the corner where a video plays when scrolled out of range, or choose none to disable sticky video.",
inputMethod: "select",
options: {
none: "none",
"top-left": "top-left",
"top-right": "top-right",
"bottom-left": "bottom-left",
"bottom-right": "bottom-right"
}
},
{
property: "sources",
title: "Other sources",
description: "List of other sources",
inputMethod: "array",
properties: [
{
property: "src",
title: "Source",
description: "The URL for this video.",
inputMethod: "textfield"
},
{
property: "type",
title: "Type",
description: "Media type data",
inputMethod: "select",
options: {
"audio/aac": "acc audio",
"audio/flac": "flac audio",
"audio/mp3": "mp3 audio",
"video/mp4": "mp4 video",
"video/mov": "mov video",
"audio/ogg": "ogg audio",
"video/ogg": "ogg video",
"audio/wav": "wav audio",
"audio/webm": "webm audio",
"video/webm": "webm video"
}
}
]
},
{
property: "tracks",
title: "Track list",
description: "Tracks of different languages of closed captions",
inputMethod: "array",
properties: [
{
property: "kind",
title: "Kind",
description: "Kind of track",
inputMethod: "select",
options: {
subtitles:
"subtitles" /*,
Future Features
'description': 'description',
'thumbnails': 'thumbnails',
'interactive': 'interactive',
'annotation': 'annotation'*/
}
},
{
property: "label",
title: "Label",
description:
'The human-readable name for this track, eg. "English Subtitles"',
inputMethod: "textfield"
},
{
property: "src",
title: "Source",
description: "Source of the track",
inputMethod: "textfield"
},
{
property: "srclang",
title:
'Two letter, language code, eg. \'en\' for English, "de" for German, "es" for Spanish, etc.',
description: "Label",
inputMethod: "textfield"
}
]
}
]
}