colonel.md

Colonel

1. Options
2. Walk-through

Options

Name	Description
el	A DOM element used to render the editor
blocks	The initial starting "seed" blocks for the instance
blockTypes	Block Types to use for this editor, see blockTypes.md
maxChildren	The maximum number of root level blocks
maxDepth	The maximum depth blocks can be nested
allow	A whitelist of block type ids.

Walk-through

Integrating Colonel Kurtz remains relatively low level. The motivation behind this is simply to evaluate how the library is used on projects before prematurely optimizing for less useful situations.

That means that there are a couple of required steps, unlike the experience of many jQuery plugins (such as Chosen)

Before we begin, we should note that for this example (and for Colonel Kurtz generally) we assume the following:

1. Your project is setup with something that can compile CommonJS from npm, such as browserify or webpack.
2. Familiarity and ability to include Sass

Basic markup

Colonel Kurtz must be instantiated onto a page, however it doesn't create its own container markup. For the purposes of this example, we'll work with the following html:

<div id="container"></div>
<input type="hidden" id="input" />

#container will eventually contain our instance of Colonel Kurtz. #input is a hidden input so that we can dump the latest JSON from the editor in without exposing JSON to the end user.

Setting up Colonel

Assuming markup from the prior section, let's begin. First, if you haven't pulled down Colonel Kurtz from npm, install it:

npm install --save colonel-kurtz

After that finishes, we need to select the container for Colonel Kurtz and the input that we want to update.

import Colonel from 'colonel-kurtz'

let container = document.querySelector('#container')
let input = document.querySelector('#input')

let editor = new ColonelKurtz({
  el: container,
  blocks: input
})

editor.start()

That's it, for now at any rate. Since #input is a DOM element, the blocks key will safely pull JSON out of the input and parse it for you. It also accepts a JavaScript array, if you would like to do this process manually.

editor.start() tells the editor to boot up and render. This is an important step! It tells Colonel Kurtz to run through all of its available plugins (plugins are not discussed in this tutorial) and then renders the editor to the screen.

Basic Styling

Colonel Kurtz comes with a Material Design inspired set of styles. These are available in the ./style directory of this repo, however we also include it with the npm package to make sure that future updates do not make it impossible to retrieve older style revisions.

For this tutorial, we will not go into detail about how to include Sass on your project, however it is important to note that the main entry point for our stylesheet is at ./style/colonel.scss.

Adding a new block type

At this point, the editor is set up. However you can't manage any content yet. This is because no block types have been defined.

A block type is a simple JavaScript object of settings. Colonel Kurtz comes with a Youtube plugin out of the box. Let's include it in our editor:

import Colonel from 'colonel-kurtz'
import Youtube from 'colonel-kurtz/addons/youtube'

let container = document.querySelector('#container')
let input = document.querySelector('#input')

let editor = new ColonelKurtz({
  el: container,
  blocks: input,
  blockTypes: [
    {
      id: 'youtube',
      label: 'Youtube',
      component: Youtube
    }
  ]
})

editor.start()

In the code above, we've added a blockTypes field that includes the YouTube plugin. Let's go over the fields for a block type that we've passed here:

1. id: A unique identifier for the block type. This maps to the type property saved for a block and helps the editor know what React Component to use when editing the content.
2. label: This is a display name for the block type in the editor. When only one block type exists, it will not display. However when more than one block type is included the "plus" button to add a new block will expand into a menu of available block types. Additionally, this label is used for accessibility purposes in other parts of the editor.
3. component: A React component. Colonel Kurtz sends information to this component that allows it to present information for a block and update it in a particular way.

When these new settings have been added, you should see a "plus" button in your editor. This should create a new YouTube block.

You may also notice that this block does not look fantastic. The Youtube addon relies on a common library of utilities for Colonel Kurtz addons. The stylesheet for those components can be found here:

https://github.com/vigetlabs/colonel-kurtz/blob/master/style/addons/common.scss

Saving data

Colonel Kurtz editors emit an event when they change. You can listen to this and update your input with:

// Assuming code from prior section
editor.listen(function() {
  input.value = JSON.stringify(editor)
})

This works because editors implement a toJSON method that serializes down blocks into a consistent structure.

Moving forward

That's it! Actually, not at all. There are a ton of things you can do with Colonel Kurtz. Many of them are documented in the ./docs folder, or used in the example project found at ./example.

Our documentation still needs improvement. Please help us by filing an issue on Github if anything is unclear.