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
bgcolor
The background color that mergely fills the margin canvas with. Defaults to '#eeeeee'
change_timeout
The timeout, after a text change, before Mergely calcualtes a diff. Only used when readonly enabled. Defaults to 500.
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'.
fadein
A jQuery fade-in value to enable the editor to fade in. Set to empty string to disable. Defaults to 'fast'
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.
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.
line_numbers
Enables/disables line numbers. Enabling line numbers will toggle the visibility of the line number margins. Defaults to true.
resize_timeout
The timeout, after a resize, before Mergely auto-resizes. Only used when autoresize enabled. Defaults to 500.
rhs_margin
Location for the rhs markup margin is either right or left. Defaults to right.
Enables/disables sidebar markers. Disabling can give a performance gain for large documents. Defaults to true.
vwcolor
The margin/viewport indicator color. Defaults to 'rgba(0, 0, 200, 0.5)'
viewport
Enables/disables the viewport. Enabling the viewport can give a performance gain for large documents. Defaults to false.
wrap_lines
Enables/disables line wrapping. Enabling wrapping will wrap text to fit the editors. Defaults to false.

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('clear', side)
Clears the editor contents.
$(selector).mergely('cm', side)
Gets the CodeMirror editor from side.
$(selector).mergely('diff')
Returns the current .diff file.
$(selector).mergely('get', side)
Gets the editor contents.
$(selector).mergely('lhs', value)
Set the value of the left-hand editor. Best used with ajax.
$(selector).mergely('merge', side)
Merges whole file from side to the opposite side.
$(selector).mergely('mergeCurrentChange', side)
Merges current cahnge from side to the opposite side.
$(selector).mergely('options', options)
Sets the editor options. After setting, call "update".
$(selector).mergely('options')
Gets the current editor options.
$(selector).mergely('resize')
Resize the editor.
$(selector).mergely('rhs', value)
Set the value of the right-hand editor. Best used with ajax.
$(selector).mergely('scrollTo', side, num)
Scrolls the side to line number num.
$(selector).mergely('scrollToDiff', direction)
Scrolls to the next change specified by direction, where direction is either prev or next.
Search the editor for text. Repeating the call will find the next available token.
$(selector).mergely('swap')
Swap the content of the left and right editors.
$(selector).mergely('unmarkup')
Clears the editor markup.
$(selector).mergely('update')
Manual update; recalculates diff and applies new settings.

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