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'sinitialize
methodloadParams
Object <optional>
any additional parameters to be
passed to the editor'sload
methoded
module:nmodule/webEditors/rc/fe/BaseWidget <optional>
optionally,
pass in an editor instance to just initialize and load that, skipping themakeFor
stepReturns:
promise to be resolved with the
instance of the editor (fully initialized and loaded), or rejected if
invalid parameters are given (including missingdom
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 onbajaux/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 withundefined
if no constructor is
registered. Note that if an invalid RequireJS module ID was passed tofe.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 - callinginstantiate()
andload()
is still your
job. (SeebuildFor
.)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 supportReturns:
promise to be resolved after the module
registration is complete. Note thatgetDefaultConstructor()
,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 onfe
. 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/BaseWidgetType:
- 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 theComplex
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 thevalue
.
You can also use a RequireJS module ID that resolves to aWidget
subclass. This parameter is most useful withbuildFor()
.dom
jQuery <optional>
the DOM element in which the new widget should
be initialized, if applicableproperties
Object | module:bajaux/Properties <optional>
the bajaux
Properties the new widget should have. If the PropertyuxFieldEditor
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 aweb: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 byBaseWidget
and its subclasses).