@uu-cdh/backbone-util

Various utilities for Backbone applications.

Rationale | Quickstart | Compatibility | Reference | Planned | Support | Development | BSD 3-Clause

Rationale

We built several applications with a Backbone client. While writing those clients, we found ourselves repeating small patterns that were not yet abstracted by Backbone itself. We factored out those patterns and bundled them in this package, so that you can reuse them in your own Backbone single-page applications (SPAs). All of these utilities are small, independent additions to what Backbone can already do:

• a view mixin that causes the view to console.log its entire contents when alt-clicked, for easier debugging of the live application;
• a Backbone.sync wrapper that automatically inserts a CSRF token header when sending a modifying request to the same origin, which is useful if (for example) you use Django REST Framework with session authentication on the server side;
• when and whenever functions that let you postpone code until an attribute is present on a model;
• an easy way to enable clickable internal links within your application with pushState: true;
• a very general mixin function that also copies non-enumerable properties, such as getters and setters;
• a model mixin that adds finer-grained state change events, which makes it suitable (for example) to act as an intermediary between router events and the placement of main page views;
• a Backbone.Model.url() wrapper that ensures URLs end with a slash, which is useful for server frameworks (such as Django) that are picky about it;
• a model mixin that adds specific methods for user models such as login, logout and register, with matching events.

These utilities are well tested and we believe most Backbone applications can use at least a few of them.

We provide prototype mixins, rather than full-blown constructors/classes, because this gives you the freedom to layer them on top of a custom base class. This also leaves the choice up to you whether you want to use classic Backbone.*.extend() syntax or the modern class/ super keywords. We even have some tips in case you want to combine Backbone with TypeScript.

Quickstart

We recommend a workflow in which you install dependencies from npm and bundle them with a tool such as Rollup.

// could also use yarn, pnpm, etcetera
npm add @uu-cdh/backbone-util

import { View } from 'backbone';
import { getAltClickMixin } from '@uu-cdh/backbone-util';

export var MyBaseView = View.extend(getAltClickMixin());
// (See the reference for all the possible ways to use the library.)

You can also use the library directly from a browser embed, but you may need to set up import maps in that case.

Compatibility

The code modules use modern import/export syntax. If your target environment does not support this, you will need to take the code through a conversion or bundling tool first. Otherwise, only syntax is used that has existed for a while, so no transpilation or polyfilling should be required.

Reference

• using mixins
• click-to-debug
• csrf
• future-attribute
• internal-links
• mixin
• state-model
• trailing-slash
• user-model

Planned features

• A tooltip view mixin and utility function, which takes care of correctly positioning tooltips relative to (a subelement of) another view.

Support

Please report security issues to cdh@uu.nl. For regular bugs, feature requests or any other feedback, please use our issue tracker.

Development

Please see the CONTRIBUTING for everything related to testing, pull requests, versioning, etcetera.

License

Licensed under the terms of the three-clause BSD license. See LICENSE.