Module: nmodule/webEditors/rc/fe/feDialogs

Functions for showing field editors in modal dialogs. Useful for prompting
the user to enter values, edit individual slots, and fire actions.

Methods


<static> action(params)

Invoke an action on a mounted component. If the action requires a
parameter, a field editor dialog will be shown to retrieve that argument
from the user.

Parameters:
Name Type Description
params Object
Properties
Name Type Description
component baja.Component

the component on which to invoke
the action. Must be mounted.

slot String | baja.Slot

the action slot to invoke. Must be
a valid Action slot.

Returns:

promise to be resolved with the action return
value if the action was successfully invoked, resolved with null if
the user clicked Cancel, or rejected if the parameters were invalid or the
action could not be invoked.

Type
Promise

<static> error(err)

Show details about an error.

Parameters:
Name Type Description
err Error | *
Returns:
Type
Promise

<static> selfClosing(params)

Show an editor in a dialog, similar to showFor, but with the added
expectation that the editor represents a one-time interaction, like a
button click, after which the dialog can be immediately closed. In other
words, the "click ok to close" functionality is embedded in the editor
itself. Only a Cancel button will be shown in the dialog itself.

In order for the dialog to close, the shown editor must trigger a
feDialogs.VALUE_READY_EVENT, optionally with a read value. When this
event is triggered, the dialog will be closed and the promise resolved
with the value passed to the event trigger.

Parameters:
Name Type Description
params Object

params to be passed to fe.buildFor

Properties
Name Type Argument Default Description
title String <optional>

title for the dialog

delay Number <optional>
200

delay in ms to wait before showing a
loading spinner. The spinner will disappear when the field editor has
finished initializing and loading.

progressCallback function <optional>

pass a progress callback to
receive notifications as the editor being shown goes through the stages
of its life cycle (created, initialized, loaded).

Returns:

promise to be resolved when the editor has
triggered its own value event. It will be resolved with any value passed
to the event trigger, or with null if Cancel was clicked.

Type
Promise
Example

Trigger a VALUE_READY_EVENT to cause the dialog to be closed.

// ...
MyEditor.prototype.doInitialize = function (dom) {
  dom.on('click', 'button', function () {
    dom.trigger(feDialogs.VALUE_READY_EVENT, [ 'my value' ]);
  });
};
//...

feDialogs.selfClosing({
  type: MyEditor
}}
  .then(function (value) {
    if (value === 'my value') {
      //success!
    }
  });

<static> showFor(params)

Shows a field editor in a dialog.

When the user clicks OK, the editor will be saved, committing any changes.
The value that the user entered will be read from the editor and used to
resolve the promise.

Parameters:
Name Type Description
params Object

params to be passed to fe.buildFor().

Properties
Name Type Argument Default Description
dom jQuery <optional>

if your widget type should be instantiated
into a specific kind of DOM element, it can be passed in as a parameter.
Note that the given element will be appended to the dialog element itself,
so do not pass in an element that is already parented. If omitted, a div
will be created and used.

title String <optional>

title for the dialog

delay Number <optional>
200

delay in ms to wait before showing a
loading spinner. The spinner will disappear when the field editor has
finished initializing and loading.

save boolean <optional>

set to false to specify that the dialog
should not be saved on clicking OK - only the current value will be read
from the editor and used to resolve the promise.

progressCallback function <optional>

pass a progress callback to
receive notifications as the editor being shown goes through the stages
of its life cycle (created, initialized, loaded), as well as whenever
the editor is validated (invalid, valid).

Returns:

promise to be resolved when the user has entered
a value into the field editor and clicked OK, or rejected if the field
could not be read. The promise will be resolved with the value that the
user entered (or null if Cancel was clicked).

Type
Promise
Example
feDialogs.showFor({
    value: 'enter a string here (max 50 chars)',
    properties: { max: 50 },
    progressCallback: function (msg, arg) {
      switch(msg) {
      case 'created':     return console.log('editor created', arg);
      case 'initialized': return console.log('editor initialized', arg.jq());
      case 'loaded':      return console.log('editor loaded', arg.value());
      case 'invalid':     return console.log('validation error', arg);
      case 'valid':       return console.log('value is ok');
      }
    }
  })
  .then(function (str) {
    if (str === null) {
      console.log('you clicked cancel');
    } else {
      console.log('you entered: ' + str);
    }
  });