@PelagicCreatures/Sargasso
Simple, Fast, Supervised Javascript controllers for html elements.
Demo Site
This framework is very lightweight, pure ES6 with only few dependencies
@author Michael Rhodes (except where noted)
@license MIT
Made in Barbados 🇧🇧
Sometimes HTML elements need a nervous system - once DOM elements are coupled with Sargasso classes many things are possible – Lazy Loading, size appropriate images and content, parallax scrolling effects, form validators, API endpoint controllers to name a few.
This framework implements a sophisticated HIJAX page loading scheme which supports deep linking and lightning fast page loads where only only content areas are updated between pages leaving css, js and wrapper elements intact.
Performance is optimized with shared event listeners which are fully debounced during large updates and services are provided to schedule content changes using the browser's animation frame event loop resulting in smooth page updates.
This framework aims to use the advanced features of modern browsers to maximum effect.
Bootstrap Sargasso Objects in ES6:
import {
bootSargasso, Sargasso, registerSargassoClass
} from 'sargasso'
let options = {
hijax: {
onError: (level, message) => {} // throw up an alert or something with message.
}
}
let loadPageHandler = bootSargasso(options)
class MyClass extends Sargasso {}
registerSargassoClass('MyClass',MyClass)
Bootstrap Sargasso Objects in ES5:
The bundle exposes App as a global so you can call the framework
- sargasso.Sargasso
- sargasso.registerSargassoClass
- sargasso.bootSargasso
<script src="/path/to/sargasso.js">
<script>
let loadPageHandler = sargasso.bootSargasso(options)
class MyClass extends sargasso.Sargasso {}
sargasso.registerSargassoClass('MyClass',MyClass)
</script>
SargassoSupervisor then watches the DOM for any elements with 'data-sargasso-class'
and instantiates the object, hooking up the appropriate observers. It also destroys
any dangling objects when the underlying element is removed from the DOM.
<div data-sargasso-class="mySubclass"></div>
You can also defer the instantiation using the lazy method:
<div data-lazy-sargasso-class="mySubclass"></div>
If using Hijax it captures <a href="..">
tags and calls the LoadPageHandler instead of letting the browser do it. LoadPageHandler(href)
is a function you should call to load a new page. New pages are merged with the current page replacing any elements marked with 'data-hijax="true"'
EG. instead of location.href= '/home'
, use LoadPageHandler('/home')
Defining SubClasses:
Your Sargasso subclasses can subscribe to event feeds to be notified of events.
class mySubclass extends Sargasso {
constructor(element, options) {
super(element, {
watchDOM: [true:false],
watchScroll: [true:false],
watchResize: [true:false],
watchOrientation: [true:false],
watchViewport: [true:false]
})
}
// Methods that will be called when various events occur. Do what you need to do.
DOMChanged() {} // called if 'watchDOM: true' when DOM changes
didScroll() {} // called if 'watchScroll: true' when scroll occurs
didResize() {} // called if 'watchResize: true' when resize changes
enterViewport() {} // called if 'watchViewport: true' when element is entering viewport
exitViewport() {} // called if 'watchViewport: true' when element is exiting viewport
enterFullscreen() {} // called if 'watchOrientation: true' when user rotates phone or if setFullscreen is called
exitFullscreen() {} // called on exit fullscreen
newPage(old,new) // on a new page
didBreakpoint() // new screen width breakpoint
elementEvent(e) // this.element receieved an 'sargasso' event
}
registerSargassoClass('mySubclass', mySubclass)
Don't do any long processes in these callbacks or things might bog down the browser UI. To avoid any chaotic repaints you should only make DOM changes inside animation frames - see a lazy loading example below.
class mySubclass extends Sargasso {
constructor(element,options = {}) {
options.watchViewport = true
super(element,options)
}
enterViewport() {
// do some stuff such as modify element html or classes
let frame = () => {
this.element.innerHTML = '<p>Hello viewport!'
}
this.queueFrame(frame)
}
}
registerSargassoClass('mySubclass', mySubclass)
Viewing the Test Page in the example directory
To use Hijax you have to serve the files (window.popstate can't deal with file://) so run this in the project directory
python -m SimpleHTTPServer 8000
then point your browser to http://localhost:8000/example/index.html