Skip to content

Latest commit

 

History

History
174 lines (112 loc) · 10.3 KB

README.md

File metadata and controls

174 lines (112 loc) · 10.3 KB
Raw

Create - On-site web editing interface

Create logo

Create, from the Midgard Project, is a comprehensive web editing interface for Content Management Systems. It is designed to provide a modern, fully browser-based HTML5 environment for managing content. Create can be adapted to work on almost any content management backend.

Midgard Create user interface, in March 2011 Midgard Create user interface, in March 2011

Features

  • Making RDFa-annotated content on pages editable
  • Managing collections of content (add, remove)
  • Local, in-browser storage and retrieval of unsaved content
  • Adaptable connector for communicating with the back-end system
  • Running workflows (approval, etc.) for content items
  • Browsing and reverting content history
  • Easy rebranding of the interface with some CSS

Future plans

Dependencies

  • Hallo - distraction-free content editor (optionally, Aloha Editor)
  • VIE - editable RDFa library
  • Backbone.js - client-side management of models, views, and collections
  • jQuery UI - widget and effect library
  • Modernizr - HTML5 browser compatibility library

Integrating Create with your CMS

In nutshell, you have to do the following:

  • Annotate your content with RDFa
  • Include the Create JavaScript file(s)
  • Implement Backbone.sync for your back-end

RDFa annotations

Create uses the VIE library to turn content in your pages into editable Backbone models. This process is guided by RDFa annotations that let your web framework to explain the content model being shown on the pages.

Annotating entities

The main editable unit in Create is an entity. For example, you could make a blog post editable with this mark-up:

<div about="http://example.net/blog/my-post" typeof="sioc:Post">
  <h1 property="dcterms:title">Blog post title</h1>
  <div property="sioc:content">
    ...
  </div>
</div>

This is enough to tell Create that the div contains an editable blog post entity. The important points here are:

  • about gives the identifier of an object. The identifiers should be URIs, but basically anything that your back-end will understand is fine
  • typeof is not necessary, but it tells us that the editable entity is a blog post
  • property tells that the h1 contains the title of the post, and the div contains the contents. These become attributes of our Backbone model instance

Annotating collections

Relationships between entities allow you to communicate structured content to Create, which will turn them into Backbone collections. For example, to annotate a list of blog posts:

<div about="http://example.net/blog/" rel="dcTerms:hasPart">
  <div about="http://example.net/my-post">...</div>
  <div about="http://example.net/second-post">...</div>
</div>

This tells Create that there is a blog entity, which contains a collection of two posts. The important things here are:

  • The first about identifies also the blog post container as an entity
  • rel tells that there is a relation between the blog container, and the blog posts under it

Create will use the first entity inside a collection as a "template", and knows how to add or remove entities from the collection. In Edit mode the user would see an Add button next to the collection.

Starting Create

Starting Create:

jQuery(document).ready(function() {
    jQuery('body').midgardCreate({
        url: '/some/backend/url'
    });
});

You can pass Create configuration options when calling the midgardCreate widget. For example, to use Aloha Editor instead of Hallo, do:

jQuery('body').midgardCreate({
    url: '/some/backend/url',
    editor: 'aloha'
});

Communications with the back-end

Create communicates with your server-side system using Backbone.sync. By default this means that we send and retrieve content encoded in JSON-LD over XmlHttpRequest calls.

If you're using this default approach, it is important to provide the URL of the endpoint on your server that you want Backbone and Create to talk with. This can be done by passing a string when initializing midgardCreate:

jQuery('body').midgardCreate({
    url: '/some/backend/url'
});

When implemented this way, all communications from Create will happen using normal RESTful HTTP calls to that URL.

  • Creating a new object makes a HTTP POST to the URL
  • Updating or fetching an object makes a HTTP PUT or HTTP GET to that URL with the id of the object appended (for example /some/backend/url/objectId)

If you need more flexibility with your URL structure, you can also pass a function that returns the URL for an object.

You can override this default communications layer by implementing your own Backbone.sync method. Some examples:

Events

Create is an event-based user interface. Normally integrators shouldn't need to deal with these events, but they're explained here in case of some customization needs.

  • midgardcreatestatechange: when user switches between browse and edit modes. Event data contains an object with key state telling the state being changed to
  • midgardtoolbarstatechange: when user opens or minimizes the toolbar. Event data contains an object with key display telling the new state
  • midgardeditableenable: when an object has been made editable. Event data contains an object with key instance providing the Backbone model instance and entityElement providing the element containing the object
  • midgardeditabledisable: when an object has been made non-editable. Event data contains an object with key instance providing the Backbone model instance and entityElement providing the element containing the object
  • midgardeditableactivated: when a particular property of an object has been activated in an editor. Event data contains keys property, instance, element and entityElement
  • midgardeditabledeactivated: when a particular property of an object has been deactivated in an editor. Event data contains keys property, instance, element and entityElement
  • midgardeditablechanged: when a particular property of an object has been changed in an editor. Event data contains keys property, instance, element and entityElement

You can use normal jQuery event methods to deal with these events.

Read more

Similar projects

Using Aloha Editor

By default, Create uses the Hallo Editor. To use Create with Aloha Editor you need to:

Using Aloha Editor with Create is covered by Aloha's FOSS License Exception:

Aloha Editor’s Free and Open Source Software ("FOSS") License Exception allows developers of FOSS applications to include Aloha Editor with their FOSS applications. Aloha Editor is typically licensed pursuant to version 3 of the General Afero Public License ("AGPLv3"), but this exception permits distribution of Aloha Editor with a developer’s FOSS applications licensed under the terms of another FOSS license listed below [MIT license is included], even though such other FOSS license may be incompatible with the AGPLv3.

Status

This repository contains the new version of Create that is having its dependencies on Midgard MVC removed so that it can work with any back-end system. This work is still ongoing, and so most of the functionality doesn't work yet.

Running Unit Tests

Direct your browser to the test/index.html file to run Create's QUnit tests.

Unit tests on Node.js

You need Node.js and NPM. Then just run:

$ npm install --dev
$ npm test

Continuous integration

Create uses Travis for continuous integration. Simply add your fork there and every time you push you'll get the tests run.

Build Status