Using adapter modules for customization

You can create adapter modules which allow your application to interact with third party applications and perform other deployment-specific customizations. Some customization examples may be launching a third-party application from NexJ CRM, changing a value such as cursor wait time, or providing localization support.

The modules are coded in JavaScript and specified when the ContactBroker portlet is defined.

For customizations related to application appearance, such as the color scheme, use the theme and CSS files instead. Use adapter modules for behavior customizations. For more information about themes and CSS, see UI themes and CSS.

Creating the adapter module

Create a .js file in the <model>/mod/nexj directory. The file must have a unique name across all the projects used in your deployment.

The adapter modules are based on the Asynchronous Module Definition (AMD) specification and are compatible with the require.js loader. For an overview of AMD, see the API documentation at https://github.com/amdjs/amdjs-api/blob/master/AMD.md. For a detailed explanation of AMD and require.js, see https://requirejs.org/docs/whyamd.html.

Adapter module examples

If you want to include third-party JavaScript code provided by a client, you may want to create two AMD modules. One is a wrapper for the code provided by the client and the other is the adapter module which loads the code.

The adapter module may look like this:

define("nexj/thirdparty/SampleAdapter", ["nexj/sys", "nexj/rpc/obj", "nexj/ui/mda", "nexj/scm", "nexj/thirdparty/CustomLaunchApi", "nexj/ui/mda/mvc"],
	function(sys, obj, mda, scm, CustomLaunchApi) {"use strict";
	var Adapter = mda.ContextAdapter;
	
	Adapter._methods = undefined;  // reset Scheme engine definitions

	Adapter.prototype.SampleLaunchAdapter = function(params) {
		var args = this.pairListToJSObj(params, false);
		CustomLaunchApi.launchApp(args);  // call into CustomLaunchApi.js
	};
});

An AMD module always contains the define(); function. It takes three parameters:

• The module name. In this example, it's "thirdparty/SampleAdapter". This must match the file name of the module in your project's mod folder. "/" in the module name represents either the folder structure or a "." in the file name.
• Dependencies, which is a list of modules and module mixins that this module depends on. In this case, it is ["nexj/sys", "nexj/rpc/obj", "nexj/ui/mda", "nexj/scm", "nexj/thirdparty/CustomLaunchApi", "nexj/ui/mda/mvc"]. One of the dependencies is the wrapper module.
• A function that takes the dependent modules as parameters and uses to arguments to call the third-party code. 

The method name added using the prototype property must be unique, unless it is intentionally overriding an existing method.

The function does not need to have a return statement.

The Adapter._methods = undefined; statement is required.

In this example, the wrapper module may look like this:

define ('nexj/thirdparty/CustomLaunchApi', function(){

function CustomLaunchApi() {}

/***** ORIGINAL THIRD-PARTY CustomLaunchApi.js contents BEGIN *****/

...

/***** ORIGINAL THIRD-PARTY CustomLaunchApi.js contents END   *****/

CustomLaunchApi.launchApp = launchApp;

return CustomLaunchApi;
});

It does not create a new class but returns a customized version of an existing class.

Calling the adapter module

Specify the adapter module names when defining the ContactBroker portlet. Multiple modules can be specified, and their names must be separated by a space. For example:

<Portlet caption="idss.ContactBrokerPortlet.caption" description="Contact application broker portlet that holds application level toolbar items and event handlers." modules="nexj/custom/adapter1 nexj/custom/adapter2">

While you can also specify the module when defining other portlets, this may interfere with expected application behavior. It is only appropriate when you are certain that the portlet is entirely independent of all other portlets in the application.

Prerequisites

In order to use the adapters, your project must be configured with the following settings.

1. Update the .project file to identify the Java builder and Java nature for the project. For example:

   XML

   <projectDescription>
   <name>ubppov</name>
   <comment></comment>
   <projects>
   </projects>
   <buildSpec>
   <buildCommand>
   <name>org.eclipse.jdt.core.javabuilder</name>
   <arguments>
   </arguments>
   </buildCommand>
   <buildCommand>
   <name>com.nexjsystems.nexjstudio.NexJBuilder</name>
   <arguments>
   </arguments>
   </buildCommand>
   </buildSpec>
   <natures>
   <nature>org.eclipse.jdt.core.javanature</nature>
   </natures>
   </projectDescription>

2. Update the .classpath file to include source references to mod and src directories. For example:

   XML

   <classpath>
   <classpathentry kind="src" path="mod"/>
   <classpathentry kind="src" path="src"/>
   <classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER"/>
   <classpathentry kind="output" path="bin"/>
   </classpath>