couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From benk...@apache.org
Subject fauxton commit: updated refs/heads/master to 763e805
Date Mon, 08 Jun 2015 15:37:43 GMT
Repository: couchdb-fauxton
Updated Branches:
  refs/heads/master 2652c9814 -> 763e80506


Updates the main README doc

This updates the outdated README and includes a new file explaining
a little about the (new) Fauxton code layout.


Project: http://git-wip-us.apache.org/repos/asf/couchdb-fauxton/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb-fauxton/commit/763e8050
Tree: http://git-wip-us.apache.org/repos/asf/couchdb-fauxton/tree/763e8050
Diff: http://git-wip-us.apache.org/repos/asf/couchdb-fauxton/diff/763e8050

Branch: refs/heads/master
Commit: 763e805060a48dcea230f22c5f67eb6f915dbc5b
Parents: 2652c98
Author: Ben Keen <ben.keen@gmail.com>
Authored: Mon Jun 8 08:07:22 2015 -0700
Committer: Ben Keen <ben.keen@gmail.com>
Committed: Mon Jun 8 08:39:16 2015 -0700

----------------------------------------------------------------------
 code-layout.md    | 84 ++++++++++++++++++++++++++++++++++++++++++++++++++
 readme.md         | 25 +++++----------
 writing_addons.md | 18 ++++++-----
 3 files changed, 102 insertions(+), 25 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/couchdb-fauxton/blob/763e8050/code-layout.md
----------------------------------------------------------------------
diff --git a/code-layout.md b/code-layout.md
new file mode 100644
index 0000000..99bcbaa
--- /dev/null
+++ b/code-layout.md
@@ -0,0 +1,84 @@
+# Fauxton Code Overview
+
+This page documents a little practical information about the Fauxton codebase to help you
get up to speed. 
+
+
+## Backbone and React 
+
+Fauxton was originally written in [Backbone](http://backbonejs.org), but in 2015 we're in
the process of upgrading 
+the codebase to build it around [React](https://facebook.github.io/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. 
+
+### React and Flux 
+
+You can read more about [React](https://facebook.github.io/react/) and [Flux](https://facebook.github.io/flux/docs/overview.html)

+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](https://facebook.github.io/react/docs/why-react.html)
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](https://github.com/facebook/flux). Information
flows 
+like this:
+
+1. User clicks on something in a React component, 
+2. the component fires an action (in an `actions.js` file),
+3. the action dispatches an event (for us, that's the `FauxtonAPI.dispatch()` call), 
+4. stores listen to these events (in their `dispatch()` methods), change the content of the
store, then notify 
+anyone that's interested that the store has changed,
+5. finally, it comes full circle. React components listen for changes in the store by listening
to their `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.
+
+### JSX 
+
+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](https://facebook.github.io/react/docs/jsx-in-depth.html). 
+
+
+## Addons
+
+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. Two good
starting points are 
+[app/addons/verifyinstall](app/addons/verifyinstall) and [app/addons/compaction](app/addons/compaction).
Both of these
+are relatively self-contained and map to specific pages in the Fauxton interface so you can
see exactly where they appear
+and what they do.
+
+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](writing_addons.md) for more information on writing your own
addons.
+
+
+## CSS / Less
+
+We use Less for generating our CSS. The bulk of the shared CSS used throughout the application
is found in 
+[assets/less/](assets/less), but any addon may contain its own `assets/less` subfolder containing
whatever unique
+styles are needed.
+
+
+## app/addons/components / app/addons/fauxton
+  
+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.
+
+

http://git-wip-us.apache.org/repos/asf/couchdb-fauxton/blob/763e8050/readme.md
----------------------------------------------------------------------
diff --git a/readme.md b/readme.md
index cb42175..5351712 100644
--- a/readme.md
+++ b/readme.md
@@ -129,26 +129,17 @@ To deploy to your local [CouchDB instance](http://localhost:5984/fauxton/_design
 
     grunt couchapp_deploy
 
-## Understanding the Fauxton Code Layout
-
-Each bit of functionality is its own separate module or addon. All core modules are stored
under `app/module` and
-any addons that are optional are under `app/addons`. We use [backbone.js](http://backbonejs.org/)
and
-[Backbone.layoutmanager](https://github.com/tbranyen/backbone.layoutmanager) quite heavily,
so best to get an
-idea how they work. It's best at this point to read through a couple of the modules and addons
to get an idea
-of how they work. Two good starting points are `app/addon/config` and `app/modules/databases`.
-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, `view.js` for your Backbone.Views.
-The `routes.js` is used to register a URL path for your view along with what layout, data,
breadcrumbs and api
-point is required for the view.
-
-Check out [writing_addons.md](writing_addons.md) for more information on writing your own
addons.
-
-Want to get involved? Check out [Jira](https://issues.apache.org/jira/browse/COUCHDB/component/12320406)
for a list
-of items to do.
-
 ## (Optional) To avoid a npm global install
     # Development mode, non minified files
     npm run couchdebug
 
     # Or fully compiled install
     npm run couchdb
+
+## Understanding the Fauxton Code Layout
+
+Interested in writing learning more? Give [this file](code-layout.md) a read over for a little
more information about 
+how Fauxton's organized. 
+
+Want to get involved? Check out [Jira](https://issues.apache.org/jira/browse/COUCHDB/component/12320406)
for a list
+of items to do.

http://git-wip-us.apache.org/repos/asf/couchdb-fauxton/blob/763e8050/writing_addons.md
----------------------------------------------------------------------
diff --git a/writing_addons.md b/writing_addons.md
index 08f44fc..805800b 100644
--- a/writing_addons.md
+++ b/writing_addons.md
@@ -1,6 +1,6 @@
 # Addons
-Addons allow you to extend Fauxton for a specific use case. Addons will usually
-have the following structure:
+
+Addons allow you to extend Fauxton for a specific use case. Addons will usually have the
following structure:
 
  * templates/
    * my_addon.html - _underscore template fragments_
@@ -14,10 +14,11 @@ have the following structure:
    * my_addon.less
 
 ## Generating an addon
-We have a `grunt-init` template that lets you create a skeleton addon,
-including all the boiler plate code. Run
-`./node_modules/.bin/grunt-init tasks/addon` and answer the questions
-it asks to create an addon:
+
+*** N.B. This is out of date: the addon should generate a React component rather than a Backbone
View *** 
+
+We have a `grunt-init` template that lets you create a skeleton addon, including all the
boiler plate code. Run
+`./node_modules/.bin/grunt-init tasks/addon` and answer the questions it asks to create an
addon:
 
     $ ./node_modules/.bin/grunt-init tasks/addon
     path.existsSync is now called `fs.existsSync`.
@@ -33,13 +34,14 @@ it asks to create an addon:
 
     Done, without errors.
 
-Once the addon is created add the name to the settings.json file to get it
-compiled and added on the next install.
+Once the addon is created add the name to the settings.json file to get it compiled and added
on the next install.
 
 ## Routes and hooks
+
 An addon can insert itself into fauxton in two ways; via a route or via a hook.
 
 ### Routes
+
 An addon will override an existing route should one exist, but in all other
 ways is just a normal backbone route/view. This is how you would add a whole
 new feature.


Mime
View raw message