Mergely
Mergely is a JavaScript component for differencing and merging files interactively in a browser (diff/merge). It provides a rich API that enables you to easily integrate Mergely into your existing web application. It is suitable for comparing text files online, for example, .txt, .html, .xml, .c, .cpp, .java, etc.
Mergely has a JavaScript implementation of the Longest Common Subsequence (LCS) diff algorithm, and a customizable markup engine. It computes the diff within the browser.
This is the latest version 5. The previous version 4 can be found here.
Usage
Usage via React
The easiest and recommended way to use Mergely is with the mergely-react component.
npm install mergely-reactUsage via Angular
There is an Angular component for Mergely mergely-angular, but it is out of date. I will accept MR for anyone willing to do the work.
Usage via webpack
The source repository mergely-webpack contains an example of how to get started with a new project that uses mergely and webpack.
git clone --depth 1 https://github.com/wickedest/mergely-webpack.git my-project
cd my-project
rm -rf .git
Usage via CDN
Unpack mergely.tgz into a folder, for example, ./lib, and add the following to the <head> of your target HTML source file.
<script src="https://cdnjs.cloudflare.com/ajax/libs/mergely/5.0.0/mergely.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/mergely/5.0.0/mergely.css"></script>Synchronous initialization
If the editor contents are retrieved asynchronously (recommended), then retrieve the editor contents and set them:
<body>
<div id="compare"></div>
<script>
const doc = new Mergely('#compare', {
lhs: 'the quick red fox\njumped over the hairy dog',
rhs: 'the quick brown fox\njumped over the lazy dog'
});
</script>
</body>Asynchronous initialization
Mergely will emit an updated event when the editor is first initialized, and each time one of the editors changes. You can listen for one event to perform one-time initialization.
<body>
<div id="compare"></div>
<script>
const doc = new Mergely('#compare');
doc.once('updated', () => {
doc.lhs('the quick red fox\njumped over the hairy dog');
doc.rhs('the quick brown fox\njumped over the lazy dog');
// Scroll to first change on next update
doc.once('updated', () => {
doc.scrollToDiff('next');
});
});
</script>
</body>Options
| Option | Type | Default value | Description |
|---|---|---|---|
| autoupdate | boolean | true | Controls whether or not the changed event will trigger a diff. |
| bgcolor | string | #eeeeee |
The background color for the left-hand and right-hand margins. |
| change_timeout | number | 150 |
The timeout, after a text change, before Mergely calculates a diff. Only used when readonly is enabled. |
| cmsettings | object | {mode: 'text/plain', readOnly: false} |
CodeMirror settings (see CodeMirror) that are combined with lhs_cmsettings and rhs_cmsettings. |
| ignorews | boolean | false |
Ignores white-space. |
| ignorecase | boolean | false |
Ignores case. |
| ignoreaccents | boolean | false |
Ignores accented characters. |
| lcs | boolean | true |
Enables/disables LCS computation for paragraphs (char-by-char changes). Disabling can give a performance gain for large documents. |
| lhs | boolean,function handler(setValue) |
null |
Sets the value of the editor on the left-hand side. |
| license | string | lgpl |
The choice of license to use with Mergely. Valid values are: lgpl, gpl, mpl or lgpl-separate-notice, gpl-separate-notice, mpl-separate-notice (the license requirements are met in a separate notice file). |
| line_numbers | boolean | true |
Enables/disables line numbers. Enabling line numbers will toggle the visibility of the line number margins. |
| lhs_cmsettings | object | {} |
The CodeMirror settings (see CodeMirror) for the left-hand side editor. |
| resize_timeout | number | 500 |
The timeout, after a resize, before Mergely auto-resizes. Only used when autoresize enabled. |
| rhs | boolean,function handler(setValue) |
null |
Sets the value of the editor on the right-hand side. |
| rhs_cmsettings | object | {} |
The CodeMirror settings (see CodeMirror) for the right-hand side editor. |
| rhs_margin | string | right |
Location for the rhs markup margin. Possible values: right, left. |
| sidebar | boolean | true |
Enables/disables sidebar markers. Disabling can give a performance gain for large documents. |
| vpcolor | string | rgba(0, 0, 200, 0.5) |
The margin/viewport indicator color. |
| viewport | boolean | false |
Enables/disables the viewport. Enabling the viewport can give a performance gain for large documents. |
| wrap_lines | boolean | false |
Enables/disables line wrapping. Enabling wrapping will wrap text to fit the editors. |
Constructor
constructor(selector: string, options?: object)
Parameters
| Name | Type | Description |
|---|---|---|
| selector | string | A CSS selector used to uniquely identify the DOM element that should be used to bind the instance of Mergely. |
| options | object | Configuration options for the instance. |
Example
new Mergely('#editor', { ignorews: true });Methods
clear(side: string)
Clears the editor contents for the specified side.
Parameters
| Name | Type | Description |
|---|---|---|
| side | string | The editor side, either lhs or rhs. |
Example
doc.clear('lhs');cm(side: string)
Gets the CodeMirror editor for the specified side.
Parameters
| Name | Type | Description |
|---|---|---|
| side | string | The editor side, either lhs or rhs. |
Example
doc.cm('lhs');diff()
Calculates and returns the current .diff file.
Parameters
None.
Example
doc.diff();get(side: string)
Gets the text editor contents for the specified side.
Parameters
| Name | Type | Description |
|---|---|---|
| side | string | The editor side, either lhs or rhs. |
Example
doc.get('lhs');lhs(value: string)
Sets the value of the left-hand editor.
Parameters
| Name | Type | Description |
|---|---|---|
| value | string | The editor text. |
Example
doc.lhs('This is text');merge(side: string)
Merges whole file from the specified side to the opposite side.
Parameters
| Name | Type | Description |
|---|---|---|
| side | string | The editor side, either lhs or rhs. |
Example
doc.merge('lhs');mergeCurrentChange(side: string)
Merges the current change from the specified side to the opposite side.
Parameters
| Name | Type | Description |
|---|---|---|
| side | string | The editor side, either lhs or rhs. |
Example
doc.mergeCurrentChange('lhs');on(event: string, handler: function)
Sets up a function to be called when the specified event is emitted. The event handler will be automatically deregistered on unbind.
Parameters
None.
Example
doc.on('updated', () => console.log('updated!'));once(event: string, handler: function)
Sets up a function to be called when the specified event is emitted. The event handler will be automatically deregistered after the handler is called.
Parameters
None.
Example
doc.unbind();options(options?: object)
Gets or sets the editor Options. With no arguments, the function will return the currenty configured options. When supplied options to change, the editor will automatically update with the new settings.
Parameters
| Name | Type | Description |
|---|---|---|
| options | object | The options to set. |
Example
const currentOptions = doc.options();
doc.options({ line_numbers: true });resize()
Resizes the editor. It must be called explicitly if autoresize is disabled.
Parameters
None.
Example
doc.resize();rhs(value: string)
Sets the value of the right-hand editor.
Parameters
| Name | Type | Description |
|---|---|---|
| value | string | The editor text. |
Example
doc.rhs('This is text');scrollTo(side: string, lineNum: integer)
Scrolls the editor side to line number specified by lineNum.
Parameters
| Name | Type | Description |
|---|---|---|
| side | string | The editor side, either lhs or rhs. |
| lineNum | number | The line number. |
Example
doc.scrollTo('lhs', 100);scrollToDiff(direction: string)
Scrolls to the next change specified by direction.
Parameters
| Name | Type | Description |
|---|---|---|
| direction | string | The direction to scroll, either prev or next. |
Example
doc.scrollToDiff('next');search(side: string, needle: string)
Search the editor for needle, scrolling to the next available match. Repeating the call will find the next available token.
Parameters
| Name | Type | Description |
|---|---|---|
| side | string | The editor side, either lhs or rhs. |
| needle | string | The text for which to search. |
Example
doc.search('lhs', 'banana');summary()
Gets a summary of the editors. Returns an object with summarized properties:
| Name | Description |
|---|---|
| a | The number of added lines. |
| c | The number of changed lines. |
| d | The number of deleted lines. |
| lhsLength | The number of characters in the lhs text. |
| rhsLength | The number of characters in the rhs text. |
| numChanges | The total number of changed lines. |
Parameters
None.
Example
console.log(doc.summary());
// { a: 0, c: 1, d: 0, lhsLength: 44, rhsLength: 45, numChanges: 1 }swap()
Swaps the content of the left and right editors. The content cannot be swapped if either editor is read-only.
Parameters
None.
Example
doc.swap();unmarkup()
Clears the editor markup.
Parameters
None.
Example
doc.unmarkup();unbind()
Unbinds and destroys the editor DOM.
Parameters
None.
Example
doc.unbind();Events
Event handlers are automatically unregistered when unbind is called.
changed
Triggered when one of the editors change, e.g. text was altered. The change_timeout controls how much time should pass after the changed event (e.g. keypress) before the updated event is triggered.
Example
mergely.once('changed', () => { console.log('changed!'); }
mergely.on('changed', () => { console.log('changed!'); }resized
Triggered after the editor is resized.
Example
mergely.once('resized', () => { console.log('resized!'); }
mergely.on('resized', () => { console.log('resized!'); }updated
Triggered after the editor finishes rendering. For example, text updates, options, or scroll events may trigger renders. This event is useful for handling a once-off initialization that should occur after the editor's first render.
Example
mergely.once('updated', () => { console.log('updated!'); }
mergely.on('updated', () => { console.log('updated!'); }