Javascript displayDialog - jcobban/Genealogy GitHub Wiki
Source: /jscripts/util.js
The function displayDialog lays out and makes a modal dialog visible. It takes the following parameters.
| parameter | contents |
|---|---|
| template | If this is a string this is the value of the id attribute of an HTML element that provides the structure and constant strings to be laid out in the dialog. Or a reference to an instance of HTMLElement may be passed. Normally this should be a <form> element since it must contain at least one action <button>. If it is not a <form> then it is wrapped in a <form>. If there are no <button>s in the template then a <button type='button'>Cancel</button> is appended to the dialog. |
| parms | an object containing values to substitute for symbols ($xxxx) in the template. |
| element | An instance of HTMLElement used for positioning the dialog for the user. This is normally the <button> for the user to request the service that is mediated by the dialog. If there is enough room to the right of this element the dialog is displayed there, otherwise it is displayed to the left of this element. If there is enough room below the element the dialog is displayed below the element, otherwise it is displayed above the element. Once displayed the dialog may be repositioned by dragging it with the mouse. |
| action | The onclick event handler[s] to set for buttons in the dialog. If null all buttons default to close the dialog. If this is an array of function references the actions are applied in order to the <button>s in the dialog. If this is a single function reference then it applies to the first button. If there are more buttons than entries in this parameter subsequent buttons close the dialog. This parameter may be omitted if there is only one <button> in the form. When the dialog is initially displayed the focus is set on the first button so that pressing the Enter key will take the default action for the dialog. |
| defer | If true leave the dialog hidden for the caller to complete and show. If this parameter is false or omitted then the dialog is displayed immediately. |
For example:
// ask user to confirm delete
displayDialog('CitDelTemplate',
parms,
this, // position relative to this Element
confirmDelete, // 1st button confirms Delete
false); // show immediately
The template for the appearance of the dialog is an HTML <form> element containing elements describing the dialog with placeholders for values supplied by the third parameter.
<!-- template for confirming the deletion of a citation-->
<form name="CitDelTemplate" id="CitDelTemplate">
<p class="message">$msg</p>
<p>
<button type="button" id="confirmDelete$idsx">
OK
</button>
<input type="hidden" id="rownum$idsx" name="rownum$idsx"
value="$rownum">
<input type="hidden" id="formname$idsx" name="formname$idsx"
value="$formname">
<button type="button" id="cancelDelete$idsx">
Cancel
</button>
</p>
</form>
The template for the dialog is defined in the application-specific and language-specific template from the common templates directory. Since the instantiation of a template by class \Templating\Template also causes placeholders to be replaced by parameter values, it is necessary either to escape the dollar signs in a run-time dialog template, or to load the run-time dialog template directly from the templates directory rather than as an instance of class Template.
An example of the third parameter is:
var parms = {"idsx" : idsx,
"rownum" : idsx,
"formname" : form.name,
"msg" : "Are you sure you want to delete this citation?"};
The matching placeholders in the template are replaced in a copy of the template.
The resulting dialog is positioned adjacent to the element passed as the fourth parameter, which is usually a <button> used to request a service. The dialog is displayed to permit the user to confirm or supply additional information about the service request.
Dialogs have one or more <button>s. In particular there must be a button that closes the dialog with no action, but there may be other buttons that take an action. In the example dialog there is a <button type="button" id="confirmDelete$idsx"> which requests that the service requested be performed, and a <button type="button" id="cancelDelete$idsx"> which causes the dialog to close without performing the service. Since the second button performs the default action, this call to displayDialog only supplies the action for the first button as a reference to a Javascript event handler. If there are more than two buttons in the dialog the fifth parameter is an array of references to Javascript event handlers.
If this method succeeds it returns a reference to the <div>. If defer is true then the caller should complete the initialization of the dialog and then make it visible by:
var dialog = displayDialog(...., true);
var form = dialog.getElementsByTagName('form')[0];
// actions on elements within the form
dialog.style.visibility = 'visible';
dialog.scrollIntoView();
dialog.style.display = 'block';
If this method fails it displays an error message in an alert, and returns false.