Echelon LNS Plug-in - Manual (Page 34)

1. The plug-in fetches the appropriate ComponentApps collection, based on the scope of the action.
If the scope of the action is device or functional-block specific (for example, the action will be
added to a DeviceTemplate’s ComponentApps collection or a
DeviceTemplate.LonMarkObject’s ComponentApps collection), you may need to create a
DeviceTemplate before you can add the ComponentApp object. To see if the system already
contains a device template for your device type, use the DeviceTemplates.ItemByProgramId
method. If the correct device template is not found, and the plug-in is not running as a remote
client, create one by adding a new DeviceTemplate object to the DeviceTemplates collection and
importing the appropriate device interface file into the newly created DeviceTemplate object.
A plug-in running on a remote LNS client (where either the LNS Server or LNS Remote Client
redistribution is also installed) can successfully create a device template if the device interface text
and binary files (.xif and xfb extensions) are located in the same directory both on the client and
on the server system and a binary (.xfb) file exists on the server system.
2. The plug-in fetches or creates a new ComponentApp object for your action. To do this, search
the ComponentApps collection to see if a ComponentApp object already exists that specifies
your server as a provider of the desired command ID for the desired class ID. If your server is
already registered as a provider of this action, skip to step 4. If it is not, you need to add a new
ComponentApp object to the collection.
When you add the new object, you must give it a name. Typically directors will display this name
in a context menu as appropriate. Since ComponentApps collections use the name as a key into
the collection, the name that you choose for your action must be unique within the collection.
Therefore, before adding your new action, you must check to see if a ComponentApp object with
your desired name already exists in the collection. For example, if your action has a very general
name, such as Test, it is quite likely that another plug-in already provides an action with this
name. If your action name is more specific, such as Test My Device Type, it is less likely
(although still possible) that another plug-in has already registered an action with this name.
If there is no object with your desired name, proceed to step 3. If your desired name is already in
use, you must pick a new name for your action. For example, you might add your plug-in name to
the action name, such as Test (My Plug-in). Continue the process until you have found an unused
name. Once you have found an unused name, proceed to step 3.
3. The plug-in creates a new ComponentApp object via the ComponentApps.Add method,
specifying the name for this action, the name of the plug-in’s server class, and the class ID of the
object to which it applies. In the framework, the name of the plug-in’s server class may be found
in the ProgId property of the PluginObject class. See Appendix C, Standard Plug-in Object
Classes, for a list of all the Class IDs for all LNS objects.
4. The plug-in then sets the following additional properties of the ComponentApp object:
Attribute Description
CommandId The command that you are registering. See Appendix
A for a complete list of plug-in command IDs.
Description The description of the service the plug-in provides for
this command. Typically a director will display this
description in a tooltip or status bar.
VersionNumber The version number of your plug-in.
ManufacturerId Your company’s manufacturer ID.
5. Finally, if you want your plug-in to provide the default action for this object type, set the
DefaultAppFlag property to True. The default application is the plug-in that the director will, by
default, call when the user invokes the specified command on the specified object. A
ComponentApps collection can only have one default action; therefore, you must examine all
other ComponentApps in the collection and set their defaultAppFlag properties to False.