DotNetNuke Inter-Module Communication (IMC)

Inter-Module Communication (IMC)
IMC particularly refers to the facility that the DotNetNuke framework provides to allow data to be passed between modules during the ASP.Net page life cycle.

• It is a very elegant solution for passing data between modules, on the server side. That said, it tends to be a topic that most first-time IMC users have trouble getting right.
• There are numerous ways to pass data between modules, both on the server and on the client side.

DotNetNuke Inter-Module Communication (IMC)

• IMC communication always occurs somewhere within the ASP.Net page life cycle.
• Therefore this method of passing data between modules requires exactly one execution of the page life cycle.
• If user interaction is required to trigger the communication, then a post-back will need to occur from the browser to trigger the page life cycle in which the IMC will take place.
• IMC functionality is divided into two parts:
•  Communicating (sending messages)  
•    Listening (receiving messages).
• In order to add one or both of these functionalities to a modules, you must have the module class implement the respective IMC interfaces which the DNN Framework has defined for you.

The IModuleCommunicator and IModuleListener Interfaces

• Both IModuleCommunicator and IModuleListener live inside the DotNetNuke.Entities.Modules.Communications namespace, so you may find it convenient to reference these namespaces at the top of your code.
• Implementing the IModuleCommunicator interface allows your module to dispatch messages to all the modules on the page that are listening for IMC messages.
• On the flip side of the equation, implementing the IModuleListener interface allows your module to receive all the messages sent from modules on the same page.

Implementing IModuleCommunicator

To implement IModuleCommunicator all you need to do is define an instance of the ModuleCommunicationEvenHandler delegate as an event named ModuleCommunication within your class.

Imports DotNetNuke.Entities.Modules

Imports DotNetNuke.Entities.Modules.Communications

Partial Class SampleCommunicatorVB

    Inherits PortalModuleBase

    Implements IModuleCommunicator

    Public Event ModuleCommunication(ByVal sender As Object, _

        ByVal e As ModuleCommunicationEventArgs) _

        Implements IModuleCommunicator.ModuleCommunication

End Class

• When you implement the IModuleCommunicator interface, the DotNetNuke framework knows that your module has an instance of the ModuleCommunicationEventHandler delegate type named ModuleCommunication.
• This guarantees that the DotNetNuke core can wire-up to your module so that it can be notified when you raise an IMC communication event.
• Somewhere deep in the DNN core code, there is likely a line that adds an event handler to your delegate if your module implements

if (yourModuleInstance is IModuleCommunicator)

{

    yourModuleInstance.ModuleCommunication +=

        new ModuleCommunicationEventHandler(notifyIMCListeners);

}

•  You Raise a ModuleCommunication Event to Send an IMC Message
• Sending an IMC message is as simple as raising your module's ModuleCommunication event.
• To raise the ModuleCommunication event , you use the RaiseEvent keyword in addition to calling ModuleCommunication(...), passing to it a reference to your module, and an instance of ModuleCommunicationEventArgs.

   RaiseEvent ModuleCommunication(Me, mcArgs)

Creating the Event Args Object

Dim mcArgs As ModuleCommunicationEventArgs  = New ModuleCommunicationEventArgs()

mcArgs.Sender = "SampleCommunicatorModule - VB"

mcArgs.Target = "Arbitrary Text"

mcArgs.Text = "Your Payload Text"

mcArgs.Type = "Your Custom Type"

Dim xmlDoc As System.Xml.XmlDocument = New System.Xml.XmlDocument()

mcArgs.Value = xmlDoc

RaiseEvent ModuleCommunication(Me, mcArgs)

• The Sender, Target, Text, and Type properties of the ModuleCommunicationEventArgs class are of type String.
•  The Value property is of type object.
•  you can pass types other than String in this property.

Implementing ImoduleListener

• In order for your module to receive IMC messages it must implement the IModuleListener interface.
• This interface requires your class to have a method named OnModuleCommunication which takes two parameters, and Object type and a ModuleCommunicationEventArgs type, respectively.

Imports DotNetNuke.Entities.Modules

Imports DotNetNuke.Entities.Modules.Communications

Partial Class SampleListenerVB

    Inherits PortalModuleBase

    Implements IModuleListener

    Sub OnModuleCommunication(ByVal s As Object, _

                              ByVal e As ModuleCommunicationEventArgs) _

        Implements IModuleListener.OnModuleCommunication

    End Sub

End Class

• When you implement the IModuleListener interface the DotNetNuke framework automatically adds your OnModuleCommunication method to the delegate that responds to all the ModuleCommunication events.
• When your OnModuleCommunication method is executed, it is passed a reference to the module that raised the ModuleCommunication even, this is the first argument of your OnModuleCommunication method
• Your method also gets passed the ModuleCommunicationEventArgs object that contains all the information that was defined by the object that raised the event.
• The ModuleCommunicationEventArgs objec is the key piece of the IMC framework because it is the single channel in which the communication happens.
• Anything placed into the ModuleCommunicationEventArgs object from inside the module that raises the ModuleCommunication event gets passed along to every OnModuleCommunication method of the modules that implement the IModuleListener interface.

How to Use It
In all cases the IMC is meant to be used within modules on a single tab, or in modules that redirect to another tab and that tab has a module on it that can receive the IMC objects.
The beauty is that you can efficiently pass objects between modules, or cast them to an interim listening device.

Step One : Determine the [SENDER]:

Here you give your modules the ability to attach to only IMC object sets from a certain Sender. This is usually the ModuleName of the sending module, as set in the module definitions. If a Sender is included in the IMC object set, and a Listener module is configured to Receive from the Sender, then it will only attach to an IMC object set for that Sender.

Step Two: Determine the [TARGET]: Here you give your modules the ability to attach to only IMC object sets aimed at a certain Target.  This is usually the ModuleName of the receiving module, as set in the module definitions. If a Module is configured to listen to only the Target of MyModule then it will only attach to an IMC object set for that target.

Step Three: Determine the [TYPE]:: a configurable property where you set the type in the Talker and then the Listener looks for that type. If a Module is configured to Listen to only the Type of MyModule then it will only attach to a IMC object set of that type.

Step Four: Determine the [VALUE]: This is the only Object property in IMC, and you can pass any complex object between modules.  This includes a dataset, a control within state, or any other thing you can imagine.  The requirement is for a listener to know what to do with the Object and its state.

Step Five :  Determine the [TEXT]:  this is a relatively straightforward answer... a simple text string.  In the original IMC, this was the only property