kattappa

Kattappa

A block based Rich Text editor.

It uses:

• ReactJS for its UI.
• Quill for rich text editing support.
• fetch for ajax calls to server (used when image files are required to be uploaded).

Installation

• For browserify users:

  • npm install kattappa.
  • var Kattappa = require('kattappa');

• To directly use in browser:

  • bower install kattappa.
  • CSS:
    • <link rel="stylesheet" type="text/css" href="bower_components/quill/dist/quill.base.css">
    • <link rel="stylesheet" type="text/css" href="bower_components/quill/dist/quill.snow.css">
    • <link rel="stylesheet" type="text/css" href="kattappa.css">. (Used for basic styling of the blocks. You can extend these to be what you want.)
  • Javascript:
    • <script type="text/javascript" src="bower_components/react/react-with-addons.min.js"></script>
    • <script type="text/javascript" src="bower_components/quill/dist/quill.min.js"></script>
    • <script src="bower_components/fetch/fetch.js"></script>
    • <script type="text/javascript" src="kattappa.js"></script>

• Or Download the latest release here.

Usage

It is available in the window global as Kattappa.

• Html:

  • <div id="editor-ui"></div>

• Script:

  • First create an editor instance.
  • Then mount it to the desired DOM node.

var editor = React.createElement(Kattappa.Editor);
React.render(editor, document.getElementById('editor-ui'));

The editor has a Save button when there are 1 or more blocks. To get the current block content, you can pass a callback function onSave as a React prop that will be called whenever Save button is clicked. This callback receives the current blocks array.

var editor = React.createElement(Kattappa.Editor, {
    onSave: function(blocks) {
        console.log('This is the list of current blocks.');
        console.log(blocks);
    }
});
React.render(editor, document.getElementById('editor-ui'));

If you already have a list of blocks (that may have been previously saved on the server): * You can first fetch the block list from the server. * Pass the list to the editor instance as a React prop. * Make sure each block has a key key. This is used by React and facilitates easy manipulation of position (up, down or remove block). * If the blocks don't have a key, you can just generate keys for each of them in the browser using the utility function provided Kattappa.uuid(). * The key functionality applies to each of the items in UL or OL.

var blocks = function() {
    var blocks = [];
    // fetch from server, and assign it to blocks.
    for(var i=0; i < blocks.length; i++) {
        if(!blocks[i].key) {
            blocks[i].key = Kattappa.uuid();
        }
        if(blocks[i].type === Kattappa.Blocks.UL.Name || blocks[i].type === Kattappa.Blocks.OL.Name) {
            for(var j = 0; j < blocks[i].content.length; j++) {
                if(!blocks[i].content[j].key) {
                    blocks[i].content[j].key = Kattappa.uuid();
                }
            }
        }
    }
    return blocks;
};
var editor = React.createElement(Kattappa.Editor, {
    blocks: blocks,
    onSave: function(blocks) {
        console.log('This is the list of current blocks.');
        console.log(blocks);
    }
});
React.render(editor, document.getElementById('editor-ui'));

Image upload

• By default, the image block just renders the image using createObjectURL.
• If you want the image to also be uploaded to the server, you can do this:
  • Change the value of UploadUrl to your server's endpoint
    • Kattappa.Block.Image.UploadUrl = '/upload_image
  • If UploadUrl is provided, the Image block will send a POST request to the url with image key having the selected image file and it expects a json reponse from the server of the following format:

{
    "type": "success",
    "message": "http://absoluteurl.to/the/uploaded/image.jpg"
}

Goodies

• Kattappa supports the following embeds out of the box:

  • Instagram
  • Youtube
  • Vimeo

• Also has Twitter embed in kattappa.embed.js. But this also has a dependency on server.

• The Twitter embed expects:

  • The server to implement a /tweet endpoint that will be called with the url=url_to_twitter_status query string.
  • The response from the server should be a json with the following structure:

  {
      "html": "The html retrived when visiting 'https://api.twitter.com/1/statuses/oembed.json?url=url_to_twitter_status' directly"
  }
  

• Current Blocks:

  • Text
  • Quote
  • Image
  • Horizontal Break
  • Ordered List
  • Unordered List
  • Embeds
    • Twitter (has dependency on server)
    • Instagram
    • Vimeo
    • Youtube

• Extra features:

  • Blocks can be rearranged.
  • Existing blocks can be deleted.
  • Automatic image upload if UploadUrl is provided.

Todo

• Add instructions to create custom blocks.

Known issues

• Better handling of Return key press when inside one of the Text blocks. (Text, Quote, H2, UL, OL)
• If a Twitter embed block is rearranged to make it go upwards, the rendered part disappears from the UI.

Made while working @ http://scroll.in