Mixin: module:nmodule/webEditors/rc/wb/mgr/MgrLearn

module:nmodule/webEditors/rc/wb/mgr/MgrLearn

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 a
Promise 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 a
TreeNode 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 named isExisting() 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 the TreeTableModel
resolved from the Promise.

Returns:
Type
module:nmodule/webEditors/rc/wb/table/tree/TreeTableModel

getLearnTable()

Returns the TreeTable widget, used to display the discovered items.

Since:
  • Niagara 4.6
Returns:

the discovery table

Type
module:nmodule/webEditors/rc/wb/table/tree/TreeTable

<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 a Column 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
database

Returns:

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 a TreeTableModel, 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's getTypesForDiscoverySubject() 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