README.md
# LooseLeaf [](https://travis-ci.org/rike422/loose-leaf) [](https://coveralls.io/github/rike422/loose-leaf?branch=master) [](https://codeclimate.com/github/rike422/loose-leaf) [](http://standardjs.com/)
LooseLeaf is a Rails Engine that allows Real-Time collaboration between users.
LooseLeaf is still a work in progress, and currently only text attributes may
be collaboratively text editor.
This project inspired by [Collabrate](https://github.com/ball-hayden/Collaborate)
## Installation
Add this line to your application's Gemfile:
```ruby
gem 'loose_leaf'
```
And then execute:
$ bundle
## Getting Started
### Prerequisites
You will need to have ActionCable set up. In particular, you will need an
`ApplicationCable::Channel` and `ApplicationCable::Connection`.
More information about setting up ActionCable can be found in its README.
### Model Setup
```ruby
class Document < ActiveRecord::Base
# Include the LooseLeaf::Document concern
include LooseLeaf::Document
# Choose which attributes may be edited collaboratively
collaborative_attributes :body, :title
end
```
Adding `collaborative_attributes` will define an extra attribute on the model
prefixed with `collaborative_` (e.g `collaborative_body`). We must use that
over `body` whenever we wish to allow realtime collaboration.
Bear in mind that the `collaborative_` attributes are stored only in the Rails
cache. You must save these attributes where appropriate:
```ruby
document = Document.first
document.body = document.collaborative_body
document.save!
# Or, using the commit_collaborative_attributes convenience method:
document.commit_collaborative_attributes(:body)
document.commit_collaborative_attributes(:body, :title)
```
### Channel Setup
You will need to set up a collaboration channel for each model that is being
collaboratively edited.
```ruby
class DocumentChannel < LooseLeaf::CollaborationChannel
private
# Set the Model class that we are editing.
def collaborative_model
Document
end
end
```
### View
As mentioned in Model Setup, we must use `collaborative_` attributes over normal
attributes when getting the values of collaborative attributes:
```erb
<%# app/views/documents/show.html.erb %>
<input id="title" type="text" value="<%= @document.collaborative_title %>">
<textarea id="body" rows="8" cols="40"><%= @document.collaborative_body %></textarea>
<%= link_to 'Back', documents_path %>
<script>
var documentId = <%= @document.id %>
</script>
```
### JavaScript
[](https://github.com/feross/standard)
#### Sprockets
Add `loose-leaf` to your `application.coffee` asset, after actionable:
```coffeescript
#= require cable
#= require loose-leaf
```
Then, wherever appropriate:
```js
// Create a new ActionCable consumer
const cable = Cable.createConsumer('ws://localhost:28080')
// Set up our collaboration object. `documentId` is (as you may expect) the ID
// of the document that is being edited.
const looseLeaf = new LooseLeaf(cable, 'DocumentChannel', documentId)
// We now specify the two attributes we are editing.
collaborativeTitle = looseLeaf.addAttribute('title')
collaborativeBody = looseLeaf.addAttribute('body')
new LooseLeaf.Adapters.TextAreaAdapter(collaborativeTitle, '#title')
new LooseLeaf.Adapters.TextAreaAdapter(collaborativeBody, '#body')
```
#### npm or yuan
```
npm install loose-leaf
```