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

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

Description:

  • 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.

Source:

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() → {Promise|*}

Description:

  • 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.

Source:
Returns:

Optionally return a Promise

Type
Promise | *

getExisting(discovery) → {Promise.<(baja.Component|undefined)>}

Description:

  • 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.

Source:
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
Promise.<(baja.Component|undefined)>

getJob() → {baja.Component}

Description:

  • Get the discovery job currently set against the manager.

Source:
Returns:
Type
baja.Component

getLearnModel() → {module:nmodule/webEditors/rc/wb/table/tree/TreeTableModel}

Description:

  • 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.

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

getLearnTableCommands() → {Promise.<Array.<module:bajaux/commands/Command>>}

Description:

  • When the learn table is right-clicked, only learn table-specific commands will be shown. This
    function defines what those commands are.

    By default, these will be any commands with the LEARN_CONTEXT_MENU flag, plus Show Existing
    and Select All commands, but not including any commands with flags that have not been
    configured (i.e. those commands with flags still set to the default value of ALL). You must
    explicitly set the command flags to a value that includes LEARN_CONTEXT_MENU to make it
    appear here.

Source:
Since:
  • Niagara 4.14
See:
  • module:nmodule/webEditors/rc/wb/mgr/commands/MgrCommand~flags
Returns:
Type
Promise.<Array.<module:bajaux/commands/Command>>

(abstract) getProposedValuesFromDiscovery(discovery, subject) → {Object|Promise.<Object>}

Description:

  • 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.

    The second argument is the corresponding value in the station database table. If using
    the Add command, this will be the brand-new instance about to added to the
    database. If using the Match command, this will be the existing instance already
    in the database.

Source:
See:
  • module:nmodule/webEditors/rc/wb/table/tree/TreeNode
Example

Return the initial values for the component name, and the 'version' and 'address' columns

MyDeviceMgr.prototype.getProposedValuesFromDiscovery = function (discovery, component) {
  return {
    name: discovery.deviceName,
    values: {
      address: discovery.address,
      version: discovery.firmwareVersionMajor + '.' + discovery.firmwareVersionMinor
    }
  };
};
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.
Returns:

an object literal with the name and
initial values to be used for the new component.

Type
Object | Promise.<Object>

(abstract) getTypesForDiscoverySubject(discovery) → {Promise.<(string|baja.Type|Array)>}

Description:

  • 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.

Source:
Parameters:
Name Type Description
discovery *

a discovery object
Returns:

a Promise that can resolve to a string,
a baja Type or an array which can be used to make MgrTypeInfos.

Type
Promise.<(string|baja.Type|Array)>

isExisting(discovery, component) → {boolean|Promise.<boolean>}

Source:
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>

isLearnModeEnabled() → {Boolean}

Source:
Since:
  • Niagara 4.14
Returns:
Type
Boolean

isMatchable(learnSelection, mainSelection) → {boolean|Promise.<boolean>}

Description:

  • This function is used to determine if the MatchCommand should be enabled or not. It does
    this by checking to see if the selection in the main table (mainSelection) is of a type that
    the type from the selection in the learn table supports (learnSelection). What types are
    supported is determined by the getTypesForDiscoverySubject() that the manager has
    implemented. If this default behaviour is not enough or a different behaviour is required
    then this function can be overridden in the manager, with the new function either returning a
    boolean or a Promise.<boolean>.
    Resolves to true if the supplied mainSelection item can be matched to the supplied
    learnSelection item.

Source:
Since:
  • Niagara 4.14
Parameters:
Name Type Description
learnSelection *

the subject selected in the learn table
mainSelection baja.Component

the subject from the main table that the learnSelection
subject is being matched to
Returns:
Type
boolean | Promise.<boolean>

makeDiscoveryCommands() → {Array.<module:bajaux/commands/Command>}

Description:

  • Creates and returns an array of discovery related commands.
    These are the LearnModeCommand (show/hide the learn pane),
    DiscoverCommand, CancelDiscoverCommand, AddCommands, and MatchCommands.

Source:
Returns:

a new array containing
the discovery related commands.

Type
Array.<module:bajaux/commands/Command>

(abstract) makeLearnModel() → {Promise.<module:nmodule/webEditors/rc/wb/table/tree/TreeTableModel>}

Description:

  • Abstract method used to obtain the model for the learn tree table. This
    should return a TreeTableModel, or a Promise that resolves to one.

Source:
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) → {Promise}

Description:

  • 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.

Source:
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

newInstancesFromDiscoverySubjects(discoveries) → {Promise.<Array.<(baja.Component|null)>>}

Description:

  • Creates new component instances for the discovered items. The default implementation
    simply iterates over the discovery objects, gets their type info and delegates to
    #newInstanceFromDiscoverySubject method.

Source:
Since:
  • Niagara 4.14
Parameters:
Name Type Description
discoveries *

an array of discovery objects
Returns:

a Promise of new component instances
from the discovered items

Type
Promise.<Array.<(baja.Component|null)>>

setJob(params) → {Promise}

Description:

  • 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.

Source:
Parameters:
Name Type Description
params Object

an Object literal containing the parameters for this function.

Properties
Name Type Attributes 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

setLearnModeEnabled(learnModeEnabled)

Source:
Since:
  • Niagara 4.14
Parameters:
Name Type Description
learnModeEnabled Boolean