Initial commit

doc/frontend/editor/js/backbone-with-organizations.md

@@ -0,0 +1,52 @@
+This document contains some notes on how to work with backbone models related to organization
+
+## Models related to organization
+
+- [cdb.admin.User](https://github.com/CartoDB/cartodb/blob/CDB-2891/lib/assets/javascripts/cartodb/models/user.js): it already existed, but it takes more importance
+- [cdb.admin.Organization](https://github.com/CartoDB/cartodb/blob/CDB-2891/lib/assets/javascripts/cartodb/models/organization.js): this represents an organization
+- [cdb.admin.Permission](https://github.com/CartoDB/cartodb/blob/CDB-2891/lib/assets/javascripts/cartodb/models/permissions.js): permission object, contains the information to know about the ownership and
+  permission list (called ``acl``) of an object. See https://github.com/Vizzuality/cartodb-management/wiki/multiuser-REST-API#permissions-object
+
+### Changes
+
+- ``User`` model has an organization attribute. Each user is **always** inside an organization, so
+  this will be always filled. When the organization contains only a user, the application behavior is the
+  same than we currently have (CartoDB 2.0)
+
+- ``Visualization`` object contains a ``permission`` attribute (instance of ``cdb.admin.Permission``)
+
+
+### How to use them
+
+- add read permissions to a table
+
+```
+canonical_visualization.permission.setPermission(user_model, 'r').save();
+```
+
+- add read/write permissions to a table
+```
+canonical_visualization.permission.setPermission(user_model, 'rw').save();
+```
+
+- how to know if the organization for the current user is single or multiuser
+```
+user.isInsideOrg()
+user.isAdminOrg()
+```
+
+- know what users have access to a visualization
+
+```
+vis.permission.acl.each(function(aclItem) {
+    console.log("user " + aclItem.get('user').get('username') + " permission: " + aclItem.get('type'))
+})
+```
+
+- know the owner of a visualization
+```
+// owner is a cdb.admin.User instance
+vis.permission.owner.get('username')
+```
+
+

doc/frontend/editor/js/conventions.md

@@ -0,0 +1,20 @@
+This article describes conventions we defined for the JS code.
+
+## Backbone
+
+### Views
+
+#### Event names
+Use `done` and `fail` for event names, to be consistent with naming convention used in [jqXHR](http://api.jquery.com/jQuery.ajax/#jqXHR) objects (typically returned from a Backbone model/collection on an asynchronious operation. Typically used for dialogs, where the final operation and its outcome should have some implication in the UI (e.g. refresh list, hide/show some view etc.)
+
+Example:
+```js
+aDialogView
+  .bind('done', function() {
+    console.log('dialog is done :)');
+    this.collection.fetch();
+  .bind('fail', function(err) {
+    console.log('something failed :/');
+    // Do nothing for now
+  };
+```

doc/frontend/editor/js/global-objects.md

@@ -0,0 +1,12 @@
+As a general rule setting variables and objects in global namespace is highly discouraged. Instead, the code related to the CartoDB should be placed in the `cdb.admin` namespace.
+
+There are some use-cases where having a global objects makes things simpler and easier to maintain, see below.
+
+### cdb.god
+The `cdb.god` is a Backbone model which is intended to be used a global event bus to make it easier to bind and trigger to events that affects the global state in some way.
+
+As a general rule accessing global objects is highly discouraged, but there are some use-cases where having a global mechanism makes things simpler and easier to maintain, e.g.:
+- Global UI state changes
+- Some UI action should have a side-effect in another view, but they either don't know about each other and/or are logically located far away from each other.
+
+[Search for `cdb.god.`](https://github.com/CartoDB/cartodb/search?utf8=%E2%9C%93&q=cdb.god.)) in the source code you can see where it's currently applied.

doc/frontend/editor/js/urls.md

@@ -0,0 +1,15 @@
+URLs within the application might be necessary.
+
+To avoid constructing these URLS manually, i.e. concatenating strings and thus duplicating logic, there are convenient ways of constructing them. Depending on context (server- or client-side) you might take one approach or another.
+
+## Rails
+In Rails simply use the [standard routing helper methods](http://guides.rubyonrails.org/v3.2.21/routing.html). Have a look at  [routes.rb](https://github.com/CartoDB/cartodb/blob/master/config/routes.rb) for the semantic names and paths available.
+
+## Client-side
+For a current sub-app you can access URLs through the current router model, e.g. `router.currentUrl()`.
+
+For a URL that is associated with a specific model you can access the URL by call `.viewUrl()` on that model, and chaining methods afterwards to "drill down" on what (available) path you want, e.g.
+- `user.viewUrl().dashboard().datasets())`, the URL to a user's datasets on the dashboard.
+- `vis.viewUrl().public()`, the URL to a visualization's public page.
+
+See the [models](https://github.com/CartoDB/cartodb/blob/master/lib/assets/test/spec/cartodb/common/urls) for available models and methods.