Custom Code

Custom code enables administrators to add profile-specific logic and styling to the map control. This feature allows you to:

• Inject custom JavaScript to extend or modify map behavior (e.g., add event listeners, automate workflows, or integrate with external APIs).
• Apply custom CSS to override or enhance the default map and UI styles for a tailored appearance.
• Implement custom validation logic to enforce business rules or data integrity specific to your organization's needs.

Custom code is managed per configuration profile, giving you granular control over the user experience and map functionality for different scenarios.

Custom JS

There are a few important requirements to ensure your custom functions work correctly:

Requirement	Description
Use globalThis	Define your function on globalThis so it is accessible to the map control.
Parameter Handling	All parameters are passed as strings; always parse them using let paramsJSON = JSON.parse(parameters);.
Dynamic Variables	To insert dynamic values, use double curly braces ({{}}). Pass parameters as a JSON string, e.g. { "userId": "{{userId}}" }.

Here is an example:

console.log('Maptaskr Power Maps has loaded');

//define "ExecuteJS" action function
globalThis.getAuthUser = function (parameters) {
	let paramsJSON = JSON.parse(parameters);
	let { userId, userName } = paramsJSON;
	console.log(userId, userName);
	alert(`Hi my name is ${userName} and my id is ${userId}`);
};

The getAuthUser function can then be called within the Map Actions as an Action type ExecuteJS

You can also register callbacks for any of the available Events, or call the Data Accessor Functions to implement custom functionality.

const control = globalThis.MaptaskrControlManager.getControl(controlId);

//Register a callback for the ExtentChanged event
control.on('ExtentChanged', (extent) => {
	console.log(extent);
});

//Navigate to Perth, Western Australia after a short delay
setTimeout(() => {
	//This will invoke the above callback!
	control.navigateToLatLong(-31.9505, 115.8575, 14);
}, 5000);

Note

controlId is provided to you by the system.

---

Custom CSS

The custom CSS editor empowers administrators to tailor the look and feel of the map control for each configuration profile. You can apply custom branding, adjust styles, and even hide or show specific features—ensuring every user group has a unique and targeted experience. This flexibility allows you to align the map interface with your organization's branding or adapt it for different scenarios.

---

Custom Validation

Custom validation lets you enforce business rules beyond the standard validation configured in Shape Definitions. It runs at save time when there are unsaved shape changes, normally once per map control for the batch, not on every edit or separately for each shape.

The script receives the map control's GUID (controlGuid), and Maptaskr waits for it to finish before saving. Return true (or another truthy value) to allow saving. A falsy result, no return value, or an exception blocks saving.

In D365, use Save for unsaved shape changes. Autosave and Save & Close are blocked until those changes are saved.

Example: Calculate the area of all shapes on save

The following script retrieves all shapes from the map control and logs their total area when save-time validation runs. It returns true so it does not block saving.

const control = globalThis.MaptaskrControlManager.getControl(controlId);

const shapes = await control.getShapes();

const totalArea = shapes.reduce((total, shape) => {
	const features = shape.geoJsonObject?.features ?? [];

	return (
		total +
		features.reduce((featureTotal, feature) => {
			const area = feature.properties?.Area;

			if (typeof area !== 'string') {
				return featureTotal;
			}

			const areaInM2 = parseFloat(area.replace(/[^0-9.-]/g, ''));

			return featureTotal + (Number.isFinite(areaInM2) ? areaInM2 : 0);
		}, 0)
	);
}, 0);

console.log(`Total area: ${totalArea.toFixed(2)} m²`);
console.log(`Total area: ${(totalArea / 10000).toFixed(4)} ha`);
console.log(`Total area: ${(totalArea / 1_000_000).toFixed(6)} km²`);

//always return true since we don't want to block save in this case.
//you can implement your own logic and return false if you want to block.

return true;

This example does not check required attributes or display a validation message. To enforce business rules, add the relevant checks, provide a helpful message in your script, and return false when those checks fail.