# Mergely **Repository Path**: mantishell/Mergely ## Basic Information - **Project Name**: Mergely - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 1 - **Created**: 2022-02-17 - **Last Updated**: 2022-02-17 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Mergely https://mergely.com Mergely is a JavaScript component for differencing and merging files interactively in a browser (diff/merge), providing 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. ## Installation ### Installation via webpack The recommended way to install mergely and its dependencies is to use a Node package manager (`npm` or `yarn`) and [webpack](https://webpack.js.org/). It is highly recommended that you start by cloning [mergely-webpack](https://github.com/wickedest/mergely-webpack). The webpack has everything that you need to get started. ### Angular 6.1.1 You can also use mergely within angular. You can start by cloning [mergely-angular](https://github.com/wickedest/mergely-angular). ### Installation via .tgz Unpack mergely.tgz into a folder, for example, `./lib`, and add the following to the `` of your target HTML source file. ```html ``` Create a div for the editor in ``. This example uses a style that provides 8px padding (`mergely-full-screen-8`): ```html
``` Then initialize mergely, setting [options](#options) as required. ```js $(document).ready(function () { $('#mergely').mergely(); }); ``` ### Synchronous content initialization The following example can be used to set the `lhs` and `rhs` editors synchronously (that is, when their contents are already known): ```js $(document).ready(function () { // set editor content $('#mergely').mergely({ 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'); } }); }); ``` ### Asynchronous initialization If the editor contents are retrieved asynchronously (recommended), then retrieve the editor contents and set them: ```js $(document).ready(function () { // initialize mergely $('#mergely').mergely(); // get async lhsResponse, then set lhs value $('#mergely').mergely('lhs', lhsResponse); // get async rhsResponse, then set rhs value $('#mergely').mergely('rhs', rhsResponse); }); ``` ## Options |Option|Type|Default value|Description| |------|----|-------------|-----------| |autoresize|boolean|`true`|Enables/disables the auto-resizing of the editor.| |autoupdate|boolean|`true`|Enables/disables the auto-updating of the editor when changes are made.| |bgcolor|string|`#eeeeee`|The background color that mergely fills the margin canvas with.| |change_timeout|number|`500`|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](https://codemirror.net)) that are combined with `lhs_cmsettings` and `rhs_cmsettings`.| |editor_width|string|`400px`|Starting width.| |editor_height|string|`400px`|Starting height.| |fadein|string|`fast`|A jQuery [fadein](http://api.jquery.com/fadein) value to enable the editor to fade in. Set to empty string to disable.| |fgcolor|string\|number\|object|`{a:'#4ba3fa', c:'#a3a3a3', d:'#ff7f7f', ca:'#4b73ff', cc:'#434343', cd:'#ff4f4f'}`|The foreground color that mergely marks changes with on the canvas. The value **a** is additions, **c** changes, **d** deletions, and the prefix *c* indicates current/active change (e.g. **cd** current delection).| |ignorews|boolean|`false`|Ignores white-space.| |ignorecase|boolean|`false`|Ignores case when differientiating.| |ignoreaccents|boolean|`false`|Ignores accented characters.| |lcs|boolean|`true`|Enables/disables LCS computation for paragraphs (word-by-word changes). Disabling can give a performance gain for large documents.| |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](https://codemirror.net)) 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_cmsettings|object|`{}`|The CodeMirror settings (see [CodeMirror](https://codemirror.net)) 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.| ## Options - Callbacks |Option|Parameters|Description| |------|----|-----------| |lhs|`function setValue(string)`|A callback that allows the value of the left-hand editor to be set on initialization synchronously. A handle to a `setValue` function is passed as an argument to be used to initialize the editor.| |loaded| |A callback to indicate that Mergely has finished initializing and is loaded.| |resized| |A callback to indicate that the container window has been resized.| |rhs|`function setValue(string)`|A callback that allows the value of the right-hand editor to be set on initialization synchronously. A handle to a `setValue` function is passed as an argument to be used to initialize the editor.| ## Methods ### clear Clears the editor contents for the specified `side`. #### Parameters |Name|Type|Description| |----|----|-----------| |side|string|The editor side, either `lhs` or `rhs`.| #### Example ```js $('#mergely').mergely('clear', 'lhs'); ``` ### cm Gets the CodeMirror editor for the specified `side`. #### Parameters |Name|Type|Description| |----|----|-----------| |side|string|The editor side, either `lhs` or `rhs`.| #### Example ```js $('#mergely').mergely('cm', 'lhs'); ``` ### diff Calculates and returns the current .diff file. #### Parameters None. #### Example ```js $('#mergely').mergely('diff'); ``` ### get Gets the text editor contents for the specified `side`. #### Parameters |Name|Type|Description| |----|----|-----------| |side|string|The editor side, either `lhs` or `rhs`.| #### Example ```js $('#mergely').mergely('get', 'lhs'); ``` ### lhs Sets the value of the left-hand editor. #### Parameters |Name|Type|Description| |----|----|-----------| |value|string|The editor text.| #### Example ```js $('#mergely').mergely('lhs', 'This is text'); ``` ### merge 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 ```js $('#mergely').mergely('merge', 'lhs'); ``` ### mergeCurrentChange 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 ```js $('#mergely').mergely('mergeCurrentChange', 'lhs'); ``` ### options Sets the editor options. Will automatically update with the new settings unless `autoupdate` is disabled, in which case, you will need to explicitly call `update`. #### Parameters |Name|Type|Description| |----|----|-----------| |options|object|The options to set.| #### Example ```js $('#mergely').mergely('options', { line_numbers: true }); ``` ### options Gets the editor options. #### Parameters None. #### Example ```js $('#mergely').mergely('options'); ``` ### resize Resizes the editor. It must be called explicitly if `autoresize` is disabled. #### Parameters None. #### Example ```js $('#mergely').mergely('resize'); ``` ### rhs Sets the value of the right-hand editor. #### Parameters |Name|Type|Description| |----|----|-----------| |value|string|The editor text.| #### Example ```js $('#mergely').mergely('rhs', 'This is text'); ``` ### scrollTo Scrolls the `side` to line number specified by `num`. #### Parameters |Name|Type|Description| |----|----|-----------| |side|string|The editor side, either `lhs` or `rhs`.| |num|number|The line number.| #### Example ```js $('#mergely').mergely('scrollTo', 'lhs', 100); ``` ### scrollToDiff Scrolls to the next change specified by `direction`. #### Parameters |Name|Type|Description| |----|----|-----------| |direction|string|The direction to scroll, either `prev` or `next`.| #### Example ```js $('#mergely').mergely('scrollToDiff', 'next'); ``` ### search Search the editor for `text`, 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`.| |text|string|The text to search.| #### Example ```js $('#mergely').mergely('search', 'lhs', 'needle'); ``` ### 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 ```js console.log($('#mergely').mergely('summary')); // { a: 0, c: 1, d: 0, lhsLength: 44, numChanges: 1, rhsLength: 45 } ``` ### swap Swaps the content of the left and right editors. #### Parameters None. #### Example ```js $('#mergely').mergely('swap'); ``` ### unmarkup Clears the editor markup. #### Parameters None. #### Example ```js $('#mergely').mergely('unmarkup'); ``` ### update Manually updates the editor by recalculating the diff and applying new settings. #### Parameters None. #### Example ```js $('#mergely').mergely('update'); ``` ## Events ### updated Triggered after the editor is updated. #### Example ```js $('#mergely').on('updated', () => { // updated }); ```