Tutorial

Client Modals

DCP Client ships with a few modals that are used in the browser to prompt the client for keystores, passphrases, and for miscellaneous other dialogs.

By default the client modal will use templates that are provided by DCP Client to build the modals, but custom templates can be provided to override the appearance. See Custom Templates for details.

Using Modals

The Client Modal module can be accessed from DCP Client:

const ClientModal = dcp['client-modal'];

It contains the following exported modals:

Export Name Description Documentation
confirm A common confirm modal, with customizable buttons for positive (returns true) and negative (returns false) confirmation. dcp/client-modal#confirm
alert A common alert modal, with a single button to dismiss the modal. dcp/client-modal#alert
getPassword A passphrase prompt modal, containing a password field for collecting the user's input. dcp/client-modal#getPassword
getKeystoreFile A keystore file upload modal, with a file input element and a checkbox for the user to choose to remember the keystore. dcp/client-modal#getKeystoreFile

Each of these modal functions will return a promise, which will resolve when the modal's form (see below) is submitted and reject only when the modal is closed by either clicking the 'x' in the top-right or pressing esc. When an onClose callback is provided, it overrides this default behavior.

Each modal contains a form for controlling when the modal will resolve. The inputs in the modal should all have the form property set on them to link them to the form, so that the buttons can submit the form when clicked.

At their core, the modals are handled by the Micromodal module, which has a few useful features; One being that you can provide an element in your custom template with the parameter data-micromodal-close which, when clicked, will cause micromodal to close the modal. This is used by the 'x' button in the default modal, and any custom elements that use it will have the same behaviour regarding promise rejection/onClose.

Custom Templates

The provided default modals can be overridden by including html that contains the IDs for the modal you would like to replace. When showing a modal, the ClientModal module will first search for its required IDs on the page (See each modal's template section for the required IDs). If the required IDs are found, the ClientModal will use those DOM elements when building the modal. If it cannot find the IDs on the page, then the default modal will be loaded.

Confirm Modal

Confirm Modal Image

Custom Template

Required IDs:

  • dcp-modal-confirm
  • dcp-modal-confirm-form
  • dcp-modal-confirm-prompt
  • dcp-modal-confirm-positive-button
  • dcp-modal-confirm-negative-button

Optional IDs:

  • dcp-modal-confirm-title

Minimal example:

<div id="dcp-modal-confirm">
  <form id="dcp-modal-confirm-form" method="dialog"></form>
  <h2 id="dcp-modal-confirm-title"></h2>
  <p id="dcp-modal-confirm-prompt"></p>

  <!--
    These buttons will be populated with button labels and be used to submit the form.
  -->
  <button form="dcp-modal-confirm-form" id="dcp-modal-confirm-negative-button"></button>
  <button form="dcp-modal-confirm-form" id="dcp-modal-confirm-positive-button"></button>
</div>
Docs:

Alert Modal

Alert Image

Custom Template

Required IDs:

  • dcp-modal-alert
  • dcp-modal-alert-form
  • dcp-modal-alert-message
  • dcp-modal-alert-submit-button

Optional IDs:

  • dcp-modal-alert-title

Minimal example:

<div id="dcp-modal-alert">
  <form id="dcp-modal-alert-form" method="dialog"></form>
  <h2 id="dcp-modal-alert-title"></h2>
  <p id="dcp-modal-alert-message"></p>

  <button form="dcp-modal-alert-form" id="dcp-modal-alert-submit-button"></button>
</div>
Docs:

Get Password Modal

Get Password Modal Image

Custom Template

Required IDs:

  • dcp-modal-password
  • dcp-modal-password-form
  • dcp-modal-password-prompt
  • dcp-modal-password-hidden-username
  • dcp-modal-password-input

Minimal example:

<div id="dcp-modal-password">
  <form id="dcp-modal-password-form" method="dialog"></form>
  <p id="dcp-modal-password-prompt"></p>
  <input id='dcp-modal-password-hidden-username' form="dcp-modal-password-form"
    type="text" autocomplete="username" name="username" style="display:none">

  <input id="dcp-modal-password-input" form="dcp-modal-password-form"
    type="password" autocomplete="current-password">

  <button form="dcp-modal-password-form">Submit</button>
</div>
Docs:

Get Keystore File Modal

Get Keystore File Modal Image

Custom Template

Required IDs:

  • dcp-modal-keystore-file
  • dcp-modal-keystore-file-form
  • dcp-modal-keystore-file-prompt
  • dcp-modal-keystore-file-input
  • dcp-modal-keystore-file-checkbox

Minimal example:

<div id="dcp-modal-keystore-file">
  <form id="dcp-modal-keystore-file-form" method="dialog"></form>
  <p id="dcp-modal-keystore-file-prompt"></p>
  <input id="dcp-modal-keystore-file-input" form="dcp-modal-keystore-file-form" type="file" required="required">

  <!-- This checkbox will cache the keystore if checked  -->
  <input id="dcp-modal-keystore-file-checkbox" form="dcp-modal-keystore-file-form" type="checkbox">
  <button form="dcp-modal-keystore-file-form">Submit</button>
</div>
Docs: