@pelagiccreatures/sargasso

@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 - 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 an asynchronous HIJAX page loading scheme which supports deep linking and lightning fast page loads where only content areas are updated between pages leaving css, js and wrapper elements intact. Sargasso objects are created and destroyed as needed when they appear or are removed from the DOM.

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 leaving as much historical cruft in the past as possible. The result is lean and fast.

npm install @pelagiccreatures/sargasso

Bootstrap Sargasso (ES6):

// import lib
import {
	bootSargasso, Sargasso, registerSargassoClass
} from 'sargasso'

// set options
let options = {
	hijax: {
		onError: (level, message) => {} // throw up an alert or something with message.
	}
}

// boot supervisors and HIJAX loader
let loadPageHandler = bootSargasso(options)

// define a custom class and register the classname
class MyClass extends Sargasso {}
registerSargassoClass('MyClass',MyClass)

Bootstrap Sargasso (ES5):

The bundle exposes sargasso as a global so you can call the framework

• sargasso.Sargasso
• sargasso.registerSargassoClass
• sargasso.bootSargasso

<script src="/path/to/dist/sargasso.js">
<script>
	// set options
	let options = {
		hijax: {
			onError: (level, message) => {} // throw up an alert or something with message.
		}
	}

	// boot supervisors and HIJAX loader
	let loadPageHandler = sargasso.bootSargasso(options)
	class MyClass extends sargasso.Sargasso {}

	// define a custom class and register the classname
	sargasso.registerSargassoClass('MyClass',MyClass)
</script>

You can also use this cdn:

<script src="https://cdn.jsdelivr.net/npm/@pelagiccreatures/sargasso/dist/sargasso.js"></script>

Adding Your Sargasso class to an HTML element

Mark the elements you want to be enhance but adding a data-sargasso-class attribute:

<div data-sargasso-class="MyClass"></div>

You can also defer the instantiation using the lazy method which will only start up the class when the element is visible in the viewport:

<div data-lazy-sargasso-class="MyClass"></div>

Sargasso watches the DOM for any elements with data-sargasso-class and instantiates the sargasso object, hooking up the appropriate observers. When the underlying element is removed from the DOM it destroys any dangling sargasso objects.

HIJAX

Is the function you should call to load a new page. Once loaded, new pages are merged with the current page only replacing elements marked with data-hijax="true". Sargasso automatically captures <a href=".."> tags and calls the LoadPageHandler instead of letting the browser load pages. LoadPageHandler(href)

EG. instead of location.href= '/home', use LoadPageHandler('/home')

Defining SubClasses:

Your Sargasso subclasses can subscribe to event feeds to be notified of events.

The instance is associated with an element this.element

class MyClass extends Sargasso {
	constructor(element, options) {
		// subscribe to events
		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 only 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 received an 'sargasso' event
}

registerSargassoClass('MyClass', MyClass)

Sargasso Object Lifecycle

When the object is created the supervisor will call the `start()`` method of the object. You should use this hook to set up any element events you need to respond to such as clicking a button or key presses. Beyond responding to scrolling, resize and other responsive events, you will probably want to interact with your element in some way.

Properties

• this.element - the element we are controlling

Utility Methods:

• this.hasClass('cssclass') // returns true if this.element has cssclass
• this.addClass('cssclass') // add cssclass to this.element
• this.removeClass('cssclass') // remove cssclass to this.element
• this.queueFrame(function) // queue a function to execute that changes the DOM

Example Button Handler:

class MyButtonClass extends Sargasso {

	// listen for click
	start() {
		super.start()

		this.clicker = (e) => {
			this.clicked()
		}
		this.element.addEventListener('click', this.clicker, false)
	}

	// cleanup listener
	sleep() {
		this.element.removeEventListener('click', this.clicker)
		super.sleep()
	}

	// use an animation frame to mutate the DOM
	clicked() {
		let frame = () {
			this.addClass('clicked')
		}
		this.queueFrame(frame)
	}
}

Then in HTML:

<style>
	.clicked { background-color:red; }
</style>

<button data-sargasso-class="MyButtonClass">Click me and I'll turn red!</button>

Using Animation Frames

Don't do any long processes in the responsive 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. You should offload any heavy weight processing to a web worker.

class MyClass 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('MyClass', MyClass)

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/example directory

python -m SimpleHTTPServer 8000

then point your browser to http://localhost:8000/index.html