A Step-by-Step Approach to Utilizing Native Function Interfaces (NFIs) in Volt MX Desktop Native Apps

HCL Volt MX Volt MX Tips
1

Overview

A Native Function Interface (NFI) allows you to utilize native functionalities within JavaScript for Electron-based desktop applications in Volt MX. You have two options for integrating NFIs into your application:

  1. Create a new NFI by defining the necessary native functionalities and configuration within Volt MX.
  2. Import an existing NFI, which is packaged as a zip file, independently created by external sources, and fully customizable by the provider.

This guide provides detailed instructions on both:

  • Creating and configuring a new NFI in Volt MX.
  • Importing pre-built NFIs that were developed externally and integrating them into your application.

By following this guide, you can seamlessly manage both custom-built and externally developed native functionalities, enhancing your desktop application’s capabilities.

Create an NFI in Volt MX into Your Desktop Native Application

To create a new NFI (Native Function Interface) in Volt MX for your desktop native application, follow these steps:

Navigate to the NFI Management:
In Volt MX, go to the menu and select Edit → Manage Native Function APIs. This will open the popup for managing NFIs.

Select the Desktop Tab:
From the popup, switch to the Desktop Tab. This tab allows you to manage NFIs specifically for desktop applications.

Create a New NFI:
Choose the Create New button to start creating a new NFI. This will open a window where you will input the details necessary to configure the NFI.

Provide NFI Details:

  • Choose the JavaScript file that contains the native APIs you want to expose.
  • Optionally, you can specify additional JavaScript files that may be required by the NFI.
  • Fill in the following details:
    • NFI Name: A meaningful name for your NFI.
    • Version: Assign a version number for the NFI.
    • API Namespace: Define a namespace for your APIs.
    • Node Dependencies: If the NFI depends on Node.js, include a package.json file with the dependencies.
    • Description: Add a brief description of the NFI, explaining its purpose and functionality.

Select the JavaScript Files:
Choose the JavaScript file that contains the native APIs you want to expose in your application. You can also specify additional JavaScript files that are required by the NFI. After selection, the table will display:

  • Function Names: The functions exported from the JavaScript file.
  • Parameter Names: The input parameters required for each function.

Configure Functions Type:
Once you have selected the JavaScript files, the functions contained in the files will be listed. You can configure the functions as either:

  • Sync: Functions that return data immediately (e.g., reading a file).
  • Async: Functions that perform background operations (e.g., writing to a file without blocking).

Enable or Disable Functions:
You can choose to disable specific functions by selecting them from the list. Disabled functions will not be exposed to the application.

Set Up Optional Additional JavaScript Files:
If your API relies on additional JavaScript files, use the Additional JS field to select the folder containing those files. These will be included in the NFI.

Complete and Create the NFI:
Once all the required information is entered, click Create to generate the NFI. The NFI will be added to the list of available interfaces and stored in the /desktopNativeNFIs directory as a .zip file.

Post-Creation: Customizing the NFI

Once the NFI is created, you can unzip it and modify key files:

Preload File: Defines the communication bridge between the Electron renderer and the main process. It cannot reference Node modules.

Handlers: This file can contain Node.js module references and handle the native logic.

Wrapper File: Provides the API interface but cannot contain Node module references.

For more details on context bridge parameters, refer to the Electron documentation.

Enable the NFI:
After creating the NFI, make sure it’s enabled in the Desktop tab so that it gets included in your desktop native application.

Note: Once the NFI is created, a folder is generated through IRIS, allowing for customization without the need to recreate the NFI.

Application Usage Example

Let’s say you’re creating an NFI called FileOperationsNFI that allows reading and writing files in your desktop native application. Follow these steps:

  • Navigate to the NFI Management:
    Go to Edit → Manage Native Function APIs and select the Desktop tab.
  • Create New NFI:
    Click Create New and enter the following details:
    • NFI Name: FileOperationsNFI
    • Version: 1.0.0
    • API Namespace: com.voltmx.file
    • Description: Provides APIs for reading and writing files.
  • Select JavaScript File:
    Choose the JavaScript file containing your file operation functions (fileOperationsAPI.js), which might include functions like:
const fs = require('fs');

function GetFileDate(pFile) {
    try {
        const dtFile = fs.statSync(pFile).mtime;
        const sYear = dtFile.getFullYear();
        const sMonth = (dtFile.getMonth() + 1).toString().padStart(2, '0');
        const sDay = dtFile.getDate().toString().padStart(2, '0');
        const sHour = dtFile.getHours().toString().padStart(2, '0');
        const sMin = dtFile.getMinutes().toString().padStart(2, '0');
        const sSec = dtFile.getSeconds().toString().padStart(2, '0');
        return `${sYear}-${sMonth}-${sDay} ${sHour}:${sMin}:${sSec}`;
    } catch (error) {
        console.error(error);
        return "";
    }
}

function SetFileDate(pFile, sNewDate) {
    try {
        const dtFile = new Date(sNewDate);
        fs.utimesSync(pFile, dtFile, dtFile);
        return "OK";
    } catch (error) {
        console.error(error);
        return `ERROR ${error}`;
    }
}

module.exports = { GetFileDate, SetFileDate };

After successfully creating the NFI, you can use the exposed (GetFileDate and SetFileDate) functions in your application.

try {
    var fileDate = com.voltmx.file.GetFileDate (<FilePath>);
     console.log(fileDate);
} catch (err) {
  console.log("Catch GetFileDate API Error log ::" + err);
}

try {
  var status = com.voltmx.file.SetFileDate (<FilePath>, <NewDate>);
  console.log(status);
} catch (err) {
  console.log("Catch SetFileDate API Error log ::" + err);
}

Import an NFI in Volt MX into Your Desktop Native Application

Desktop native NFIs are packaged as zip files created independently from the Volt MX environment. You can import these zip files and integrate the functionalities into your application

Navigate to the NFI Management:
In Volt MX, go to the menu and select Edit → Manage Native Function APIs. This will open the popup for managing NFIs.

Select the Desktop Tab:
From the popup, switch to the Desktop Tab. This tab allows you to manage NFIs specifically for desktop applications.

Import an NFI:
Choose the Import option, which allows you to bring in an existing NFI package. Select the .zip file that contains the NFI you want to import.

NFI Identification:
The metadata.properties file inside the .zip package identifies the important details related to the NFI (such as its name, version, description, and dependencies). These details will automatically populate when you import the NFI, and it will be added to the list of available NFIs.

NFI Files

API file (.js)
This is the JavaScript file that contains the functions you want to call from your desktop native application.

Wrapper file (.js)
The wrapper file assigns the API defined in your preload file into the namespace, making it accessible to the Volt MX application.

Preload file (.js)
The preload file defines the APIs and parameters that need to be passed across the bridge between the renderer and main processes.

Handler file (.js)
The handler file receives calls in the main process and invokes the APIs from the API file.

Bootstrap file (.js)
This file defines the channel constants that identify the requests being passed across the bridge.

Intellisense directory with a tern.json file
The tern.json file is used for providing intellisense of the APIs.

Metadata.properties file
This file contains the metadata of the NFI, allowing Volt MX code generation to identify the APIs and include them in the application.

Metadata.properties File Properties

The metadata.properties file includes several properties that define important information about the NFI module:

  • moduleName: The name of the NFI module. Example: VoltMXApplication
  • moduleVersion: The version of the NFI module. Example: 1.0.0
  • moduleDescription: A description of the purpose of the NFI and the categories of APIs provided.
  • os: Must always be ‘Desktop’.
  • sdkVersion: Typically, this will be the same as the module version for desktop native.
  • apiNamespace: The namespace to categorize the APIs. Example: com.sample.io
  • wrapperFile: The name of the wrapper JS file.
  • handlerFile: The name of the handler JS file.
  • preloadFile: The name of the preload JS file.
  • nodeModules: Optional: A comma-separated list of Node module dependencies and their versions.

Enable the Imported NFI:
Once the NFI is imported, make sure it’s enabled in the Desktop tab, so it gets included in your desktop native application.

Application Usage Example

Suppose you have created or imported an NFI called FileOperationsNFI, which allows your desktop native application to read and write files. The NFI has already been packaged into a zip file (FileOperationsNFI.zip), and you want to import it into your Volt MX desktop application.

Steps for Importing:

Access the NFI Management Dialog:
Open Volt MX, and from the menu, go to Edit → Manage Native Function APIs. In the popup that appears, go to the Desktop tab.

Choose the Import Option:
In the Desktop tab, click on the Import button. You’ll be prompted to select a .zip

Select the NFI Package:
Navigate to where your FileOperationsNFI.zip file is located and select it for import.

NFI Metadata Details:
After selecting the file, Volt MX will read the metadata.properties file inside the package. Here’s what the metadata.properties file might look like for the FileOperationsNFI:

**moduleName**=FileOperationsNFI

**moduleVersion**=1.0.0

**moduleDescription**= Provides APIs for reading and writing files in the desktop native application.

**os**=Desktop

**sdkVersion**=1.0.0

**nodeModules**=fs:1.0.0

**apiNamespace**=file

**wrapperFile**=FileOperationsNFIWrapper.js

**handlerFile**=FileOperationsNFIHandlers.js

**preloadFile** =FileOperationsNFIPreload.js

The moduleName, moduleVersion, and other properties will automatically populate in the popup, based on the metadata.properties file.

Complete the Import:
Once the NFI is successfully imported, it will appear in the list of available NFIs under the Desktop tab. Ensure that the FileOperationsNFI is enabled.

Using the NFI in Your Application:
After successfully importing the NFI, you can use the exposed (GetFileDate and SetFileDate) functions by calling them through the specified namespace (file) in your application.

try {
    var fileDate = com.voltmx.file.GetFileDate (<FilePath>);
     console.log(fileDate);
} catch (err) {
  console.log("Catch GetFileDate API Error log ::" + err);
}

try {
  var status = com.voltmx.file.SetFileDate (<FilePath>, <NewDate>);
  console.log(status);
} catch (err) {
  console.log("Catch SetFileDate API Error log ::" + err);
}
1 Like