Tag Archives: getControl

Microsoft Dynamics 365: Counting Sub-grid Records and Enabling Users to Hide Empty Sub-grids

In Microsoft Dynamics 365, we can use sub-grids to present data to users in a tabular format. This is a nice and compact way of displaying data. However, sometimes there is no data in those sub-grids to display and the end users might prefer to get back that space and optimize the space on the form. In this blog post, we cover how we can dynamically obtain the number of records in a sub-grid using JavaScipt and use that information to give end users the flexibility to optimize the space on forms by hiding empty sub-grids.

There are two types of sub-grids on Dynamics 365 forms:

  • Read-only sub-grids: Show data in a tabular format but do not allow users to edit data directly on the sub-grid. To edit the data, users have to double click on the record in the grid to open the form, edit the data, and then save it.
  • Editable sub-grids: Apart from showing data in a tabular format, editable sub-grids offer rich inline editing capabilities on web and mobile clients including the ability to group, sort, and filter data within the same sub-grid so that you do not have to switch records or views. In addition to providing all these extensive editing capabilities, editable sub-grids still honor the read-only sub-grid metadata and field-level security settings as well as the general Microsoft Dynamics 365 security model.

Summary of the key syntax

Here is a high-level summary of the main Microsoft Dynamics 365 JavaScript syntax covered in this blog post.

  • Count the number of records in sub-grid, where <subgridName> is the logical name of the sub-grid :
    formContext.getControl("<subgridName>").getGrid().getTotalRecordCount();
  • Remove the blank option in an option set, where <optionsetName> is the logical name of the option set:
    formContext.getControl("<optionsetName>").removeOption("");
  • Get the option set’s selected value , where <optionsetName> is the logical name of the option set:
    formContext.getAttribute("<optionsetName>").getValue();
  • Set the selected value of an option set, where <optionsetName> is the logical name of the option set and <value> is the value the option set will be set to:
    formContext.getAttribute("<optionsetName>").setValue("<value>");
  • Enable/Disable a field, where <fieldName> is the logical name of the field and <Boolean> can be true or false (i.e. true disables field and false enables it):
    formContext.getControl("<fieldName>").setDisabled(<Boolean>);
  • Hide/Unhide section, where <nameOfTab> is the name of the tab containing the section, <nameOfSection> is the name of the section and <Boolean> can be true or false (i.e. true makes the section visible and false hides the section):
    formContext.ui.tabs.get("<nameOfTab>").sections.get("<nameOfSection>").setVisible( <Boolean>);

Application Example: Enabling Users to Hide Empty Sub-grids

Using the code below, we can give end users the flexibility to optimize the space on forms by hiding empty sub-grids. In the code below, the hideEmptyOfficesSubgrid function is the entry point and is called when saving the form and loading the form.

function hideEmptyOfficesSubgrid(executionContext) {  
    var formContext = executionContext.getFormContext();
    var operationsTabName = "tab_operations";
    var officeGridSectionName = "office_grid_section";
    var officeGridName = "office_subgrid";
    var enableOfficeGridName = "hos_enableofficesgrid";
    var no = 183840000;
    var yes = 183840001;
    formContext.getControl(enableOfficeGridName).removeOption(""); 

    setTimeout(function () {
        if (formContext.getControl(officeGridName) != null && formContext.getControl(officeGridName) != undefined) {
            var count = formContext.getControl(officeGridName).getGrid().getTotalRecordCount();
            var enableOfficeGrid = formContext.getAttribute(enableOfficeGridName);
            var enableOfficeGridCtrl = formContext.getControl(enableOfficeGridName);
            var officeGridSection = formContext.ui.tabs.get(operationsTabName).sections.get(officeGridSectionName);
            disableSubgridControlField(count, enableOfficeGridCtrl);
            hideEmptySubgrid(count, enableOfficeGrid, officeGridSection, no, yes);
        }
    }, 5000);      
}

function disableSubgridControlField(count, subgridCtrlField) {  
    if (count <= 0) 
        subgridCtrlField.setDisabled(false);       
    else if (count > 0) 
        subgridCtrlField.setDisabled(true);
}

function hideEmptySubgrid(count, subgridCtrlField, subgridSection, no, yes) {  
    if (areTheseTwoInputsIdentical(subgridCtrlField.getValue(), yes)) 
        subgridSection.setVisible(true);       
    else if (count <= 0 && (areTheseTwoInputsIdentical(subgridCtrlField.getValue(), no) || subgridCtrlField.getValue() == null)) 
        subgridSection.setVisible(false);
    else if (count > 0 && areTheseTwoInputsIdentical(subgridCtrlField.getValue(), no)) {
        subgridCtrlField.setValue(yes);
        subgridSection.setVisible(true);
    }
}

function areTheseTwoInputsIdentical(input1, input2) {
    if (input1 == input2) 
        return true;
    else 
        return false;
}

How the code works

In the first image below, the account record is not enabled for Offices (i.e. the value of Enable Office Grid option set is No). Therefore, Offices grid is empty and hidden.
Account record not enabled for Offices sub-grid

After enabling the account record for Offices by changing the value of the option set field, “Enable Offices Grid” to Yes, the Offices sub-grid shows up and we can add offices to the sub-grid as shown below. The “Enable Offices Grid” field controls the appearance and disappearance of the Offices sub-grid.
Account record enabled for Offices sub-grid

As shown in the image above, the Enabled Office Grid option set is locked as soon as we add and save records to the Offices sub-grid. This prevents a scenario of logic inconsistency where an account record has offices in it’s sub-grid and the user proceeds to change the value of the Enable Offices Grid field to No. Therefore, the Enable Office Grid field value can only be changed back to No and hide the Offices grid after the sub-grid emptied up and there are no more records in it. Therefore, using the solution above, end users can be empowered with the option of hiding empty sub-grids and optimize the space on the form.

Microsoft Dynamics 365: Notifications Using JavaScript

In Microsoft Dynamics 365, sometimes we need to send automated notifications to end users. These notifications can come from the server (i.e. back-end automation using workflows, plugins, etc) or from the code loaded in the user’s web browser (i.e. front-end or client side automation using JavaScript). The latter notifications will make up the scope of this blog post. We will cover form level notifications (with and without persistence), field level notifications and popup boxes notifications using JavaScript.

Summary of the key syntax

Here is a high-level summary of the main Microsoft Dynamics 365 JavaScript notifications demonstrated in this blog post.

  • Form Level Notifications – Set Notification
    formContext.ui.setFormNotification(message, messageType, uniqueId);
  • Form Level Notifications – Clear Notification
    formContext.ui.clearFormNotification(uniqueId);
  • Field Specific Notifications – Set Notification
    formContext.getControl(fieldLogicalName).setNotification(message, uniqueId);
  • Field Specific Notifications – Clear Notification
    formContext.getControl(fieldLogicalName).clearNotification(uniqueId);
  • Alert Box
    alert(message);
  • Confirmation Box
    confirm(message);
  • Prompt Box
    prompt(message, sampleText);

Form Level Notifications

Here is an example of form level notifications applied to the Contact entity’s form. The notification options available at form-level are: Error, Warning and Information. These notification options have different icons as shown in the image below.
Page Level Notification

Below is the JavaScript code that was used to generate the notifications shown in the image above. Therefore, every time a user opens up a contact form, these notifications will always appear at the top of the form.

function FormLevelNotification(executionContext) {
    var formContext = executionContext.getFormContext();    
    formContext.ui.setFormNotification("Example of an ERROR notification. ", "ERROR");
    formContext.ui.setFormNotification("Example of a WARNING notification. ", "WARNING");
    formContext.ui.setFormNotification("Example of an INFORMATION notification.", "INFO");    
}

Instead of having persistent notifications (ever present whenever a user opens the contact form), it is commons for organizations to implement a modified version of these notifications i.e. where the notifications above expire after a specifies amount of time. Therefore, every time a user opens a contact form (or any other form where this functionality is implemented), they get notifications similar to image above, but after a specified amount of time, the notifications disappear and user end up with form like the one below.
Page Level Notification Expired

This modified option where the form level notifications disappear after a specified amount of time can be accomplished using the code below. In code below, I have chosen an expiration time of 30 seconds. Therefore, the form level notifications would only persist for the first 30 seconds after a user opens up a contact form.

function FormLevelNotificationWithExpiration(executionContext) {
    var formContext = executionContext.getFormContext();
    var notificationTime = 30000; // 30 seconds in milliseconds 
    var errorId = "error";
    var warningId = "warning";
    var infoId = "info";
    //Set notifications
    formContext.ui.setFormNotification("Example of an ERROR notification. ", "ERROR", errorId);
    formContext.ui.setFormNotification("Example of a WARNING notification. ", "WARNING", warningId);
    formContext.ui.setFormNotification("Example of an INFORMATION notification.", "INFO", infoId);

    //Clear the notifications after the specified amount of time time e.g. 5 seconds
    setTimeout(
        function () {      
            formContext.ui.clearFormNotification(errorId);
            formContext.ui.clearFormNotification(warningId);           
            formContext.ui.clearFormNotification(infoId);
        },
        notificationTime
    );
}

Field Specific Notifications

To guide users in completing a form correctly, you can provide field specific notification like the ones below. The example below shows the subscription section on the Contact entity’s form. Logically, the Subscription Start Date must precede the Subscription End Date. Whenever a users enters a Subscription End Date that precedes the Subscription Start Date, the field level notifications appear advising the user that “The Subscription End Date cannot be before Subscription Start Date” as show below.
Field Level Notifications

The functionality shown in the image above was accomplished using the following JavaScript functions.

//Validation of the TV Subscription Dates
function TvSuscriptionDateValidation(executionContext) {
    var formContext = executionContext.getFormContext();
    var tvSubStartDateLogicalName = "hos_tvsubstartdate";
    var tvSubEndDateLogicalName = "hos_tvsubenddate";
    var startDateField = formContext.getAttribute(tvSubStartDateLogicalName);
    var endDateField = formContext.getAttribute(tvSubEndDateLogicalName);
    var endDateFieldControl = formContext.getControl(tvSubEndDateLogicalName);
    var startDate, endDate;

    if (startDateField != null && endDateField != null) {
        startDate = startDateField.getValue();
        endDate = endDateField.getValue();
        if (IsDate(startDate) && IsDate(endDate) && startDate > endDate ) {
            //Display an error message if the dates entered are logically invalid.
            endDateFieldControl.setNotification("The Subscription End Date cannot be before Subscritpion Start Date.", "tvEndDate");
            endDateField.setValue(null);
        }
        else {
            endDateFieldControl.clearNotification("tvEndDate");            
        }
    }
}

//Verify that the field contains date instead of a null value
function IsDate (input) {
    if (Object.prototype.toString.call(input) === "[object Date]") {
        return true;
    }   
    return false;
}

Popup Notifications

Sometimes you really to get the user’s attention, that is, prevent them from interacting with the form until they have acknowledged your message. To accomplish that endeavor using JavaScript, you can use the popup boxes. There are 3 types of popup boxes (i.e. alert box, confirmation box and prompt box). In this section, we will show what these popup look like in Dynamics 365 and provide an example of how to implement them.

Alert Box

Here is an example of an Alert Box in Dynamics 365. The user can acknowledge the message by pressing OK and proceed interact with the form.
Alert Box

The functionality shown in the image above was accomplished using the following JavaScript function.

function AlertBox() {
    alert("This is an example of a JavScript Alert window ");

    //Alternatively way of writing an Alert Box with the Window prefix:    
    //window.alert("This is an example of a JavScript Alert window ");
}

Confirmation Box

Here is an example of an Confirmation Box in Dynamics 365. The user is given two options. Depending on the user’s choice, you can proceed to add more logic. In this example, we use an alert box to notify user of the choice that was selected.
Confirmation Box

The functionality shown in the image above was accomplished using the following JavaScript function.

function ConfirmBox() {    
    var confirmationText;
    if (confirm("Would you like to proceed?")) {
        confirmationText = "You pressed OK!";
    } else {
        confirmationText = "You pressed Cancel!";
    }
    //Using the alert notification to show the option selected
    alert(confirmationText);

    //Alternatively way of writing an Confirm Box with the Window prefix:    
    //window.confirm("Press a button: 'OK' or 'Cancel'");
}

Prompt Box

Here is an example of an Prompt Box in Dynamics 365. The user is given a text box where they can enter an answer as well as two options (i.e. OK and Cancel). Depending on the user’s responses, you can proceed to add more logic. In this example, we use an alert box to notify user of the text that was entered, if they click on OK.
Prompt Box

The functionality shown in the image above was accomplished using the following JavaScript function.

function PromptBox() {
    var userText = prompt("Please enter your name below", "This is sample text ");
    //Using the alert notification to show the text entered in the prompt box
    alert("You said your name is: \n" + userText);   

    //Alternatively way of writing an Prompt Box with the Window prefix:
    //window.prompt("Please enter some text below", "This is sample text ");
}

Best Practices and Recommendations

For demonstration purposes in this blog post, I included the notification messages in the code. However, for easier maintenance and to give more flexibility to the end users, who may not be Dynamics 365 software developers, it is recommended to put the notification messages in the Dynamics 365 Configuration Data and then create JavaScript helper function(s) that retrieve the data at runtime using a key. Using this approach, end users with the appropriate security roles can update the JavaScript notification messages anytime without calling upon the services of a Dynamics 365 software developer with JavaScript experience.