-
Notifications
You must be signed in to change notification settings - Fork 529
Server Specification
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).
Saving is done using the Mercury.saveURL. This will default to whatever the url is that you're editing, but can be changed in several ways. Primarily though, setting Mercury.saveURL before saving will work.
An Ajax request is made to that url with the POST method by default, and the server is expected to respond with a 200 on success, and any other failure status code on failure (eg, 404, 500). The response can contain any valid JSON, and can be blank if you don't have any need for it -- this is there in case you want to customize it with error messages etc.
Much of this can be customized based on your server needs, but it's primarily done following the REST pattern.
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.
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
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
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
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.
Incomplete spec..