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. ####Note: Inject our utils as singleton would be awesome.

#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);

####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);
 }

If you want to create your own tyle, 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.

###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.

Play with it.

###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.