How to add (toggle) breakpoints on the ACE Editor gutter

Inside an integrated development environment sessions, a breakpoint is basically a marker that you can define to specify where the execution should stop when your applications is running through the IDE's debugger. Those breakpoints are stored obviously in the IDE, not in the code itself, so you can share such information between debugging sessions. Ace editor is a web based code editor component that you can embed in your applications to add a very robust "IDE". This means, that you will be also able to add breakpoints in Ace editor following some steps.

In this article, we will explain you how to set and remove breakpoints in Ace editor with JavaScript easily.

1. Enable breakpoint toggling

Ace editor offers an internal way of handling breakpoints through the guttermousedown event and the current editor session with the methods setBreakpoint, clearBreakpoint and getBreakpoints. You can easily attach this event to the current editor with the on method, providing as first argument the name of the event that you want to handle and as second argument the callback that will be executed and will receive the event. Basically, when the user clicks somewhere in the gutter this callback is executed, inside this callback you need to verify some rules:

• If the clicked element doesn't contain the ace_gutter-cell class, nothing will happen as the clicked element won't be a line and therefore won't be a breakpoint.
• If the current editor isn't focused, nothing should happen as well.
• If the clicked area on the gutter is the area after the number e.g 1, 2, 3 then nothing should happen as well.

After checking if the previous conditions weren't true, then you can continue inside the same event to handle the breakpoints positioning:

• Store the current session breakpoints into a variable obtaining them through the session.getBreakpoints method.
• Store the current row that is updated when you click inside the gutter with the current line.
• Check if in the stored breakpoints, the current row is already registered, if it is, the logic that you would apply here is to remove the breakpoint as the user clicked on an already defined breakpoint, otherwise, the breakpoint should be added to the editor.

The following logic describes how a simple initialized ace editor instance in PHP mode can be configured to process the breakpoints logic through the mentioned event and methods:

// 1. Initialize ace editor
var editor = ace.edit("editor");

// 2. Initialize with a custom theme
editor.setTheme("ace/theme/monokai");

// 3. Predefine some highlight mode, in our case PHP
editor.getSession().setMode({
    path: "ace/mode/php",
    inline: true
});

// 4. Attach an event listener to handle when the user clicks on some row of the gutter
//    In this case, the breakpoint will be added in the clicked position of the document
editor.on("guttermousedown", function(e) {
    var target = e.domEvent.target;

    if (target.className.indexOf("ace_gutter-cell") == -1){
        return;
    }

    if (!editor.isFocused()){
        return; 
    }

    if (e.clientX > 25 + target.getBoundingClientRect().left){
        return;
    }

    var breakpoints = e.editor.session.getBreakpoints(row, 0);
    var row = e.getDocumentPosition().row;

    // If there's a breakpoint already defined, it should be removed, offering the toggle feature
    if(typeof breakpoints[row] === typeof undefined){
        e.editor.session.setBreakpoint(row);
    }else{
        e.editor.session.clearBreakpoint(row);
    }

    e.stop();
});

2. Define the styles of the breakpoint

If you already tested the previous JavaScript, you will see, that although no exception is thrown, because everything is working perfectly, there are no visible breakpoints in the editor just like in other IDE's. That happens because you haven't added some style to customize the ace_breakpoint. You can add a very generic one with the following CSS:

.ace_gutter-cell.ace_breakpoint{ 
    border-radius: 20px 0px 0px 20px;
    /* Change the color of the breakpoint if you want */
    box-shadow: 0px 0px 1px 1px #248c46 inset; 
}

The following codepen shows a functional ACE Editor working with breakpoints, so click on the gutter before some number and you will see that the breakpoint will be added using a green mark:

See the Pen ACE Editor with Breakpoints by Our Code World (@ourcodeworld) on CodePen.

Obviously, you are free to modify the style of the breakpoint and customize it as you want, adding some special character like a • or something else.

Happy coding !