@webhandle/backbone-view 1.0.0

package/README.md

@@ -0,0 +1,167 @@
+# Webhandle Backbone View
+
+A replacement for Backbone's View.
+
+I really like Backbone's View. It's a perfect level of abstraction and container for when a framework
+is too big and managing a few different object types becomes messy.
+
+However, it requires jQuery and Underscore, which add a staggering 600k to the bundle making it unsuitable for the
+creation of little modules. Additionally, its code was written to run on older IE browsers and still
+uses that packaging and those techniques.
+
+While that level of backward compatibility can be useful, I want to write code that uses classes,
+modules, etc, and want my tools to support that.
+
+
+
+## Install
+
+```bash
+npm install @webhandle/backbone-view
+```
+
+It's about 1027 bytes zipped as part of a webpack bundle, so about 1% of the size of Backbone and its
+dependencies. 
+
+
+## Usage
+
+
+Import like
+
+```js
+const View = require('@webhandle/backbone-view').View
+```
+
+or
+
+```js
+import { View } from '@webhandle/backbone-view'
+```
+
+[Backbone's actual documentation](https://backbonejs.org/#View) is still pretty descriptive of what this does.
+But in brief, the basic process is to extend View and define how the data will be rendered and how events will be handled.
+
+
+Setting callbacks to handle events is done by creating an events object, where `this.events` is a hash like:
+
+```json
+{"event selector": "callback"}
+```
+
+Events are things like `click` and `mousedown`. Selectors are standard css selectors like `button`, `footer .ok`, or `.ok`. Each
+selector is assumed to target only elements within the view. A special selector value, `.`, is used to indicate the
+root element of the view.
+
+Events are handled by event listeners on the view's root element. That means that while you have to have the
+events defined when the view is created, you can change the content of the view's dom section however you want and 
+whenever you want. Events on those new elements will still get handled. 
+
+Callbacks are either a string, which refers to a method of the view, or functions. In either case the method/function
+will be called with the view as the `this` object. These functions will receive the dom event and the element matching
+the selector which the event bubbled through. This may not be the same as the `evt.target` since a child element of the matching
+element may have been the actual thing clicked (or whatever). Essentially, the second argument is what the `evt.target` would
+have been if the event listener had been added directly to that element instead of the view root.
+
+Rendering (via the `render` method) is the most free from. It requires that the contents of `this.el` (the view's root element)
+get modified to show content appropriate to `this.model`. You can use any templating library or no templating library at all.
+
+Include the view into the page by adding the view object's `el` (the root element of the view) to any place in the dom. There
+are two convience functions `appendTo` and `replaceContentsOf`.
+
+And don't forget to call `render`, either before or after the element is added to the dom, or you won't see any content. 
+
+
+```js
+import { View } from '@webhandle/backbone-view'
+
+class DollarView extends View {
+	preinitialize() {
+		this.events = {
+			'click .one': 'oneClicked',
+			'click .': function (evt) {
+				console.log(`${this.model} it got clicked`)
+			}
+		}
+	}
+
+	render() {
+		this.el.innerHTML = "$" + `<span id="${this.id}one" class="one"><span id="${this.id}two" class="two">${parseFloat(this.model)}</span></span>`
+		return this
+	}
+
+	oneClicked(evt, selected) {
+		console.log(`one clicked ${selected.id}`)
+	}
+}
+
+let one = new DollarView({
+	model: 123.45
+})
+
+one.render()
+one.appendTo(document.body)
+```
+
+A view will accept the options 'model', 'el', 'id', 'attributes', 'className', 'tagName', and 'events'.
+It's possible to pass these in as options to an instance or as options via the subclass's constructor.
+However, I think it looks cleaner to implement the `preinitialize` function, which is called before
+the view creates any elements.
+
+
+## Differences from Backbone
+
+As mentioned above, there are no dependencies. The View also lacks some of the functions used by Backbone
+for interaction with its Model and Collections components. Since there is no jQuery, some of the members
+like `this.$el` don't exist and events will be plain HTML dom events.
+
+Backbone also limits which members of the options will be added to the View instance object to those listed
+above. That seems unnecessarily limiting so this View adds all members.
+
+While broadly compatible, I wouldn't expect the behaviors to be identical.
+
+## An Only Slightly More Complicated Example
+
+```js
+import { View } from '@webhandle/backbone-view'
+
+class DollarView extends View {
+	preinitialize() {
+		this.events = {
+			'click .one': 'oneClicked'
+			, 'click .math-button': 'doMath'
+			, 'click .': function (evt) {
+				console.log(`${this.model} it got clicked`)
+			}
+		}
+	}
+
+	render() {
+		this.el.innerHTML = "$" + `<span id="${this.id}one" class="one"><span id="${this.id}two" class="two">${parseFloat(this.model)}</span></span><button class="add-one math-button">Add One</button><button class="substract-one math-button">Subtract One</button>`
+		return this
+	}
+
+	oneClicked(evt, selected) {
+		console.log(`one clicked ${selected.id}`)
+	}
+
+	doMath(evt, selected) {
+		if(selected.classList.contains('add-one')) {
+			this.model = this.model + 1
+		}
+		else if(selected.classList.contains('subtract-one')) {
+			this.model = this.model - 1
+		}
+		this.el.querySelector('.two').innerHTML = parseFloat(this.model)
+		console.log(this.randomInfo)
+	}
+}
+
+let one = new DollarView({
+	model: 1.45
+	, randomInfo: 20
+})
+
+one.render()
+one.appendTo(document.body)
+```

package/client-js/event-entry-mapper.js

@@ -0,0 +1,16 @@
+export default function eventEntryMapper([key, value]) {
+	key = key.trim()
+	let parts = key.split(' ')
+	let event = parts.shift().trim()
+	let selector = parts.join(' ').trim()
+	
+	if(typeof value === 'string') {
+		value = value.trim()
+	}	
+	
+	return {
+		event: event,
+		selector: selector,
+		handler: value
+	}
+}

package/client-js/extract-event-names.js

@@ -0,0 +1,7 @@
+export default function extractEventNames(eventTriggers) {
+	let eventNames = Array.from(eventTriggers.reduce((acc, trigger) => {
+		acc.add(trigger.event)
+		return acc
+	}, new Set()))
+	return eventNames
+}

package/client-js/generate-id.js

@@ -0,0 +1,12 @@
+/**
+ * Generates a random string id in the browser. Will probably not work
+ * on the server.
+ * @returns A base64 web url safe string
+ */
+export default function generateId() {
+	let array = new Uint8Array(32)
+	window.crypto.getRandomValues(array)
+	let value = btoa(array)
+	value = value.replace(/\//g, "_").replace(/\+/g, "-").replace(/=+$/, "")
+	return value
+}

package/client-js/index.js

@@ -0,0 +1,5 @@
+
+import {View} from "./view.js"
+export {
+	View
+}

package/client-js/pick.js

@@ -0,0 +1,14 @@
+/**
+ * Duplicates and returns an object with only the speicified keys.
+ * @param {object} foucs
+ * @param {string[]} keys
+ */
+export default function pick(focus = {}, keys = []) {
+	let clone = {}
+	for(let key of keys) {
+		if(typeof focus[key] !== 'undefined'){
+			clone[key] = focus[key]
+		}
+	}
+	return clone
+}

package/client-js/view.js

@@ -0,0 +1,199 @@
+import generateId from "./generate-id.js"
+// import pick from "./pick.js"
+import eventEntryMapper from "./event-entry-mapper.js"
+import extractEventNames from "./extract-event-names.js"
+
+let defaultOptions = {
+	// The default `tagName` of a View's element is `"div"`.
+	tagName: 'div'
+	
+	, events: {}
+
+}
+let viewOptions = ['model', 'el', 'id', 'attributes', 'className', 'tagName', 'events'];
+
+/**
+ * A way to connect data to be displayed, a way to display it, and an organization
+ * of functions to handle events.
+ */
+export class View {
+	constructor(options) {
+		this.id = generateId()
+		Object.assign(this, defaultOptions)
+		this.preinitialize.apply(this, arguments);
+		Object.assign(this, options)
+		this._ensureElement()
+		this.initialize.apply(this, arguments);
+	}
+
+
+	/**
+	 * preinitialize is an empty function by default. You can override it with a function
+	 * or object.  preinitialize will run before any instantiation logic is run in the View
+	 */
+	preinitialize() { }
+
+	/**
+	 * Initialize is an empty function by default. Override it with your own
+	 * initialization logic.
+	 */
+	initialize() { }
+
+	/**
+	 * **render** is the core function that your view should override, in order
+	 * to populate its element (`this.el`), with the appropriate HTML. The
+	 * convention is for **render** to always return `this`.
+	 * @returns this
+	 */
+	render() {
+		return this
+	}
+	
+	/**
+	 * Removes the element from the dom. Does not disable event listeners
+	 */
+	remove() {
+		this.el.parentElement.removeChild(this.el)
+	}
+	
+	/**
+	 * Adds this view as a child to a containing element. Nothing special is going on here.
+	 * This is just a shortcut for container.appendChild
+	 * @param {Element} container 
+	 */
+	appendTo(container) {
+		container.appendChild(this.el)
+	}
+
+	/**
+	 * Clears the contents of the container and adds this view.
+	 * @param {Element} container 
+	 */
+	replaceContentsOf(container) {
+		container.innerHTML = ''
+		this.appendTo(container)
+	}
+
+	/**
+	 * Set the element for this view, and if new, adds listeners to it in accordance
+	 * with the "events" member.
+	 * @param {Element} el The dom element which will be the root of this view
+	 * @returns this
+	 */
+	setElement(el) {
+		if (this.el !== el) {
+			this.el = el
+			this._addListeners()
+		}
+		return this
+	}
+
+	/**
+	 * Produces a DOM element to be assigned to your view. Exposed for
+	 * subclasses using an alternative DOM manipulation API.
+	 * @param {string} name The element tag name
+	 * @returns The dom element
+	 */
+	_createElement(name) {
+		let el = document.createElement(name)
+		el.view = this
+		return el
+	}
+
+	/**
+	 * Ensures that the element exists. Applies attributes and className
+	 * to it regardless
+	 */
+	_ensureElement() {
+		if (!this.el) {
+			this.setElement(this._createElement(this.tagName))
+		}
+		this._setAttributes()
+		if (this.className) {
+			this.el.classList.add(this.className)
+		}
+	}
+
+	/**
+	 * Set attributes from a hash on this view's element.  Exposed for
+	 * subclasses using an alternative DOM manipulation API.
+	 * @param {object} attributes 
+	 */
+	_setAttributes(attributes) {
+		if (this.attributes) {
+			for (let [key, value] of Object.entries(this.attributes)) {
+				this.el.setAttribute(key, value)
+			}
+		}
+	}
+
+	/**
+	 * 
+	 * Set callbacks, where `this.events` is a hash of
+	 * *{"event selector": "callback"}*
+	 *
+	 *    {
+	 *       'mousedown .title':  'edit',
+	 *       'click .button':     'save',
+	 *       'click .open':       function(e) { ... },
+	 *       'keydown .':     	  'handleKey'
+	 *    }
+	 * pairs. Callbacks will be bound to the view, with `this` set properly.
+	 * 
+	 * 
+	 * Note that the selector `.` will match the root element and can be used
+	 * as a final chance to handle events or for events like an escape key
+	 * which are essentially global to the widget.
+	 * 
+	 */
+	_addListeners() {
+		this.eventTriggers = Object.entries(this.events).map(eventEntryMapper)
+		let eventNames = extractEventNames(this.eventTriggers)		
+
+		for(let eventName of eventNames) {
+			this.el.addEventListener(eventName, this._eventHandler.bind(this))
+		}
+	}
+	
+	/**
+	 * Get the elements from the view which match the selector
+	 * @param {string} selector A css selector. `.` will select the root element
+	 * @returns An array of elements
+	 */
+	_getCandidates(selector) {
+		if(selector === '.') {
+			return [this.el]
+		}
+		return Array.from(this.el.querySelectorAll(selector))
+	}
+	
+	/**
+	 * Handles all events for all elements within the view. It attempts to find a
+	 * trigger matching the event and then process it. It will match and invoke
+	 * only one trigger.
+	 * @param {Event} evt 
+	 */
+	_eventHandler(evt) {
+		for(let trigger of this.eventTriggers) {
+			if(evt.type == trigger.event) {
+				let candidates = this._getCandidates(trigger.selector)
+				let found = null
+				for(let candidate of candidates) {
+					if(candidate === evt.target || candidate.contains(evt.target)) {
+						found = candidate
+						break
+					}
+				}
+				if(found) {
+					if(typeof trigger.handler === 'string') {
+						this[trigger.handler].call(this, evt, found)
+					}	
+					else if(typeof trigger.handler === 'function') {
+						trigger.handler.call(this, evt, found)
+					}
+					break
+				}
+			}
+		}
+	}
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+	"name": "@webhandle/backbone-view",
+	"version": "1.0.0",
+	"description": "",
+	"main": "client-js/index.js",
+	"scripts": {
+		"test": "node_modules/mocha/bin/mocha",
+		"less-build": "npx lessc --source-map --source-map-include-source less/pages.less public/css/pages.css",
+		"less-compress": "npx uglifycss public/css/pages.css > public/css/pages.min.css",
+		"client-js-build": "npx webpack --config pages.webpack.cjs",
+		"client-js-compress": "npx uglifyjs public/js/pages.cjs -o public/js/pages.min.cjs -c --source-map url=public/js/pages.min.cjs.map",
+		"client-js-browserify-build": "npm run client-js-pages-browserify-build",
+		"client-js-pages-browserify build": "npx browserify client-js/pages.cjs --debug | npx exorcist public/js/pages.cjs.map > public/js/pages.cjs",
+		"dev-less-watch": "onchange 'less/**/*.less' -- npm run less-build",
+		"dev-client-js-watch": "onchange 'client-js/**/*js' 'client-js-test/**/*js' -- npm run client-js-build",
+		"dev-server-js-watch": "onchange 'server-js/**/*js' -- pm2 restart $npm_package_name-web",
+		"start": "node ./web-server.js",
+		"testDebug": "node --inspect-brk node_modules/mocha/bin/mocha",
+		"bg": "parallelshell 'npm run dev-less-watch' 'npm run dev-client-js-watch'",
+		"pm2-bg": "parallelshell 'npm run dev-less-watch' 'npm run dev-client-js-watch' 'npm run dev-server-js-watch'",
+		"dev": "parallelshell 'npm run start' 'npm run dev-less-watch' 'npm run dev-client-js-watch'"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/EmergentIdeas/webhandle-backbone-view.git"
+	},
+	"bugs": {
+		"url": "https://github.com/EmergentIdeas/webhandle-backbone-view/issues"
+	},
+	"homepage": "https://github.com/EmergentIdeas/webhandle-backbone-view#readme",
+	"keywords": [
+		"Backbone",
+		"View"
+	],
+	"author": "Dan Kolz",
+	"license": "ISC",
+	"devDependencies": {
+		"browserify": "^14.4.0",
+		"chai": "^4.3.4",
+		"exorcist": "^2.0.0",
+		"express": "^4.17.1",
+		"file-sink": "^1.0.4",
+		"filter-log": "0.0.5",
+		"input-value-injector": "^1.0.8",
+		"less": "^3.10.3",
+		"mocha": "^9.1.3",
+		"node-polyfill-webpack-plugin": "^2.0.1",
+		"onchange": "^3.2.1",
+		"parallelshell": "3.0.1",
+		"tripartite": "^1.1.1",
+		"uglify-js": "^3.17.4",
+		"webhandle": "^1.0.32",
+		"webhandle-js-widget-setup": "^1.0.5",
+		"webpack-cli": "^5.1.4"
+	},
+	"browserify": {
+		"transform": [
+			"tripartite/browserify-transform"
+		]
+	},
+	"files": [
+		"/client-js",
+		"README.md"
+	],
+	"type": "module"
+}