Mergely Manual

Overview

The core of mergely is a javascript-based diff and customizable markup engine. Mergely provides a rich API that enables integration into your own application. It can be used as a diff tool (read-only) or as both a diff and merge tool for plain text, CSS, HTML, XML, javascript, PHP, C, C++, etc.

Basic Usage

Mergely requires jQuery and CodeMirror. A supported implementation of CodeMirror is provided in the Mergely download.

To use Mergely, you need to first load the required javascript and css files:

<script type="text/javascript"
 src="http://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js"></script>

<script type="text/javascript" src="../lib/codemirror.min.js"></script>
<link type="text/css" rel="stylesheet" href="../lib/codemirror.css" />

<script type="text/javascript" src="../lib/mergely.js"></script>
<link type="text/css" rel="stylesheet" href="../lib/mergely.css" />

Then, create a div for the editor:

<div id="compare"><div>

Then, initialize the 'compare' div with the mergely jquery plugin, setting options as required:

$(document).ready(function () {
	$('#compare').mergely({
		cmsettings: { readOnly: false, lineNumbers: true },
		lhs: function(setValue) {
			setValue('the quick red fox\njumped over the hairy dog');
		},
		rhs: function(setValue) {
			setValue('the quick brown fox\njumped over the lazy dog');
		}
	});
});

Options

The following options are available on initialization:

autoresize: Enables/disables the auto-resizing of the editor. Defaults to true.
cmsettings: CodeMirror settings (see CodeMirror). Defaults to {mode: 'application/xml', readOnly: false, lineWrapping: false, lineNumbers: true}.
editor_width: Starting width. Defaults to '400px'.
editor_height: Starting height. Defaults to '400px'.
resize_timeout: The timeout, after a resize, before Mergely auto-resizes. Only used when autoresize enabled. Defaults to 500.
change_timeout: The timeout, after a text change, before Mergely calcualtes a diff. Only used when readonly enabled. Defaults to 500.
fgcolor: The foreground color that mergely marks changes with on the canvas. Defaults to '#4ba3fa'
bgcolor: The background color that mergely fills the margin canvas with. Defaults to '#eeeeee'
fadein: A jQuery fade-in value to enable the editor to fade in. Set to empty string to disable. Defaults to 'fast'

Callbacks

The following callbacks are available on initialization:

lhs(setValue): Allows the opportunity to set the value of the left-hand editor on initialization. A handle to a setValue function is passed as an argument.
rhs(setValue): Allows the opportunity to set the value of the right-hand editor on initialization. A handle to a setValue function is passed as an argument.
height(h): Allows the opportunity to adjust the height when then the editor is resized. Return the adjusted height.
width(w): Allows the opportunity to adjust the width when the editor is resized. Return the adjusted width.
loaded(): A callback to indicate that Mergely has finished initializing and is loaded.
resized(): A callback to indicate that Mergely has been resized.

Methods

The following methods are available after initialization:

$(selector).mergely('lhs', value): Set the value of the left-hand editor. Best used with ajax.
$(selector).mergely('rhs', value): Set the value of the right-hand editor. Best used with ajax.
$(selector).mergely('swap'): Swap the content of the left and right editors.
$(selector).mergely('merge', side): Merge from side to the opposite side.
$(selector).mergely('get', side): Gets the editor contents.
$(selector).mergely('clear', side): Clears the editor contents.
$(selector).mergely('search', side, text): Search the editor for text. Repeating the call will find the next available token.
$(selector).resize(): Resize the editor.

Styles

The following styles will allow you to brand your own editor:

.mergely-column: The editors.
.mergely-active: The active editor.
mergely-c-start: Styles the starting line of a change.
mergely-c-end: Styles the ending line of a change.
mergely-a-start: Styles the starting line of an addition.
mergely-a-mid: Styles the middle text region of an addition.
mergely-a-end: Styles the ending line of an addition.
mergely-d-start: Styles the starting line of a deletion.
mergely-d-mid: Styles the middle text region of a deletion.
mergely-d-end: Styles the ending line of a deletion.
mergely-c-rem: Styles the middle text region of a deletion.
mergely-c-add: Styles the middle text region of an addition.
mergely-a-start-lhs: Styles the start of an addition on the left-hand side.
mergely-a-end-lhs: Styles the end of an addition on the left-hand side.
mergely-d-start-rhs: Styles the start of an deletion on the right-hand side.
mergely-d-end-rhs: Styles the start of an deletion on the right-hand side.