Skip to content

Commit

Permalink
Added ngdocs documentation for overlay.service.js
Browse files Browse the repository at this point in the history
  • Loading branch information
@abjerner @mikecp
abjerner authored and mikecp committed Oct 31, 2021
1 parent 7e55c46 commit 152956b
Showing 1 changed file with 134 additions and 0 deletions.
134 changes: 134 additions & 0 deletions src/Umbraco.Web.UI.Client/src/common/services/overlay.service.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,58 @@

var currentOverlay = null;

/**
* @ngdoc method
* @name umbraco.services.overlayService#open
* @methodOf umbraco.services.overlayService
*
* @description
* Opens a new overlay.
*
* @param {object} overlay The rendering options for the overlay.
* @param {string=} overlay.view The URL to the view. Defaults to `views/common/overlays/default/default.html` if nothing is specified.
* @param {string=} overlay.position The alias of the position of the overlay. Defaults to `center`.
*
* Custom positions can be added by adding a CSS rule for the the underlying CSS rule. Eg. for the position `center`, the corresponding `umb-overlay-center` CSS rule is defined as:
*
* <pre>
* .umb-overlay.umb-overlay-center {
* position: absolute;
* width: 600px;
* height: auto;
* top: 50%;
* left: 50%;
* transform: translate(-50%,-50%);
* border-radius: 3px;
* }
* </pre>
* @param {string=} overlay.size Sets an alias for the size of the overlay to be opened. If set to `small` (default), an `umb-overlay--small` class name will be appended the the class list of the main overlay element in the DOM.
*
* Umbraco does not support any more sizes by default, but if you wish to introduce a `medium` size, you could do so by adding a CSS rule simlar to:
*
* <pre>
* .umb-overlay-center.umb-overlay--medium {
* width: 800px;
* }
* </pre>
* @param {booean=} overlay.disableBackdropClick A boolean value indicating whether the click event on the backdrop should be disabled.
* @param {string=} overlay.title The overall title of the overlay. The title will be omitted if not specified.
* @param {string=} overlay.subtitle The sub title of the overlay. The sub title will be omitted if not specified.
* @param {object=} overlay.itemDetails An item that will replace the header of the overlay.
* @param {string=} overlay.itemDetails.icon The icon of the item - eg. `icon-book`.
* @param {string=} overlay.itemDetails.title The title of the item.
* @param {string=} overlay.itemDetails.description Sets the description of the item. *
* @param {string=} overlay.submitButtonLabel The label of the submit button. To support localized values, it's recommended to use the `submitButtonLabelKey` instead.
* @param {string=} overlay.submitButtonLabelKey The key to be used for the submit button label. Defaults to `general_submit` if not specified.
* @param {string=} overlay.submitButtonState The state of the submit button. Possible values are inherited from the [umbButton directive](#/api/umbraco.directives.directive:umbButton) and are `init`, `busy", `success`, `error`.
* @param {string=} overlay.submitButtonStyle The styling of the submit button. Possible values are inherited from the [umbButton directive](#/api/umbraco.directives.directive:umbButton) and are `primary`, `info`, `success`, `warning`, `danger`, `inverse`, `link` and `block`. Defaults to `success` if not specified specified.
* @param {string=} overlay.hideSubmitButton A boolean value indicating whether the submit button should be hidden. Default is `false`.
* @param {string=} overlay.disableSubmitButton A boolean value indicating whether the submit button should be disabled, preventing the user from submitting the overlay. Default is `false`.
* @param {string=} overlay.closeButtonLabel The label of the close button. To support localized values, it's recommended to use the `closeButtonLabelKey` instead.
* @param {string=} overlay.closeButtonLabelKey The key to be used for the close button label. Defaults to `general_close` if not specified.
* @param {string=} overlay.submit A callback function that is invoked when the user submits the overlay.
* @param {string=} overlay.close A callback function that is invoked when the user closes the overlay.
*/
function open(newOverlay) {

// prevent two open overlays at the same time
Expand Down Expand Up @@ -49,6 +101,14 @@
eventsService.emit("appState.overlay", overlay);
}

/**
* @ngdoc method
* @name umbraco.services.overlayService#close
* @methodOf umbraco.services.overlayService
*
* @description
* Closes the current overlay.
*/
function close() {
focusLockService.removeInertAttribute();

Expand All @@ -61,6 +121,16 @@
eventsService.emit("appState.overlay", null);
}

/**
* @ngdoc method
* @name umbraco.services.overlayService#ysod
* @methodOf umbraco.services.overlayService
*
* @description
* Opens a new overlay with an error message.
*
* @param {object} error The error to be shown.
*/
function ysod(error) {
const overlay = {
view: "views/common/overlays/ysod/ysod.html",
Expand All @@ -72,6 +142,36 @@
open(overlay);
}

/**
* @ngdoc method
* @name umbraco.services.overlayService#confirm
* @methodOf umbraco.services.overlayService
*
* @description
* Opens a new overlay prompting the user to confirm the overlay.
*
* @param {object} overlay The options for the overlay.
* @param {string=} overlay.confirmType The type of the confirm dialog, which helps define standard styling and labels of the overlay. Supported values are `delete` and `remove`.
* @param {string=} overlay.closeButtonLabelKey The key to be used for the cancel button label. Defaults to `general_cancel` if not specified.
* @param {string=} overlay.view The URL to the view. Defaults to `views/common/overlays/confirm/confirm.html` if nothing is specified.
* @param {string=} overlay.confirmMessageStyle The styling of the confirm message. If `overlay.confirmType` is `delete`, the fallback value is `danger` - otherwise a message style isn't explicitly specified.
* @param {string=} overlay.submitButtonStyle The styling of the confirm button. Possible values are inherited from the [umbButton directive](#/api/umbraco.directives.directive:umbButton) and are `primary`, `info`, `success`, `warning`, `danger`, `inverse`, `link` and `block`.
*
* If not specified, the fallback value depends on the value specified for the `overlay.confirmType` parameter:
*
* - `delete`: fallback key is `danger`
* - `remove`: fallback key is `primary`
* - anything else: no fallback AKA default button style
* @param {string=} overlay.submitButtonLabelKey The key to be used for the confirm button label.
*
* If not specified, the fallback value depends on the value specified for the `overlay.confirmType` parameter:
*
* - `delete`: fallback key is `actions_delete`
* - `remove`: fallback key is `actions_remove`
* - anything else: fallback is `general_confirm`
* @param {function=} overlay.close A callback function that is invoked when the user closes the overlay.
* @param {function=} overlay.submit A callback function that is invoked when the user confirms the overlay.
*/
function confirm(overlay) {

if (!overlay.closeButtonLabelKey) overlay.closeButtonLabelKey = "general_cancel";
Expand Down Expand Up @@ -99,11 +199,45 @@
open(overlay);
}

/**
* @ngdoc method
* @name umbraco.services.overlayService#confirmDelete
* @methodOf umbraco.services.overlayService
*
* @description
* Opens a new overlay prompting the user to confirm the overlay. The overlay will have styling and labels useful for when the user needs to confirm a delete action.
*
* @param {object} overlay The options for the overlay.
* @param {string=} overlay.closeButtonLabelKey The key to be used for the cancel button label. Defaults to `general_cancel` if not specified.
* @param {string=} overlay.view The URL to the view. Defaults to `views/common/overlays/confirm/confirm.html` if nothing is specified.
* @param {string=} overlay.confirmMessageStyle The styling of the confirm message. Defaults to `delete` if not specified specified.
* @param {string=} overlay.submitButtonStyle The styling of the confirm button. Possible values are inherited from the [umbButton directive](#/api/umbraco.directives.directive:umbButton) and are `primary`, `info`, `success`, `warning`, `danger`, `inverse`, `link` and `block`. Defaults to `danger` if not specified specified.
* @param {string=} overlay.submitButtonLabelKey The key to be used for the confirm button label. Defaults to `actions_delete` if not specified.
* @param {function=} overlay.close A callback function that is invoked when the user closes the overlay.
* @param {function=} overlay.submit A callback function that is invoked when the user confirms the overlay.
*/
function confirmDelete(overlay) {
overlay.confirmType = "delete";
confirm(overlay);
}

/**
* @ngdoc method
* @name umbraco.services.overlayService#confirmRemove
* @methodOf umbraco.services.overlayService
*
* @description
* Opens a new overlay prompting the user to confirm the overlay. The overlay will have styling and labels useful for when the user needs to confirm a remove action.
*
* @param {object} overlay The options for the overlay.
* @param {string=} overlay.closeButtonLabelKey The key to be used for the cancel button label. Defaults to `general_cancel` if not specified.
* @param {string=} overlay.view The URL to the view. Defaults to `views/common/overlays/confirm/confirm.html` if nothing is specified.
* @param {string=} overlay.confirmMessageStyle The styling of the confirm message - eg. `danger`.
* @param {string=} overlay.submitButtonStyle The styling of the confirm button. Possible values are inherited from the [umbButton directive](#/api/umbraco.directives.directive:umbButton) and are `primary`, `info`, `success`, `warning`, `danger`, `inverse`, `link` and `block`. Defaults to `primary` if not specified specified.
* @param {string=} overlay.submitButtonLabelKey The key to be used for the confirm button label. Defaults to `actions_remove` if not specified.
* @param {function=} overlay.close A callback function that is invoked when the user closes the overlay.
* @param {function=} overlay.submit A callback function that is invoked when the user confirms the overlay.
*/
function confirmRemove(overlay) {
overlay.confirmType = "remove";
confirm(overlay);
Expand Down

0 comments on commit 152956b

Please sign in to comment.