yonote/yjs
19
0
Fork 0
Code Pull Requests 1 Releases Activity

added CodeMirror example

Browse Source
This commit is contained in:
Kevin Jahns 2017-03-29 13:18:45 +02:00
parent a492a83f0c
commit 53682c17fb
3 changed files with 66 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

96
README.md
View File

@ -1,9 +1,10 @@
# ![Yjs](http://y-js.org/images/yjs.png) # ![Yjs](http://y-js.org/images/yjs.png)
Yjs is a framework for offline-first p2p shared editing on structured data like text, richtext, json, or XML. Yjs is a framework for offline-first p2p shared editing on structured data like
It is fairly easy to get started, as Yjs hides most of the complexity of concurrent editing. text, richtext, json, or XML. It is fairly easy to get started, as Yjs hides
For additional information, demos, and tutorials visit [y-js.org](http://y-js.org/). most of the complexity of concurrent editing. For additional information, demos,
and tutorials visit [y-js.org](http://y-js.org/).
### Extensions ### Extensions
Yjs only knows how to resolve conflicts on shared data. You have to choose a .. Yjs only knows how to resolve conflicts on shared data. You have to choose a ..
@ -11,7 +12,8 @@ Yjs only knows how to resolve conflicts on shared data. You have to choose a ..
* *Database* - a database to store your changes * *Database* - a database to store your changes
* one or more *Types* - that represent the shared data * one or more *Types* - that represent the shared data
Connectors, Databases, and Types are available as modules that extend Yjs. Here is a list of the modules we know of: Connectors, Databases, and Types are available as modules that extend Yjs. Here
is a list of the modules we know of:
##### Connectors ##### Connectors
@ -38,7 +40,7 @@ Connectors, Databases, and Types are available as modules that extend Yjs. Here
|[map](https://github.com/y-js/y-map) | A shared Map implementation. Maps from text to any stringify-able object | |[map](https://github.com/y-js/y-map) | A shared Map implementation. Maps from text to any stringify-able object |
|[array](https://github.com/y-js/y-array) | A shared Array implementation | |[array](https://github.com/y-js/y-array) | A shared Array implementation |
|[xml](https://github.com/y-js/y-xml) | An implementation of the DOM. You can create a two way binding to Browser DOM objects | |[xml](https://github.com/y-js/y-xml) | An implementation of the DOM. You can create a two way binding to Browser DOM objects |
|[text](https://github.com/y-js/y-text) | Collaborate on text. Supports two way binding to the [Ace Editor](https://ace.c9.io), textareas, input elements, and HTML elements (e.g. <*h1*>, or <*p*>) | |[text](https://github.com/y-js/y-text) | Collaborate on text. Supports two way binding to the [Ace Editor](https://ace.c9.io), [CodeMirror](https://codemirror.net/), textareas, input elements, and HTML elements (e.g. <*h1*>, or <*p*>) |
|[richtext](https://github.com/y-js/y-richtext) | Collaborate on rich text. Supports two way binding to the [Quill Rich Text Editor](http://quilljs.com/)| |[richtext](https://github.com/y-js/y-richtext) | Collaborate on rich text. Supports two way binding to the [Quill Rich Text Editor](http://quilljs.com/)|
##### Other ##### Other
@ -48,13 +50,15 @@ Connectors, Databases, and Types are available as modules that extend Yjs. Here
|[y-element](http://y-js.org/y-element/) | Yjs Polymer Element | |[y-element](http://y-js.org/y-element/) | Yjs Polymer Element |
## Use it! ## Use it!
Install Yjs, and its modules with [bower](http://bower.io/), or [npm](https://www.npmjs.org/package/yjs). Install Yjs, and its modules with [bower](http://bower.io/), or
[npm](https://www.npmjs.org/package/yjs).
### Bower ### Bower
``` ```
bower install --save yjs y-array % add all y-* modules you want to use bower install --save yjs y-array % add all y-* modules you want to use
``` ```
You only need to include the `y.js` file. Yjs is able to automatically require missing modules. You only need to include the `y.js` file. Yjs is able to automatically require
missing modules.
``` ```
<script src="./bower_components/yjs/y.js"></script> <script src="./bower_components/yjs/y.js"></script>
``` ```
@ -64,7 +68,8 @@ You only need to include the `y.js` file. Yjs is able to automatically require m
npm install --save yjs % add all y-* modules you want to use npm install --save yjs % add all y-* modules you want to use
``` ```
If you don't include via script tag, you have to explicitly include all modules! (Same goes for other module systems) If you don't include via script tag, you have to explicitly include all modules!
(Same goes for other module systems)
``` ```
var Y = require('yjs') var Y = require('yjs')
require('y-array')(Y) // add the y-array type to Yjs require('y-array')(Y) // add the y-array type to Yjs
@ -135,23 +140,35 @@ Here is a simple example of a shared textarea
## Get Help & Give Help ## Get Help & Give Help
There are some friendly people on [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/y-js/yjs?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) who are eager to help, and answer questions. Please join! There are some friendly people on [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/y-js/yjs?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) who are eager to help, and answer questions. Please join!
Report _any_ issues to the [Github issue page](https://github.com/y-js/yjs/issues)! I try to fix them very soon, if possible. Report _any_ issues to the
[Github issue page](https://github.com/y-js/yjs/issues)! I try to fix them very
soon, if possible.
# API # API
### Y(options) ### Y(options)
* Y.extend(module1, module2, ..) * Y.extend(module1, module2, ..)
* Add extensions to Y * Add extensions to Y
* `Y.extend(require('y-webrtc'))` has the same semantics as `require('y-webrtc')(Y)` * `Y.extend(require('y-webrtc'))` has the same semantics as
`require('y-webrtc')(Y)`
* options.db * options.db
* Will be forwarded to the database adapter. Specify the database adaper on `options.db.name`. * Will be forwarded to the database adapter. Specify the database adaper on
* Have a look at the used database adapter repository to see all available options. `options.db.name`.
* Have a look at the used database adapter repository to see all available
options.
* options.connector * options.connector
* Will be forwarded to the connector adapter. Specify the connector adaper on `options.connector.name`. * Will be forwarded to the connector adapter. Specify the connector adaper on
* All our connectors implement a `room` property. Clients that specify the same room share the same data. `options.connector.name`.
* All of our connectors specify an `url` property that defines the connection endpoint of the used connector. * All our connectors implement a `room` property. Clients that specify the
* All of our connectors also have a default connection endpoint that you can use for development. same room share the same data.
* Set `options.connector.generateUserId = true` in order to genenerate a userid, instead of receiving one from the server. This way the `Y(..)` is immediately going to be resolved, without waiting for any confirmation from the server. Use with caution. * All of our connectors specify an `url` property that defines the connection
endpoint of the used connector.
* All of our connectors also have a default connection endpoint that you can
use for development.
* Set `options.connector.generateUserId = true` in order to genenerate a
userid, instead of receiving one from the server. This way the `Y(..)` is
immediately going to be resolved, without waiting for any confirmation from
the server. Use with caution.
* Have a look at the used connector repository to see all available options. * Have a look at the used connector repository to see all available options.
* options.sourceDir (browser only) * options.sourceDir (browser only)
* Path where all y-* modules are stored * Path where all y-* modules are stored
@ -167,16 +184,27 @@ require('y-map')(Y)
// .. // ..
``` ```
* options.share * options.share
* Specify on `options.share[arbitraryName]` types that are shared among all users. * Specify on `options.share[arbitraryName]` types that are shared among all
* E.g. Specify `options.share[arbitraryName] = 'Array'` to require y-array and create an y-array type on `y.share[arbitraryName]`. users.
* If userA doesn't specify `options.share[arbitraryName]`, it won't be available for userA. * E.g. Specify `options.share[arbitraryName] = 'Array'` to require y-array and
* If userB specifies `options.share[arbitraryName]`, it still won't be available for userA. But all the updates are send from userB to userA. create an y-array type on `y.share[arbitraryName]`.
* In contrast to y-map, types on `y.share.*` cannot be overwritten or deleted. Instead, they are merged among all users. This feature is only available on `y.share.*` * If userA doesn't specify `options.share[arbitraryName]`, it won't be
* Weird behavior: It is supported that two users specify different types with the same property name. available for userA.
E.g. userA specifies `options.share.x = 'Array'`, and userB specifies `options.share.x = 'Text'`. But they only share data if they specified the same type with the same property name * If userB specifies `options.share[arbitraryName]`, it still won't be
available for userA. But all the updates are send from userB to userA.
* In contrast to y-map, types on `y.share.*` cannot be overwritten or deleted.
Instead, they are merged among all users. This feature is only available on
`y.share.*`
* Weird behavior: It is supported that two users specify different types with
the same property name.
E.g. userA specifies `options.share.x = 'Array'`, and userB specifies
`options.share.x = 'Text'`. But they only share data if they specified the
same type with the same property name
* options.type (browser only) * options.type (browser only)
* Array of modules that Yjs needs to require, before instantiating a shared type. * Array of modules that Yjs needs to require, before instantiating a shared
* By default Yjs requires the specified database adapter, the specified connector, and all modules that are used in `options.share.*` type.
* By default Yjs requires the specified database adapter, the specified
connector, and all modules that are used in `options.share.*`
* Put all types here that you intend to use, but are not used in y.share.* * Put all types here that you intend to use, but are not used in y.share.*
### Instantiated Y object (y) ### Instantiated Y object (y)
@ -186,7 +214,8 @@ require('y-map')(Y)
* The specified database adapter is loaded * The specified database adapter is loaded
* The specified connector is loaded * The specified connector is loaded
* All types are included * All types are included
* The connector is initialized, and a unique user id is set (received from the server) * The connector is initialized, and a unique user id is set (received from the
server)
* Note: When using y-indexeddb, a retrieved user id is stored on `localStorage` * Note: When using y-indexeddb, a retrieved user id is stored on `localStorage`
The promise returns an instance of Y. We denote it with a lower case `y`. The promise returns an instance of Y. We denote it with a lower case `y`.
@ -204,7 +233,8 @@ The promise returns an instance of Y. We denote it with a lower case `y`.
* y.connector.disconnect() * y.connector.disconnect()
* Force to disconnect this instance from the other instances * Force to disconnect this instance from the other instances
* y.connector.reconnect() * y.connector.reconnect()
* Try to reconnect to the other instances (needs to be supported by the connector) * Try to reconnect to the other instances (needs to be supported by the
connector)
* Not supported by y-xmpp * Not supported by y-xmpp
* y.close() * y.close()
* Destroy this object. * Destroy this object.
@ -216,12 +246,14 @@ The promise returns an instance of Y. We denote it with a lower case `y`.
* Removes all data from the database * Removes all data from the database
* Returns a promise * Returns a promise
* y.db.stopGarbageCollector() * y.db.stopGarbageCollector()
* Stop the garbage collector. Call y.db.garbageCollect() to continue garbage collection * Stop the garbage collector. Call y.db.garbageCollect() to continue garbage
collection
* y.db.gc :: Boolean * y.db.gc :: Boolean
* Whether gc is turned on * Whether gc is turned on
* y.db.gcTimeout :: Number (defaults to 50000 ms) * y.db.gcTimeout :: Number (defaults to 50000 ms)
* Time interval between two garbage collect cycles * Time interval between two garbage collect cycles
* It is required that all instances exchanged all messages after two garbage collect cycles (after 100000 ms per default) * It is required that all instances exchanged all messages after two garbage
collect cycles (after 100000 ms per default)
* y.db.userId :: String * y.db.userId :: String
* The used user id for this client. **Never overwrite this** * The used user id for this client. **Never overwrite this**
@ -247,7 +279,9 @@ localStorage.debug = 'y*'
``` ```
## Contribution ## Contribution
I created this framework during my bachelor thesis at the chair of computer science 5 [(i5)](http://dbis.rwth-aachen.de/cms), RWTH University. Since December 2014 I'm working on Yjs as a part of my student worker job at the i5. I created this framework during my bachelor thesis at the chair of computer
science 5 [(i5)](http://dbis.rwth-aachen.de/cms), RWTH University. Since
December 2014 I'm working on Yjs as a part of my student worker job at the i5.
## License ## License
Yjs is licensed under the [MIT License](./LICENSE). Yjs is licensed under the [MIT License](./LICENSE).

2
dist

@ -1 +1 @@
Subproject commit bbfb1d9bcb7902bae257a793c74fdd8c0df796f9 Subproject commit 54b0bf9e4ca6853bd0e12b907f6f15972674d04c

1
src/y.js
View File

@ -9,7 +9,6 @@ require('./Utils.js')(Y)
require('./Connectors/Test.js')(Y) require('./Connectors/Test.js')(Y)
Y.debug = require('debug') Y.debug = require('debug')
// Y.debug.log = console.log.bind(console)
var requiringModules = {} var requiringModules = {}