Lateralus is a single page web application framework. It is designed around the idea that UIs should be divided into discreet, reusable, loosely-coupled components. These components should communicate only indirectly and be easily swappable or removable. Lateralus provides patterns and utilities to cleanly isolate individual components of your app.
Lateralus is built upon Backbone, Lodash, jQuery, and Mustache.
The standard build of Lateralus does not have its dependencies baked, so you must provide them at runtime. Lateralus expects and is tested with:
To install Lateralus into an existing app:
npm install --save lateralus
Lateralus is a UMD module, so load it however you like. This README's examples use the AMD format.
Once loaded, you can instantiate a Lateralus app:
app is a reference to a running Lateralus application.
Working with components
Building upon the previous example:
Much of the Lateralus workflow involves creating and wiring up components. The majority of code in a Lateralus app should be handled by components, everything outside of component code should focus on glueing them together and providing utilities.
Lateralus's functionality is divided up into several primary Objects under the
- A stylesheet
Contains static utility methods, such as
The primary class used within the framework to define UI components. Typically, a component encompasses a
Lateralus.Component.View and a template (though these are not required).
A component is distinct from a view. A view is a graphical, interactive representation of a model. A component represents all of the interrelated parts of significant, individual part of the UI. This usually includes one or more Views, a template, a Model, and anything else a UI component needs to function. A component is a higher-level abstraction than a View.
This is the standard directory structure for a typical component:
my-component/ styles/ main.sass main.js view.js model.js template.mustache
main.js is the main entry point for the component and defines the
view.js defines the primary
Lateralus.Component.View instance, and
template.mustache is the primary DOM template. All components should adhere to this directory structure, but you are also free change the directory structure to suit your needs. If you do this, you will need to update the dependency paths in your component's AMD modules.
Boilerplate for a standard
Lateralus.Component instances have a reference to the central
Lateralus instance as
styles/main.sass file is not
@imported for you automatically in your main Sass file, you will need to do that manually when you set up a new component.
Lateralus uses Mustache.js for its templating engine. Components that render something have at least one template associated with them as
This Object extends
Backbone.View with Lateralus-specific functionality. Here's a basic
Lateralus.Component.View subclass module:
Lateralus.Component.View has a reference to the central
Lateralus instance as
this.lateralus, and a reference to the
Lateralus.Component it belongs to with
this.component. This is necessary for using the
listenFor mixin methods to communicate with the rest of the app. Generally, you can use
Lateralus.Component.View exactly as you would
Backbone.View, but it gives you a few additional APIs.
As a convenience,
Lateralus.Component.View implicitly binds DOM nodes in the template as jQuery objects. If the component's template looks like this:
The view will automatically have properties
this.$header that are jQuery objects referencing the
div and the
Lateralus.Component.View transparently renders its template for you.
this.renderTemplate is called by
Lateralus.Component.View.prototype.initialize (which is why you should generally call
baseProto.initialize as demonstrated above), but you are free to do further rendering with
this.render should be used for partial updates, whereas
this.renderTemplate should be used to completely replace the contents of the View's
$el with whatever is in
Lateralus.Component.View, this object extends its Backbone counterpart —
Backbone.Model. This doesn't add much in the way of new functionality, but it does have a reference to the central
Lateralus instance and can therefore
Lateralus.Component.Model, this works consistently with
Backbone.Collection, but in a way that is compatible with Lateralus.
Each component can (and should) have its own
.sass file. It is recommended that all rules be nested under the
[component-name]-view CSS class, as that class is dynamically added to all
Lateralus.Component.View instances. This provides clean and easy component-based style isolation.
You can run the Lateralus unit tests both in your browser as well as in a command line environment. To run the tests in your browser:
npm run start
And then navigate to http://127.0.0.1:8080/test/.
To run them at the command line:
Publishing new versions
Once things are ready, you should use
- change the version in the
- build the documentation (with the new version).
- commit the new documentation
- tag the new version
- push to the repo.
Once this is done, Travis will publish the change to NPM.