API Status: Development
A mixin to provide learn support to a bajaux manager view.
To support discovery, in addition to applying this mixin, the target manager object must
provide several functions that this mixin will use to accomplish the discovery and the
creation of new components from the discovered items.
The concrete manager must provide a makeLearnModel()
method. This should return aPromise
that will resolve to a TreeTableModel
. This will be used as the data model
for the discovery table. On completion of the discovery job, the manager should use the
result of the job to insert items into the discovery model.
The concrete manager must also provide an implementation of a doDiscover()
function
that will create a job (typically by invoking an action that will submit a job
and return the ord), and then set the job on the manager via the setJob()
function.
This function will accept the job instance or the ord for a job, specified either as
a baja.Ord
or a string.
Once the job is complete, a 'jobcomplete' tinyevent will be emitted on the manager. The
concrete manager will also typically have a handler for that event, which will get the
discovered items from the job by some means, and then update the discovery table. This
will normally involve inserting nodes into the learn model. The manager may store arbitrary
data on those nodes, which it may retrieve later via the node's value()
function.
The manager must also implement a getTypesForDiscoverySubject()
function. This will be called
when dragging an item from the discovery table to the database table or invoking the 'add'
command. The function may be called several times, each time its argument will be aTreeNode
representing the item to be added into to the database table. The implementation
of this function is expected to return a single MgrTypeInfo
instance or any array of them.
These will be used to create a new component instance of the required type for the discovered
node.
Also to support the addition of new components, the manager should implement a function
called getProposedValuesFromDiscovery()
. This will be passed the tree node that was dragged
from the discovery table to the database table. The function should obtain any information
the manager had set on the node at discovery time and use it to create an object containing
the initial values for the new component. The names of properties on the object returned by
the function will be compared against the column names in the main database model. For the
columns that have matching names, the values of those properties will be used to set the
initial proposed values on the new row(s) when the dialog for editing the new instances is
displayed.
Example
Add the MgrLearn mixin to a Manager subclass to add learn functionality.
require([...'nmodule/webEditors/rc/wb/mgr/MgrLearn'], function (...MgrLearn) { function MyManager() { Manager.apply(this, arguments); MgrLearn(this); } MyManager.prototype = Object.create(Manager.prototype); //implement abstract functions MyManager.prototype.doDiscover = function () { ... });
Extends
Methods
-
<abstract> doDiscover()
-
Abstract method used to initiate the discovery process. What this
implementation does is a matter for the concrete manager, but the typical
pattern will be to invoke an Action that will submit a job, and then set
that job or its Ord on the manager via the#setJob()
function.Returns:
Optionally return a Promise
- Type
- Promise | *
-
getExisting(discovery)
-
Search for the existing component that matches the given node from the
discovery table. To match a component, the concrete manager subclass
must contain a function namedisExisting()
which will be passed the
discovery object and a component. The function will be used as a predicate and
should return true if the given component represents the same item as
the discovery table item, false otherwise. If the manager does not provide
such a function, all discovery nodes will be considered as not matching any
existing components.Parameters:
Name Type Description discovery
* a discovered object
Returns:
the existing component that was found to match
the given discovery node, or undefined if no such match was found.- Type
- baja.Component
-
getJob()
-
Get the discovery job currently set against the manager.
Returns:
- Type
- baja.Component
-
getLearnModel()
-
Get the learn model. The model will have been created via a call to
makeLearnModel()
; a
function that the concrete manager must provide. This will return theTreeTableModel
resolved from the Promise.Returns:
-
getLearnTable()
-
Returns the TreeTable widget, used to display the discovered items.
- Since:
-
- Niagara 4.6
Returns:
the discovery table
-
<abstract> getProposedValuesFromDiscovery(discovery, subject)
-
Abstract method to get the initial values for a discovered node when it is
being added to the station as a new component. This method should return an
Object instance, with the values to be used by the new instances. The
returned object may have a property called 'name', which will be used to
set the slot name of the new component. It may also have a child object
named 'values'. Each property of this object with a name that matches the
name of aColumn
in the main table model will have that property's value
used as the initial value when the component editor is displayed.Parameters:
Name Type Description discovery
* an object obtained from a node in discovery table.
subject
* the subject of the
Row
whose values are to be
proposed.- See:
-
- module:nmodule/webEditors/rc/wb/table/tree/TreeNode
Returns:
an object literal with the name and
initial values to be used for the new component.- Type
- Object | Promise.<Object>
Example
Return the initial values for the component name, and the 'version' and 'address' columns
MyDeviceMgr.prototype.getProposedValuesFromDiscovery = function (discovery) { return { name: discovery.deviceName, values: { address: discovery.address, version: discovery.firmwareVersionMajor + '.' + discovery.firmwareVersionMinor } }; };
-
<abstract> getTypesForDiscoverySubject(discovery)
-
Abstract method to get the Component type(s) that could be created for the
given discovery node when adding it to the station as a component. If
returning an array, the first element of the array should be the type that
represents the best mapping for the discovery item.Parameters:
Name Type Description discovery
* a discovery object
Returns:
an array of TypeSpecs that could be
constructed from this node, or a Promise resolving to one- Type
- Promise.<Array.<string>>
-
isExisting(discovery, component)
-
Parameters:
Name Type Description discovery
* the discovery item
component
baja.Component component already existing in local
databaseReturns:
true if the local component already
represents the discovery item- Type
- boolean | Promise.<boolean>
-
makeDiscoveryCommands()
-
Creates and returns an array of discovery related commands.
These are the LearnModeCommand (show/hide the learn pane),
DiscoverCommand, CancelDiscoverCommand, AddCommand, and MatchCommand.Returns:
a new array containing
the discovery related commands.- Type
- Array.<module:bajaux/commands/Command>
-
<abstract> makeLearnModel()
-
Abstract method used to obtain the model for the learn tree table. This
should return aTreeTableModel
, or a Promise that resolves to one.Returns:
a
tree table model that will be used by the manager's discovery table.- Type
- Promise.<module:nmodule/webEditors/rc/wb/table/tree/TreeTableModel>
-
newInstanceFromDiscoverySubject(discovery, typeInfos)
-
Creates a new component instance from the types the manager specified
for a particular node in the discovery table. If the manager returned
more than one type, this default implementation will return a new
instance based on the first type info.Parameters:
Name Type Description discovery
* an instance of a discovery object (e.g. an
ndriver:NDiscoveryLeaf
), dragged from the discovery table and dropped
onto the database table or selected when the 'Add' command was invoked.typeInfos
Array.<module:nmodule/webEditors/rc/wb/mgr/MgrTypeInfo> an
array of MgrTypeInfos, created from the type or types returned
by the manager'sgetTypesForDiscoverySubject()
implementation.Returns:
a Promise of new component instance for the discovered item
based on the provided type information.- Type
- Promise
-
setJob(params)
-
Attach a job to this manager, typically as part of a driver discovery process.
The act of attaching a job will subscribe to it, and cause a 'jobcomplete' event
to be emitted once the job is complete. A manager will typically update the learn
model at that point.Parameters:
Name Type Description params
Object an Object literal containing the parameters for this function.
Properties
Name Type Argument Description jobOrOrd
string | baja.Ord | baja.Component <optional>
either a BJob instance, an
Ord referencing a job, or a String containing the ord for a job.depth
Number <optional>
optional parameter that will be used when subscribing to
the job once it has completed; this allows the job plus its final set of children to
be subscribed. A depth of 1 will subscribe to the job, 2 will subscribe the job and
its children, and so on. Subscription will default to a depth of 1 if this parameter
is not specified.Returns:
- Type
- Promise