Dynamics 365 portal ACE Editor Enhancements

Web templates are extensively used to render web pages for Dynamics 365 Portals. They make use of an ACE editor that allows users to write the necessary code to display data using Liquid and to control the appearance and behavior of html elements with CSS and JavaScript.

The ACE editor used by web templates does the job, but for a tool that is being used as frequently, it could use some modifications to provide a better user experience.

The Enhancements made to the ACE editor that we describe in this article try to improve its user interface with two main goals in mind: 1.Increase the area used for writing code and 2.provide a customizable and personalized color scheme.

Let’s take a look at the form in CRM where web template information is displayed along with the ACE editor and let’s compare it to what it looks like after applying the enhancements to it. The picture below shows the form for the OOB Search web template:

As the picture shows, there is space that’s not being used all around the editor that could be used once the name, website and MIME Type (if any) of the web template have been saved. Also notice that the background color of the editor is white, which some developers may try to avoid, instead going for a dark background.

The picture below shows the same web template with the enhancements made to improve the user experience:

As the picture shows, the entire screen space is being used with the name of the web template record being shown at the top and center of the screen and the number of lines of code being twice as many. Also a dark theme has been applied to the ACE editor.

 

How are enhancements made?

The enhancements to the ACE editor are made by manipulating the html elements that make up the entire page where the editor is displayed using JavaScript and CSS.

To expand the workspace, the html elements used to display the web template information, name, website and MIME type are hidden away as well as the CRM bar to create new, deactivate, etc. Then the width and height of the html element containing the ACE editor itself are increased to use all the available space left on the screen. The following code snippet shows the code for some of the manipulations that take place to achieve an expanded workspace.

// Hide unnecessary elements at top left of web template
$innerDoc1.find("#formselectorcontainer").css("display", "none");
$innerDoc1.find("#FormSecNavigationControl-Icon-div").css("display", "none");
$innerDoc1.find(".ms-crm-InlineTabHeader).css("display", "none");
$innerDoc1.find("#FormTitle").css("width", "100%");

// Hide name and website fields
var tableRows = innerDoc1.getElementsByTagName("tr");
tableRows[1].style.display = "none";
tableRows[2].style.display = "none";

// Hide Source field label
innerDoc1.getElementsByTagName("col")[2].setAttribute("width", "0");

// Hide MIME Type field
$innerDoc1.find("#adx_mimetype_c").parent().hide();

// Hide unnecessary vertical scrollbar
$innerDoc1.find("#tdAreas").css({
    'overflow-y': "hidden",
    'background-color': "#1E1E1E"
});

// Modify main container for optimal workspace
$innerDoc1.find("#mainContainer").css({
    'max-width': "100%",
    'left': "-1px",
    'right': "0",
    'border': "0"
});

// Modify crmFormTabContainer for optimal workspace
$innerDoc1.find("#crmFormTabContainer").css({
    'margin-top': "0",
    'height': "inherit",
    'background-color': "#1E1E1E"
});

// Modify ms-crm-FormSection for optimal workspace
$innerDoc1.find(".ms-crm-FormSection").css({
    'margin': "0",
    'padding': "0",
    'border-spacing': "0",
    'margin-top': "0",
    'box-shadow': "0 -10px #1E1E1E",
     'background-color': "#1E1E1E"
});

// Set height to inherit for these elements for optimal workspace
$innerDoc1.find("#formBodyContainer, #tab0, .W.ms-crm-InlineTabBody-Read, .ms-crm-tabcolumn0, .ms-crm-FormSection-Container").css("height", "inherit");
innerDoc1.getElementsByTagName("table")[1].style.height = "inherit";

// Set height to 100% for these elements for optimal workspace
$innerDoc1.find("#WebResource_adx_source_ace_d, #WebResource_adx_source_ace").css("height", "100%");

On this code snippet, $innerDoc1 represents the document object of an iframe that contains all the elements that need to be changed. The following picture shows which elements are manipulated on the code snippet.

The section of code that starts al line 1 hides the elements enclosed in green rectangles and makes the div element that contains the web template name occupy the whole width of the screen so that the name can then be placed in the top center.

The code that starts at line 7 hides the elements enclosed in the light blue rectangle.

The code in lines 13 and 16 hides the elements enclosed in red rectangles.

The code section that starts at line 18, removes the scroll bar for editor since new scroll bar will be for the whole page.

The code at line 24 increases the horizontal space being used which be default only goes to the thick black line at the right.

The code sections that starts at line 32, 39, 49 and 53 modify div elements so that no space is left without being used at the top and bottom of the screen.

 

Modifying color scheme

The ACE editor is composed of DIV and span html elements. All of these have CSS classes applied to them that define their color. Changing the background color of the editor to a dark color, leaves all the other elements that make up the code very difficult to read since they were designed for a white background. Therefore, a whole new color scheme was necessary to make all text readable again.

There can be almost up to 40 CSS classes being applied to the elements making up the code on the editor for a given web template. So in order to make the job easier to apply new colors for each one of those classes, a new tool was created. The picture below shows this tool.

This tool was created and inserted into the web template html using JavaScript and CSS as well. It can be accessed by clicking Settings on the top right corner of the editor. From here we can do three things: Apply a color to all elements with any given class on the editor, reset the color scheme to default (more on this below) and increase/decrease the font size of all elements within the editor.

 

Applying a color

To apply a color to an element on the editor, we first need to choose an item from the dropdown element. Most of the items on the dropdown represent all the CSS classes that an element on the editor could have. The last two items on the list are specific to a couple of elements (more on this below). If we choose a class from the dropdown that an element in the current editor view has, then that element will be enclosed in a rectangle with white borders on the editor so that we can see all the elements that have that CSS class applied. Once the class is chosen, we can just click on one of the colors below the dropdown to apply that color to all elements on the editor with that class. Doing this will also display the hexadecimal representation of the color applied on the textbox below the colors section. If we had a specific color in mind, we can also provide it directly on this textbox and click the GO button to have the color applied. If it is an html color, then its name can be provided, otherwise, any other valid color representation like RGB and hexadecimal would also work.

 

Using local storage for personalized color scheme

As part of this color scheme enhancement, there is functionality that stores any changes made to the default color scheme into the browser’s local storage. So next time we open a web template, the changes made to the default color scheme will still be there as this information is being retrieved from local storage and used to override the default scheme.

 

Resetting the scheme

If we wanted to go back the default color scheme, we just need to click on the Reset Scheme button which will clear all the personalized color information from the browser’s local storage allowing the default color scheme to take place.

 

Increasing/Decreasing the font size

The font size of all text within the editor can be increased or decreased by clicking on the buttons located at the bottom of the configuration tool shown in the picture below. The idea behind this functionality was to allow users to increase the font size in case the default was difficult to read.

 

Special dropdown Items

The dropdown also has two items at the bottom of the list for elements that can be easily referred to: Line Numbers and Liquid Variable Declaration.

We choose Line Numbers when we want to change the color of the numbers representing each line of code.

A special enhancement was made so that liquid variables being declared/assigned could have their own distinctive color. Choosing Liquid Variable Declaration from the dropdown will select the elements representing these liquid variable declarations so that any given color can be applied just to them.

 

Command based code saving feature

Last but not least on the enhancements list, is the ability to save our work by pressing Ctrl-S. By default, Ctrl-S just shows a window for you to choose the location on your hard drive where you want to save the entire html document. Once the enhancements are applied, we will be able to save our code like we normally do with any other code editor, by pressing Ctrl-S.

// Functionality to save changes on the editor by pressing Ctrl-S
$editor.on("keydown", function (e) {
    if (e.ctrlKey && e.which === 83) {
        e.preventDefault();
        $innerDoc1.find(".inline-block.save-status-icon.status-icon a img").click();
    }
});

Applying Enhancements

There is an elegant and simple way to apply the JavaScript based enhancements to the web templates that requires only one click once you set everything up. And setting everything up comes down to the creation of a bookmarklet.

Boorkmarklets are simply browsers bookmarks that contain JavaScript instead of an actual URL. You can create a bookmark and paste the following into the URL field to get a “Hello World” message on your browser window:

javascript:alert(“Hello World”);

Once you create the bookmarklet with the JavaScript linked below in the GitHub Gist used to make all the enhancements described above, you just need to click it and your web template will undergo the transformation in a fraction of a second.

Javascript source code

https://gist.github.com/Manfroy/71ff254735e806603248882954f4888e

Bookmarklet source code

https://gist.github.com/Manfroy/ffe6d887f61a0875e33326acb7f1ba61