basic-wrapped-standard-element
v0.8.0
Published
Wraps a standard HTML element so that the standard behavior can then be extended.
Downloads
10
Readme
API Documentation
WrappedStandardElement ⇐ ElementBase
Wraps a standard HTML element so that the standard behavior can then be extended.
See also basic-autosize-textarea and
basic-current-anchor. The former uses
WrappedStandardElement to wrap a standard <textarea> and <a>,
respectively.
The Custom Elements spec does not currently (as of March 2016) allow you to
extend the behavior of a standard HTML element like <a> or <button>.
As a partial workaround, the WrappedStandardElement class can create a class
for you that wraps an instance of a standard HTML element. For example, the
code below creates a class that will wrap an instance of a standard <a>
element:
class WrappedA extends WrappedStandardElement.wrap('a') {
customMethod() { ... }
}
document.registerElement('wrapped-a', WrappedA);An instance of the resulting class will look to the user like an instance of
the standard element class it wraps. The resulting class will not be an
instanceof the standard class (here, HTMLAnchorElement). Another limitation
is that the resulting <wrapped-a> will not automatically pick up CSS styles
for standard <a> elements. However, the resulting class can be extended.
E.g., instances of the above class have a customMethod() available to them.
Any properties defined by the original standard element will be exposed on the resulting wrapper class, and calls to get or set those properties will be delegated to the wrapped element instance. Continuing the above example:
let wrapped = document.createElement('wrapped-a');
wrapped.href = 'http://example.com/';
wrapped.textContent = 'Click here';Here, the created custom <wrapped-a> element will contain inside its
shadow tree an instance of a standard <a> element. The call to set the
wrapper's href property will ultimately set the href on the inner link.
Moreover, the text content of the <wrapped-a> element will appear inside
the inner link. The result of all this is that the user will see what looks
like a normal link, just as if you had written
<a href="http://example.com/">Click here</a>. However, the actual element
will be an instance of your custom class, with whatever behavior you've
defined for it.
Wrapped elements should raise the same events as the original standard
elements. E.g., if you wrap an <img> element, the wrapped result will raise
the standard load event as expected.
Some elements, such as <body>, <html>, and <style> cannot be wrapped
and still achieve their standard behavior.
Kind: global class Extends: ElementBase
- WrappedStandardElement ⇐ ElementBase
- .ariaLabel : string
- .inner : HTMLElement
- .template : string | HTMLTemplateElement
- .wrap(extendsTag)
wrappedStandardElement.ariaLabel : string
A description for the user of the element's purpose on the page. Setting this applies the label to the inner element, ensuring that screen readers and other assistive technologies will provide a meaningful description to the user.
Kind: instance property of WrappedStandardElement
wrappedStandardElement.inner : HTMLElement
Returns a reference to the inner standard HTML element.
Kind: instance property of WrappedStandardElement
wrappedStandardElement.template : string | HTMLTemplateElement
The template copied into the shadow tree of new instances of this element.
The default value of this property is a template that includes an instance
the standard element being wrapped, with a <slot> element inside that
to pick up the element's light DOM content. For example, if you wrap an
<a> element, then the default template will look like:
<template>
<style>
:host {
display: inline-block;
}
</style>
<a id="inner">
<slot></slot>
</a>
</template>The display styling applied to the host will be block for elements that
are block elements by default, and inline-block (not inline) for other
elements.
If you'd like the template to include other elements, then override this property and return a template of your own. The template should include an instance of the standard HTML element you are wrapping, and the ID of that element should be "inner".
Kind: instance property of WrappedStandardElement
WrappedStandardElement.wrap(extendsTag)
Creates a class that wraps a standard HTML element.
Note that the resulting class is a subclass of WrappedStandardElement, not
the standard class being wrapped. E.g., if you call
WrappedStandardElement.wrap('a'), you will get a class whose shadow tree
will include an anchor element, but the class will not inherit from
HTMLAnchorElement.
Kind: static method of WrappedStandardElement
| Param | Type | Description | | --- | --- | --- | | extendsTag | string | the standard HTML element tag to extend |