Javascript
This document is an attempt to distill our approach to javascript in Brambling into a set of design patterns and best practices as well as to document the objects and plugins that are currently in Brambling.
We are still very early in the process of bringing structure to our javascript, so these guidelines are still very much in flux.
Brambling evolved as a project with the bulk of the logic in Python. Over time we've added a number of small javascript components, mostly ad hoc'd on either as jQuery plugins or code written directly inline to the page templates.
We are currently in the process of bringing more structure to this, moving more of Brambling to a reactive and asynchronous model, and reorganizing those early attempts. This restructuring involves the integration of new libraries (Ractive, Underscore, Backbone, Django-REST-Framework, etc.) as well as the formulation of guidelines such as this document.
A lot of early Brambling javascript is written using jQuery and jQuery plugins. While jQuery is wonderful for writing small pieces of interactivity into otherwise static sites, it's not good for larger projects that require a separation of the DOM from data. Writing new javascript for Brambling with jQuery is a deprecated approach that should be avoided. Rewriting old jQuery plugins to be Ractive components and Backbone models is admirable.
Underscore is a small javascript utility library that Backbone relies on. It provides useful methods, such as _.each(), _.findIndex(), for manipulating native javascript types. We are currently using these utility methods in a few places in Brambling. We will need to use them more as we wean more things off of jQuery.
Backbone is a minimal javascript library that provides models, collections, routers, and views. We are not currently using this, but we should be using at least models and collections and probably routers. We will use Ractive in place of views.
Ractive is a javascript library that includes a template language and objects for handling the binding of data to those templates. We are currently using a few small ractive components as well as a couple large ones.
The high level overview of how we want these technologies to interact can be looked at through the lens of the Model-View-Controller design pattern. Backbone should be responsible for the definition of "Models" which handle data storage, manipulation, and syncing back to the server. Ractive templates are the "Views" that handle displaying data and receiving input. Ractive components are the controllers that mediate between the views and the models, handling any necessary logic between them.
Because this is a web-based application we also need "Routers" which map URLs to certain sections of the application. Backbone provides those.
This chart provided by the Backbone documentation is educational, though it omits the controller mediating between the model and the view:
