Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
1403 lines (950 sloc) 42.7 KB

Classes

ZephComponent
ZephObserver
ZephService

Objects

ZephUtils : object
ZephComponents : object

Functions

from(fromTagName)void
alias(aliasName)void
html(content, [options])void
css(content, [options])void
asset(selector, url, [options])void
attribute(attributeName, initialValue)void
property(propertyName, initialValue, transformFunction)void
binding(sourceName, targetElement, targetName, transformFunction)void
bindingAt(sourceElement, sourceName, targetElement, targetName, transformFunction)void
onInit(listener)void
onCreate(listener)void
onAdd(listener)void
onRemove(listener)void
onAdopt(listener)void
onAttribute(attributeName, listener)void
onProperty(propertyName, listener)void
onEvent(eventName, listener)void
onEventAt(selector, eventName, listener)void

ZephComponent

Kind: global class
Summary: ZephJS's representation of a component and all its descriptive metadata. This include the component name, its origin, the definition code, and the context produce by executing the definition code. All of these items are used to generate a unique Class which is used in by the Custom Elements registry.

It should be noted that this is not the same as the Element produced when using a component as an HTML tag or from document.createElement(). ZephComponent is the definition of that element, not the element itself.

ZephCompoonent is returned when you ask ZephComponents to get the component.


zephComponent.context ⇒ Object

The context object that was built by executing the component definition. Depending on when this member is examined, the context might be very simple or very complex; it depends on whether or not the ZephComponent has been "defined". Prior to being "defined" the definition code has not yet been executed and thus the context will have very little in it. Once "defined" the code will have been executed and the resulting context populated.

This is an object with a number of highly specialized fields that are used when the element is created. As such, changing it is not allowed.

Kind: instance property of ZephComponent


zephComponent.name ⇒ String

The name of the component, which is also the tag-name used in HTML for the component.

Kind: instance property of ZephComponent


zephComponent.origin ⇒ String

The origin, in string form, of where the component was defined, or the best guess as to where that is. Origin is not always going to be super accurate, but its tries its best.

Kind: instance property of ZephComponent


zephComponent.code ⇒ String | function

The code that is to be or was executed for this component when defined. This will either be a string or a Function, depending on what was passed to the define method.

Kind: instance property of ZephComponent


zephComponent.defined ⇒ boolean

Returns true if the ZephComponent was "defined" and has a registered custom element class.

Kind: instance property of ZephComponent


zephComponent.customElementClass ⇒ ZephElementClass

Returns the custom element class that was used to register the component with the CustomElements registry.

Kind: instance property of ZephComponent


zephComponent.define() ⇒ Promise

Executes the code, which in turn builds the context, which is given to ZephElementClass.generateClass() to generate a unique class representation for this component. This class is then used along with the name, to register the custom element.

Kind: instance method of ZephComponent


ZephObserver

Kind: global class
Summary: Utility wrapper class for observing an element for changes. This uses the MutationObserver API internally and is largely just a shell for it.


new ZephObserver(element)

Create an Element Observer for a given element. This does not actually start the observation, just sets it up. You must call start() to begin the observation.

Param Type
element HTMLElement

zephObserver.addAttributeObserver(attribute, handler) ⇒ void

Adds a handler to fire on an attribute change.

Kind: instance method of ZephObserver

Param Type
attribute string
handler function

zephObserver.removeAttributeObserver(attribute, handler) ⇒ void

Removes a specific attribute handler.

Kind: instance method of ZephObserver

Param Type
attribute String
handler function

zephObserver.removeAllAttributeObservers(attribute) ⇒ void

Removes all attribute handlers.

Kind: instance method of ZephObserver

Param Type
attribute String

zephObserver.addContentObserver(handler) ⇒ void

Adds a handler to fire on any content change.

Kind: instance method of ZephObserver

Param Type
handler function

zephObserver.removeContentObserver(handler) ⇒ void

Removes a specific content handler.

Kind: instance method of ZephObserver

Param Type
handler function

zephObserver.removeAllContentObservers() ⇒ void

Remove all content handlers.

Kind: instance method of ZephObserver


zephObserver.start() ⇒ void

Start the observer watching the element.

Kind: instance method of ZephObserver


zephObserver.stop() ⇒ void

Stop the observer watching the element.

Kind: instance method of ZephObserver


zephObserver.handleMutation(records) ⇒ void

Function to read the mutation event and parcel it out to the correct handlers.

Kind: instance method of ZephObserver

Param Type
records Array

zephObserver.handleAttributeMutation(record) ⇒ void

Executes the apropriate attribute handlers.

Kind: instance method of ZephObserver

Param Type
record Object

zephObserver.handleContentMutation(record) ⇒ void

Executes the appropriate content handlers.

Kind: instance method of ZephObserver

Param Type
record Object

ZephService

Kind: global abstract class
Summary: ZephService is a utility class you can inherit from to build an eventable service, that is a service that can fire events.


new ZephService()

Create a new service.


zephService.fire(event, ...args) ⇒ void

Fire a specific event.

Kind: instance method of ZephService

Param Type
event String
...args *

zephService.addEventListener(event, listener)

Register a listener for a specific event.

Kind: instance method of ZephService

Param Type
event String
listener function

zephService.removeEventListener(event, listener) ⇒ void

Remove a listener for a specific event.

Kind: instance method of ZephService

Param Type
event String
listener function

zephService.on(event, listener) ⇒ void

Register a listener for a specific event. Same as addEventListener.

Kind: instance method of ZephService

Param Type
event String
listener function

zephService.once(event, listener) ⇒ void

Registers a one time listener for a specific event.

Kind: instance method of ZephService

Param Type
event String
listener function

zephService.off(event, listener) ⇒ void

Remove a listener for a specific event. Same as removeEventListener.

Kind: instance method of ZephService

Param Type
event String
listener function

ZephUtils : object

Kind: global namespace
Summary: Common utilities for working with ZephJS.


ZephUtils.ready() ⇒ boolean

Returns true if ZephJS is in the "ready" state. ZephJS is in the "ready" state if ZephJS is loaded and all ZephComponents.define() methods are believed to be complete.

Kind: static method of ZephUtils


ZephUtils.tryprom(f) ⇒ Promise

A utility function to execute the given function f in the context of a nice clean try/catch block. This really is here just to save a bunch of characters in ZephJS when minimized.

Kind: static method of ZephUtils

Param Type
f function

ZephUtils.exists(url) ⇒ Promise

Performs a HEAD fetch request to determine if a given URL "exists". Returns a promise that will resolve to true or false depending on the result.

Kind: static method of ZephUtils

Param Type
url URL

ZephUtils.fetch(url) ⇒ Promise

A simplified fetch wrapper.

Kind: static method of ZephUtils

Param Type
url URL

ZephUtils.fetchText(url) ⇒ Promise

Fetch but also resolves the content as plaintext. Useful for reading HTML and CSS files.

Kind: static method of ZephUtils

Param Type
url URL

ZephUtils.fetchBinary(url) ⇒ Promise

Fetch but also resolves the content as binary. Useful for reading Images, audio, video, etc. Returns an object which contains the data and the contentType.

Kind: static method of ZephUtils

Param Type
url URL

ZephUtils.resolve(url, [base]) ⇒ URL

Given some URL resolves it against a base url to ensure correct pathing.

Kind: static method of ZephUtils

Param Type Default
url URL
[base] URL document.URL

ZephUtils.resolveName(url, [base], [extension]) ⇒ Promise

Given a simple name, resolve it against a base URL and then find out if it exists or not. ZephJS uses this to determine where something are located. This can produce upwards of four separate network requests. However, ZephJS only tries that if absolutely necessary.

Kind: static method of ZephUtils

Param Type Default
url URL
[base] URL document.URL
[extension] String ".js"

ZephUtils.parseDataURL(url) ⇒ Object

Given some data: url this function returns the contentType and data from that url.

Kind: static method of ZephUtils

Param Type
url URL

ZephComponents : object

Kind: global namespace
Summary: Define the ZephComponents singleton which is our exposed API for defining new components.


zephComponents.components ⇒ Array

Returns an array of all components defined with ZephJS.

Kind: instance property of ZephComponents


zephComponents.names ⇒ Array

Returns an array of all component names defined with ZephJS.

Kind: instance property of ZephComponents


zephComponents.has(name) ⇒ Boolean

Returns true if a component of a given name is already defined or in the process of being defined.

Kind: instance method of ZephComponents

Param Type
name String

zephComponents.get(name) ⇒ ZephComponent

Returns the ZephComponent for a component of the given name, if the component has been registered.

Kind: instance method of ZephComponents

Param Type
name String

zephComponents.waitFor(name) ⇒ Promise

Returns a promise that resolve when the component of the given name completes its definition and registration process. This is useful to ensure that component XYZ exists and is avialable before going off and doing something. Most of the time this is unneceessary and ZephJS will take care of it.

Kind: instance method of ZephComponents

Param Type
name String

zephComponents.define(name, code) ⇒ Promise

Used to define a new ZephJS component of the given name with the given definition.

Component names must be strings and must have at least one dash character within them.

The code argument represents a function that within it defines the component through the use of one or more definition methods.

The code argument has the signature

	`(methods) => {}`

where methods is an object which contains all of the definition methods one can use within a definition function. This is provided for developers who would prefer to access the definition methods via destructuring in the definition argument rather than importing each with an import statement. Either approach is valid and both can be used interchangable:

```javascript
import {ZephComponents} from "./zeph.min.js";

ZephComponents.define("my-button",({html,css,attribute})=>{
	html("./my-button.html");
	css("./my-button.css");

	attribute("icon","");
});
```

This returns a promise that will resolve when all of the definition and registration is complete. In most cases waiting for the promise to resolve is unnecessary, but it is provided in case you need to block until it is complete.

Kind: instance method of ZephComponents

Param Type
name String
code String | function

zephComponents.undefine(name) ⇒ void

Removes a ZephJS component. It is very important to note here that the Custom Elements API does not provide a facility to unregister a component once it has been registered. This function then does not actually remove the component, only ZephJS's awareness of it.

Kind: instance method of ZephComponents

Param Type
name String

from(fromTagName) ⇒ void

Kind: global function
Summary: Definition Method used for inheriting from another ZephComponent. Inheritence works by cloning the inherited components Context, and then appending the new components context on top of that. Inheritence does not actually inherit in the classic object oriented approach.

Param Type
fromTagName String

alias(aliasName) ⇒ void

Kind: global function
Summary: Definition Method used to provide one or more alias names for a componet. In essence, when the component is registered with the Custome Element registry, if there are any aliases, those names are also registered at the same time using a clone of the original method.

Aliases are useful if you need a component to have multiple tag names or shortcut names.

Param Type
aliasName String

html(content, [options]) ⇒ void

Kind: global function
Summary: Definition Method to provide HTML content to a component when it is created. The HTML provided becomes the content of the new element's Shadow DOM (and is refered to through this documentation as "the content").

The html() Definition Method can take either a url or relative filename or the actual HTML as string content. if a url or relative filename is given, ZephJS will download that url content, if possible, and use that as the content. This allows developers to separate thier HTML from the Component Definition JavaScript.

Each call to the html() Definition Method will be appended together to form a single block of HTML content. However, you may specify the option "overwrite" in the options object as "true" and the html() definition methods, to that point, will be overwritten by the given content. (It should be noted that subsequent html() calls after and overwrite are appended to the overwrite content.)

Another option "noRemote" if set to true, will prevent ZephJS from downloading the html() content if it is a valid url or relative filename and just treat it like a literal content string. This can be useful as sometimes ZephJS does not always know the difference between referenced content and literal content and may try to guess and load things that dont exist.

Param Type Default
content string
[options] Object {}
[options.overwrite] boolean false
[options.noRemote] boolean false

css(content, [options]) ⇒ void

Kind: global function
Summary: Definition Method to provide CSS content to a component when it is created. The CSS provided becomes a <style></style> element within the new element's Shadow DOM.

The css() Definition Method can take either a url or relative filename or the actual CSS as string content. if a url or relative filename is given, ZephJS will download that url content, if possible, and use that as the content. This allows developers to separate thier CSS from the Component Definition JavaScript.

Each call to the css() Definition Method will be appended together to form a single block of CSS content. However, you may specify the option "overwrite" in the options object as "true" and the css() definition methods, to that point, will be overwritten by the given content. (It should be noted that subsequent css() calls after and overwrite are appended to the overwrite content.)

Another option "noRemote" if set to true, will prevent ZephJS from downloading the css() content if it is a valid url or relative filename and just treat it like a literal content string. This can be useful as sometimes ZephJS does not always know the difference between referenced content and literal content and may try to guess and load things that dont exist.

Param Type Default
content string
[options] Object {}
[options.overwrite] boolean false
[options.noRemote] boolean false

asset(selector, url, [options]) ⇒ void

Kind: global function
Summary: Definition Method to associate some external asset like an image, audio clip, or video, with some element within the components internal content.

In order for asset() to assoicate you must provide both the CSS Query Selector you want to associate to, and a url or filename to the external asset you want associated.

The association is done by converting the asset into its base64 encoded binary data and making it part of a data: url. This url is then associated with the appropriate src attribute on the selected elements. (The associating attribute can be changed with the target option.)

asset() is really powerful for bundling purposes as the CLI bundle command will download the asset and inline the content as a data: url this allowing one to ship both the component and its dependant resources.

It should be noted, however, that using this approach can explode your asset sizes by up to 4 times and is not recommended in all scenarios.

Param Type Default
selector string
url string
[options] Object {}
[options.target] boolean false

attribute(attributeName, initialValue) ⇒ void

Kind: global function
Summary: Definition Method to define an attribute on the new element. This method takes the attribute name and an initial value (or "undefined" if no value specified.)

Using this method to define an attribute is strictly optional, but it will save having to buildout an onCreate() method and set attributes there.

The initial value passed in is set ONLY IF the element does not already have a value set for the attribute. Setting an initial value of "undefined" means that the attribute is actively removed from the element. Also, please note that attribute values are strings and any non-string passed in will be converted to a string. If you are trying to set a boolean attribute value like "disabled" which is present or not, but has no actual value, set it to an empty string ("") for true, and remove it ( by setting it to "undefined" for false.)

Param Type
attributeName string
initialValue *

property(propertyName, initialValue, transformFunction) ⇒ void

Kind: global function
Summary: Definition Method to create a new property on the element object. This method takes the property name, an initial value, and an optional transform function.

Using this method to define a property is strictly optional, but it will save having to buildout an onCreate() method and set properties there.

The initial value passed in is set ONLY IF the element does not already have a value set for the property.

The transform function, if given, will be executed any time the property is changed. It takes a single argument, x, which is the new value. Whatever it returns, will be what is set on the property. You can also through an exception in the transform function which would prevent the set from occuring; this can be useful in validation.

Param Type
propertyName string
initialValue *
transformFunction function

binding(sourceName, targetElement, targetName, transformFunction) ⇒ void

Kind: global function
Summary: Definition Method to bind one part of the new element or its content to some other part of the new element or its content. Bindings are a useful way to avoid having to write a lot of custom code to do some very common actions in custom elements. They are highly recommended over custom code.

Bindings work thusly:

I want to bind changes to X on element Y to modify A on element B.

X can be an attribute, property, or the content of element Y. Y can be the custom element itself or any part of its internal content.

A can be an attribute, property, or the content of element B. B can be the custom element itself or any part of its internal content.

With the bind() definition method, Y is always the custom element itself. With the bindAt() definition method, Y is specified by a CSS selector.

You specify X and A using a special syntax to tell ZephJS whether it is an attribute, a property, or the content that you are watching or modifying.

Attributes have the form "@" like this:

"@value"

Properties have the form "." like this:

".value"

Content has the form "$" and has nothing more to it:

"$"

You specify Y and B using a CSS Query Selector string. If you specify "." as the entirety of the CSS Query Selector string, ZephJS will return the custom element itself. Also, note that if the CSS Query Selector string matches multiple elements, all elements will be bound.

The bind() method has the following signature:

bind(sourceName,targetElement,targetName,transformFunction)

sourceName is the X from above; it identifies the attribute, property, or content you want to watch for changes. When the given attribute, property, or content changes, the binding will propagate the change to the target (A and B).

targetElement is the B from above an is a CSS Query Selector string. It may match multiple elements and if so, each becomes a target. If the string "." is used the target is the custom element itself.

targetName is the X from above; it identifies the attribute, property, or content you want to modify when a change occurs. targetName is optional and if left out the sourceName will also be used as the targetName, saving a little typing.

transformFunction is an optional function that if given will be executed when the change is triggered. It recieves the value being set and whatever it returns is set instead. Also, an exception thrown in the transformFunction will cause the binding to not set and thus prevent it.

Param Type
sourceName string
targetElement string
targetName string
transformFunction function

bindingAt(sourceElement, sourceName, targetElement, targetName, transformFunction) ⇒ void

Kind: global function
Summary: Definition Method to bind one part of the new element or its content to some other part of the new element or its content. Bindings are a useful way to avoid having to write a lot of custom code to do some very common actions in custom elements. They are highly recommended over custom code.

Bindings work thusly:

I want to bind changes to X on element Y to modify A on element B.

X can be an attribute, property, or the content of element Y. Y can be the custom element itself or any part of its internal content.

A can be an attribute, property, or the content of element B. B can be the custom element itself or any part of its internal content.

With the bind() definition method, Y is always the custom element itself. With the bindAt() definition method, Y is specified by a CSS selector.

You specify X and A using a special syntax to tell ZephJS whether it is an attribute, a property, or the content that you are watching or modifying.

Attributes have the form "@" like this:

"@value"

Properties have the form "." like this:

".value"

Content has the form "$" and has nothing more to it:

"$"

You specify Y and B using a CSS Query Selector string. If you specify "." as the entirety of the CSS Query Selector string, ZephJS will return the custom element itself. Also, note that if the CSS Query Selector string matches multiple elements, all elements will be bound.

The bindAt() method has the following signature:

bindAt(sourceElement,sourceName,targetElement,targetName,transformFunction)

sourceElement is the Y from above; it identifies the custom element or some element in the internal content to be watched. sourceElement is a CSS Query Selector string. If multiple elements match, each is bound as described.If the string "." is used the source is the custom element itself.

sourceName is the X from above; it identifies the attribute, property, or content you want to watch for changes. When the given attribute, property, or content changes, the binding will propagate the change to the target (A and B).

targetElement is the B from above an is a CSS Query Selector string. It may match multiple elements and if so, each becomes a target. If the string "." is used the target is the custom element itself.

targetName is the X from above; it identifies the attribute, property, or content you want to modify when a change occurs. targetName is optional and if left out the sourceName will also be used as the targetName, saving a little typing.

transformFunction is an optional function that if given will be executed when the change is triggered. It recieves the value being set and whatever it returns is set instead. Also, an exception thrown in the transformFunction will cause the binding to not set and thus prevent it.

Param Type
sourceElement string
sourceName string
targetElement string
targetName string
transformFunction function

onInit(listener) ⇒ void

Kind: global function
Summary: Definition Method to register a function to execute on the Initialized Lifecycle event. If multiple onInit() methods are called, each will execute in order.

The Initialized Lifecycle event occurs after a component is registered with the Custom Element Registry, but before any instances of the components have been created. As such, the onInit() method does not have access to the element or its content.

The function passed to onInit() is executed with the signature

(name,component)

  • name is the component name,
  • componet is the ZephComponent instance describing the component.
Param Type
listener function

onCreate(listener) ⇒ void

Kind: global function
Summary: Definition Method to register a function to execute on the Created Lifecycle event. If multiple onCreate() methods are called, each will execute in order.

The Created Lifecycle event occurs after an element of the component is created via document.createElement() or through tag usage.

The function passed to onCreate() is executed with the signature

(element,content)

  • element is the custom element.
  • content is the Document Fragment of the internal content.
Param Type
listener function

onAdd(listener) ⇒ void

Kind: global function
Summary: Definition Method to register a function to execute on the Add Lifecycle event. If multiple onAdd() methods are called, each will execute in order.

The Add Lifecycle event occurs when an element of the component is add to a document or document fragment.

The function passed to onAdd() is executed with the signature

(element,content)

  • element is the custom element.
  • content is the Document Fragment of the internal content.
Param Type
listener function

onRemove(listener) ⇒ void

Kind: global function
Summary: Definition Method to register a function to execute on the Remove Lifecycle event. If multiple onRemove() methods are called, each will execute in order.

The Remove Lifecycle event occurs when an element of the component is remove from a document or document fragment.

The function passed to onRemove() is executed with the signature

(element,content)

  • element is the custom element.
  • content is the Document Fragment of the internal content.
Param Type
listener function

onAdopt(listener) ⇒ void

Kind: global function
Summary: Definition Method to register a function to execute on the Adopt Lifecycle event. If multiple onAdopt() methods are called, each will execute in order.

The Adopt Lifecycle event occurs when an element of the component is adopted by a new document or document fragment. It is very rarely needed.

The function passed to onAdopt() is executed with the signature

(element,content)

  • element is the custom element.
  • content is the Document Fragment of the internal content.
Param Type
listener function

onAttribute(attributeName, listener) ⇒ void

Kind: global function
Summary: Definition Method to register a function to execute on the Attribute Lifecycle event. If multiple onAttribute() methods are called, each will execute in order.

The Attribute Lifecycle event occurs when an element of the component has an attribute that is changed.

The function passed to onAttribute() is executed with the signature

(attributeName,value,element,content)

  • attributeName is the name of the changed attribute.
  • value is the new value being changed to.
  • element is the custom element.
  • content is the Document Fragment of the internal content.
Param Type
attributeName String
listener function

onProperty(propertyName, listener) ⇒ void

Kind: global function
Summary: Definition Method to register a function to execute on the Property Lifecycle event. If multiple onProperty() methods are called, each will execute in order.

The Property Lifecycle event occurs when an element of the component has an property that is changed.

The function passed to onProperty() is executed with the signature

(propertyName,value,element,content)

  • propertyName is the name of the changed attribute.
  • value is the new value being changed to.
  • element is the custom element.
  • content is the Document Fragment of the internal content.
Param Type
propertyName String
listener function

onEvent(eventName, listener) ⇒ void

Kind: global function
Summary: Definition Method to register an event handler to execute on some event. Events are just as you would expect them, but onEvent() and onEventAt() allows you to define the handlers without needing to write complicated onCreate() functions to deal with it.

onEvent() attaches an event handler for the given event name to the custom element itself. For example:

onEvent("click",myClickHandler);

Would execute myClickHandler when the custom element receives a click event.

The given listener executes with the following signature:

(event,element,content)

  • event is the event object.
  • element is the custom element.
  • content is the Document Fragment of the internal content.
Param Type
eventName String
listener function

onEventAt(selector, eventName, listener) ⇒ void

Kind: global function
Summary: Definition Method to register an event handler to execute on some event. Events are just as you would expect them, but onEvent() and onEventAt() allows you to define the handlers without needing to write complicated onCreate() functions to deal with it.

onEventAt() attaches an event handler for the given event name to the all elements that match a given CSS Query Selector. For example:

onEventAt("div > button.active","click",myClickHandler);

Would execute myClickHandler when any matching internal content element receives a click event. If the selector matches more than one element each element gets the event handler attach to it, so be careful.

The given listener executes with the following signature:

(event,selected,element,content)

  • event is the event object.
  • selected it the element that matched the selector.
  • element is the custom element.
  • content is the Document Fragment of the internal content.
Param Type
selector String
eventName String
listener function

You can’t perform that action at this time.