Raptor Editor

Mar 21, 2014 in Text Editor 10363 views

Download

Overview
Documents
Demos

User Rating: 3/5 ( 4 votes)

Your Rating:

CONTENT EDITORS & PUBLISHERS

Quick and Easy Content Editing: What you see is really what you get - edit content in place exactly as it would display once published, no more switching between edit and preview modes.
Packed With Features: Raptor comes packed with user-friendly features for publishing and editing HTML content including; flexible docking options, advanced 'clean pasting' and much more.
Drop Dead Sexy: Raptor has been designed from the ground up to be beautifully user-friendly and delightful to use and can be themed to suit your software.

DEVELOPERS

Well Documented: Working with Raptor is made easy with detailed API documentation and guides for installing, integrating and configuring Raptor Editor.
Backed By Unit Tests: Raptor is backed by a comprehensive suite of built-in unit tests and comes packaged with a visual test interface.
Modern Standards & Technology: Raptor uses modern standards and technology including HTML5, jQuery and an extensible plugin architecture.
Free & Open Source: Raptor Editor is Open Source and completely feee to use under GPLv3. Flexible commercial licenses are available for non-copyleft closed source use.
Themeable: Raptor comes ready to use with a beautiful custom theme and several alternatives but can be fully skinned to suit any visual design.
Modular and Extensible: Plugins made easy. Raptor is built with an extensible plugin architecture making it easy to enhance functionality or add features.

BASIC INTEGRATION

Raptor may be integrated into a site many ways. This article aims to cover the simplest integration possible.

STEP 1: INCLUDE RAPTOR IN YOUR PAGE

The Raptor editor is a pure JavaScript application, and is most commonly included as one file. To get started download Raptor and add it to your project so it is available at /javascripts/raptor.min.js. Now the following snippet to the of your page:

<head>
//...
<script type="text/javascript" src="/javascripts/raptor.min.js"></script>
//...
</head>

STEP 2: INITIALISE RAPTOR

Raptor can be used to enable users to edit any element on a HTML page. The example below shows how to make all div's with the class "raptor" editable.

<div class="raptor">
    <p>Raptor may be integrated into a site many ways. This article aims to cover the simplest integration possible.</p>
</div>
<script>
    $(function() {
        $('.raptor-editable').raptor();
    });
    /*
    Note: if using a Raptor no conflict build jQuery will be renamed to "raptor"
    So you would initialise Raptor like:
        raptor(function($) {
            $('.raptor-editable').raptor();
        });
    */
</script>

BASIC SAVING

Raptor offers two save implementation types: JSON and REST. In this tutorial, a very basic JSON save implementation will be introduced.

STEP 1: INITIALIZATION OPTIONS

When applying Raptor to an element or group of elements, the editor's behaviour, and that of its plugins, may be modified by passing an options hash as the first parameter. In the below example, basic save JSON configuration is being passed.

STEP 2: ON THE SERVER

The second part of saving Raptor content must take place on the server. Following is a very basic skeleton for processing the data posted by Raptor's save JSON plugin with PHP.

<?php
 
// Handle incorrect requests
if (!isset($_POST['raptor-content'])) {
    header('HTTP/1.0 400 Bad Request');
    exit;
}
 
$raptorContent = json_decode($_POST['raptor-content']);
foreach($raptorContent as $content) {
    // process content here
}
 
header('HTTP/1.0 200');
 
// Report success
echo json_encode(array(
    'status' => 'ok'
));

STEP 3: CREATE!

How you process the posted content is entirely up to you.

SAVING CONTENT WITH SAVE REST

The Rest save method is simple to implement on your server.

A working example can be found here:
https://github.com/PANmedia/Raptor/blob/master/example/save-rest/example.php

Example JavaScript

The following is an example of how you might configure Raptor to save content with REST.

$('#element-to-edit').raptor({
    plugins: {
        // The save UI plugin/button
        save: {
            // Specifies the UI to call the saveRest plugin to do the actual saving
            plugin: 'saveRest'
        },
        saveRest: {
            // The URI to send the content to
            url: 'save.php',
            // Returns an object containing the data to send to the server
            data: function(html) {
                return {
                    id: this.raptor.getElement().data('id'),
                    content: html
                };
            }
        }
    }
});

Example HTML

A very simple example of HTML that this technique might be applied to.

Example Rails Controller

The following Rails code describes how you might access and save the content.

RAPTOR CONFIGURATION OPTIONS OVERVIEW

This article will detail the standard Raptor Editor configuration options and describe how they affect the editor's behaviour.

enableHotkeys

This option determines whether the Raptor Editor instance should process hotkeys as registered by UI components or plugins. True by default.

hotkeys

Any custom hotkey objects. These should be constructed as below.

layouts

The default layouts to use for this instance. An example using the default toolbar & hover panel is shown below.

plugins

Plugin option overrides should go here. An example showing how to configure the dock plugin is shown below.

ui

UI component option overrides should go here.

namespace

A namespace used to prevent persistence keys from conflicting with other stored values. null by default.

unify

A switch that indicates whether some events should be automatically applied to all editors that have this same switch set to true

persistence

A switch that indicates whether Raptor should store some user-modified settings. By default this is set to true.

persistenceName

The name used to store any persisted values under. Defaults to uiEditor.

unloadWarning

This switch determines whether the user is warned if they try to navigate away from the page without saving any changes made to Raptor content.

autoEnable

If this is set to true, Raptor will enable itself as soon as possible.

partialEdit

If this is set to a valid jQuery selector, only the element(s) selected will be editable when the editor instance is instantiated. Defaults to false.

enablePlugins

This switch specifies whether all plugins should be enabled, or only those specified with the pluginsconfiguration option.

disabledPlugins

An array of names of plugins that should be disabled.

enableUi

A switch specifying whether all UI components should be automatically enabled. Defaults to true.

disabledUi

An array of UI components to explicitly disable

replace

If this switch is set to true, the element being edited will be replaced with a div. The value / html of the element being edited will be updated automatically when Raptor's content is modified.

This switch is especially useful when combined with autoEnable and applied to a textarea. This will convert the textarea to an attractive and usable WYSIWYG editing area. For an example of this, see Enabling / Disabling Features.

replaceStyle

This is a list of styles that will be copied from the element replaced using replace. The default array of styles is sufficient for most instances. If not, copy the default list and add your own.

baseClas

A string that will be used as first segment of all dynamically generated class names for Raptor elements. Defaults to raptor

cssPrefix

The CSS class prefix that is prepended to the classname of any styling elements inserted by Raptor, for example by the bold UI component.

draggable

If this switch is set to true, an undocked Raptor instance may be dragged by the user.

EVENTS

Raptor has custom events that occur when editing. You can bind to event using initialisation options, or when developing plugins.

Options Example

This example loads the source of the block from a data base 64 encoded attribute before enabling editing, then on save it puts the new source back into the data attribute.

$('.editable').raptor({
    bind: {
        enabling: function() {
            var element = this.getElement(),
                source = element.attr('data-source');
            if (source) {
                element.html(atob(source));
            }
        },
        saved: function() {
            var html = this.getHtml();
            this.getElement()
                .attr('data-source', btoa(html));
        }
    }
});

Plugin Example

This example is taken from this dock plugin.

DockPlugin.prototype.init = function() {
    ...
    this.raptor.bind('toolbarReady', function() {
        if (docked) {
            this.toggleState();
        }
    }.bind(this));
    ...
}

Event List

cancel -- Triggered when cancelling editing
change -- Triggered after a change to the block source is made 
cleaned -- Triggered when the source code is the same as it's original source code
destroy -- Triggered when Raptor is destroyed (this is when plugins should clean up)
dirty -- Triggered when the source code is edited for the first time (opposite of clean)
disabled -- Triggered when editing is disabled
enabled -- Triggered when editing is enabled
enabling -- Triggered just before editing is enabled, which allows modification of the source before editing
historyChange -- Triggered when the history (undo/redo) is changed
html -- Triggered the the source of the block is set via raptor.setHtml(html)
layoutHide -- Triggered to alert all layouts to hide themselves 
layoutReady -- Triggered by a layout when it is ready
layoutShow -- Triggered to alert all layouts to show themselves
ready -- Triggered when Raptor is ready
resize -- Triggered when something resizes which indicates layouts/plugins should adjust accordingly 
saved -- Triggered on successful save
selectionChange -- Triggered when the select is changed
selectionCustomise -- Triggered before applying an action which allows plugins to provide a custom selection (such as only the table column content rather than an entire row)