Mergely Reference Manual

Overview

The core of mergely is a javascript-based Longest Common Subsequence diff algorithm (LCS) 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.9.0/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.
autoupdate: Enables/disables the auto-updating of the editor when changes are made. 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'.
ignorews: Ignore white-space. Defaults to false.
lcs: Enables/disables LCS computation for paragraphs (word-by-word changes). Disabling can give a performance gain for large documents. Defaults to true.
sidebar: Enables/disables sidebar markers. Disabling can give a performance gain for large documents. Defaults to true.
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 {a:'#4ba3fa',c:'#cccccc',d:'#ff7f7f'}. The 'a' option is the color for additions, the 'c' option is the color for changes, and the 'd' option is the color for deletions.
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.
$(selector).mergely('update'): Manual update; recalculates diff and applies new settings.
$(selector).mergely('options', options): Sets the editor options. After setting, call "update".
$(selector).mergely('options'): Gets the current editor options.
$(selector).mergely('cm', side): Gets the CodeMirror editor from side.

Styles

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

.mergely-column: The editors.
.mergely-active: The active editor.
.mergely-canvas: The mergely canvas elements
mergely.a.rhs: Styles an addition to the right-hand side, regardless of starting or ending lines
mergely.a.rhs.start: Styles the starting line of an addition to the right-hand side
mergely.a.rhs.end: Styles the ending line of an addition to the right-hand side
mergely.a.rhs.start.end: Styles the start and ending line of an addition to the right-hand side when the start and end are the same line
mergely.d.lhs: Styles a deletion from the left-hand side, regardless of starting or ending lines
mergely.d.lhs.start: Styles the starting line of a deletion from the left-hand side
mergely.d.lhs.end: Styles the ending line of a deletion from the left-hand side
mergely.d.lhs.start.end: Styles the start and ending line of a deletion from the left-hand side when the start and end are the same line
mergely.c.lhs: Styles a change to the left-hand side, regardless of starting or ending lines
mergely.c.lhs.start: Styles the starting line of a change to the left-hand side
mergely.c.lhs.end: Styles the starting line of a change to the left-hand side
mergely.c.rhs: Styles a change to the right-hand side, regardless of starting or ending lines
mergely.c.rhs.start: Styles the starting line of a change to the right-hand side
mergely.c.rhs.end: Styles the starting line of a change to the right-hand side
mergely.ch.a.rhs: Styles the text of a change to the right-hand side
mergely.ch.a.lhs: Styles the text of a change to the right-hand side