@pelagiccreatures/sargasso
Advanced tools
@pelagiccreatures/sargasso - npm Package Compare versions
Comparing version 0.5.10 to 0.5.11
@@ -280,2 +280,6 @@ /** | ||
| setCSS (cssObject) { | ||
| elementTools.setCSS(this.element, cssObject) | ||
| } | ||
| isVisible () { | ||
@@ -282,0 +286,0 @@ return elementTools.isVisible(this.element) |
| { | ||
| "name": "@pelagiccreatures/sargasso", | ||
| "version": "0.5.10", | ||
| "version": "0.5.11", | ||
| "description": "Simple, Fast, Reactive, supervised Javascript controllers for html elements.", | ||
@@ -5,0 +5,0 @@ "main": "index.js", |
128
README.md
@@ -15,13 +15,16 @@ # @PelagicCreatures/Sargasso | ||
| 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. | ||
| 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 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. | ||
| 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. | ||
| 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. | ||
| Bootstrap Sargasso Objects in ES6: | ||
| ```npm install @pelagiccreatures/sargasso``` | ||
| Bootstrap Sargasso (ES6): | ||
| --------------------------------- | ||
| ``` | ||
| // import lib | ||
| import { | ||
@@ -31,2 +34,3 @@ bootSargasso, Sargasso, registerSargassoClass | ||
| // set options | ||
| let options = { | ||
@@ -38,4 +42,6 @@ hijax: { | ||
| // boot supervisors and HIJAX loader | ||
| let loadPageHandler = bootSargasso(options) | ||
| // define a custom class and register the classname | ||
| class MyClass extends Sargasso {} | ||
@@ -46,5 +52,5 @@ registerSargassoClass('MyClass',MyClass) | ||
| Bootstrap Sargasso Objects in ES5: | ||
| Bootstrap Sargasso (ES5): | ||
| --------------------------------- | ||
| The bundle exposes App as a global so you can call the framework | ||
| The bundle exposes sargasso as a global so you can call the framework | ||
| * sargasso.Sargasso | ||
@@ -55,6 +61,16 @@ * sargasso.registerSargassoClass | ||
| ``` | ||
| <script src="/path/to/sargasso.js"> | ||
| <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) | ||
@@ -64,14 +80,23 @@ </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. | ||
| You can also use this cdn: | ||
| ``` | ||
| <script src="https://cdn.jsdelivr.net/npm/@pelagiccreatures/sargasso@0.5.10/dist/sargasso.js"></script> | ||
| ``` | ||
| `<div data-sargasso-class="mySubclass"></div>` | ||
| ### Adding Your Sargasso class to an HTML element | ||
| You can also defer the instantiation using the lazy method: | ||
| Mark the elements you want to be enhance but adding a data-sargasso-class attribute: | ||
| `<div data-lazy-sargasso-class="mySubclass"></div>` | ||
| `<div data-sargasso-class="MyClass"></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"' | ||
| 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')` | ||
@@ -83,5 +108,8 @@ | ||
| The instance is associated with an element `this.element` | ||
| ``` | ||
| class mySubclass extends Sargasso { | ||
| class MyClass extends Sargasso { | ||
| constructor(element, options) { | ||
| // subscribe to events | ||
| super(element, { | ||
@@ -96,3 +124,3 @@ watchDOM: [true:false], | ||
| // Methods that will be called when various events occur. Do what you need to do. | ||
| // Methods that will be called when various events occur. Do only what you need to do. | ||
@@ -108,13 +136,67 @@ DOMChanged() {} // called if 'watchDOM: true' when DOM changes | ||
| didBreakpoint() // new screen width breakpoint | ||
| elementEvent(e) // this.element receieved an 'sargasso' event | ||
| elementEvent(e) // this.element received an 'sargasso' event | ||
| } | ||
| registerSargassoClass('mySubclass', mySubclass) | ||
| registerSargassoClass('MyClass', MyClass) | ||
| ``` | ||
| 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. | ||
| ### 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 mySubclass extends Sargasso { | ||
| 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 = {}) { | ||
@@ -134,3 +216,3 @@ options.watchViewport = true | ||
| registerSargassoClass('mySubclass', mySubclass) | ||
| registerSargassoClass('MyClass', MyClass) | ||
@@ -140,3 +222,3 @@ ``` | ||
| ### 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 | ||
| To use Hijax you have to serve the files (window.popstate can't deal with file://) so run this in the project/example directory | ||
| ``` | ||
@@ -146,2 +228,2 @@ python -m SimpleHTTPServer 8000 | ||
| then point your browser to `http://localhost:8000/example/index.html` | ||
| then point your browser to `http://localhost:8000/index.html` |
Sorry, the diff of this file is too big to display
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by1.64%
180035
- Lines of code
- increased by0.2%
2020
- Number of lines in readme file
- increased by60.29%
218
No dependency changes