edemaine:sharejs

v0.11.1Published 9 months ago

meteor-sharejs

Meteor smart package for transparently adding ShareJS editors to an app. Includes bindings for CodeMirror and the Ace editor.

This package is only tested for meteor 1.3 or later

This is a fork of mizzao:sharejs to experiment with fixes and/or additional features:

Install

For vanilla ShareJS with text only:

$ meteor add edemaine:sharejs

For ShareJS with the Ace editor

$ meteor add  edemaine:sharejs-ace

For ShareJS with the CodeMirror editor:

$ meteor add edemaine:sharejs-codemirror

Usage

No configuration necessary for anonymous document editing. If you want to integrate with Meteor accounts, see below.

Use this helper on the client to get a textarea with the specified docid (as an argument) and with a DOM id of "editor", for example:

{{> sharejsText docid=docid id="editor"}}

Use this helper to get an Ace editor. Make sure you specify a size (via CSS) on the #editor div or you won't see anything.

{{> sharejsAce docid=docid id="editor"}}

Use this helper to get a CodeMirror editor.

{{> sharejsCM docid=docid id="editor"}}

The templates will clean themselves up when re-rendered (i.e., you have several documents and docid changes.)

Client Configuration

You can define an onError callback to define custom sharejs error handling behavior.

For the Ace and CodeMirror editors, you can define onRender and onConnect callbacks in the options hash and use it to configure the editor. onRender is called when the editor is initially rendered, and onConnect is called after each successful connection to a document.

{{> sharejsAce docid=document onRender=config onConnect=setMode id="editor"}}

All standard Ace themes and extensions are supported. Note that the helper has to return a function inside of a function:

Template.foo.config = function () {
  return function(editor) {
    # Set some reasonable options on the editor
    editor.setTheme('ace/theme/monokai')
    editor.getSession().setMode('ace/mode/javascript')
    editor.setShowPrintMargin(false)
    editor.getSession().setUseWrapMode(true)
  }
};

CodeMirror is an peer NPM dependency: you must meteor npm install codemirror. The advantage of this approach is that you can choose which version to include. To include a CodeMirror theme or addon, use an import statement to include the module or CSS. For example:

1import 'codemirror/theme/monokai.css';          // theme
2import 'codemirror/addon/fold/foldcode';        // addon
3import 'codemirror/addon/fold/foldgutter';      // addon needing CSS
4import 'codemirror/addon/fold/foldgutter.css';  // addon's CSS

Server Configuration

See this example config file for the various settings that you can use.

If you are running on mobile via Meteor's Cordova, you'll also need to specify a cors rule to allow the mobile device's localhost server to make a cross-origin request, such as the following:

1{
2  "sharejs": {
3    "options": {
4      "browserChannel": {
5        "cors": "*"
6      },
7      ...
8    }
9  }
10}

Persistence

By default, the documents and edit operations will be persisted in Meteor's Mongo database. Mongo is the recommended usage as you don't need a separate database and user integration is supported. "opsCollectionPerDoc": false can be useful to set if you don't want a separate ops collection for each document.

You can also use db.type of none to have all documents and operations in memory.

Meteor User-Accounts Integration

The Authorization was removed in version 0.9.0, because the current implementation did not added any security as Meteor.userId is not a secret token.

Advanced

You can access the ShareJS Server API via import { ShareJS } from 'meteor/edemaine:sharejs'. For example, you may want to delete documents ops when the document is deleted in your app. See the demo for an example.

Notes

  • When using the default mongo driver, you must not use collections called docs or ops. These are used by ShareJS.
  • It's best to create a Meteor.Collection for your documents which generates good unique ids to connect to ShareJS with. Use these to render the templates above. See the demo for examples.

Please submit pull requests for better features and cooperation!

Contributors