<commit_before><commit_msg>added documentation about the organization models CDB-3097<commit_after>
# organizations

this document contains some notes on how to work with backbone models realted to organization

## models related to organization

- cdb.admin.User: it already existed, but it takes more importance
- cdb.admin.Organization: this represents an organization
- cdb.admin.Permission: 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 a organization attribute. Each user is **always** inside a organization, so
  this be always filled. When the organization contains only an user the application behavior is the
  same than we have currently (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()
```

- 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')
```


{'fraction_non_alphanumeric': 0.11164179104477612, 'fraction_numerical': 0.003582089552238806, 'mean_word_length': 4.86013986013986, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 1, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3262802', 'n_tokens_mistral': 476, 'n_tokens_neox': 449, 'n_words': 169}