Dialog Builder Documentation

Contents

Installation and Usage

  1. Download and install the latest managed solution. If updating from the v2.1 unmanaged solution, you will need to delete the solution (not the components) before importing the new managed solution. If you've previously created the alert.js files using your own publisher prefix, it is recommended that you replace these with the 'mag_' files contained in the managed solution for better support going forward, however if you need to keep using your own prefix for now, get in contact with us to discuss options.
  2. Purchase a license, or continue to use the full feature trial version for 30 days.
  3. Create a new JavaScript web resource or use an existing web resource to create your custom functions which will call the alert.js functions.
  4. Add a reference to the alert.js web resource on your form or view (the other required files are loaded automatically).
    • For forms, this is simply added through the form properties.
    • For views, add a "JavaScript Function Action" to the "Command Actions" for your button command, calling the alert.js web resource, where the function is isNaN. Using the Ribbon Workbench to edit the command is recommended.
  5. Add a reference to your custom JavaScript web resource where you're making the calls to alert.js. This should be added after the reference to alert.js.
  6. Call your custom function from your JavaScript library, e.g. from the command bar button, or from the form onload event.

For more information, check out our Dialog Builder product page, including a walkthrough video, screenshots, and features. You can also view our release notes for information on the latest new features.

Code Samples

Check out some interactive code samples showing various use cases.

Base Dialog object

Create a new instance of a dialog, passing in all the options required for the dialog. This can then be used and reused with the supported functions, e.g. show(), close(), etc. Not all options are available for all types of dialogs. See each individual function for more information about which options are available for each. Options that are not available will be ignored, or may have unexpected results.

var dialog = new Dialog(options)

Parameters

options

object (recommended). An object containing all the options for displaying a dialog. 

{
    id: "saleDialog",
    title: "Would you like to create a sale?",
    icon: "QUESTION"
}

The options object can contain the following properties:

id

  • string (recommended). Set a custom ID to allow you to stack multiple dialogs without the previous being overwritten.
    "saleDialog"

title

  • string (recommended). The main (large) text to display inside the message. This should not exceed a single line on the dialog.
    "Would you like to create a sale?"

message

  • string (optional). The sub-heading (smaller) text to display directly below the title. This should not exceed a single line on the dialog. 
    "This will create and open the new sale record."

content

  • string | HTMLElement (optional). This displays below the title, message, and icon, and fills the remaining space on the dialog (centered vertically). This value accepts HTML strings, and also HTML elements, so if you want to display more complex messages, you can pass in custom HTML. You can also display plugin traces or error messages here, or even create more complex HTML objects like iframes etc spanning multiple lines, displaying a scrollbar as needed. Note: use the htmlEncode function to display things like XML.
    "This will create and open the new sale record."

fields

  • object[] (optional). The fields to display inside the dialog.
    [
    new Dialog.Input({ id: "name", label: "Name" }),
    new Dialog.MultiLine({ id: "details", label: "Details" })
]
    • Each field object should be created using the following constructors (depending on the field type):
    • Group: new Dialog.Group(options, extraAttributes) - Used to display a group of fields in a contained section.
      • options: object (required). The options for the field. The following properties can be set.
        • id: string (recommended). A unique identifier for the group. This will be used as the 'id' property when getting prompt responses.
        • label: string (optional). The label text above the group.
        • inline: boolean (optional). Sets the label to be aligned above the group (like a section), or beside the group inline (like a field). Defaults to false.
        • fields: object[] (required). The fields to display inside the group. These fields are created exactly as above.
        • columns: string | number (optional). Allows for settings the "columns" CSS property on the group to display fields in more than 1 column, and optionally with a min width, e.g. "100px 2". If not specified, group fields will display in a single column by default.
      • extraAttributes: object (optional). Extra HTML attributes that will be added to the div containing the fields. This can include things like: { style: "max-height: 100px" } to add a scrollbar to the group if the fields exceed the max height.
    • Input: new Dialog.Input(options, extraAttributes) - Creates an <input> element, used for text, number, date, checkbox, radio, file, and other HTML input field types.
      • options: object (recommended). The options for the field. The following properties can be set.
        • id: string (recommended). A unique identifier for the field. This will be used as the 'id' property when getting prompt responses.
        • label: string (recommended). The label text above or beside the field (depending on the type). Checkbox and Radio inputs have the label to the right. If no label is provided, the input will be displayed without a label.
        • inline: boolean (optional). Sets the label to be aligned above the field, or beside the field inline. Defaults to true.
        • value: any (optional). The default value for the input. The type of object depends on the 'type' used for this input. E.g. 'number' takes a Number, 'date' and 'datetime-local' take a Date object, 'text' takes a String, and 'radio' or 'checkbox' take a bool.
        • type: string (optional). The type of HTML input to use. This will default to 'text' if not specified. Any HTML input type can be used, but the following are supported:
          • text
          • number. Specify 'min' and 'max' etc using extraAttributes.
          • date. Does not display a date picker in Internet Explorer.
          • datetime-local. Does not display a date picker in Internet Explorer, or Firefox/Safari web.
          • radio. Specify 'name' using extraAttributes.
          • checkbox
          • file. Specify 'multiple' using extraAttributes.
          • range
      • extraAttributes: object (optional). Extra HTML attributes that will be added to the input. This can include things like: { name: "radiolist" } to add a name grouping to radio buttons.
    • MultiLine: new Dialog.MultiLine(options, extraAttributes) - Creates a <textarea> element for capturing multiple lines of text.
      • options: object (recommended). The options for the field. The following properties can be set.
        • id: string (recommended). A unique identifier for the field. This will be used as the 'id' property when getting prompt responses.
        • label: string (recommended). The label text above the field. If no label is provided, the text area will be displayed without a label.
        • inline: boolean (optional). Sets the label to be aligned above the field, or beside the field inline. Defaults to true.
        • value: string (optional). The default value for the text area.
      • extraAttributes: object (optional). Extra HTML attributes that will be added to the text area. This can include things like: { maxlength: 200 } to set a max length on the text area. Or { style: "height: 200px" } to set a custom height for the text area.
    • OptionSet: new Dialog.OptionSet(options, extraAttributes) - Creates a <select> element with <option> elements to select a specific value or values.
      • options: object (required). The options for the field. The following properties can be set.
        • id: string (recommended). A unique identifier for the field. This will be used as the 'id' property when getting prompt responses.
        • label: string (recommended). The label text above the field. If no label is provided, the option set will be displayed without a label.
        • inline: boolean (optional). Sets the label to be aligned above the field, or beside the field inline. Defaults to true.
        • value: number | string | string[] (optional). The default value for the option set. This should be the 'value' of the option to select by default. If the 'multiple' additionalAttribute is set, this value can be an Array of Strings to select multiple values by default.
        • options: object[] (required). The options to display in the option set. This value uses the same structure as the .getOptions() function on a CRM optionset field. Each object in the array consists of the following properties:
          • text. string (required). The text to display in the option set for this option.
          • value. number | string (required). The value returned if this option is selected. Options with a value of -1 (as a number) or "null" (as a string) will be ignored. Options with a value of "" (empty string) will return a null value if selected.
          • title. string (optional). The text to display in the tooltip when hovering over the option. If not specified, this will default to the option 'text'.
      • extraAttributes: object (optional). Extra HTML attributes that will be added to the option set. This can include things like: { multiple: "multiple", style: "height: 100px" } to create a multi-select option set with a fixed height of 100px.
    • Lookup: new Dialog.Lookup(options, extraAttributes) - Creates a lookup to a Dataverse table to select one or more rows. Only supported in Dynamics 365 version 9.0 and above
      • options: object (required). The options for the field. The following properties can be set.
        • id: string (recommended). A unique identifier for the field. This will be used as the 'id' property when getting prompt responses.
        • label: string (recommended). The label text above the field. If no label is provided, the lookup will be displayed without a label.
        • inline: boolean (optional). Sets the label to be aligned above the field, or beside the field inline. Defaults to true.
        • value: object[] (optional). The default value for the lookup. This should follow the exact same structure as CRM when using .getValue() from a lookup field. The lookup object should contain 'id', 'name', and 'entityType'. Although this is an Array, only one lookup object is supported.
        • entityTypes: string[] (required). The entity types to look up. E.g. ["contact"] for a contact lookup, or ["account", "contact"] for a customer lookup.
        • disableMru: boolean (optional). Decides whether to display the most recently used (MRU) items. Available only for Unified Interface.
        • allowMultiSelect: boolean (optional). Allows for selecting and returning multiple values from the lookup window.
        • callback: function (optional). Allows for executing a callback function immediately after a lookup value is selected, i.e. to automatically trigger the next step in a process. The first parameter of this function is the Array of selected Lookup Objects, with the same structure as a CRM lookup using .getValue(). The lookup object consists of a 'name', 'id', and 'entityType'.
        • filters: object[] (optional). Used to filter the lookup results. These are added on top of the default lookup view filters. Each object in the array contains the following properties:
          • filterXml: string (required). A FetchXML custom filter to apply on top of the lookup view filters. This should not be URL encoded.
          • entityLogicalName: string (required). The entity type to apply this filter to.
        • viewIds: string[] (optional). The view ID's to include in the lookup window. The first view is set as the default view. If not specified, all views are displayed.
      • extraAttributes: object (optional). Extra HTML attributes that will be added to the lookup text box.
    • Custom: new Dialog.Custom(options) - Used to display custom text or HTML in place of a field.
      • options: object (recommended). The options for the field. The following properties can be set.
        • id: string (recommended). A unique identifier for the field. This will be used as the 'id' property when getting prompt responses.
        • label: string (optional). The label text above the field. If no label is provided, the text area will be displayed without a label.
        • inline: boolean (optional). Sets the label to be aligned above the field, or beside the field inline. Defaults to true.
        • value: string | HTMLElement (recommended). The custom HTML or element to display in place of the field. This can be static text, HTML, or a combination.

buttons

  • Type: object[] (optional). The buttons to display inside the dialog. If this is not set, a default "OK" button is displayed, which simply closes the message. If this is set to an empty array, no buttons will be displayed, meaning the dialog can only be dismissed using the 'X' or the close function. Note: the default OK button is not displayed when using showIFrame, showWebResource, or showCanvasApp.
    [
    new Dialog.Button("Create Sale", createSaleFunction, true),
    new Dialog.Button("Not now")
]
    • Each button object should be created using the following constructor:
    • new Dialog.Button(label, callback, setFocus, preventClose)
      • label: string (required). The text to display on the button.
      • callback: function (optional). A custom function to call when the button is clicked. A callback is not required, as the button can still close the dialog by default (unless you specify otherwise). Can be used with showAsync to perform validation while the dialog stays open (e.g. with preventClose = true).
        • Parameters: This function takes a single input parameter, which contains either the prompt responses returned by getPromptResponses when using the show method with fields, or the iFrame window returned by getIFrameWindow when using showIFrame and showWebResource.
        • Return type: Return false when using showAsync to prevent the promise from firing, e.g. to allow validation to run inside the button callback while the main dialog stays open.
      • setFocus: boolean (optional). Specify whether this button should have focus set to it by default, i.e. to allow pressing 'enter' to fire the button command. If there is only one button, focus is automatically set to the button, unless you explicitly set this to false. Buttons with setFocus set to true will display as a 'blue' primary button.
      • preventClose: boolean (optional). Specify whether this button should not close the dialog after executing the callback function. By default, if this value is not specified, the dialog will be automatically closed after clicking the button. Set this to true if you want to keep the dialog open, for example if your button does something like the 'download log' for CRM errors, where you want to keep the error open, or if you want to run some validation before closing the dialog.

icon

  • Type: string (optional). The icon to display beside the message. This can display a static icon by passing in one of the values below, or a custom image can be displayed by passing in a full URL to an image, or a relative URL to a web resource etc.

    • ERROR: Message will display an error icon.
    • WARNING: Message will display a warning icon.
    • INFO: Message will display an info icon.
    • SUCCESS: Message will display a green tick (success) icon.
    • QUESTION: Message will display a question mark icon.
    • LOADING: Message will display a CRM loading spinner icon.
    • SEARCH: Message will display a search icon.
    • /WebResources/mag_icon.svg: Message will display a custom image web resource.
    "QUESTION"

width

  • Type: number | string (optional). The width of the dialog in pixels, or represented as a CSS string (e.g. "200px" or "90%"). If not specified, this will default to 500px.
    500

height

  • Type: number | string (optional). The height of the dialog in pixels, or represented as a CSS string (e.g. "200px" or "90%"). If not specified, this will default to 250px. If the message content exceeds the height of the dialog, a scroll bar will be added allowing the user to read the whole message, and copy the content if needed.
    250

preventClose

  • Type: boolean (optional). Specify whether the 'X' to close the dialog should be hidden, preventing the user from closing the dialog without using one of the specified buttons. By default the 'X' will be displayed, so to hide the 'X', set this to true.
    true

allowDismiss

  • Type: boolean (optional). Specify whether to allow the user to dismiss/cancel the dialog by clicking outside of the dialog. If this is set to true, clicking anywhere outside of the dialog will perform a 'hide' on the topmost dialog, without firing any button callbacks. This performs similar to clicking the 'X' in the top right corner. By default, clicking outside of the dialog will not close the dialog, so to enable this for a specific dialog, set this to true.
    true

padding

  • Type: number | string (optional). Specify custom padding around the popup in pixels, or as a CSS string (e.g. "20px" or "10px 20px"). If not specified, or set to null, this will default to 20px for standard dialogs and prompts, and 10px for iframes and web resources.
    20

fullscreen

  • Type: boolean (optional). Setting this to true will cause the dialog to expand to 100% of the available screen size. This overrides the width and height properties.
    true

preventResize

  • Type: boolean (optional). Setting this to true will hide and disable the fullscreen/restore button on dialogs, and also prevents manually resizing the dialog (dragging from the bottom corner).
    true

columns

  • Type: number | string (optional). Allows for settings the "columns" CSS property on the dialog to display fields in more than 1 column, and optionally with a min width, e.g. "100px 2". If not specified, dialog fields will display in a single column by default.
    "100px 2"

color

  • Type: string (optional). Set the primary color of the title and buttons. This should be a hex code, but other valid CSS color strings are accepted. If not specified, this will default to the CRM theme's main color.
    "#666666"

canvasAppName

  • Type: string (optional). The unique name of a canvas app from the current environment to display in an iframe. This can be obtained from a solution, and is the 'Name' of the app component. Canvas app unique names are persisted when deployed across environments.
    "mag_appname_9d035"

webResourceName

  • Type: string (optional). The schema name of an HTML web resource to display inside the dialog.
    "mag_/html/config.html"

iframeUrl

  • Type: string (optional). The URL of a webpage to display inside the dialog as an iframe. This webpage must allow being displayed inside an iframe. E.g. "http://bing.com" works but "http://google.com" does not. 
    "https://www.bing.com"

iframeContent

  • Type: string (optional). Custom HTML to display inside the iframe. Ideally, this should be an entire HTML page, including the body and head tags etc.
    "<p>This is inserted into the iframe document.</p>"

iframeQueryStrings

  • Type: object (optional). Set the query string parameters to append to the iframe URL. Each Object key is a new query string parameter, and the Object value is the query string value. This can be used with canvasAppName, webResourceName, or iframeUrl options. 
    {
    someVar1: "value1",
    someVar2: 2
}
    Note: Web resource query strings are all added to a 'data' parameter, rather than being added separately (see MS docs), e.g.: ?data=someVar1%3Dvalue1%26someVar2%3D2. Canvas app and regular iframe query strings are added directly, e.g.: ?someVar1=value1&someVar2=2.

Adding additional options

Once you've created a new Dialog() object, you can add additional options at any time. Each of the 'options' properties can also be used as a function on the base Dialog object. These will automatically update the values on a dialog that has already been shown, and can be chained together. E.g.:

new Dialog({ title: "Create new sale", message: "This will create the new sale record." }).show();

is the same as:

new Dialog().title("Create new sale").message("This will create the new sale record.").show();

which is also the same as:

var dialog = new Dialog({ title: "Create new sale"}).show();
dialog.message("This will create the new sale record.");

This can be useful when creating multi-page prompts, for example, to maintain a base dialog object, and modify individual properties as needed before displaying the next page. All functions (with the exception of the 'get' functions) return the base Dialog object, so you can chain them together on one line. This includes the options .title(), .message(), etc, and also the main functions .show(), .close(), etc.

show

Use this method to show any type of dialog. This can be called from a form, view, or anywhere that supports JavaScript.

dialog.show()

Parameters

dialog

Return type

  • Type: Dialog object. Returns the base dialog object used to create the dialog.

Example

The following example displays a dialog with 2 fields.

var options = {
    title: "Dialog example",
    message: "This is an example dialog",
    height: 300,
    buttons: [new Dialog.Button("OK")],
    fields: [
        new Dialog.Input({ label: "Subscribe", type: "checkbox" }),
        new Dialog.MultiLine({ label: "Details" })
    ]
};

var dialog = new Dialog(options).show();

close

Use this method to close the dialog and completely remove it from the document.

dialog.close()

Parameters

dialog

  • Created with new Dialog(options). See how to create the Base Dialog object for more info.

Return type

  • Type: Dialog object. Returns the base dialog object used to create the dialog.

Example

The following code sample shows a dialog with the id "newSale", then closes it.

var options = { id: "newSale" };
var dialog = new Dialog(options).show();

dialog.close();

addField

Use this method to add or update a field on a dialog without having to refresh all fields (i.e. using the .fields() method).

dialog.addField(field, insertAtIndex)

Parameters

dialog

  • Created with new Dialog(options). See how to create the Base Dialog object for more info.

field

  • Type: object (required). A single Field object to add to the dialog. If the field id matches an existing field, it overwrites the existing field, otherwise it is added as a new field. This can be any field type, including Group.
    new Dialog.Input({ id: "input", label: "Field name" })

insertAtIndex

  • Type: number (optional). Specify the position of the field to be placed within the dialog in relation to other fields (i.e. 0 inserts the field at the start). If not specified, it will maintain its position (for updates), or be appended to the end of the dialog (for new).
    0

Return type

  • Type: Dialog object. Returns the base dialog object used to create the dialog.

Example

The following example displays a dialog with an input, then adds an additional input at the start.

var options = {
    fields: [
        new Dialog.Input({ id: "input", label: "Field name" })
    ]
};
var dialog = new Dialog(options).show();

dialog.addField(new Dialog.Input({ id: "input2", label: "Field 2 name" }), 0);

removeField

Use this method to remove a field on a dialog without having to refresh all fields (i.e. using the .fields() method).

dialog.removeField(id)

Parameters

dialog

  • Created with new Dialog(options). See how to create the Base Dialog object for more info.

id

  • Type: string | number (required). The id (string), or index (number) of an existing field to remove from the dialog.
    "fieldID"

Return type

  • Type: Dialog object. Returns the base dialog object used to create the dialog.

Example

The following example displays a dialog with 2 inputs, then removes the first input by its index.

var options = {
    fields: [
        new Dialog.Input({ id: "input", label: "Field name" }),
        new Dialog.Input({ id: "input2", label: "Field 2 name" })
    ]
};
var dialog = new Dialog(options).show();

dialog.removeField(0); // Or dialog.removeField("input");

showLoading

Use this method to display a small loading spinner with the text "Loading...". This is just a simple wrapper for the Dialog.show method with a few standardised defaults, making it easier to reuse when needing to display a loading message.

dialog.showLoading()

Parameters

dialog

  • Created with new Dialog(options). See how to create the Base Dialog object for more info.
  • The following options are supported with this method:

Return type

  • Type: Dialog object. Returns the base dialog object used to create the dialog.

Example

The following example displays a default loading spinner with a custom id.

var options = { id: "loading" };
var dialog = new Dialog(options).showLoading();

showCanvasApp

Use this method to show a canvas app from the current environment in a dialog via iframe. Specify the canvas app unique name from a solution, and optionally pass additional query parameters.

dialog.showCanvasApp(appUniqueName, additionalQueryParams)

Parameters

dialog

appUniqueName

  • Type: string (required). The unique name of the canvas app. Overwrites the canvasAppName Dialog option. This can be obtained from a solution, and is the 'Name' of the app component. Canvas app unique names are persisted when deployed across environments.
    "mag_appname_9d035"

additionalQueryParams

  • Type: object (optional). Additional query string parameters to pass to the canvas app. Overwrites the iframeQueryStrings Dialog option. Each Object key is a new query string parameter, and the Object value is the query string value.
    {
  someVar1: "value1",
  someVar2: 2
}

Return type

  • Type: Dialog object. Returns the base dialog object used to create the dialog.

Example

The following example displays a canvas app, and passes an additional query parameter.

var options = { title: "App name" };
var dialog = new Dialog(options).showCanvasApp("mag_appname_9d035", { someVar: "someValue" });

In the above example, the canvas app URL displayed in the dialog will be something like below (note this URL is retrieved dynamically based on the appUniqueName):

https://apps.powerapps.com/play/{appid}?tenantId={tenantid}&hint={hint}&someVar=someValue

The query strings can be accessed inside the canvas app using the Power Fx Param function.

showWebResource

Use this method to display an HTML web resource inside a light-box. The URL of the web resource is generated and then passed into the Dialog.showIFrame function, which creates an iframe to the web resource. You can also optionally add custom titles, buttons, and padding, just like the standard Dialog.show function. NOTE: If you're wanting to capture input from a user, consider using showPrompt.

dialog.showWebResource(webResourceName)

To access the web resource document, i.e. to get the values from inputs on the web resource, you can make a call to getIFrameWindow. This allows you to access any elements inside the web resource being displayed. Note that this is also the first parameter passed to your button callback functions.

To access CRM components from inside the web resource document, i.e. to execute some other form logic on click of a button inside your web resource, you can make a call to getCrmWindow from anywhere inside the web resource. This allows you to call other functions, or access form fields directly from within the web resource.

Parameters

dialog

webResourceName

  • Type: string (required). The schema name of the HTML web resource to display inside the dialog. Overwrites the webResourceName Dialog option. Additional query string parameters can be added to the web resource URL using the iframeQueryStrings Dialog option.
    "new_/html/tester.html"

Return type

  • Type: Dialog object. Returns the base dialog object used to create the dialog.

Example

The following example displays a fullscreen web resource, and accesses the value of an input on the web resource in the button callback.

var buttonCallback = function(context) {
    alert(context.document.getElementById("someinput").value);
};

var options = { fullscreen: true, buttons: [ new Dialog.Button("OK", buttonCallback) ] };
var dialog = new Dialog(options).showWebResource("new_/html/tester.html");

showIFrame

Use this method to display a webpage or custom HTML inside a light-box, via an iFrame. You can also optionally add custom titles, buttons, and padding, just like the standard show function.

dialog.showIFrame(iframeUrl, iframeContent)

To access the iframe document, i.e. to get the values from inputs on the web page, you can make a call to getIFrameWindow. This allows you to access any elements inside the web page being displayed. Note that this is also the first parameter passed to your button callback functions. Cross-domain scripting is not allowed, so the web page being displayed in the iframe must be on the same domain as CRM for you to access its document via this method.

To access CRM components from inside the iframe document, i.e. to execute some other form logic on click of a button inside your web page, you can make a call to getCrmWindow from anywhere inside the web page. This allows you to call other functions, or access form fields directly from within the iframe document. Note that cross-domain scripting is not allowed, so the web page being displayed in the iframe must be on the same domain as CRM for you to call into CRM from its document.

Parameters

dialog

iframeUrl

  • Type: string (recommended). The URL of the webpage to display inside the dialog. Overwrites the iframeUrl Dialog option. This webpage must allow being displayed inside an iframe. E.g. "http://bing.com" works but "http://google.com" does not. This parameter can be set to null if iframeContent is being set.
    "http://bing.com"

iframeContent

  • Type: string (optional). Custom HTML to display inside the iframe. Overwrites the iframeContent Dialog option. Ideally, this should be an entire HTML page, including the body and head tags etc. This will override the iframeUrl if provided.
    "<p>This is inserted into the iframe document.</p>"

Return type

  • Type: Dialog object. Returns the base dialog object used to create the dialog.

Example

The following example displays a fullscreen iframe to bing.

var options = { id: "bingFrame", fullscreen: true };
var dialog = new Dialog(options).showIFrame("https://bing.com");

showPrompt

Use this method to show a prompt containing fields to capture input from the user, then return the responses using getPromptResponses, or using the first parameter inside the button callback, and then use those values to continue processing. NOTE: You can also just use the show method, and set fields in the base Dialog options.

dialog.showPrompt(fields)

Parameters

dialog

  • Created with new Dialog(options). See how to create the Base Dialog object for more info.
  • The following options are supported with this method:
    • title (defaults to "", i.e. empty string)
    • message (defaults to "", i.e. empty string)
    • content (defaults to "", i.e. empty string)
    • fields (defaults to [new Dialog.Input()], i.e. a single text input)
    • buttons (defaults to [new Dialog.Button("OK")], i.e. a single "OK" button)
    • icon (defaults to null, i.e. no icon)
    • width (defaults to 500)
    • height (defaults to 250)
    • preventClose (defaults to false)
    • allowDismiss (defaults to false)
    • padding (defaults to 20)
    • fullscreen (defaults to false)
    • preventResize (defaults to false)
    • columns (defaults to 1)
    • color (defaults to the CRM theme main color)
    • id (defaults to "", i.e. empty string)

fields

  • Type: object[] (required). The fields to display inside the dialog. Overwrites the fields Dialog option. Each type of field is constructed differently. See the fields Dialog option for structure.
    [new Dialog.Input({ label: "Name" }), new Dialog.MultiLine({ label: "Details" })]

Return type

  • Type: Dialog object. Returns the base dialog object used to create the dialog.

Example

The following example displays a dialog with 2 fields, and accesses the values in the button callback.

var options = {
    id: "promptExample",
    buttons: [new Dialog.Button("OK", function(results) {
        var subscribe = results[0].value;
        var details = results[1].value;

        alert("Subscribe: " + subscribe);
        alert("Details: " + details);
    })]
};

var dialog = new Dialog(options).showPrompt([
    new Dialog.Input({ label: "Subscribe", type: "checkbox" }),
    new Dialog.MultiLine({ label: "Details" })
]);

showAsync

Use this method to show a dialog and await a response before continuing code execution.

var response = await dialog.showAsync()

Parameters

dialog

  • Created with new Dialog(options). See how to create the Base Dialog object for more info.
  • All options for showAsync are the same as for the show method.

Return type

  • Type: Promise<object>. Returns a promise containing the field responses from the dialog, and the button which was selected. Can be awaited, or accessed via .then(callback). Promise object contains the following properties:
    • button (object): The Dialog.Button object which was selected to close the dialog. This contains all the properties from the dialog button, including label, callback, setFocus, and preventClose. If the dialog is closed without using a dialog button, this will be an empty object, e.g. {}.
    • data (object): Returns an object containing each of the fields from the dialog as a property. Each property will be named using the id of the field if specified, or by its index prefixed with an underscore, e.g. _0. Follows the same structure as the getData method.
    • window (window): Returns the window object from the dialog iframe or web resource when using showIFrame or showWebResource. Used to access iframe document to get custom inputs etc.

Example

Using await to get the dialog field value after the 'OK' button is pressed.

var dialog = new Dialog({
    buttons: [new Dialog.Button("OK")],
    fields: [new Dialog.Input({ id: "input01" })]
});

var response = await dialog.showAsync();

if (response.button.label === "OK") {
    var input = response.data.input01; // input01 is the field ID
    alert(input);
}

The same example as above, but using .then() instead of await.

var dialog = new Dialog({
    buttons: [new Dialog.Button("OK")],
    fields: [new Dialog.Input({ id: "input01" })]
});

dialog.showAsync().then(function(response) {
    if (response.button.label === "OK") {
        var input = response.data.input01; // input01 is the field ID
        alert(input);
    }
});

getIFrameWindow

Use this method to get the context of an iFrame being displayed in the light-box. For example, if you're capturing input via a web resource, you can use this function to access the inputs on the web resource from inside a custom function. This allows you to use custom buttons to access the iFrame data. This value is also returned as the first parameter of each button callback when using showIFrame or showWebResource.

var iframeWindow = dialog.getIFrameWindow()

Parameters

dialog

  • Created with new Dialog(options). See how to create the Base Dialog object for more info.

Return type

  • Type: window. The window representing the current iFrame being displayed in the light-box. If no iFrames are available, this will return null.

Example

The following example displays a web resource, and gets the iframe window in the button callback.

var options = { id: "webResource" };
var dialog = new Dialog(options);

var buttonCallback = function (context) {
    var iframeWindow = dialog.getIFrameWindow(); // This is the same as the context parameter
    alert(iframeWindow.document.getElementById("somefield").value);
};

dialog.buttons([new Dialog.Button("OK", buttonCallback)]);
dialog.showWebResource("new_/html/tester.html");

getPromptResponses

This method gets the responses from the last displayed prompt. Responses are returned in the same order they are displayed. This value is also returned as the first parameter of each button callback when showing a dialog fields.

var responses = dialog.getPromptResponses()

Parameters

dialog

  • Created with new Dialog(options). See how to create the Base Dialog object for more info.

Return type

  • Type: object[]. The responses from all fields on a dialog. Each object consists of an 'id' and a 'value'. Each response is returned in the same order as it is added to the dialog, so they can be accessed by their index in the array or by checking their 'id' attribute.
    • id (string): The 'id' exactly matches the 'id' given to the field when creating the dialog. If no 'id' was specified on the field, this will be an empty string.
    • value (any): The 'value' represents the field value. This is different depending on the type of field used. Empty values will become 'null'.
      • Dialog.Group: Returns object[]. This contains all the fields within this group. Each object follows the same structure as above, consisting of an 'id' and 'value'.
      • Dialog.Input: The value returned will depend on the HTML input 'type' used. The following values will be returned for different HTML input types.
        • text: Returns a string.
        • date: Returns a Date.
        • datetime-local: Returns a Date.
        • radio: Returns a boolean. Returns true if checked, otherwise false.
        • checkbox: Returns a boolean. Returns true if checked, otherwise false.
        • number: Returns a number.
        • range: Returns a number.
        • file: Returns a File[] containing the data for the uploaded file(s). Each File object has the following properties:
          • lastModified: number. The last modified time of the file in milliseconds.
          • name: string. The file name.
          • size: number. The file size in bytes.
          • type: string. The file type, e.g. "text/plain".
          • value: string. The file contents in base64.
      • Dialog.MultiLine: Returns a string.
      • Dialog.OptionSet: Returns a number, string, or (string | number)[]. This is the value from the selected option(s). If this is numeric, it will return a number, otherwise a string. If the 'multiple' attribute is added to the field, this will return a (string | number)[] of the selected options.
      • Dialog.Lookup: Returns an object[]. This returns the same structure as a CRM lookup using .getValue(). The lookup object consists of a 'name', 'id', and 'entityType'.
      • Dialog.Custom: Returns the HTMLElement for the parent span of the custom HTML/elements. This can be further filtered using .querySelector() to access specific elements or .innerHTML to simply access the inner HTML string.

Example

The following example displays a prompt with 2 fields, and accesses the values in the button callback.

var options = {
    fields: [
        new Dialog.Input({ id: "subscribe", label: "Subscribe", type: "checkbox" }),
        new Dialog.MultiLine({ id: "details", label: "Details" })
    ],
    buttons: [
        new Dialog.Button("OK", function(responses) {
            var results = dialog.getPromptResponses(); // This is the same as 'responses'

            var subscribe = results[0].value;
            var details = results[1].value;

            alert("Subscribe: " + subscribe);
            alert("Details: " + details);
        })
    ]
};

var dialog = new Dialog(options).show();

PromptResponses Extensions

These extension methods can be used with the PromptResponses (Array of Objects) returned from the getPromptResponses method, or from the buttons callback function, or the return value of the Dialog.Group field type.

getValue

This extension method gets the value of a prompt response by specifying the field id (string) or index (number).

var value = responses.getValue(id)

Parameters

responses

  • Type: PromptResponses object. The return value from the getPromptResponses method, or from the buttons callback function, or the return value of the Dialog.Group field type.

id

  • Type: string | number (required). The 'id' (string) relating to a field/group within the array of prompt fields. Or the index (number) of a field/group within the array of prompt fields.
    "name"

Return Type

  • Returns the value of the selected field. This is different depending on the type of field used. See getPromptResponses for the different types of values that can be returned.
    "Value from a text Input or MultiLine"

Example

The following example gets the values of 2 fields using the field id and using the array index.

var options = {
    fields: [
        new Dialog.Input({ id: "subscribe", label: "Subscribe", type: "checkbox" }),
        new Dialog.MultiLine({ id: "details", label: "Details" })
    ],
    buttons: [
        new Dialog.Button("OK", function(responses) {
            var subscribe = responses.getValue("subscribe"); // By field id
            var details = responses.getValue(1); // By array index

            alert("Subscribe: " + subscribe);
            alert("Details: " + details);
        })
    ]
};

var dialog = new Dialog(options).show();

getSelected

This extension method gets the id of all fields within the prompt response array which have a true value. Used to get just the selected field(s) from a group of radio or checkbox fields.

var checked = responses.getSelected();

Parameters

responses

  • Type: PromptResponses object. The return value from the getPromptResponses method, or from the buttons callback function, or the return value of the Dialog.Group field type.

Return Type

  • Type: string[]. The id's of any fields within the array of prompt responses which have a true value. Returns "" (empty string) for any fields with no id.
    ["news","email","tips"]

Example

The following example displays a group of checkboxes, and alerts the selected id's in the callback.

var options = {
    fields: [
        new Dialog.Group({ id: "subs", label: "Subscriptions", fields: [
            new Dialog.Input({ id: "news", type: "checkbox", label: "Newsletter" }),
            new Dialog.Input({ id: "email", type: "checkbox", label: "Emails" }),
            new Dialog.Input({ id: "tips", type: "checkbox", label: "Tips" })]
        })
    ],
    buttons: [
        new Dialog.Button("OK", function(responses) {
            var subsGroup = responses.getValue("subs"); // The group of checkboxes
            var checked = subsGroup.getSelected(); // ["news","email","tips"] (if checked)

            alert("Selected: " + checked);
        })
    ]
};

var dialog = new Dialog(options).show();

getData

This extension method converts the prompt responses array into an object structure using the field id as the property name (or the index prefixed with an underscore, e.g. _0 if the field has no id), and the field value as the property value. This structure can be used with HTTP requests or with Power Automate to create strongly typed properties and values.

var data = responses.getData()

Parameters

responses

  • Type: PromptResponses object. The return value from the getPromptResponses method, or from the buttons callback function, or the return value of the Dialog.Group field type.

Return Type

  • Type: object. Returns an object containing each of the fields in the prompt responses array as a property. Each property will be named using the id of the field if specified, or by its index prefixed with an underscore, e.g. _0.
    { subscribe: true, details: "Details about the record" }

Example

The following example gets the prompt responses array from the callback and converts it into an object structure used to easily access each value.

var options = {
    fields: [
        new Dialog.Input({ id: "subscribe", label: "Subscribe", type: "checkbox" }),
        new Dialog.MultiLine({ id: "details", label: "Details" })
    ]
};

var dialog = new Dialog(options).show();

var responses = dialog.getPromptResponses();
var data = responses.getData(); // { subscribe: false, details: null }

alert("Subscribe: " + data.subscribe);
alert("Details: " + data.details);

getElement

This method gets the first element within the dialog matching a query selector, e.g. "#field1 input". If no query selector is specified, the outer dialog element is returned. This must be called after showing the dialog.

var element = dialog.getElement(querySelector)

Parameters

dialog

  • Created with new Dialog(options). See how to create the Base Dialog object for more info.

querySelector

  • Type: string (optional). The query selector to find an HTML element within the dialog. Uses Element.querySelector from the context of the base dialog element. If no querySelector is provided, the base dialog element is returned.
    "#field1 input"

Return type

  • Type: HTMLElement. The first matching HTML Element returned by the query selector. If no querySelector provided, the root HTML Element for current dialog is returned. If the query selector matches no elements, null is returned.

Example

The following example gets the HTML Input Element for a particular field within the dialog, and uses it to add an onchange event.

var options = {
    id: "promptExample",
    fields: [
        new Dialog.Input({ id: "inputExample" })
    ]
};

var dialog = new Dialog(options).show();

var element = dialog.getElement("#inputExample input");
element.addEventListener("change", function() { alert(this.value); });

getElements

Similar to getElement, this method gets all elements within the dialog matching a query selector, e.g. ".dialog-js-prompt-field". This must be called after showing the dialog.

var elements = dialog.getElement(querySelector)

Parameters

dialog

  • Created with new Dialog(options). See how to create the Base Dialog object for more info.

querySelector

  • Type: string (required). The query selector to find HTML elements within the dialog. Uses Element.querySelectorAll from the context of the base dialog element.
    "#field1 input, #field2 input"

Return type

  • Type: HTMLElement[]. All matching HTML Elements returned by the query selector. If no matching elements, an empty Array is returned. Note: Unlike Element.querySelectorAll, this returns an Array of HTMLElement's, rather than a NodeList.

Example

The following example gets all the HTML Input Elements from the dialog, and adds an onchange event to each.

var options = {
    id: "promptExample",
    fields: [
        new Dialog.Input({ id: "field1" }),
        new Dialog.Input({ id: "field2" })
    ]
};

var dialog = new Dialog(options).show();

var elements = dialog.getElements("input");
elements.forEach(a => a.addEventListener("change", function() { alert(this.value); }));

htmlEncode

Use this method to encode a custom message which contains HTML characters, to allow it to be displayed inside the dialog message. For example, if displaying formatted XML with indented spacing and XML tags, calling this method will format the text into an HTML friendly message that displays nicely inside the dialog. The returned value should then be passed to the 'message' or 'content' of the Dialog.show method.

NOTE: If you want to actually use HTML tags, like <b>bold</b>, you should not use this method.

var html = Dialog.htmlEncode(text)

Parameters

text

  • Type: string (required). The text to encode, e.g. a trace log.
    "  <InnerFault>\n" +
"    <ErrorCode>-2147220969</ErrorCode>\n" +
"    <ErrorDetails xmlns:d3p1=\"http://schemas.datacontract.org/2004/07/System.Collections.Generic\" />\n" +
"    <Message>account With Id = b966e678-1d9d-e011-9293-000c2981699a Does Not Exist</Message>\n" +
"    <Timestamp>2016-06-22T04:13:14.4579317Z</Timestamp>\n" +
"    <InnerFault i:nil=\"true\" />\n" +
"    <TraceText i:nil=\"true\" />\n" +
"  </InnerFault>"

Return type

  • Type: string. The text passed into the method, with all HTML tags encoded, including line breaks and spacing.
    "&nbsp;&nbsp;&lt;InnerFault&gt;<br />&nbsp;&nbsp;&nbsp;&nbsp;&lt;ErrorCode&gt;-2147220969&lt;/ErrorCode&gt;<br />&nbsp;&nbsp;&nbsp;&nbsp;&lt;ErrorDetails xmlns:d3p1=&quot;http://schemas.datacontract.org/2004/07/System.Collections.Generic&quot; /&gt;<br />&nbsp;&nbsp;&nbsp;&nbsp;&lt;Message&gt;account With Id = b966e678-1d9d-e011-9293-000c2981699a Does Not Exist&lt;/Message&gt;<br />&nbsp;&nbsp;&nbsp;&nbsp;&lt;Timestamp&gt;2016-06-22T04:13:14.4579317Z&lt;/Timestamp&gt;<br />&nbsp;&nbsp;&nbsp;&nbsp;&lt;InnerFault i:nil=&quot;true&quot; /&gt;<br />&nbsp;&nbsp;&nbsp;&nbsp;&lt;TraceText i:nil=&quot;true&quot; /&gt;<br />&nbsp;&nbsp;&lt;/InnerFault&gt;"

Example

The following example encodes a plugin trace log containing XML markup, line breaks, and spacing, and then displays it in the message of a dialog.

var errorTrace = 
    "  <InnerFault>\n" +
    "    <ErrorCode>-2147220969</ErrorCode>\n" +
    "    <ErrorDetails xmlns:d3p1=\"http://schemas.datacontract.org/2004/07/System.Collections.Generic\" />\n" +
    "    <Message>account With Id = b966e678-1d9d-e011-9293-000c2981699a Does Not Exist</Message>\n" +
    "    <Timestamp>2016-06-22T04:13:14.4579317Z</Timestamp>\n" +
    "    <InnerFault i:nil=\"true\" />\n" +
    "    <TraceText i:nil=\"true\" />\n" +
    "  </InnerFault>";

var html = Dialog.htmlEncode(errorTrace);

var options = {
    id: "pluginError",
    title: "Error occurred during plugin execution",
    message: "Plugin stack trace:",
    content: html,
    icon:"ERROR",
    width: 620,
    height: 310
};

new Dialog(options).show();

TypeScript Definition

The full TypeScript definition file for v3.1+ can be found here: https://github.com/PaulNieuwelaar/alertjs/blob/master/alert.d.ts. This should also support earlier versions in theory since the code is backwards compatible.

You can reference this from your PCF controls for example along with the js, css, and img files found in the solution. If using a PCF control, you can make use of the PCF ComponentFramework PopupService, WebApi, and Utility by setting these when initializing your control.

Dialog.popupService = context.factory.getPopupService();
Dialog.utility = context.utils;
Dialog.webAPI = context.webAPI;

Deprecated functions

This area lists all deprecated functions and options for Dialog Builder. For a more complete list of version history and changes, view the release notes.

Deprecated in v3.3.2

getCrmWindow

Using parent.Dialog is no longer recommended as the parent Dialog can be inconsistently overwritten by other forms/web resources. Accessing the CRM form scripts from an HTML web resource is also not best practice. Instead, you should only be running code from within the HTML web resource. Try not to access scripts from other frames. This is particularly important now that CRM can display forms within forms. Add a reference directly to Dialog Builder from HTML web resources using e.g. `<script data-preserve-html-node="true" src="mag/js/alert.js">`._

This method can be called from inside an iframe (web resource), and gives you context of the CRM form where other form scripts are loaded. This allows you to access CRM functions, and your own custom JavaScript libraries from inside iframe dialogs. From inside a web resource, for example, you can call parent.Dialog.getCrmWindow().doSomething();, where "doSomething()" represents a custom function loaded onto the parent form.

var crmWindow = parent.Dialog.getCrmWindow()

Return type

  • Type: window. The window representing the CRM form, or client API wrapper if turbo forms are enabled. This window contains all of your custom web resource libraries loaded onto the form.

Example

var crmWindow = parent.Dialog.getCrmWindow();

crmWindow.Xrm.Page.getAttribute("name").setValue("something")

Deprecated in v3.3.0

jQuery Dialog option and function

  • Type: JQuery object. Using jQuery is no longer recommended. Use .getElement() to return the HTML dialog element instead, then use .querySelector/.querySelectorAll. Sets the global jQuery reference to be used by all dialogs. If not set, the window/parent jQuery reference will be used.
    window.jQuery || window.$

.$() function

Using jQuery is no longer recommended. Use .getElement() to return the HTML dialog element instead, then use .querySelector/.querySelectorAll. This method acts as a wrapper for jQuery, which can be used to access elements from a Dialog, e.g. prompt fields. This can be used from a Dialog object dialog.$("jquery-selector") which automatically sets the jQuery context to the dialog being used, or as a static function Dialog.$("jquery-selector") which will default to the top Dialog context, which will apply to all dialogs being displayed at the time.

Dialog.$(selector, context)

Parameters:

selector

  • Type: String. The jQuery selector expression to use. This works exactly the same as the selectors for jQuery normally.
    "#someInput"

context

  • Type: Element or jQuery object. An optional parameter to filter the selector to within a certain context, i.e. a particular dialog. This works exactly the same as the second context parameter for jQuery normally. The context can be set to a specific dialog using the .get() function, and is automatically set to the current dialog when used from a Dialog object. 
    dialog.get()

Return type:

  • Type: jQuery object. The jQuery object containing the results of the selector query. This is exactly the same as what jQuery normally returns.

Example:

The following example gets the jQuery object for a dialog, and uses it to access the content of the dialog to add an onchange event to one of the inputs.

var options = { id: "promptExample" };
var dialog = new Dialog(options);
dialog.showPrompt([new Dialog.Input({ id: "inputExample" })]);

var $inputExample = dialog.$("#inputExample input");
$inputExample.on("change", function() { alert(this.value); });

.get() function

Using jQuery is no longer recommended. Use .getElement() to return the HTML dialog element instead, then use .querySelector/.querySelectorAll. This method gets the jquery object for this dialog - used for accessing specific inner elements when multiple dialogs are displayed. This must be called after showing the dialog. Note: Using the $ function from a Dialog object will automatically scope to that dialog, e.g. dialog.$("jquery-selector").

var $dialog = dialog.get()

Parameters:

dialog

  • Created with new Dialog(options). See how to create the Base Dialog object for more info.

Return type:

  • Type: jQuery object. The jQuery object wrapper for a particular dialog being displayed.

Example:

The following example gets the jQuery object for a dialog, and uses it to access the content of the dialog to add an onchange event to one of the inputs.

var options = { id: "promptExample" };
var dialog = new Dialog(options);
dialog.showPrompt([new Dialog.Input({ id: "inputExample" })]);

var $dialog = dialog.get();
var $inputExample = Dialog.$("#inputExample input", $dialog);
$inputExample.on("change", function() { alert(this.value); });

Deprecated in v3.2.0

.hide() and .remove() functions

A new .close() method has been added to replace both. The new .close() method acts the same as .remove() previously. The .hide() method will still exist for backwards compatibility, and is still used by default when a dialog button is pressed to avoid issues with callbacks.

preventCancel Dialog option and function

Renamed to preventClose. The old preventCancel naming still exists for backwards compatability. This change is to make the name/purpose clearer and in line with other changes.

Deprecated in v3.1.0

Alert namespace (renamed to Dialog)

Version 3.1 has replaced the Alert namespace with Dialog. The Alert namespace will continue to be supported for backwards compatibility, but will simply reference the Dialog namespace. Existing code does not need to be updated, but going forward Dialog should be used instead of Alert, e.g. new Dialog({ title: "Create sale", message: "This will create a sale" }).show();.

showDialogProcess

Version 3.1 has deprecated the showDialogProcess function, as showPrompt provides similar functionality, and is much more supported.

Use this method to display a CRM dialog process inside a light-box. The URL of the dialog process is generated and then passed into the showIFrame function, which creates an iframe to the dialog process. You can also optionally specify a callback function which will execute when the dialog is completed or cancelled, allowing you to refresh the form for example.

dialog.showDialogProcess(dialogId, entityName, recordId, callback)

Options:

See how to create the Base Dialog object above for more info on setting these options.

Parameters:

dialog

  • Created with new Dialog(options). See how to create the Base Dialog object for more info.
  • The following options are supported with this method:
    • width (defaults to 800)
    • height (defaults to 600)
    • preventCancel (defaults to false)
    • allowDismiss (defaults to false)
    • padding (defaults to 0)
    • fullscreen (defaults to false)
    • id (defaults to empty string)

dialogId

  • Type: String. The Guid of the dialog to display. You can find this by opening the process, and getting the 'id' query string parameter from the URL.
    "ac03c16e-40b2-41c4-9831-4f651b77f393"

entityName

  • Type: String. The schema name of the entity the dialog is being run for.
    "account"

recordId

  • Type: String. The Guid of the record to run the dialog against. To run the dialog against the current record (i.e. from a form), you can use Xrm.Page.data.entity.getId().
    Xrm.Page.data.entity.getId()

callback

  • Type: function. A function to call when the dialog is closed. This should include any code you wish to execute after the user is finished with the dialog, e.g. to refresh the form. Note that this function will fire whether the user completed the dialog, or closed it without completing it. The callback function accepts no parameters, and can be declared inline as a dynamic function.
    function () {
  Xrm.Page.data.refresh(); 
}

Return type

  • Type: Dialog object. Returns the base dialog object used to create the dialog.

Example:

The following example displays a standard dialog process with a basic callback to refresh the form data.

var recordId = Xrm.Page.data.entity.getId();
var dialogId = "ac03c16e-40b2-41c4-9831-4f651b77f393";
var callback = function() {
    Xrm.Page.data.refresh(); 
};

var options = { id: "dialogProcess" };
new Dialog(options).showDialogProcess(dialogId, "account", recordId, callback);

Deprecated in v3.0.9

customFilters Lookup option

customFilters has been deprecated by Microsoft in Dynamics 365 online v9.1+. This will still be supported for backawards compatibility (however doesn't work in the Unified Interface anyway). The new filters Lookup option should be used instead.

  • customFilters: Array of Strings. Custom filters to apply to the lookup results. Each custom filter will be applied to each of the specified entityTypes. These should not be URL encoded.

Deprecated in v3.0.0

Alert.show(), Alert.hide(), etc

Version 3.0 has deprecated the old functions for creating dialogs, e.g. using Alert.show("Create sale", "This will create a sale");. These functions are still included in the solution, and will continue to work as they did in v2.1. Old code should be updated to follow the new structure going forward, e.g. using new Alert({ title: "Create sale", message: "This will create a sale" }).show();.

baseUrl Dialog option

baseUrl is no longer required as this should always be automatically obtained from the form context. This option will still exist for backwards compatibility, or in the rare scenarios where it is not obtainable from the form context.

  • baseUrl: String. The CRM server base URL. Not required on forms or views. If not specified, it will default to Xrm.Page.context.getClientUrl(). Must be specified where Xrm.Page is not available, e.g. from web resources.
    "http://server/org"