Snippets

Snippets in Mercury are really flexible and cool but there are some gotcha's.

What is a snippet?

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.

Getting started

Setting up:

• Create your Snippet folder in app/views/mercury/snippets example snippet written for Rails
• Add your snippet to the Snippet list in app/views/mercury/panels/snippets.html example list for snippet view

It's worth noting that all of these urls are customizable in mercury.js so you may consider bundling your own configuration and databases along with your server implementation.

Storing the snippets to your database

• Mercury doesn't render the snippets before saving. Make sure you save your snippets along with your content to a database. A good way is to serialize the snippet database field so that you get exact the same hash when loading your snippets to the region.

Rendering the snippets on to the page

Mercury doesn't render the snippets as content so you have to render them yourself and replace [snippet_32/1] (id and version) with the correct html code. There two steps needed here:

• Replacing the [snippet_32/1] tag with the correct snippet view and parsing the view with the correct snippet options (you got the options in your database)

You can parse with Nokogiri or you can choose to do it the easy way with Javascript. The problem with Javascript is that you can see your snippets load.

• Loading snippet options into Mercury with javascript javascript jQuery(window).bind('mercury:ready', function() { Mercury.Snippet.load({ snippet_1: {name: 'example', options: {'favorite_beer': "Bells Hopslam", 'first_name': "Jeremy"}} }); });

After loading your snippets this way Mercury can edit existing snippets.


## General information ##

### 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](https://github.com/jejacks0n/mercury/blob/master/app/views/mercury/panels/snippets.html)

### 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](https://github.com/jejacks0n/mercury/blob/master/app/views/mercury/snippets/example/options.html.erb)

### 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](https://github.com/jejacks0n/mercury/blob/master/app/views/mercury/snippets/example/preview.html.erb)

### Example Implementation ###

The [cmsimple project](https://github.com/modeset/cmsimple#snippets) has an implementation of snippets using [cells](https://github.com/apotonick/cells) and may provide insight to how to create your own implementation.