Custom code

Overview

ActiveReportsJS offers a diverse assortment of expressions you can use for various tasks like calculations, numeric and date formatting, applying conditional formatting, and more. However, there could be scenarios where your reports require functions that exceed the capabilities provided by these built-in expressions. You might need to perform intricate mathematical operations, implement sophisticated conditional formatting, or maintain the Don't-Repeat-Yourself (DRY) principle by reusing the same code throughout your report.

In such instances, you can leverage the power of the custom code feature in ActiveReportsJS.

Crafting Custom Code

To incorporate custom code into a report, the code needs to be composed first. Adherence to the following principles is crucial:

• Breakdown the code into JavaScript functions.

• Ensure each function serves a single purpose or responsibility.

• Each function should be synchronous, as asynchronous functions aren't supported.

• Every function should be pure, implying that its output relies solely on its input, without causing any side effects.

Below is an example of such a function. It converts a numeric value into a currency format relative to its magnitude. This represents a synchronous, pure function carrying out a single task.

function formatCurrencyValue(value) {
    let currencySymbol = '$'; 
    if (value >= 1000000000) {
        return currencySymbol + (value / 1000000000).toFixed(1) + 'B';
    } else if (value >= 1000000) {
        return currencySymbol + (value / 1000000).toFixed(1) + 'M';
    } else if (value >= 1000) {
        return currencySymbol + (value / 1000).toFixed(1) + 'K';
    } else {
        return currencySymbol + value.toFixed(1);
    }
}

Integrating Custom Code

You register custom code at the application level using the registerFunctions method of the Core object. This method accepts an array of custom function definitions, each with the following structure:

{
    name: <name to call the function>,
    body: <function definition>,
    info: {                         
      description: <function description for the expression editor>, 
      example: <sample function invocation for the expression editor>, 
      syntax: <function syntax for the expression editor>
    }          
  }

The info object is optional and should only be used if you want to make the custom function available to users of the report designer component. Registered functions are displayed in the Custom Code section of the Function node in the expression editor:

Below is the custom code definition for the formatCurrencyValue function discussed earlier.

var customCode = [
  {
    name: 'FormatCurrencyValue',
    body: formatCurrencyValue,
    info: {                         
      description: 'Format a number to currency in relation to their magnitude', 
      example: 'Code.numberToWords(Sum(SalesAmount))',
      syntax: 'Code.numberToWords(<number>)'
    }          
   }
]

Here's a full example of how to register the function in a pure JavaScript application:

<script src="https://cdn.mescius.com/activereportsjs/5.latest/dist/ar-js-core.js"></script>
<script>
MESCIUS.ActiveReportsJS.Core.CustomCode.registerFunctions(customCode);  
</script>  

And for an application built using code modules, the code will look like this:

import { Core } from "@mescius/activereportsjs";
Core.CustomCode.registerFunctions(customCode);  

Integrating Custom Code in the Standalone Designer Application

To use custom code within the Standalone Report Designer application, create a customCode.json file in the corresponding directories:

• Windows: %AppData%\ActiveReportsJS Designer\

• MacOS: ~/Library/Application Support/ActiveReportsJS Designer/

• Linux Desktop: ~/.config/ActiveReportsJS Designer/

Serialize the custom code definition as outlined earlier into JSON format and save it in this customCode.json file within the functions object as showed below.

{
	"functions": [
		{
			"name": "FormatCurrencyValue",
			"body": "function(value) {let currencySymbol = '$'; if (value >= 1000000000) {return currencySymbol + (value / 1000000000).toFixed(1) + 'B';} else if (value >= 1000000) {return currencySymbol + (value / 1000000).toFixed(1) + 'M';} else if (value >= 1000) {return currencySymbol + (value / 1000).toFixed(1) + 'K';} else {return currencySymbol + value.toFixed(1);}}",
			"info": {
				"description": "Format a number to currency in relation to their magnitude",
				"example": "Code.numberToWords(Sum(SalesAmount))",
				"syntax": "Code.numberToWords(<number>)"
			}
		}
	]
}

Keep in mind that third-party libraries aren't supported in the standalone designer application, so custom code that utilizes these libraries will not operate.