Skip to content

Commit 152956b

Browse files
abjernermikecp
abjerner
authored and
mikecp
committed
Added ngdocs documentation for overlay.service.js
1 parent 7e55c46 commit 152956b

File tree

1 file changed

+134
-0
lines changed

1 file changed

+134
-0
lines changed

‎src/Umbraco.Web.UI.Client/src/common/services/overlay.service.js

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,58 @@
1212

1313
var currentOverlay = null;
1414

15+
/**
16+
* @ngdoc method
17+
* @name umbraco.services.overlayService#open
18+
* @methodOf umbraco.services.overlayService
19+
*
20+
* @description
21+
* Opens a new overlay.
22+
*
23+
* @param {object} overlay The rendering options for the overlay.
24+
* @param {string=} overlay.view The URL to the view. Defaults to `views/common/overlays/default/default.html` if nothing is specified.
25+
* @param {string=} overlay.position The alias of the position of the overlay. Defaults to `center`.
26+
*
27+
* 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:
28+
*
29+
* <pre>
30+
* .umb-overlay.umb-overlay-center {
31+
* position: absolute;
32+
* width: 600px;
33+
* height: auto;
34+
* top: 50%;
35+
* left: 50%;
36+
* transform: translate(-50%,-50%);
37+
* border-radius: 3px;
38+
* }
39+
* </pre>
40+
* @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.
41+
*
42+
* 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:
43+
*
44+
* <pre>
45+
* .umb-overlay-center.umb-overlay--medium {
46+
* width: 800px;
47+
* }
48+
* </pre>
49+
* @param {booean=} overlay.disableBackdropClick A boolean value indicating whether the click event on the backdrop should be disabled.
50+
* @param {string=} overlay.title The overall title of the overlay. The title will be omitted if not specified.
51+
* @param {string=} overlay.subtitle The sub title of the overlay. The sub title will be omitted if not specified.
52+
* @param {object=} overlay.itemDetails An item that will replace the header of the overlay.
53+
* @param {string=} overlay.itemDetails.icon The icon of the item - eg. `icon-book`.
54+
* @param {string=} overlay.itemDetails.title The title of the item.
55+
* @param {string=} overlay.itemDetails.description Sets the description of the item. *
56+
* @param {string=} overlay.submitButtonLabel The label of the submit button. To support localized values, it's recommended to use the `submitButtonLabelKey` instead.
57+
* @param {string=} overlay.submitButtonLabelKey The key to be used for the submit button label. Defaults to `general_submit` if not specified.
58+
* @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`.
59+
* @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.
60+
* @param {string=} overlay.hideSubmitButton A boolean value indicating whether the submit button should be hidden. Default is `false`.
61+
* @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`.
62+
* @param {string=} overlay.closeButtonLabel The label of the close button. To support localized values, it's recommended to use the `closeButtonLabelKey` instead.
63+
* @param {string=} overlay.closeButtonLabelKey The key to be used for the close button label. Defaults to `general_close` if not specified.
64+
* @param {string=} overlay.submit A callback function that is invoked when the user submits the overlay.
65+
* @param {string=} overlay.close A callback function that is invoked when the user closes the overlay.
66+
*/
1567
function open(newOverlay) {
1668

1769
// prevent two open overlays at the same time
@@ -49,6 +101,14 @@
49101
eventsService.emit("appState.overlay", overlay);
50102
}
51103

104+
/**
105+
* @ngdoc method
106+
* @name umbraco.services.overlayService#close
107+
* @methodOf umbraco.services.overlayService
108+
*
109+
* @description
110+
* Closes the current overlay.
111+
*/
52112
function close() {
53113
focusLockService.removeInertAttribute();
54114

@@ -61,6 +121,16 @@
61121
eventsService.emit("appState.overlay", null);
62122
}
63123

124+
/**
125+
* @ngdoc method
126+
* @name umbraco.services.overlayService#ysod
127+
* @methodOf umbraco.services.overlayService
128+
*
129+
* @description
130+
* Opens a new overlay with an error message.
131+
*
132+
* @param {object} error The error to be shown.
133+
*/
64134
function ysod(error) {
65135
const overlay = {
66136
view: "views/common/overlays/ysod/ysod.html",
@@ -72,6 +142,36 @@
72142
open(overlay);
73143
}
74144

145+
/**
146+
* @ngdoc method
147+
* @name umbraco.services.overlayService#confirm
148+
* @methodOf umbraco.services.overlayService
149+
*
150+
* @description
151+
* Opens a new overlay prompting the user to confirm the overlay.
152+
*
153+
* @param {object} overlay The options for the overlay.
154+
* @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`.
155+
* @param {string=} overlay.closeButtonLabelKey The key to be used for the cancel button label. Defaults to `general_cancel` if not specified.
156+
* @param {string=} overlay.view The URL to the view. Defaults to `views/common/overlays/confirm/confirm.html` if nothing is specified.
157+
* @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.
158+
* @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`.
159+
*
160+
* If not specified, the fallback value depends on the value specified for the `overlay.confirmType` parameter:
161+
*
162+
* - `delete`: fallback key is `danger`
163+
* - `remove`: fallback key is `primary`
164+
* - anything else: no fallback AKA default button style
165+
* @param {string=} overlay.submitButtonLabelKey The key to be used for the confirm button label.
166+
*
167+
* If not specified, the fallback value depends on the value specified for the `overlay.confirmType` parameter:
168+
*
169+
* - `delete`: fallback key is `actions_delete`
170+
* - `remove`: fallback key is `actions_remove`
171+
* - anything else: fallback is `general_confirm`
172+
* @param {function=} overlay.close A callback function that is invoked when the user closes the overlay.
173+
* @param {function=} overlay.submit A callback function that is invoked when the user confirms the overlay.
174+
*/
75175
function confirm(overlay) {
76176

77177
if (!overlay.closeButtonLabelKey) overlay.closeButtonLabelKey = "general_cancel";
@@ -99,11 +199,45 @@
99199
open(overlay);
100200
}
101201

202+
/**
203+
* @ngdoc method
204+
* @name umbraco.services.overlayService#confirmDelete
205+
* @methodOf umbraco.services.overlayService
206+
*
207+
* @description
208+
* 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.
209+
*
210+
* @param {object} overlay The options for the overlay.
211+
* @param {string=} overlay.closeButtonLabelKey The key to be used for the cancel button label. Defaults to `general_cancel` if not specified.
212+
* @param {string=} overlay.view The URL to the view. Defaults to `views/common/overlays/confirm/confirm.html` if nothing is specified.
213+
* @param {string=} overlay.confirmMessageStyle The styling of the confirm message. Defaults to `delete` if not specified specified.
214+
* @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.
215+
* @param {string=} overlay.submitButtonLabelKey The key to be used for the confirm button label. Defaults to `actions_delete` if not specified.
216+
* @param {function=} overlay.close A callback function that is invoked when the user closes the overlay.
217+
* @param {function=} overlay.submit A callback function that is invoked when the user confirms the overlay.
218+
*/
102219
function confirmDelete(overlay) {
103220
overlay.confirmType = "delete";
104221
confirm(overlay);
105222
}
106223

224+
/**
225+
* @ngdoc method
226+
* @name umbraco.services.overlayService#confirmRemove
227+
* @methodOf umbraco.services.overlayService
228+
*
229+
* @description
230+
* 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.
231+
*
232+
* @param {object} overlay The options for the overlay.
233+
* @param {string=} overlay.closeButtonLabelKey The key to be used for the cancel button label. Defaults to `general_cancel` if not specified.
234+
* @param {string=} overlay.view The URL to the view. Defaults to `views/common/overlays/confirm/confirm.html` if nothing is specified.
235+
* @param {string=} overlay.confirmMessageStyle The styling of the confirm message - eg. `danger`.
236+
* @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.
237+
* @param {string=} overlay.submitButtonLabelKey The key to be used for the confirm button label. Defaults to `actions_remove` if not specified.
238+
* @param {function=} overlay.close A callback function that is invoked when the user closes the overlay.
239+
* @param {function=} overlay.submit A callback function that is invoked when the user confirms the overlay.
240+
*/
107241
function confirmRemove(overlay) {
108242
overlay.confirmType = "remove";
109243
confirm(overlay);

0 commit comments

Comments
 (0)