@lrnwebcomponents/hax-body-behaviors
Advanced tools
@lrnwebcomponents/hax-body-behaviors - npm Package Compare versions
Comparing version 0.0.33 to 0.0.34
@@ -6,4 +6,132 @@ /** | ||
| import { dom } from "@polymer/polymer/lib/legacy/polymer.dom.js"; | ||
| /** | ||
| * In order to use this, the user must supply a haxProperties object | ||
| * which returns what settings are allowed as well as their format. | ||
| * For example, the default of: | ||
| * | ||
| * { | ||
| * 'api': '1', | ||
| * 'canScale': true, | ||
| * 'canPosition': true, | ||
| * 'canEditSource': true, | ||
| * 'gizmo': {}, | ||
| * 'settings': { | ||
| * 'quick': [], | ||
| * 'configure': [], | ||
| * 'advanced': [], | ||
| * }, | ||
| * 'saveOptions': {} | ||
| * } | ||
| * | ||
| * This tells hax-body's context menu for custom-elements that this element | ||
| * can use the scaling widget and the positioning widget as well as have a traditional source editor view when in an advanced form. | ||
| * | ||
| * So now you're probably saying 'What's a gizmo???'. Well, gizmo is what we call widgets or custom-elements when an end user of HAX places them in the page. It's our playful way of explaining what's happening to an end user as well as ensuring when developers talk to each other then don't use words that have duplicate meanings. It's also just a fun word. | ||
| * A gizmo helps describe the element to the HAX Gizmo manager so that a user can select the element they want to place in the page. Think of your custom-element as an app in an app store. Well, how would you describe your 'app' or Gizmo to a store of apps (in our case the Gizmo manager). | ||
| * | ||
| * This is an example of th gizmo object that is expressed in the lrn-table tag: | ||
| * 'gizmo': { | ||
| * 'title': 'CSV Table', | ||
| * 'descrption': 'This can generate a table from a CSV file no matter where it is located.', | ||
| * 'icon': 'editor:border-all', | ||
| * 'color': 'green', | ||
| * 'groups': ['Presentation', 'Table', 'Data'], | ||
| * 'handles': [ | ||
| * { | ||
| * 'type': 'data', | ||
| * 'url': 'csvFile' | ||
| * } | ||
| * ], | ||
| * 'meta': { | ||
| * 'author': 'LRNWebComponents' | ||
| * } | ||
| * }, | ||
| * | ||
| * Groups is like a filter that someone could search amongst dozens of gizmos for the type of one they are looking for. So if you said your gizmo is for presenting video then you could tag it as Video and people looking for ways to present videos could filter by just Video gizmos. | ||
| * handles has to do with hax-sources of gizmos (think remote app stores you are searching to bring in an app if that was even possible in cell phones);. This says that if a gizmo source claims to be able to supply 'data', that lrn-table is able to handle data and that the property to map to when producing a haxElement is called csvFile. If only 1 handler exists for a response type from a source then it'll auto select it, otherwise the user will have the option of which custom element / gizmo they want to use to render that source material. | ||
| * meta is typical meta data, these things will be printed in a table in the event anyone wants to see them. Author is a logical one so people know who an element came from; like if you wanted to have a core gizmo's vs 3rd party gizmo's concept. | ||
| * | ||
| * Other settings can be expressed through beyond these simple layout modifiers. | ||
| * This example illustrates how you can show forms in three different areas of HAX. | ||
| * Items in the 'quick' key group means that it would show up in hax's in-place editor | ||
| * on the context menu. Things keyed with 'configure' show up in a | ||
| * form / preview display mode in a modal above the interface. Things in 'advanced' will | ||
| * show up on a sub-set of the configure form for more advanced operations. | ||
| * 'settings': { | ||
| * 'quick': [ | ||
| * { | ||
| * 'property': 'responsive', | ||
| * 'title': 'Responsive', | ||
| * 'description': 'The video automatically fills the available area.', | ||
| * 'inputMethod': 'boolean', | ||
| * 'icon': 'video' | ||
| * } | ||
| * ], | ||
| * 'configure': [ | ||
| * { | ||
| * 'property': 'citation', | ||
| * 'title': 'Citation', | ||
| * 'description': 'Proper MLA or other standard citation format for the image.', | ||
| * 'inputMethod': 'textfield', | ||
| * 'icon': 'text-format', | ||
| * 'required': true | ||
| * }, | ||
| * { | ||
| * 'property': 'responsive', | ||
| * 'title': 'Responsive', | ||
| * 'description': 'The video automatically fills the available area.', | ||
| * 'inputMethod': 'boolean', | ||
| * 'icon': 'video' | ||
| * } | ||
| * ], | ||
| * 'advanced': [ | ||
| * { | ||
| * 'slot': 'area1', | ||
| * 'title': 'Section 1', | ||
| * 'description': 'Content that goes in the fist area in the layout.', | ||
| * 'inputMethod': 'textarea', | ||
| * 'icon': 'layout' | ||
| * } | ||
| * ] | ||
| * } | ||
| * `saveOptions` is a more open ended object which can be used to help | ||
| * support future flexibility / needs. The first major thing this supports | ||
| * is the wipeSlot flag (default false). wipeSlot is used to inform HAX | ||
| * that when it's going to save the current item to a backend (convert to html / text) | ||
| * that it needs to first wipe out the contents of the element. This is not a common | ||
| * operation but useful for things like tokens and other tags that leverage slot | ||
| * in order to present information but should not be saving that information | ||
| * to a backend. Elements that dynamically pull content from an end point are | ||
| * the perfect example of when you'd want to wipe the slot. A content element | ||
| * like a block-quote tag which uses slot to allow users to write whatever | ||
| * they want inside the tag would NOT want to use this, otherwise the contents | ||
| * would be lost. | ||
| * Another used saveOption is `unsetAttributes`. `unsetAttributes` is an Array | ||
| * which can be used to tell a hax-body save operation to NOT save certain | ||
| * attributes. The form of these is in the html style, NOT the javascript | ||
| * style of attribute definition. In this way, you can define non property | ||
| * based values that you require not saving. For example, the following | ||
| * would be a valid use of `unsetAttributes`: | ||
| * 'saveOptions': { | ||
| * 'unsetAttributes': [ | ||
| * 'displayed-answers', | ||
| * 'data-some-value', | ||
| * 'id', | ||
| * 'colors' | ||
| * ] | ||
| * }, | ||
| * | ||
| * Specialized functions | ||
| * `preProcessHaxNodeToContent` - If you define this function on your element | ||
| * then it will run BEFORE the conversion to text. This can be used to do | ||
| * specialized processing that may not be standard prior to conversion to content. | ||
| * | ||
| * `postProcesshaxNodeToContent` - If you define this function on your element | ||
| * then it will run AFTER the node has been converted to Content and allows you | ||
| * to act upon the content even further. This could be to clean up / regex against | ||
| * the text certain patterns or to look for certain elements at the end of | ||
| * the conversion routine. | ||
| * | ||
| */ | ||
| /** | ||
| * Object to validate HAX | ||
@@ -228,3 +356,3 @@ */ | ||
| console.warn( | ||
| "This is't a valid usage of hax-body-behaviors API. See hax-body-behaviors for more details on how to implement the API. Most likely your hax item just was placed in an iframe as a fallback as opposed to a custom element." | ||
| "This is't a valid usage of hax API. See hax-body-behaviors/lib/HAXWiring.js for more details on how to implement the API. Most likely your hax item just was placed in an iframe as a fallback as opposed to a custom element." | ||
| ); | ||
@@ -231,0 +359,0 @@ } |
@@ -14,3 +14,3 @@ { | ||
| }, | ||
| "version": "0.0.33", | ||
| "version": "0.0.34", | ||
| "description": "Wire any element up to HAX", | ||
@@ -42,3 +42,3 @@ "repository": { | ||
| "devDependencies": { | ||
| "@lrnwebcomponents/deduping-fix": "^0.0.33", | ||
| "@lrnwebcomponents/deduping-fix": "^0.0.34", | ||
| "@polymer/iron-component-page": "github:PolymerElements/iron-component-page", | ||
@@ -59,3 +59,3 @@ "@polymer/iron-demo-helpers": "3.0.2", | ||
| }, | ||
| "gitHead": "3765fe3f5c9ee9b0e3e20ace85862d34b8113dd6" | ||
| "gitHead": "85bf1e684f0f88c1ce807c92255af222057eeaa0" | ||
| } |
323
README.md
@@ -7,17 +7,320 @@ # <hax-body-behaviors> | ||
| ## Usage | ||
| To use this web component in your project you can utilize one of the following styles of syntax. | ||
| [Video showing how we integrate HAX with elements](https://www.youtube.com/watch?v=P-ZA4CQASpY&index=1&list=PLJQupiji7J5eTqv8JFiW8SZpSeKouZACH) | ||
| HAX body behaviors provide a consistent way to rapidly wire Polymer elements up to HAX. While anything can talk to HAX via consistent property and event usage, these body behaviors reduce the time and increase accuracy when trying to wire to HAX (drastically). | ||
| The major is in HAX Schema defintion which can be translated to JSON Schema with a single function. This allows for rapidly building out headless "forms" in HAX while the elements themselves just define the JSON blob as to how it should function and what should be wired where. It's more complicated then it sounds. | ||
| ## Examples | ||
| For full documentation just open the `lib/HAXWiring.js` file as it's got a lot of documentation but here's the relevent parts from [example-hax-element](https://github.com/elmsln/lrnwebcomponents/tree/master/elements/example-hax-element/example-hax-element.js). | ||
| ```js | ||
| /* In an existing module / web component */ | ||
| import '@lrnwebcomponents/hax-body-behaviors.js'; | ||
| /* At top of an application */ | ||
| <script type="module" src="hax-body-behaviors.js"></script> | ||
| /* Alternatives for top of application */ | ||
| <script type="module"> | ||
| import '@lrnwebcomponents/hax-body-behaviors.js'; | ||
| import {HaxBodyBehaviors} from '@lrnwebcomponents/hax-body-behaviors'; | ||
| </script> | ||
| import { HAXWiring } from "@lrnwebcomponents/hax-body-behaviors/lib/HAXWiring.js"; | ||
| class ExampleHaxElement extends HTMLElement { | ||
| ... | ||
| // haxProperty definition | ||
| static get haxProperties() { | ||
| return { | ||
| canScale: true, | ||
| canPosition: true, | ||
| canEditSource: false, | ||
| gizmo: { | ||
| title: "Example hax-element", | ||
| description: | ||
| "Provide an example to pick apart of a working HAX element", | ||
| icon: "icons:android", | ||
| color: "green", | ||
| groups: ["Hax"], | ||
| handles: [ | ||
| { | ||
| type: "todo:read-the-docs-for-usage" | ||
| } | ||
| ], | ||
| meta: { | ||
| author: "You", | ||
| owner: "Your Company" | ||
| } | ||
| }, | ||
| settings: { | ||
| quick: [], | ||
| configure: [ | ||
| { | ||
| property: "title", | ||
| description: "", | ||
| inputMethod: "textfield", | ||
| required: false, | ||
| icon: "icons:android" | ||
| }, | ||
| { | ||
| property: "available", | ||
| description: "", | ||
| inputMethod: "boolean", | ||
| required: false, | ||
| icon: "icons:android" | ||
| } | ||
| ], | ||
| advanced: [] | ||
| } | ||
| }; | ||
| } | ||
| // properties available to the custom element for data binding | ||
| static get properties() { | ||
| return { | ||
| title: { | ||
| name: "title", | ||
| type: "String", | ||
| value: "My Example" | ||
| }, | ||
| available: { | ||
| name: "available", | ||
| type: "Boolean", | ||
| value: "" | ||
| } | ||
| }; | ||
| } | ||
| /** | ||
| * life cycle, element is afixed to the DOM | ||
| */ | ||
| connectedCallback() { | ||
| this.HAXWiring = new HAXWiring(); | ||
| this.HAXWiring.setHaxProperties( | ||
| ExampleHaxElement.haxProperties, | ||
| ExampleHaxElement.tag, | ||
| this | ||
| ); | ||
| } | ||
| ... | ||
| ``` | ||
| Here's a much more complex example from a Polymer Legacy style element who calls attached when it is fixed to the DOM (`video-player/video-player.js`): | ||
| ``` | ||
| /** | ||
| * Attached. | ||
| */ | ||
| attached: function() { | ||
| // Establish hax properties if they exist | ||
| let props = { | ||
| canScale: true, | ||
| canPosition: true, | ||
| canEditSource: false, | ||
| gizmo: { | ||
| title: "Video player", | ||
| description: | ||
| "This can present video in a highly accessible manner regardless of source.", | ||
| icon: "av:play-circle-filled", | ||
| color: "red", | ||
| groups: ["Video", "Media"], | ||
| handles: [ | ||
| { | ||
| type: "video", | ||
| source: "source", | ||
| title: "caption", | ||
| caption: "caption", | ||
| description: "caption", | ||
| color: "primaryColor" | ||
| } | ||
| ], | ||
| meta: { | ||
| author: "LRNWebComponents" | ||
| } | ||
| }, | ||
| settings: { | ||
| quick: [ | ||
| /*{ | ||
| 'property': 'responsive', | ||
| 'title': 'Responsive', | ||
| 'description': 'The video automatically fills the available area.', | ||
| 'inputMethod': 'boolean', | ||
| 'icon': 'image:photo-size-select-small', | ||
| },*/ | ||
| { | ||
| property: "accentColor", | ||
| title: "Accent color", | ||
| description: "Select the accent color for the player.", | ||
| inputMethod: "colorpicker", | ||
| icon: "editor:format-color-fill" | ||
| }, | ||
| { | ||
| property: "dark", | ||
| title: "Dark theme", | ||
| description: "Enable dark theme for the player.", | ||
| inputMethod: "boolean", | ||
| icon: "invert-colors" | ||
| } | ||
| ], | ||
| configure: [ | ||
| { | ||
| property: "source", | ||
| title: "Source", | ||
| description: "The URL for this video.", | ||
| inputMethod: "textfield", | ||
| icon: "link", | ||
| required: true, | ||
| validationType: "url" | ||
| }, | ||
| { | ||
| property: "track", | ||
| title: "Closed captions", | ||
| description: "The URL for the captions file.", | ||
| inputMethod: "textfield", | ||
| icon: "link", | ||
| required: true, | ||
| validationType: "url" | ||
| }, | ||
| { | ||
| property: "thumbnailSrc", | ||
| title: "Thumbnail image", | ||
| description: "Optional. The URL for a thumbnail/poster image.", | ||
| inputMethod: "textfield", | ||
| icon: "link", | ||
| required: true, | ||
| validationType: "url" | ||
| }, | ||
| { | ||
| property: "mediaTitle", | ||
| title: "Title", | ||
| description: "Simple title for under video", | ||
| inputMethod: "textfield", | ||
| icon: "av:video-label", | ||
| required: false, | ||
| validationType: "text" | ||
| }, | ||
| { | ||
| property: "accentColor", | ||
| title: "Accent color", | ||
| description: "Select the accent color for the player.", | ||
| inputMethod: "colorpicker", | ||
| icon: "editor:format-color-fill" | ||
| }, | ||
| { | ||
| property: "dark", | ||
| title: "Dark theme", | ||
| description: "Enable dark theme for the player.", | ||
| inputMethod: "boolean", | ||
| icon: "invert-colors" | ||
| } | ||
| ], | ||
| 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" | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| }; | ||
| this.setHaxProperties(props); | ||
| }, | ||
| ``` | ||
| ## Develop | ||
@@ -24,0 +327,0 @@ |
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by29.77%
264188
- Number of package files
- increased by3.45%
30
- Lines of code
- increased by4.51%
3037
- Number of lines in readme file
- increased by488.71%
365
No dependency changes