Modulus
Robust Web Component interface, based on @wide/dom-observer.
Install
npm install @wide/modulus --save
Usage
Register a regular component
import modulus from '@wide/modulus'
modulus.component('foo-bar', class {
run() {
}
})
// or batch
modulus.components({
'foo-bar': class {
run() {
}
}
})<body>
<div is="foo-bar">Hey!</div>
</body>Register a web component
The name given to the component must contains a - to comply to the custom-element naming convention.
import modulus from '@wide/modulus'
modulus.webComponent('foo-bar', class {
run() {
}
})
// or batch
modulus.webComponents({
'foo-bar': class {
run() {
}
}
})<body>
<foo-bar>Hey!</foo-bar>
</body>Get all components by name and selector
import modulus from '@wide/modulus'
modulus.seekAll('foo-bar') // Array<FooBar>
modulus.seekAll('foo-bar', '.visible') // Array<FooBar.visible>Get one component by name and selector
import modulus from '@wide/modulus'
modulus.seek('foo-bar') // first FooBar instance
modulus.seek('foo-bar', '#foobar1') // FooBar#foobar1 instanceGet component(s) from external source
document.queryComponent('foo-bar') // first FooBar instance
document.queryComponents('foo-bar', '.visible') // Array<FooBar.visible>
Call component's method from html
Use the [data-call] helper with a formatted value name#id.method:
<button data-call="modal#register.open">do something</button>will internally trigger:
modulus.seek('modal', '#register').open({ el, e, data })| Value | Description |
|---|---|
el |
HTMLElement object binded to the event |
e |
Event object of the event listener method callback |
data |
Optional parameters defined in [data-call.params]
|
Parameters
Use the [data-call.params] to pass custom values:
<button data-call="modal#register.open" data-call.params='[{ "myAttr": "myValue" }]'>do something</button>
⚠️ Note:data-call.paramsis waiting a JSON format only
Exmple with the previous HTML code:
modulus.component('modal', class extends Component {
run() {
// ...
}
/**
* Open modal and do some stuff
*
* @params {HTMLElement} el
* @params {Event} e
* @params {Object|null} [data]
*/
open({ el, e, data }) {
// el: <button ...>
// e: Event{ ... }
// data: { ... } | null
}Deprecated method: To ensure compatibility with the old $event and $el parameters (used by Modulus below v2.2.0), it still possible to use them. For this, consult the old documentation.
⚠️ Note: Keep in mind that this method should not be used with new projects. It can be removed at any time on the next release.
Component class
The Component class offers shortcuts for accessing element or sending events to other components.
import modulus from '@wide/modulus'
import Component from '@wide/modulus/src/component'
modulus.component('foo-bar', class extends Component {
run() {
this.log(`I'm in the DOM !`)
},
destroy() {
this.log(`I'm no longer in the DOM...`)
}
})Properties
-
elthe DOM element binded to the class -
uidunique ID given at the registration -
attrselement's attributes -
datasetelement's data-attributes -
refselement's specific children (fetched using[ref]and[ref.dyn]attributes)-
[ref]elements are computed on component initial load -
[ref.dyn]elements are computed on each access -
[ref.group]elements are grouped in an array under the same key ([ref=bar]->this.refs.bar[0])
-
Hooks
-
run()hook called when the element is inserted in DOM -
destroy()hook called when the element is removed from DOM
Methods
-
child(selector)alias ofthis.el.querySelector(), returnHTMLElement -
children(selector)alias ofthis.el.querySelectorAll(), returnNodeList -
on(event, callback)listen global event -
emit(event, callback)trigger global event -
off(event, callback)remove global listener -
log(...args)log message with unique identifier -
log.info(...args)log message with INFO severity -
log.warn(...args)log message with WARN severity -
log.error(...args)log message with ERROR severity
Garbage Collector
Every event listeners created using this.on() are automatically off()ed on component destruction.
Config
Log level
To keep only warn and error logs (for production usage), set production to true:
import modulus from '@wide/modulus'
modulus.config({ production: true })Or manually assign a log level:
import modulus, { LOG_LEVELS } from '@wide/modulus'
modulus.config({
log: {
level: LOG_LEVELS.INFO // DEBUG (default), INFO, WARN, ERROR, NONE
}
})
⚠️ Note: assign a log level will override theproductionsetting.
To disable logs, set enabled to false:
import modulus from '@wide/modulus'
modulus.config({
log: {
enabled: false
}
})The default config is setted to show all kind of logs.
Authors
- Aymeric Assier - github.com/myeti
- Julien Martins Da Costa - github.com/jdacosta
Contributors
- Sébastien Robillard - github.com/robiseb
- Kévin Poccard Soudard - github.com/kevpoccs
License
This project is licensed under the MIT License - see the licence file for details