Module: alfresco/services/DialogService

alfresco/services/DialogService

This service subscribes to ALF_CREATE_FORM_DIALOG_REQUEST and ALF_CREATE_DIALOG_REQUEST topics and should be used to manage dialogs displayed on Aikau pages.

When creating a form dialog the value of the form will be published on the topic set by the formSubmissionTopic attribute. You can include additional data in the published payload by using the formSubmissionPayloadMixin attribute. You only need to include the form controls in the widgets attribute - the underlying form will be created automatically.

When creating a normal dialog any buttons included in the dialog will have its payload updated to include a dialogContent attribute that will be an array containing all the root widgets that were created from the widgetsContent attribute.

It is strongly recommended that you include a dialogId attribute when requesting to create either type of dialog since it is used to help the service manage the dialogs. It is only possible to stack dialogs (e.g. display one dialog on top of another) when the dialogs have different dialogId values. If another dialog with the same dialogId then any existing dialog with that same dialogId will be destroyed. This is done to ensure that the browser DOM does not become over populated with unusable elements

It is also possible to create form dialogs that follow the "Create and create again" pattern by configuring the "dialogRepeats" attribute in the ALF_CREATE_FORM_DIALOG_REQUEST to be true. This will include an additional button in the dialog that when used will publish the value of the current form and then recreate a new dialog with a new copy of the form.

In order to be notified when a dialog is cancelled by either clicking on the cross in the top corner, or by pressing escape, a "cancelPublishTopic" can be supplied. This will never be published by someone clicking a "cancel" button - it will only be triggered using one of the two methods above. Scope can be overridden from the default response scope by providing a custom "cancelPublishScope" property. This can be used on normal dialogs and form dialogs.

Author:
  • Dave Draper
  • David Webster
Support:
  • This module is safe to be used in an Aikau page model (at least until the next major release).
Copyright:
  • Copyright (C) 2005-2020 Alfresco Software Limited
License:
Source:

Examples

Example button that requests a form dialog

{
   name: "alfresco/buttons/AlfButton",
   config: {
      label: "Display form dialog",
      publishTopic: "ALF_CREATE_FORM_DIALOG_REQUEST",
      publishPayload: {
         cancelPublishScope: "",
         cancelPublishTopic: "DIALOG_CANCELLED",
         dialogId: "NAME_DIALOG",
         dialogTitle: "User name",
         dialogConfirmationButtonTitle: "Save",
         dialogCancellationButtonTitle: "Quit",
         formSubmissionTopic: "MY_CUSTOM_TOPIC",
         formSubmissionPayloadMixin: {
            extra: "bonus data"
         },
         formValue: {
            name: "Bob"
         },
         widgets: [
            {
               name: "alfresco/forms/controls/TextBox",
               config: {
                  name: "name",
                  label: "Name?"
                  description: "Please enter your name"
               }
            }
         ]
      }
   }
}

Example button that requests basic status dialog

{
   name: "alfresco/buttons/AlfButton",
   config: {
      label: "Alert",
      publishTopic: "ALF_CREATE_DIALOG_REQUEST",
      publishPayload: {
         dialogId: "ALERT_DIALOG",
         dialogTitle: "Warning!",
         textContent: "You have been warned"
      }
   }
}

Example button that requests a dialog with a custom widget model

{
   name: "alfresco/buttons/AlfButton",
   config: {
      label: "Show Logo",
      publishTopic: "ALF_CREATE_DIALOG_REQUEST",
      publishPayload: {
         dialogId: "LOGO_DIALOG",
         dialogTitle: "A logo",
         widgetsContent: [
            {
               name: "alfresco/logo/Logo"
            }
         ],
         widgetsButtons: [
            {
               name: "alfresco/buttons/AlfButton",
               config: {
                  label: "Close dialog",
                  publishTopic: "CUSTOM_TOPIC"
               }
            }
         ]
      }
   }
}

Extends

Members

<static> _activeDialogs :Object[]

The stack of active dialogs
Type:
  • Object[]
Source:

_formCancellationTopic :string

The topic published when the cancellation button is used.
Type:
  • string
Default Value:
  • "ALF_CLOSE_DIALOG"
Source:

_formConfirmationRepeatTopic :string

The topic published when the button confirming the current dialog, but requesting to repeat the dialog is used.
Type:
  • string
Default Value:
  • "ALF_CREATE_REPEATING_FORM_DIALOG_MIXIN_CONFIRMATION_TOPIC"
Source:

_formConfirmationTopic :string

The topic published when the confirmation button is used.
Type:
  • string
Default Value:
  • "ALF_CREATE_FORM_DIALOG_MIXIN_CONFIRMATION_TOPIC"
Source:

_scrollbarWidth :number

The scrollbar width for this browser-environment
Type:
  • number
Since:
  • 1.0.53
Default Value:
  • null
Source:

defaultFormDialogConfig :object

The default configuration for form dialogs. This is used as a base when requests are received.
Type:
  • object
Source:

formSubmissionTopic :string

This is the topic that will be published when the dialog is "confirmed" (e.g. the "OK" button is clicked)
Type:
  • string
Default Value:
  • null
Source:

i18nRequirements :object[]

An array of the i18n files to use with this widget.
Type:
  • object[]
Default Value:
  • [{i18nFile: "./i18n/DialogService.properties"}]
Source:

idToDialogMap :object

This is used to map the dialog created on for each request against the "dialogId" associated with that request. Only one instance of a dialog with the same "dialogId" can exist at one time. If a new request is made with the same "dialogId" as has been used for an existing dialog, then that existing dialog will be destroyed.
Type:
  • object
Default Value:
  • null
Source:

idToHandleMap :object

This us used to map all the subscription and aspect handles created for each requested dialog against the "dialogId" associated with the request to create that dialog. This is done so that all handles can be removed when the dialog is destroyed. Each "dialogId" is associated with an object into which handles can be mapped against a specific key. This allows the service to check for an existing handle before creating duplicates (e.g. when handling repeating dialog requests).
Type:
  • object
Default Value:
  • null
Source:

widgets :object

The configuration for the contents of the dialog to be displayed. This should be provided either on instantiation or by the widget that mixes this module in
Type:
  • object
Default Value:
  • null
Source:

Methods

_getScrollbarWidth() → {number}

Get the scrollbar width for the current browser environment. This is cached after first retrieval for faster access.
Since:
  • 1.0.53
Source:
Returns:
The scrollbar width
Type
number

_handleCancellation(payload, dialog)

When a cancelTopic has been defined, make sure it's published when the dialog is cancelled (via escape keypress or cross-button click).
Parameters:
Name Type Description
payload object The original payload
dialog object The dialog widget
Source:

_handleEscape()

Handle escape key being pressed at the body level
Source:

_repeatFormDialogRequestAfterHide(payload, dialog)

When repeating a request for a dialog (the "Create and then create another" paradigm) it is necessary to wait until the previous dialog has been completely hidden before attempting to create another one if there is a fade out animation configured on the dialog.
Parameters:
Name Type Description
payload object A copy of the original form dialog creation request
dialog object The dialog that must be fully hidden before the request for a new dialog is made.
Source:

_showDialog(payload, dialog)

Show the supplied dialog (also used for adding hooks to the show/hide methods)
Parameters:
Name Type Description
payload Object The original request payload
dialog Object The dialog to show
Source:

changeDialogTitle(payload)

Change the title of the current (i.e. top-most) dialog.
Parameters:
Name Type Description
payload object The payload
Source:

cleanUpAnyPreviousDialog(payload)

This deletes any previously created dialog that was requested for the same id.
Parameters:
Name Type Description
payload object The payload for the new dialog request.
Source:

cleanUpDialogHandles(map)

Cleans up any subscription or aspect handles created for a dialog that has been destroyed.
Parameters:
Name Type Description
map object A map of handles to remove
Source:

createDialog()

Creates and returns a dialog using the configuration provided.
Since:
  • 1.0.96
Source:

createDialogConfig(config, formConfig) → {object}

Creates the configuration object to pass to the dialog.
Parameters:
Name Type Description
config object
formConfig object
Source:
Returns:
The dialog configuration.
Type
object

createFormConfig(widgets, formValue) → {object}

Creates and returns the form configuration to be added to the dialog
Parameters:
Name Type Description
widgets object This is the configuration of the fields to be included in the form.
formValue object The initial value to set in the form.
Source:
Returns:
The configuration for the form to add to the dialog
Type
object

mapRequestedIdToDialog(payload, dialog)

Maps the id requested for the dialog to the dialog created so that it can be destroyed when a request is made to create a dialog with the same id. If an id has not been requested then the dialog will be mapped to null. Only one dialog is no requested id can exist at any one time.
Parameters:
Name Type Description
payload object The payload passed when requesting to create the dialog
dialog object The dialog created
Source:

onCloseDialog(dialog)

Closes the supplied dialog.
Parameters:
Name Type Description
dialog object The dialog to close.
Source:

onCreateDialogRequest(payload)

Handles requests to create basic dialogs.
Parameters:
Name Type Description
payload module:alfresco/services/DialogService~event:ALF_CREATE_DIALOG_REQUEST The details of the widgets and buttons for the dialog
Source:

onCreateFormDialogRequest(payload)

Handles requests to create the dialog containining a form. It will delete any previously created dialog (to ensure no stale data is displayed) and create a new dialog containing the form defined.
Parameters:
Name Type Description
payload module:alfresco/services/DialogService~event:ALF_CREATE_FORM_DIALOG_REQUEST The payload published on the request topic.
Source:

onFailedSubmission(dialog)

Handles failed form submission by re-enabling the dialog buttons so that the user to submit alternative data.
Parameters:
Name Type Description
dialog object The dialog to enable the buttons for
Since:
  • 1.0.58
Source:

onFormDialogConfirmation(payload)

This handles the user clicking the confirmation button on the dialog (typically, and by default the "OK" button). This has a special handler to process the payload and construct a simple object reqpresenting the content of the inner form.
Parameters:
Name Type Description
payload object The dialog content
Source:

publishOnShow(publication)

This function is called when the request to create a dialog includes publication data to be performed when the dialog is displayed.
Parameters:
Name Type Description
publication object The publication configuration
Source:

registerSubscriptions()

Since:
  • 1.0.32
Source:
Listens to Events:

repeatFormDialogRequest(payload)

Parameters:
Name Type Description
payload object The original payload request
Source:

<inner> mapRequestedIdToHandle(payload, id, handle)

Maps a handle against a specific handle id within the map of dialogId to handles.
Parameters:
Name Type Description
payload object The create dialog request payload
id string The id to map the handle against
handle object A subscription or aspect handle
Source:

Events

ALF_CREATE_DIALOG_REQUEST

Create a dialog containing either widgets or text with and configurable buttons.
Properties:
Name Type Argument Default Description
dialogTitle string The text to set in the dialog title bar
dialogId string <optional>
 null The ID of the dialog to display. Only one dialog with no dialogId can exist on a page at a time, therefore it is sensible to always include an id for your dialogs to allow stacking.
duration number <optional>
 0 The duration of the fade effect when showing or hiding the dialog
textContent string <optional>
 null Text to display in the dialog body
widgetsContent array <optional>
 null A widget model to display in the dialog body (this supercedes any textContent attribute)
widgetsButtons Array <optional>
 null A widget model of buttons to display in the dialog footer
dialogWidth String <optional>
 null The width to make the dialog panel (needs to include units, e.g. "px")
contentWidth String <optional>
 null The width to set the dialog body (needs to include units, e.g. "px")
contentHeight String <optional>
 null The height to set the dialog body (needs to include units, e.g. "px")
handleOverflow Boolean <optional>
 false Should scrollbars be added to if the content is bigger than the dialog
fixedWidth Boolean <optional>
 false If set to true, prevents the dialog resizing to fit the content
publishOnShow Array <optional>
 null An array of publications objects to make when the dialog is displayed
fullScreenMode boolean <optional>
 false Whether or not to create the dialog the size of the screen
fullScreenPadding boolean <optional>
 10 The padding to leave around the dialog when in full screen mode
noMinWidth boolean <optional>
 false Indicates whether the minimum width restriction should be lifted
Source:
Listeners of This Event:

ALF_CREATE_FORM_DIALOG_REQUEST

Create a dialog that contains a form
Properties:
Name Type Argument Default Description
dialogTitle string The text to set in the dialog title bar
duration number <optional>
 0 The duration of the fade effect when showing or hiding the dialog
formSubmissionTopic string The topic to publish when the confirmation button is used (the published payload will be the form value)
formSubmissionPayloadMixin Object An additional object to "mixin" to the form value before it is published
formSubmissionGlobal boolean <optional>
 true Whether or not to publish the form submission topic globally
formSubmissionScope string <optional>
 null A custom scope to be used when publishing the form submission topic
formValue Object <optional>
 {} The initial value to apply to the form when created. This should be an object with attributes mapping to the "name" attribute of each form control.
dialogId string <optional>
 null The ID of the dialog to display. Only one dialog with no dialogId can exist on a page at a time, therefore it is sensible to always include an id for your dialogs to allow stacking.
dialogRepeats boolean <optional>
 false Indicates that an additional button the publishes the current form and then recreates the dialog again
dialogConfirmationButtonTitle string <optional>
 "OK" The label for the dialog confirmation button
dialogConfirmAndRepeatButtonTitle string <optional>
 "OK (and repeat)" The label for the button indicating the dialog should be repeated
dialogCancellationButtonTitle string <optional>
 "Cancel" The label for the dialog cancellation button
dialogCloseTopic string <optional>
 null If this is set then the dialog will not automatically be closed when the confirmation button is pressed. Instead the dialog will remain open until this topic is published on.
dialogEnableTopic string <optional>
 null If this is set then the dialog buttons will automatically be disabled when the form is submitted. When this topic is published, the buttons will be re-enabled. This topic should be published on submission faiure.
widgets array <optional>
 null An array of form controls to include in the dialog
dialogWidth string <optional>
 null The width to make the dialog panel (needs to include units, e.g. "px")
contentWidth string <optional>
 null The width to set the dialog body (needs to include units, e.g. "px")
contentHeight string <optional>
 null The height to set the dialog body (needs to include units, e.g. "px")
handleOverflow boolean <optional>
 false Should scrollbars be added to if the content is bigger than the dialog
fixedWidth boolean <optional>
 false If set to true, prevents the dialog resizing to fit the content
hideTopic string <optional>
 null Topic to subscribe to to trigger a dialog hide. If this is set
fullScreenMode boolean <optional>
 false Whether or not to create the dialog the size of the screen
fullScreenPadding boolean <optional>
 10 The padding to leave around the dialog when in full screen mode
showValidationErrorsImmediately boolean <optional>
 true Indicates whether or not to display form errors immediately
customFormConfig object <optional>
 null Any additional configuration that can be applied to a Form (please note that the following form configuration attributes will always be overridden by specific form dialog configuration: "additionalCssClasses", "displayButtons", "widgets", "value", "warnings" and "warningsPosition")
noMinWidth boolean <optional>
 false Indicates whether the minimum width restriction should be lifted
Source:
Listeners of This Event: