@wide/modulus
v2.2.3
Published
Robust Web Component interface
Downloads
476
Keywords
Readme
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 instance
Get 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.params
is 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
el
the DOM element binded to the classuid
unique ID given at the registrationattrs
element's attributesdataset
element's data-attributesrefs
element'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 DOMdestroy()
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 eventemit(event, callback)
trigger global eventoff(event, callback)
remove global listenerlog(...args)
log message with unique identifierlog.info(...args)
log message with INFO severitylog.warn(...args)
log message with WARN severitylog.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 the
production
setting.
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