This page documents a little practical information about the Fauxton codebase to help you get up to speed.
Fauxton was originally written in Backbone, but in 2015 we‘re in the process of upgrading the codebase to build it around React. We’re replacing all Backbone Views with (unit-tested!) React components. Backbone models and collections are still being used for server-side data retrieval and storage as is URL routing, but the plan is to phase out all Backbone over time.
You can read more about React and Flux on their sites, but a few quick words about both.
React is a relatively new framework created by Facebook, built on the idea of automatic DOM re-renders. Contrary to other frameworks, React decides when and where to redraw your UI based on changes to the underlying data set - and uses a virtual DOM to handle the re-rendering. The key decisions to moving to React were simplicity, performance and ease of testing. Check out this page for a few more remarks.
Flux is primarily a pattern for keeping your code organized over time. One of its key ideas is to have one-way communication as shown in the diagram here. Information flows like this:
actions.js file),FauxtonAPI.dispatch() call),dispatch() methods), change the content of the store, then notify anyone that's interested that the store has changed,change events. That‘s the purpose of the storeName.on('change', this.onChange) lines you’ll see in the code.So why do all this. The benefit is that it standardizes how data moves around the application, and keeps things simple - regardless of how much bigger the application gets. This is pretty cool.
Here's a simple example: imagine if a user shrunk/expanded the main sidebar, and multiple components in the page needed to know about it to make use of the new space. Maybe one was a graph and needed to redraw for the extra space, and maybe another component could switch from “basic” to “advanced” view or something.
With Flux, you can just publish the single event, then each store could listen for it, change whatever data was needed internally, then notify any components that was listening: and they would then have the choice to rerender or not, based on what changed. This is basic “pub/sub”: allowing you to keep code loosely coupled, but still communicate.
You'll noticed that some of our files have .jsx extensions. JSX is a javascript pre-parser, allowing us embed markup directly into our javascript, linking template and code.
Read more about JSX here.
Each bit of functionality is its own separate module or addon. Addons are located in their own app/addons/myaddon-name folder. As noted above, new code is being written in React so please favour React components over backbone views.
A good place to get started is to read through a couple of the existing addons. A good starting point is app/addons/verifyinstall. This is relatively self-contained and maps to a specific page in the Fauxton interface so you can see exactly where it appears and what it does.
Each module must have a base.js file, this is read and compiled when Fauxton is deployed. A resources.js file is usually used for your Backbone.Models and Backbone.Collections, components.react.jsx for your React components. The routes.js is used to register one or more URL paths for your addon along with what layout, data, breadcrumbs and API point is required for the view.
Check out writing_addons.md for more information on writing your own addons.
We use Less for generating our CSS. The bulk of the shared CSS used throughout the application is found in assets/less/, but any addon may contain its own assets/less subfolder containing whatever unique styles are needed.
These two contain React components and functionality intended for sharing throughout the app. You'll find many common elements in there, like trays, buttons, loading lines, clipboard functionality and more.