diff --git a/README.md b/README.md index 695b12a0..d51e3c15 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,10 @@ # ![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. -It is fairly easy to get started, as Yjs hides most of the complexity of concurrent editing. -For additional information, demos, and tutorials visit [y-js.org](http://y-js.org/). +Yjs is a framework for offline-first p2p shared editing on structured data like +text, richtext, json, or XML. It is fairly easy to get started, as Yjs hides +most of the complexity of concurrent editing. For additional information, demos, +and tutorials visit [y-js.org](http://y-js.org/). ### Extensions 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 * 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 @@ -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 | |[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 | -|[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/)| ##### 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 | ## 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 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. ``` ``` @@ -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 ``` -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') 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 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 ### Y(options) * Y.extend(module1, module2, ..) * 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 - * Will be forwarded to the database adapter. Specify the database adaper on `options.db.name`. - * Have a look at the used database adapter repository to see all available options. + * Will be forwarded to the database adapter. Specify the database adaper on + `options.db.name`. + * Have a look at the used database adapter repository to see all available + options. * options.connector - * Will be forwarded to the connector adapter. Specify the connector adaper on `options.connector.name`. - * All our connectors implement a `room` property. Clients that specify the same room share the same data. - * 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. + * Will be forwarded to the connector adapter. Specify the connector adaper on + `options.connector.name`. + * All our connectors implement a `room` property. Clients that specify the + same room share the same data. + * 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. * options.sourceDir (browser only) * Path where all y-* modules are stored @@ -167,16 +184,27 @@ require('y-map')(Y) // .. ``` * options.share - * Specify on `options.share[arbitraryName]` types that are shared among all users. - * E.g. Specify `options.share[arbitraryName] = 'Array'` to require y-array and create an y-array type on `y.share[arbitraryName]`. - * If userA doesn't specify `options.share[arbitraryName]`, it won't be available for userA. - * 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 + * Specify on `options.share[arbitraryName]` types that are shared among all + users. + * E.g. Specify `options.share[arbitraryName] = 'Array'` to require y-array and + create an y-array type on `y.share[arbitraryName]`. + * If userA doesn't specify `options.share[arbitraryName]`, it won't be + available for userA. + * 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) - * Array of modules that Yjs needs to require, before instantiating a shared type. - * By default Yjs requires the specified database adapter, the specified connector, and all modules that are used in `options.share.*` + * Array of modules that Yjs needs to require, before instantiating a shared + 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.* ### Instantiated Y object (y) @@ -186,7 +214,8 @@ require('y-map')(Y) * The specified database adapter is loaded * The specified connector is loaded * 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` 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() * Force to disconnect this instance from the other instances * 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 * y.close() * 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 * Returns a promise * 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 * Whether gc is turned on * y.db.gcTimeout :: Number (defaults to 50000 ms) * 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 * The used user id for this client. **Never overwrite this** @@ -247,7 +279,9 @@ localStorage.debug = 'y*' ``` ## 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 Yjs is licensed under the [MIT License](./LICENSE). diff --git a/dist b/dist index bbfb1d9b..54b0bf9e 160000 --- a/dist +++ b/dist @@ -1 +1 @@ -Subproject commit bbfb1d9bcb7902bae257a793c74fdd8c0df796f9 +Subproject commit 54b0bf9e4ca6853bd0e12b907f6f15972674d04c diff --git a/src/y.js b/src/y.js index ff7a9b98..7b828d97 100644 --- a/src/y.js +++ b/src/y.js @@ -9,7 +9,6 @@ require('./Utils.js')(Y) require('./Connectors/Test.js')(Y) Y.debug = require('debug') -// Y.debug.log = console.log.bind(console) var requiringModules = {}