nmodule/webEditors/rc/fe/feDialogs

Methods

(static) action(params) → {Promise}

Description:

• 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.

Source:

• fe/feDialogs.js, line 719

Parameters:

Returns:

Type

Promise

(static) error(err, paramsopt) → {Promise}

Description:

• Show details about an error.

Source:

• fe/feDialogs.js, line 919

Parameters:

Returns:

Type

Promise

(static) props(props, paramsopt) → {Promise.<(object|null)>}

Description:

• A simple mechanism for editing multiple properties at once.

Source:

• fe/feDialogs.js, line 838

Since:

• Niagara 4.14

Examples

Edit a simple key->value map.

return feDialogs.props({ foo: 'bar' }); // resolves an object with user-edited "foo" property

Edit a nested key->value map.

return feDialogs.props({
  user: { value: { firstName: 'Moe', lastName: 'Howard' } }
}); // resolves an object with a "user" property containing user-editor "firstName" and "lastName"

Specify display name

return feDialogs.props({
  foo: { displayName: 'Your foo value', value: 'bar' }
}); // resolves an object with user-entered "foo" property, but user was shown customized display name

Use display name from lexicon

return feDialogs.props({
  overrideValue: { displayName: '%lexicon(control:override.value)%', value: 0 }
}); // resolves an object with user-entered "overrideValue" property but user was shown "Override Value" from lexicon

Specify flags

return feDialogs.props({
  hidden: { value: 'hiddenValue', hidden: true },
  readonly: { value: 'readonlyValue', readonly: true }
}); // resolves an object with "hidden" and "readonly" values. User did not see "hidden" and was not able to edit "readonly".

Specify properties

return feDialogs.props({
  percent: { value: 0, properties: { min: 0, max: 100 } }
}); // resolves an object with "percent" value. Editor was validated to be between 0 and 100.

Edit a Complex directly

const comp = baja.$('control:NumericWritable');
return feDialogs.props(comp); // please note that the input Complex will be *saved* when the user clicks OK

Specify title and summary

return feDialogs.props({ foo: 'bar' }, {
  title: 'Foo Dialog',
  summary: 'Please enter your foo value'
});

Parameters:

Returns:

Type

Promise.<(object|null)>

(static) selfClosing(params) → {Promise}

Description:

• 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.

Source:

• fe/feDialogs.js, line 667

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!
    }
  });

Parameters:

Returns:

Type

Promise

(static) showFor(params) → {Promise}

Description:

• 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.

Source:

• fe/feDialogs.js, line 383

Examples

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 valid', arg);
      }
    }
  })
  .then(function (str) {
    if (str === null) {
      console.log('you clicked cancel');
    } else {
      console.log('you entered: ' + str);
    }
  });

Specify custom button handlers. If the user clicks one of these custom buttons, the showFor promise will be resolved with the value resolved by its handler.

feDialogs.showFor({
  value: 'enter a string',
  buttons: [ {
    name: 'uppercase',
    displayName: 'Uppercase It',
    handler: (dialog, event, editor) {
      // the arguments to the button handler are: the Dialog instance, the click event,
      // and the editor being shown in the dialog.
      // call `dialog.keepOpen` if you are not ready for the dialog to close. the dialog will
      // stay open and the promise will not be resolved yet.

      dialog.keepOpen();
      return editor.read().then((string) => editor.load(string.toUpperCase());
    }
  }, {
    name: 'lowercase',
    displayName: 'Lowercase It',
    handler: (dialog, event, editor) {
      dialog.keepOpen();
      return editor.read().then((string) => editor.load(string.toLowerCase()));
    }
  }, {
    // default 'ok' behavior is to read the value and resolve the promise. you don't have to
    // specify a handler to do this.
    name: 'ok'
  } ]
});

The strings 'ok', 'cancel', 'yes', and 'no' are special - you can include them in the buttons parameter to get their default behavior.

// only show the OK button, and resolve the promise with the entered value. 'yes' works the same.
feDialogs.showFor({ value: 'enter a string', buttons: [ 'ok' ] });

// only show the Cancel button, and resolve the promise with null. 'no' works the same.
feDialogs.showFor({ value: 'your changes will not be used', buttons: [ 'cancel' ] });

The buttons parameter can be an object literal, where the values are button definitions or handler functions.

feDialogs.showFor({
  value: 'Value to Edit',
  buttons: {
    ok: () => 'my custom ok result', // the value can be just a handler function. the default display name will be used.
    cancel: {
      displayName: "Never Mind"
      // omit the handler, and default handler for "cancel" will resolve null.
    },
    yes: {}, // just an empty object will use the default display name and default handler.
    no: {
      handler: () => 'user clicked "no"' // include a handler to override the default handler.
    },
    delete: {
      // for anything other than 'ok', 'cancel', 'yes', or 'no', you'll need to provide a
      // display name - or else just the button name will be used.
      displayName: 'Delete Everything',
      handler: () => deleteEverything()
    },
    retry: shouldShowRetryButton() && { // falsy values will cause the button _not_ to be shown.
      displayName: 'Try Again',
      handler: () => letUserTryAgain()
    }
  }
});

Use the 'on' parameter to respond to any bajaux events that are triggered by the editor.

const { MODIFY_EVENT } = events;
feDialogs.showFor({
  value: 'edit me',
  properties: { max: 10 },
  on: {
    [MODIFY_EVENT]: (dialog, event, editor) {
      return editor.validate()
        .catch(() => alert('no more than 10 characters pls'));
    }
  }
});

Parameters:

Returns:

Type

Promise