SC.dialog.js
SC.dialog.showModalActivityBox(title, message)
Displays a modal containing an animated ActivityIndicator element. Used to indicate that actions are being processed by the server.
Parameters
| Name | Type | Description |
| title | String | Text to display within the head of the modal box |
| message | String | Text to display within the body of the modal box |
Return type
Returns the modal to be displayed
Example
A showProc function is defined for the SC.dialog.showModalActivityAndReload method defining how the modal should appear.
var showProc = function () {
SC.dialog.showModalActivityBox(SC.res['ActivityPanel.Title'],
SC.res['ActivityPanel.' + (SC.util.isNullOrEmpty(operationKey) ? '' : operationKey) +
'ReloadingMessage']);
};
SC.dialog.showModalActivityAndReload(operationKey, shouldWaitForRestart, reloadUrl)
Displays a modal capable of reloading to a new location after a service restart. Primarily used to signify server-side changes and redirect the user after a period of time.
Parameters
| Name | Type | Description |
|
operationKey |
String | Used to index the resx file, like ActivityPanel.<operationKey>.ReloadingMessage |
| shouldWaitForRestart | Boolean | Determination of whether the modal should wait before executing the checkProc to see if the activity has completed |
| reloadUrl | String | Location to where the browser should be redirected within the checkProc |
Return type
void
Example
A global handler is added to the PageDataDirtied event to automatically reload the entire page and return the user to the same page.
SC.event.addGlobalHandler(SC.event.PageDataDirtied, function () {
SC.dialog.showModalActivityAndReload(null, true, window.location.href);
});
SC.dialog.showModalPromptCommandBox(commandName, requiresData, isDataMultiLine, completeProc, optionalSubCommand)
Displays a modal used to gather specific text input from a user.
Parameters
| Name | Type | Description |
| commandName | String | Identification used to link events to particular DOM objects |
| requiresData | Boolean | Determines whether or not a TextBox will be added to the mainContentPanel |
| isDataMultiLine | Boolean | Determines whether the TextBox will have multi-line data |
| completeProc | function | Function to be executed upon submission of the modal |
| optionalSubCommand | String | An optional sub-identification used to link events to particular DOM objects |
Return type
void
Example
When the UninstallExtension command is executed, the modal prompt command box prompts the user for confirmation before proceeding and processing the uninstall.
switch (eventArgs.commandName) {
case 'UninstallExtension':
SC.dialog.showModalPromptCommandBox(eventArgs.commandName, false, false,
function (data, onSuccess) {
SC.service.UninstallExtension(
extensionInfo.ExtensionID,
function () {
onSuccess();
SC.pagedata.notifyDirty();
});
});
break;
}
SC.dialog.showModalErrorBox(message)
Displays a modal capable of displaying text and an error indicator
Parameters
| Name | Type | Description |
| message | String | Text to display within the body of the modal |
Return type
Returns the modal to be displayed
Example
When the fileReader object is initialized, its onerror handler is defined to display any error within the defined modal.
fileReader.onerror = function (event) {
SC.dialog.showModalErrorBox(fileReader.error instanceof FileError ? "FileReader error - code: " + fileReader.error.code : fileReader.error.name + ": " +
fileReader.error.message);
uploadCompleteProc();
};
SC.dialog.showModalMessageBox(title, message)
Displays a simple modal containing a title and body.
Parameters
| Name | Type | Description |
| title | String | Text to display within the head of the modal box |
| message | String | Text to display within the box of the modal |
Return type
Returns the modal to be displayed
Example
When the SendTestEmail server-side method is invoked and returns successfully, a simple message modal is displayed.
SC.service.SendTestEmail(from, relayHost, to, function (email) {
SC.dialog.showModalMessageBox(SC.res["MailPane1 .SuccessHeading"],
SC.res["MailPanel.SuccessMessage"]);
});
SC.dialog.showModalPage(title, url, onHideProc)
Displays a webpage of your choosing within a page-sized modal using an iframe.
Note: this function does not allow the user to navigate to a site of a different domain that the initially displayed page.
Parameters
| Name | Type | Description |
| title | String | Text to display within the head of the modal box |
| url | String | Location to be displayed within the modal |
| onHideProc | Function | Function to be executed when a user closes the modal |
Return type
void
Example
When the ShowExtensionBrowser command executes, the Extension Marketplace is loaded within the browser to allow for in-application extension installation
SC.dialog.showModalPage(
SC.res['ExtensionsPanel.ExtensionBrowser.Title'],
SC.res['ExtensionsPanel.BaseUrl'] + 'Extension-Browse' + SC.util.getQueryString({ Select: eventArgs.commandArgument }),
function () {
if (window._needsReloadOnExtensionBrowserExit) {
SC.dialog.showModalActivityAndReload('Save', true);
return true; // stop propagation of escape key handling to prevent reload modal from immediately closing
}
}
);
SC.dialog.showConfirmationDialog(subClassName, title, message, buttonText, executeProc)
Displays a simple modal used to prompt a user for confirmation before executing an action.
Parameters
| Name | Type | Description |
| subClassName | String | Class(es) assigned to the modal when added to the DOM. Used for specific styling of modal using base CSS files, files inside the extension, or files at an external source |
| title | String | Text to display within the body of the modal |
| message | String | Text to display within the body of the modal |
| buttonText | String | Text to display on the command button at the bottom of the modal |
| executeProc | Function | Function to be executed when the modal's button is pressed. This can be used alongside the buttonCommandName to act upon both generic and context-specific actions |
Return type
void
Example
When a User Role is deleted the Administrator is prompted for confirmation before proceeding.
case 'DeleteRole':
SC.dialog.showConfirmationDialog(
'DeleteRole',
SC.res['DeleteRolePane1.Title'],
$p({
innerHTML: SC.res['DeleteRolePanel.Text']
}),
SC.res['DeleteRolePanel.ButtonText'],
function (onSuccess, onFailure) {
SC.service.DeleteRole(
SC.command.getEventDataItem(eventArgs).Name,
function () {
onSuccess();
SC.pagedata.notifyDirty();
},
onFailure);
});
break;
SC.dialog.showModalButtonDialog(subClassName, title, buttonText, buttonCommandName, contentBuilderProc, onExecuteCommandProc, onQueryCommandButtonStateProc)
Displays a modal with a specified title, body, and single button; the content of the modal's body and the action generated by the button are can be specified via functions
| Name | Type | Description |
| subClassName | String | Class(es) assigned to the modal when added to the DOM; used for specific styling of modal using base CSS files, files inside the extension, or files at an external source |
| title | String | Text to display within the head of the modal box |
| buttonText | String | Text to display on the command button at the bottom of the modal |
| buttonCommandName | String | Name used to assign any commands to the modal's button. Recommended to use when multiple buttons might need to share a single command (e.g. "Close") |
| contentBuilderProc | Function | Function used to add elements inside the body of the modal. Elements added to the container will be displayed at this function's execution |
| onExecuteCommandProc | Function | Function to be executed when the modal's button is pressed. This can be used alongside the buttonCommandName to act upon both generic and context-specific actions |
| onQueryCOmmandButtonStateProc | Function | Function to be executed when an inquiry about the button's state is processed |
Return type
None
Example
Using the SC.command functions, a button dialog modal is displayed when a particular button is pressed. In this example, the modal displays placeholder content for an example where the user is required to provide consent prior to executing a specific action. Similar implementations could be used to provide warnings and/or consent prompts prior to executing a particular action.
SC.event.addGlobalHandler(SC.event.QueryCommandButtons, function (eventArgs) {
switch (eventArgs.area) {
case 'ToolsPanel':
eventArgs.buttonDefinitions.unshift({
commandName: 'doActionWithConsent',
text: 'Action'
});
break;
}
});
SC.event.addGlobalHandler(SC.event.ExecuteCommand, function (eventArgs) {
switch (eventArgs.commandName) {
case 'doActionWithConsent':
SC.dialog.showModalButtonDialog(
'Prompt',
'Warning',
'I Agree',
'Default',
function (container) {
SC.ui.addElement(container, 'P', 'This action does something important.');
SC.ui.addElement(container, 'P', 'It requires your consent before executing.');
},
function (eventArgs) {
SC.dialog.hideModalDialog();
// doAction();
alert('Here is the placeholder for that action.');
});
break;
}
});
SC.dialog.showModalDialog(subClassName, title, content)
Displays an informational modal with a specified title and message; this differs from the message box modal in the fact that in accepts element objects rather than text, meaning it can display more complex information.
Parameters
| Name | Type | Description |
| subClassName | String | Class(es) assigned to the modal when added to the DOM; used for specific styling of modal using base CSS files, files inside the extension, or files at an external source |
| title | String | Text to display within the head of the modal box |
| content | Array | An array of element objects to be displayed within the body of the modal |
Return type
void
Example
Using the SC.command functions, a message box modal is displayed when a particular button is pressed. In this example, the modal displays a placeholder where information could be presented to the user. Implementations could be used display information, perhaps graphical, to the user (e.g. display current session status to Admin users)
SC.event.addGlobalHandler(SC.event.QueryCommandButtons, function (eventArgs) {
switch(eventArgs.area) {
case 'ToolsPanel':
eventArgs.buttonDefinitions.push(
{ commandName: 'Button', text: 'Status' }
);
break;
}
});
SC.event.addGlobalHandler(SC.event.ExecuteCommand, function (eventArgs) {
switch (eventArgs.commandName) {
case 'Button':
SC.dialog.showModalDialog(
'Prompt',
'Modal Title',
[
SC.ui.createElement('P', 'This is a test of the Dialog Modal'),
SC.ui.createElement('P', 'It may be used when information must be relayed to the user.')
]);
break;
}
});
SC.dialog.showModalDialogRaw(subclassName, dialogPanels, onExecuteCommandProc, onQueryCommandButtonStateProc, onHideProc)
Used to display a wider variety of potential modals. Allows for greater customization of the CSS, contents, and functionality.
Parameters
| Name | Type | Description |
| subClassName | String | Class(es) assigned to the modal when added to the DOM |
| dialogPanels | DOM Array | a list of DOM panel elements |
| onExecuteCommandProc | Function | Function to be executed when the modal's button is pressed. This can be used alongside the buttonCommandName to act upon both generic and context-specific actions |
| onQueryCommandButtonStateProc (Function) | Function | Function to be executed when an inquiry about the button's state is processed |
| onHideProc | Function | Function to execute upon closing the modal |
Return type
void
Example
When a JoinSession event is initiated from the web application, a simple modal is displayed to give additional instructions to the user.
SC.dialog.showModalDialogRaw('JoinSession', [titlePane1, contentPanel, buttonPanel],
onExecuteCommandProc, null, function () {
SC.event.removeGlobalHandler(SC.event.PageDataRefreshed, refreshProc);
});
SC.dialog.getModalDialog()
A helper method used to retrieve the currently displayed modal
Parameters
| Name | Type | Description |
| None |
Return type
Returns the currently displayed modal dialog
Example
Lorem ipsum
SC.dialog.hideModalDialog()
A helper method used to hide the currently displayed modal. It also ensures execution of the modal’s onHideProc if defined.
Parameters
| Name | Type | Description |
| None |
Return type
Lorem ipsum
Example
When a session is edited from the Host page, the new values are pulled from the EditSessions modal and passed to the server. If this action is successful then the EditSessions modal is hidden.
SC.service.UpdateSessions(
sessionGroupName,
sessionIDs,
names,
customPropertyValues,
function () {
SC.dialog.hideModalDialog();
},
function (error) {
SC.dialog.setButtonPanelError(buttonPanel, error);
});
SC.dialog.createTitlePanel(title)
A helper method used to create the title panel in modals
Parameters
| Name | Type | Description |
| title | String |
Return type
Returns the created panel
Example
The titlePanel is created containing only a single string.
function showEditSessionsDialog(sessionGroupName, sessions) {
var titlePanel = SC.dialog.createTitlePane1(SC.res['EditSessionsPanel.Title']);
var mainContentPanel = SC.dialog.createContentPanel();
var buttonPanel =
SC.dialog.createButtonPanel(SC.res['EditSessionsPanel.ButtonText']);
var definitionList = SC.ui.addElement(mainContentPanel, 'DL');
SC.dialog.createContentPanel(varargs)
A helper method used to create the content panel in modals
Parameters
| Name | Type | Description |
| varargs | DOM Object Array | A list of objects to be added to the panel |
Return type
Returns the created panel
Example
An empty content panel is instantiated and then a single definition list element is added
function showEditSessionsDialog(sessionGroupName, sessions) {
var titlePanel = SC.dialog.createTitlePanel(SC.res['EditSessionsPane1.Title']);
var mainContentPanel = SC.dialog.createContentPanel();
var buttonPanel =
SC.dialog.createButtonPanel(SC.res['EditSessionsPanel.ButtonText']);
var definitionList = SC.ui.addElement(mainContentPanel, 'DL');
SC.dialog.createButtonPanel(defaultButtonText, varargs)
A helper method used to create the button panel used in some modals
Parameters
| Name | Type | Description |
| defaultButtonText | String | Text to display on the command button within the panel |
| varargs | DOM Object Array | A list of objects to be added to the panel |
Return type
Returns the created panel
Example
A button panel is created containing a single button.
function showEditSessionsDialog(sessionGroupName, sessions) {
var titlePanel = SC.dialog.createTitlePanel(SC.res['EditSessionsPanel.Title']);
var mainContentPanel = SC.dialog.createContentPanel();
var buttonPanel = SC.dialog.createButtonPanel(SC.res['EditSessionsPanel.ButtonText']);
var definitionList = SC.ui.addElement(mainContentPanel, 'DL');
SC.dialog.setButtonPanelError(buttonPanel, error)
A helper method used to set the inner contents of the button panel of a modal
Parameters
| Name | Type | Description |
| buttonPanel | DOM Object Array | A list of existing button panels to be modified |
| error | String | The error message contents |
Return type
void
Example
When a Session is edited from the Host page, the new values are pulled from the EditSessions modal and passed to the server. If this action encounters an error then the error’s contents are returned to the button panel
SC.service.UpdateSessions(
sessionGroupName,
sessionIDs,
names,
customPropertyValues,
function () { SC.dialog.hideModalDialog(); },
function (error) { SC.dialog.setButtonPanelError(buttonPanel, error); }
);