Upgrade Mergely from v4 to v5

The latest version of Mergely is v4 v5.

Dependencies

A separate CodeMirror dependency is no longer required.

To use Mergely, previously it was required to include the CodeMirror as a separate dependency. While this grants some control on the dependency (e.g. the plugins that can be used), for the most part it was an unnecessary burden and over-complicated usage. Now, CodeMirror is bundled with Mergely.

Initialization

Mergely is a jQuery plugin JavaScript object.

The most significant change from v4 to v5 is that Mergely is no longer a jQuery plugin, so the way Mergely is initialized has changed. Previously, you would initialize Mergely as a jQuery plugin using #mergely as the selector of the DOM node on which to bind.

$('#mergely').mergely(options);

Now, it is an object constructor that returns an instance.

const mergely = new Mergely('#mergely', options);

Select first change

Previously, the first change was automatically selected. Users could continue with prev/next. However, there was no way to not select the first change (e.g. if you only wanted to show the diff). Beginning in the v5 release, selecting the first change is optional. To select the first change, you must handle the updated event and call scrollToDiff. See the example scroll-to-first-change.html.

mergely.once('updated', () => {
    mergely.scrollToDiff('next');
});

Changes to methods

Calling Mergely methods are called via jQuery plugin arguments instance methods.

Previously, the methods were handled by the jQuery plugin as arguments.

$('#mergely').mergely('get', 'lhs');

Now, all of the methods are functions on the Mergely instance. None of the method names or argument have changed.

mergely.get('lhs');

Layout and resize

Mergely resize and layout is a pain easy to use.

Another significant change is how Mergely is added to the DOM and how it resizes. Previously, Mergely needed to be contained in container elements, and size was auto-calculated or explcitly provided. It was very clunky and unnecessary.

<div class="mergely-full-screen-8">
  <div class="mergely-resizer">
    <div id="mergely"></div>
  </div>
</div>

Now, Mergely is appended to the DOM element that you identify with an id, and the element requires an explicit height assigned to it. Mergely will automatically expand to take the full height and width of the container in which it is contained.

<div id="mergely" class="fullscreen"></div>

Styles, options, and events that were related to this have been removed.

Changes to options

Mergely has 7 0 options related to reszing and layout.

The following options have been removed.

autoresize - See Layout and resize.
editor_width - See Layout and resize.
editor_height - See Layout and resize.
fadein - Used to show the editor when it was first initialized, but now the updated event is a better solution. See the visible.html example.
fgcolor - Colors are now taken directly from the CSS.
height - See Layout and resize.
loaded - The updated event is a better solution.
resize - See Layout and resize.
resized - See Layout and resize.
width - See Layout and resize.

Changes to events

Resize notification is handled via the resize callback event.

Previously, resize notifications were handled as a callback option passed on initialization.

$('#mergely').mergely({
    resize: () => { console.log('resized!'); }
});

Now, you can register an event handler for the resized event.

mergey.on('resized', () => {
  console.log('resized!');
});

The on method is also new. It is a persistent event handler that is called every time the event is triggered. Event handlers that are registered are automatically cleaned up.

Also new is once, which is similar to on but will only be called once and will be cleaned up after.

Changes to styles

The styles for .mergely-resizer, .mergely-full-screen-0, and .mergely-full-screen-8 have been removed and are no longer necessary.

The style system employed got a major rewrite. One of the main reasons for this was that CodeMirror can style the line background separately from the text. The CSS is too complicated to explain in detail, so if you want to modify the styles, start here. The class styles have the following meanings:

lhs - The left-hand editor.
rhs - The right-hand editor.
start - The top line of a change.
no-start - There is no top line of a change in cases where an entire line was added or removed.
start - The bottom line of a change.
no-end - There is no bottom line of a change in cases where an entire line was added or removed.
ina - An inline change, text added.
ind - An inline change, text deleted.
current - The currently selected change.

Upgrading Mergely from v4 to v5