ACE Utils API

ACE utils class provides visualizations for:

• Text highlighting of expressions within given ranges [Ace's markers]

• A popup when hovering over expressions within given ranges showing their matching values [Tooltips]

• Text and style in the gutter and actions when hovering over them [Ace's gutter decorations]

Getting Ace Utils

The first step is to get the library in your class.

Import the library

Add the following import at the top of your code:

import {AceUtils} from '../utils/ace-utils';

Remember that the path when importing is relative.

Instantiate

let aceUtils = new AceUtils();

I would suggest to instantiate it in your class constructor and keep it as an attribute of your class.

Ace Utils Data Model and Trace Service Traces

Ace Utils uses a general data structure with ranges as data model. Trace Service provides data structures that satisfy such model, the traces. For operations in the trace, check Trace Helper.

A way to use Ace Utils is when iterating over a trace:

for(let key in trace){
	if(trace.hasOwnProperty(key)){
		let element = trace[element];
		if(element.range){
// your operations
		}
	}
	
}

A method like isPositioninRange() offers Ace's format for a given position and resolves if a trace element has matching range.

Adding Text Highlighting

You will need an instance of Ace Utils, a collection of elements with range property and if desired, a CSS style for customization of your markers.

Get an Ace Marker Manager

It requires an Ace editor to work, if your class already have one, use that one instead.

let aceEditor= ace.edit('aceJsEditorDiv'); // example
let aceMarkerManager = aceUtils.makeAceMarkerManager(aceEditor);

Make sure your items have a range property

Ace Utils needs that the elements of your collection (e.g. an array) have range properties:

let element1Range =
 {start: {row: 0, column:0}, end: {row: 0, column:10}};
let elementsWithRangeProperty =
 [{elementProperty: "a property of element 1", range: element1Range }];

First, "element1Range" uses Ace's range format(Trace Service results use the same format). This the only attribute "updateAceMarkers" will read from your array ("elementsWithRangeProperty" in this case). If an element that does not have a range, it will be ignored and the highlighting will continue.

Highlight!

Once you get the manager, you can call the markers update method:

aceUtils.updateAceMarkers(aceMarkerManager, elementsWithRangeProperty);

Note. updateAceMarkers method will remove your previous markers before adding the new ones. Make sure your logic is compatible with this behavior.

Warning: Be sure that you are not accessing the DOM when you make such call. It will alter your page "silently". Please analyze Trace Search, I added a timeout to avoid such problem.

Customize your text highlighting

Create your own style

This is the default style for the marker renderer:

 .ace-chrome .ace_marker-layer .expression-range {
   position: absolute;
   background: rgb(250, 250, 155);
   border: 1px solid rgb(200, 200, 150);
 }

WARNING: is "ace_marker-layer" not "ace-marker-layer". Thanks Varun =)

If you want to create your own style, use this one as a template. Remember to keep the tag ".ace_marker-layer" (Ace will enforce this match), and the position to be absolute. You can add your highlighter code in the src/ace/ace-editor.css, and add the marker reference in getAvailableMarkers() in src/utils/ace-utils.js.

Update the manager

aceMarkerManager.markerRenderer = "expression-range";

In this case, "expression-range" should be replaced with your style tag. Ace allows to send a renderer function, that is the reason for the name. When a string is sent, it will match for CSS style instead.

You can also choose to highlight the text in the range or the whole line:

aceMarkerManager.markerType= "text";

The previous case is for text, use "fullLine" to highlight the whole line (you knew that =]).

Finally, you can decide if you want the highlight in front or in the back of the text:

aceMarkerManager.inFront= false;

If false like the previous snippet, it will put your highlight behind the text.

Where do I see text highlighting being used?

Check our trace search component.

You can try this style jsfiddle.

What if I want to have different highlighters?

Of course you can. Create an Ace marker manager per each set of elements you want to highlight. Remember to define different CSS styles for each of them as well.

More info?

Ace's API.

Ace's Google group.

[Documentation in progress -->]

Adding Tooltips

Adding gutter decorations

Ace uses default gutter decorations that show text only: annotations. They could be for errors, warnings, and info. A common issue is to decide if annotations are enough for your cases. The rule of the thumb is: do you want to show Ace annotations with yours or more that text is to be shown? if so use decorations, otherwise use annotations.

Annotations are not be extended( based on the Gutter code). You can add decorations to change the CSS class of the gutter cell and override the gutter renderer to add custom text. Any other visual widget must be added from scratch. Obtaining configuration values from the gutter will help you shape your widgets accordingly.

To add custom decorations we need a CSS class and the row where we want to add it. As a collection, your decorations should be removed in proper system events such document or gutter changes.

Defining your class

please take a look and customize it. You can also send yours.

Adding decorations

Removing decorations

Adding or removing gutter decorations trigger "changeBreakpoint" events. That is, do not work with them when capturing that event.