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:nmodule/webEditors/rc/fe/BaseWidget <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:nmodule/webEditors/rc/fe/BaseWidget

Type:
  • Object
Properties:
Name Type Argument Description
value * <optional>

the value to be loaded into the new widget, if
applicable.

complex baja.Complex <optional>

if given (with slot as well), will
instantiate a complex editor that will save changes back to the Complex
instance.

slot baja.Slot | String <optional>

if given (with complex as well), will
instantiate an editor for the value at this slot.

type String | function <optional>

a bajaux/Widget subclass constructor
function - if given an instance of that Widget will always be
instantiated instead of dynamically looked up from the type of the value.
You can also use a RequireJS module ID that resolves to a Widget
subclass. This parameter is most useful with buildFor().

dom jQuery <optional>

the DOM element in which the new widget should
be initialized, if applicable

properties Object | module:bajaux/Properties <optional>

the bajaux
Properties the new widget should have. If the Property uxFieldEditor is
present, its string value will be used to determine the type of widget to
create. This can be a type spec that resolves to a web:IJavaScript type,
or a RequireJS module ID.

facets Object | baja.Facets <optional>

(Deprecated: use properties) additional Facets information to
apply to the new widget. Facets will be added as hidden transient
bajaux Properties. (If a Property with the same key is also given, it will
be overridden by the facet.)

enabled Boolean <optional>

set to false to cause the new widget to be
disabled. Not used for lookups.

readonly Boolean <optional>

set to true to cause the new widget to be
readonly. Not used for lookups.

formFactors String | Array.<String> <optional>

the possible form factors
the new widget should have. The created widget could match any of these
form factors depending on what is registered in the database. If no widget
is found that supports any of these form factors, then no widget will be
created (even if one is present that supports a different form factor). If
no form factor is given, then the widget created could be of any form
factor.

formFactor String <optional>

same as a formFactors array of length 1.

data Object <optional>

an object literal containing any additional
values to be passed to the new widget's constructor (only supported by
BaseWidget and its subclasses).