Skip to content

Server Specification

gcastagneti edited this page Jan 10, 2012 · 10 revisions

This document is intended for developers looking to create their own integration with various servers, frameworks, and languages. It outlines and details the features necessary for backend integration of Mercury, and is broken into two categories. The first category outlines the aspects for Snippets, and the second outlines the features required for Image processing (uploading, resizing, cropping etc).

Snippets

Snippets are chunks of markup that can be inserted into a region. These are added by developers and are intended to provide more complex functionality that can be placed within content. When inserting a snippet, a user is prompted to enter options. Once the options are submitted, a preview of the snippet is rendered to the page.

You can check out the example snippet written for Rails

It's worth noting that all of these urls are available in the configuration, so you may consider bundling your own configuration along with your server implementation.

Listing Snippets

When you open the Snippet Panel an Ajax request is made to the server (/mercury/panels/snippets by default) and it's expected to respond with a list of snippets. This view provides a filterable list of snippets and snippet icons, that a user can then drag into regions.

To see what this markup should look like, check the snippet view

Options View

Upon dragging a snippet icon into a region, an Ajax request is made to the server for the options form for the given snippet. The default path for this is /mercury/snippets/:name/options -- :name will be replaced with the snippet name (eg. 'example'). The server is expected to respond with an options form that's associated with the given snippet.

For an example of this view check the example options

Snippet Preview

Upon entering and submitting options for a snippet, a third Ajax request is made to the server for a preview of the snippet. The default path is /mercury/snippets/:name/preview. This is used to populate the content within the snippet, and should provide as accurate of a representation as possible for the given snippet.

For an example of this check this view

Images

Uploading Images on Drag & Drop

When a user drags an image into regions types that support it (editable and markupable), the image is automatically uploaded to the server and inserted. This section outlines what Mercury is expecting in the response.

When an image is uploaded using Mercury a multipart form is built on the client and submitted via POST using Ajax. The form submitted contains a single field named image[image] by default. It's expected that any server would treat this as an array, but you can change the name of this field in the configuration.

After successfully processing the image and writing it to disk, the server should respond with a JSON representation of the image. This JSON should be constructed like one of the following examples:

{"image":{"url":"/system/images/1/original/imagename.jpg?1309022763"}}
{"url":"/system/images/1/original/imagename.jpg?1309022763"}

The client side processes url or image.url from the JSON response and uses that to insert the image into the region. Any additional information will be disregarded.

Cropping and Resizing

Incomplete spec..