webEditors

Module: nmodule/webEditors/rc/fe/fe

Functions for registering, looking up, and instantiating editors for
certain Baja types.

Methods

<static> buildFor(params [, ed])

Instantiates an editor as in makeFor, but with the added steps of
initializing and loading the editor. When the promise resolves, the
editor will be initialized within the DOM, and the passed value will have
been loaded into the editor.

Parameters:
Name Type Argument Description
params module:nmodule/webEditors/rc/fe/fe~FeParams
Properties
Name Type Argument Description
initializeParams Object <optional>

any additional parameters to be
passed to the editor's initialize method
loadParams Object <optional>

any additional parameters to be
passed to the editor's load method
ed module:bajaux/Widget <optional>

optionally,
pass in an editor instance to just initialize and load that, skipping the
makeFor step
Returns:

promise to be resolved with the
instance of the editor (fully initialized and loaded), or rejected if
invalid parameters are given (including missing dom parameter).

Type
Promise.<module:bajaux/Widget>
Examples

Build a raw editor for a String

fe.buildFor({
    value: 'my string',
    properties: { multiLine: true },
    dom: $('#myStringEditorDiv')
  }).then(function (editor) {
    //editor is now fully initialized and loaded
  });

Build an editor for a slot on a component

var myComponent = baja.$('baja:Component', { mySlot: 'hello world' });

  fe.buildFor({
    complex: myComponent,
    slot: 'mySlot',
    properties: { multiLine: true },
    dom: ${'#myStringSlotEditorDiv')
  }).then(function (editor) {
    //editor is now fully initialized and loaded

    $('#saveButton').click(function () {
      editor.save().then(function () {
        alert('your changes are applied to the component');
      });
    });
  });

Build a StringEditor even though you plan to load a different kind of value into it.

fe.buildFor({
    type: StringEditor,
    value: 5,
    dom: $('#myStringEditorDiv')
  }).then(function (stringEditor) {
    //StringEditor better be able to load the value you specified,
    //or this will reject instead.
  });

Example showing the effects of the uxFieldEditor facet (BFacets.UX_FIELD_EDITOR). By setting this slot facet to the type spec of a `BIJavaScript` implementation, you can force the usage of a particular field editor instead of relying on the agent registration. 

fe.buildFor({
    value: 5,
    dom: $('#myStringEditorDiv'),
    properties: { uxFieldEditor: 'webEditors:StringEditor' }
  }).then(function (stringEditor) {
    //uxFieldEditor facet enforced usage of StringEditor instead of the
    //default NumericEditor
  });

<static> getConstructors(type [, params])

Retrieve all available widget constructors for the given type.

Parameters:
Name Type Argument Description
type String | Type
params Object <optional>
Properties
Name Type Argument Description
formFactors Array.<String> <optional>
Returns:

promise to be resolved with an array
of constructor functions.

Type
Promise.<Array.<function()>>

<static> getDefaultConstructor(type [, params])

Retrieve the Widget constructor function registered for the given Type.

Parameters:
Name Type Argument Description
type String | Type
params Object <optional>
Properties
Name Type Argument Description
formFactors Array.<(String|Number)> <optional>

describes the form
factors that the resolved constructor is required to support. These can
be Strings referencing a form factor property on
bajaux/Widget.formfactor, or the value itself. If a constructor matches
any of these form factors it will be returned (union, not intersection).
Returns:

a promise to be resolved with the constructor
function for the given Type, or with undefined if no constructor is
registered. Note that if an invalid RequireJS module ID was passed to
fe.register(), it will still look up the supertype chain in an attempt
to resolve something.

Type
Promise.<function()>
Example
function StringEditor() {} //extends Widget
  fe.register('baja:String', StringEditor, {
    formFactors: [ Widget.formfactor.mini ]
  });

  //resolves StringEditor
  fe.getDefaultConstructor('baja:String', { formFactors: [ 'mini' ] });

  //resolves undefined
  fe.getDefaultConstructor('baja:String', { formFactors: [ 'compact' ] });

<static> makeFor(params)

Instantiate a new editor for a value of a particular Type.

Note that you will receive a constructed instance of the editor, but
it is uninitialized - calling instantiate() and load() is still your
job. (See buildFor.)

Parameters:
Name Type Description
params module:nmodule/webEditors/rc/fe/fe~FeParams
Returns:

promise to be resolved with an
editor instance, or rejected if invalid parameters are given.

Type
Promise.<module:bajaux/Widget>
Example

Instantiate an editor for a baja value. Note that the workflow below is easily simplified by using fe.buildFor() instead.

var myString = 'my string';
  fe.makeFor({
    value: myString
    properties: { multiLine: true }
  }).then(function (editor) {
    return editor.initialize($('#myStringEditorDiv'))
     .then(function () {
       return editor.load(myString);
     });
  });

<static> register(type, module [, params])

Registers a RequireJS module to a baja Type. This takes a RequireJS
module ID string which resolves to a module exporting a constructor for a
Widget subclass.

Parameters:
Name Type Argument Description
type Type | String
module String

RequireJS module ID
params Object <optional>
Properties
Name Type Argument Description
formFactors Array.<String> <optional>

form factors that this editor
should support
Returns:

promise to be resolved after the module
registration is complete. Note that getDefaultConstructor(), makeFor(),
etc. will still work (with some possible extra network calls) before the
promise is fully resolved. Promise will be rejected if RequireJS is unable
to resolve a given module ID.

Type
Promise
Example

Register StringEditor on baja:String, so that it can be used to build "mini" editors for Strings.

fe.register('baja:String', 'nmodule/webEditors/rc/fe/baja/StringEditor', {
    formFactors: [ Widget.formfactor.mini ]
  });

Type Definitions

FeParams

This type describes the available parameters to be passed to the various
methods on fe. These values will be used both to look up the type of the
desired editor, and also to construct that editor. In other words, the
data to look up a widget will also be used in the same turn to construct
that widget. See module:bajaux/Widget

Type:
  • module:bajaux/lifecycle/WidgetManager~BuildParams | FeSpecificParams