Skip to content

Commit

Permalink
Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
@mixonic
mixonic committed Jul 27, 2015
1 parent ee2e1a4 commit 9d417f0
Showing 1 changed file with 56 additions and 79 deletions.
135 changes: 56 additions & 79 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,58 +1,38 @@
## ContentKit-Editor [![Build Status](https://travis-ci.org/bustlelabs/content-kit-editor.svg?branch=master)](https://travis-ci.org/bustlelabs/content-kit-editor)
## Content-Kit Editor [![Build Status](https://travis-ci.org/bustlelabs/content-kit-editor.svg?branch=master)](https://travis-ci.org/bustlelabs/content-kit-editor)

ContentKit is a modern WYSIWYG editor supporting interactive cards. Try a
demo at [http://content-kit.herokuapp.com/](http://content-kit.herokuapp.com/).
Content-Kit is a WYSIWYG editor supporting rich content via cards. Try a
demo at [content-kit.herokuapp.com](http://content-kit.herokuapp.com/).

ContentKit articles (we will use the term article, but any kind of content could
be authored) are built from models. Models represent rows of content, and can
be static or dynamic.
* It makes limited use of Content Editable, the siren-song of doomed web editor
technologies.
* Content-Kit is designed for *rich* content. We call these sections of an
article "cards", and implementing a new one doesn't require an understanding
of Content-Kit internals. Adding a new card take an afternoon, not several
days.
* Posts are serialized to a JSON payload called **Mobiledoc** instead of to
HTML. Mobiledoc can be rendered for the web, mobile web, or in theory on any
platform. Mobiledoc is portable and fast.

For example, the teardown of an article might look like:
**FIXME** this needs to be updated:
To learn more about Content-Kit in the abstract,
[read this announcement blog post](http://madhatted.com/2015/7/27/announcing-content-kit-and-mobiledoc).

```
┌──────────────────────────────────────────────────────────────────────────────┐
│ ┌──────────┐ │
│ │ Article │ │
│ └──────────┘ │
│┌────────────────────────────────────────────────────────────────────────────┐│
││ ┌──────────────┐ ││
││ │ MarkupModel │ ││
││ └──────────────┘ ││
││ <h2>One Weird Trick</h2> ││
│└────────────────────────────────────────────────────────────────────────────┘│
│┌────────────────────────────────────────────────────────────────────────────┐│
││ ┌──────────────┐ ││
││ │ BlockModel │ ││
││ └──────────────┘ ││
││ <p> ││
││ You will never guess what <i>happens</i> ││
││ when these cats take a <b>bath</b> ││
││ </p> ││
│└────────────────────────────────────────────────────────────────────────────┘│
│┌────────────────────────────────────────────────────────────────────────────┐│
││ ┌──────────────┐ ││
││ │ EmbedModel │ ││
││ └──────────────┘ ││
││ <img src="http://some-cdn.com/uploaded.jpg" /> ││
││ <!-- this HTML is generated by the embed API endpoint at edit-time --> ││
│└────────────────────────────────────────────────────────────────────────────┘│
│┌────────────────────────────────────────────────────────────────────────────┐│
││ ┌────────────────────────┐ ││
││ │ BlockModel (type CARD) │ ││
││ └────────────────────────┘ ││
││ node.innerHTML = 'Cards can change content at render time. For example, ││
││ use an Ember component'; ││
│└────────────────────────────────────────────────────────────────────────────┘│
└──────────────────────────────────────────────────────────────────────────────┘
```
Content-Kit saves posts to
**[Mobiledoc](https://github.com/bustlelabs/content-kit-editor/blob/master/MOBILEDOC.md)**.

### Usage

ContentKit is attached to a DOM node when the `Editor` factory is instantiated.
The `ContentKit.Editor` class is invoked with an element to render into and
optionally a Mobiledoc to load. For example:

```js
var editor = new ContentKit.Editor(this.element, options);
var simpleMobiledoc = [[], [
[1, "p", [
[[], 0, "Welcome to Content-Kit"]
]]
];
var element = $('#editor')[0];
var options = { mobiledoc: simpleMobiledoc };
var editor = new ContentKit.Editor(element, options);
```

`options` is an object which may include the following properties:
Expand All @@ -63,67 +43,53 @@ var editor = new ContentKit.Editor(this.element, options);
* `spellcheck` - a boolean option enabling spellcheck. Default is true.
* `autofocus` - a boolean option for grabbing input focus when an editor is
rendered.
* `serverHost` - a URL prefix for embed and image API request. **[FIXME Remove]**
* `cards` - an object describing available cards.

### Public Editor API

* `editor.loadPost(post)` - render the editor with a post. **[FIXME Implement]**
* `editor.serializePost()` - serialize the current post for persistence. **[FIXME Implement]**

### Deploy the demo website
### Editor API

The demo website is hosted at github pages.
To publish a new version do:

* `npm run build-website`. This builds the website into `website/` and commits it
* `npm run deploy-website`. Pushes the `website/` subtree to the `gh-pages` branch at github

Visit [http://bustlelabs.github.io/content-kit-editor/demo](http://bustlelabs.github.io/content-kit-editor/demo).
* `editor.serialize()` - serialize the current post for persistence. Returns
Mobiledoc.
* `editor.destroy()` - teardown the editor event listeners, free memory etc.

### Contributing

Running ContentKit tests and demo server locally requires the following dependencies:
Fork the repo, write a test, make a change, open a PR.

* [node.js](http://nodejs.org/) ([install package](http://nodejs.org/download/)) or `brew install node`
* `broccoli`, via `npm install -g broccoli-cli`

### Tests
#### Tests

Install npm and bower:

* `bower i i`
* `npm i`
* [Node.js](http://nodejs.org/) is required
* `npm install -g npm && npm install -g bower`
* `broccoli`, via `npm install -g broccoli-cli`
* `bower install`
* `npm install`

Run tests via the built-in broccoli server:

* `npm run serve`
* `broccoli serve`
* `open http://localhost:4200/tests`

Or run tests via testem:
Or run headless tests via testem:

* `npm test`

To view the demo:
To quickly view the demo:

* `broccoli serve`
* open http://localhost:4200/demo
* (Note that image uploads and embeds are not currently working)
* Image uploads and embeds are not supported running in this manner.

#### To Do

Bring back image uploads and embed. Notes below:

For uploads and embeds to work, you will have to configure AWS and
Embedly keys as environment variables:
To view the full demo with uploads and embed, you will have to configure AWS
and Embedly keys as environment variables:

```bash
export AWS_ACCESS_KEY_ID=XXXXXX
export AWS_SECRET_ACCESS_KEY=XXXXXX
export EMBEDLY_KEY=XXXXXX
```

Also, set the `bucketName` in `server/config.json` with the name of your AWS
Also set the `bucketName` in `server/config.json` with the name of your AWS
S3 bucket for uploading files.

Then to boot the server:
Expand All @@ -132,4 +98,15 @@ Then to boot the server:
node server/index.js
```

And visit http://localhost:5000/dist/demo/index.html
And visit [localhost:5000/dist/demo/index.html](http://localhost:5000/dist/demo/index.html)

#### Re-deploy the demo

The demo website is hosted at github pages. To publish a new version:

* `npm run build-website` - This builds the website into `website/` and commits it
* `npm run deploy-website` - Pushes the `website/` subtree to the `gh-pages` branch at github

Visit [bustlelabs.github.io/content-kit-editor/demo](http://bustlelabs.github.io/content-kit-editor/demo).

*Initial development of Content-Kit was generously funded by [Bustle Labs](http://www.bustle.com/labs). Bustle Labs is the tech team behind the editorial staff at [Bustle](http://www.bustle.com), a fantastic and successful feminist and women’s interest site based in NYC.*

0 comments on commit 9d417f0

Please sign in to comment.