(Recommendation) Prefer $uibModalInstance.close() to dismiss modals

[jniles]

This recommendation is based off a conversation with @DedrickEnc, who brought it to my attention.

The normal method for canceling or dismissing modals is to use the $uibModalInstance.dismiss() call. Unfortunately, this will reject the modal's promise instance, causing the .catch() method on the promise to fire.

A better way would be to call close with no data (or with false), and exit out of the promise chain that way. See below:

var modal = Modals.openSomeModal();

modal.then(function (data) {

  // if we call $uibModalInstance.close(), or $uibModalInstance.close(false), we can 
  // use the 'if' statement below to exit out of this promise statement before 
  // any other logic occurs.
  if (!data) { return; }

  // this will never fire if data is false-y
  return $http.post('/some/url', data);
})
.catch(function (err) {

  // if we call $uibModalInstance.dismiss() inside the modal, we will end 
  // up in this catch statement.  This is bad if this promise chain 
  // also involves a HTTP request, or uses Notify.handleError()
  // to automatically try and display an error to the user!

  Notify.handleError(err);  // oh-no! `err` is undefined!
});