Skip to content
This repository

etch

branch: master

This branch is 0 commits ahead and 0 commits behind master

moved documentation into readme file

modified etch.js a bit to better be ready to incorporate etch-image when it is ready
fixed weirdness with the 'clear formatting' icon that was bugging me
fixed issue where mouse.editor listener was doubling up
switched demo to use latest versions of backbone, underscore, and jquery
latest commit 253b0abaf0
Josh Nielsen authored
Octocat-spinner-32 demo moved documentation into readme file January 26, 2014
Octocat-spinner-32 scripts moved documentation into readme file January 26, 2014
Octocat-spinner-32 styles moved documentation into readme file January 26, 2014
Octocat-spinner-32 .gitignore moved documentation into readme file January 26, 2014
Octocat-spinner-32 README.md moved documentation into readme file January 26, 2014
Octocat-spinner-32 license.txt moved documentation into readme file January 26, 2014
README.md

About

Etch is a content editor built on Backbone.js and is designed to be easily plugged into your Backbone app or stand alone.

Include Dependencies

Etch depends on jQuery, Underscore, Backbone, as well as Rangy if you need support for legacy browsers (IE8 and prior).

You can exclude Rangy and shave 41k off of your footprint if you don't need legacy support.

Once you have the dependencies squared away simply include the etch.js script after them and before the script where you define your Models/Views.

At this point your scripts section should look something like this:

  <!-- dependencies -->
  <script src="/media/scripts/lib/jquery.js"></script>
  <script src="/media/scripts/lib/underscore.js"></script>
  <script src="/media/scripts/lib/backbone.js"></script>

  <!-- etch -->
  <script src="/media/scripts/etch/scripts/etch.js"></script>

  <!-- Your code -->
  <script src="/media/scripts/article.js"></script>

Ensure that your scripts are in the right order or everything will likely be broken.

Also you need to add etch.css to your stylesheets

  <link rel="stylesheet" href="/media/scripts/etch/styles/etch.css" />

Building The Model

This part is simple, we just define a model and give it a url and some defaults. Your model will probably end up being more complex but this is all it takes to get Etch working.

  var article = Backbone.Model.extend({
    url: '/some/api/url/',

    defaults: {
      title: 'Default Title',
      body: 'Default body text'
    }
  });

Building The View

Basically all we need to do is call etch.editableInit when a user clicks (mousedown) on an editable element. Because of how backbone delegates events we need to call an intermediate function, editableClick, which references etch.editableInit.

  var articleView = Backbone.View.extend({
    events: {
      'mousedown .editable': 'editableClick'
    },

    editableClick: etch.editableInit
  });

etch.editableInit handles everything else for you except for saving. Etch will trigger a 'save' event on your model when the save button is clicked. All we need to do is listen for it by adding a binding to the view like so:

  var articleView = Backbone.View.extend({
    initialize: function() {
      _.bindAll(this, 'save');
      this.model.bind('save', this.model.save);
    },

    events: {
      'mousedown .editable': 'editableClick'
    },

    editableClick: etch.editableInit
  });

Customizing

You may have noticed that the demo had different buttons in the editor widget depending on if you were editing the body or the title. Etch allows you to customize which buttons to show on a given 'editable' by adding a data-button-class attribute to the element.

The default classes are:

  etch.config.buttonClasses = {
    'default': ['save'],
    'all': ['bold', 'italic', 'underline', 'unordered-list', 'ordered-list', 'link', 'clear-formatting', 'save'],
    'title': ['bold', 'italic', 'underline', 'save']
  };

The 'default' button class will be used if no button class is defined on the element.

Defining your own button classes can be accomplished by extending etch.config.buttonClasses. Here we override 'default' to add more buttons and add a 'caption' class.

  _.extend(etch.config.buttonClasses, {
    'default': ['bold', 'italic', 'underline', 'save'],
    'caption': ['bold', 'italic', 'underline', 'link', 'save']
  });

The order of buttons in the array is how they will be presented in the editor widget.

If the class '.editable' causes conflicts for you or you need to change it for any reason you can do so by setting etch.config.selector.

  etch.config.selector = '.my-new-editable-class';

All functions are public and can be overridden to customize functionality

For instance, if you want to create a custom popup for the link url prompt:

  etch.views.Editor.prototype.urlPrompt = function(callback) {
    // Custom popup code to get url
    callback(url)
  }
Something went wrong with that request. Please try again.