mXrap Developer Migration Guide: Version 5 to 6.0.0

Last update: 13 November 2023

Introduction

Returning Points in a Row Calculation

Returning Null Points

Checking Null Points in a Row Calculation

Octal Literals

Problems with Omori Library

Table Column Widths

# Introduction

Short story: Ask the mXrap team to upgrade the root folder, and check your own Apps for the problems described below.

Version 6 is intended to be backwards and forward compatible with Version 5.

This means you can switch between Version 6 and Version 5 without compatibility issues.

You can develop Apps in Version 6, and deploy to a Version 5 site, and everything will work.

...

We almost achieved that goal.

...

The new Javascript engine in Version 6 delivers "ECMAScript 6" support, which brings changes to the way the JS language works.

Your Javascript code MAY require changes to work in Version 6.

The mXrap team's standard code in your root folders has been upgraded, so  ensure we have upgraded your root folder BEFORE you start using Version 6.

# Returning Points in a Row Calculation

Screenshot

Code

return [1,2,3];

Warning Message

WARNING: use the provided 'result' variable to return array results for efficiency.

Solution

A "result" variable is automatically provided.
Fill it with the results and return it, like so:

result[0] = 1;

result[1] = 2;

result[2] = 3;

return result;

Reason

return [1,2,3]; creates an unnecessary Array - this is slower and consumes more memory.

We want to encourage good consistent coding practices and use the same code pattern everywhere.

Before

After

# Returning Null Points

Screenshot

Code

return [null,null,null];

Warning Message

WARNING: do not return [null,null,null], instead return null

Solution

Reason

Null coordinates are now specified as null instead of [null,null,null].  This is more efficient and simpler to code, as there is no Array involved.

Before

After

# Checking Null Points in a Row Calculation

Screenshot

Code

if(override[0] == null || override[1] == null || override[2] == null)

Warning Message

Solution for Version 6 only

This is the future: use this if you don't need to support users on Version 5

if(override === null)

Note the use of 3 = signs, not 2.

=== compares both type and value: you want this!

== will do conversions and may not do what you expect.

Backwards Compatible Solution for both

Version 5 and 6

if(override === null || override[0] == null || override[1] == null || override[2] == null)

Tip: add override === null to the front of the if statement.

Reason

Null coordinates are now specified as null instead of [null,null,null].  Thus the check should be much simpler, as there is no Array involved anymore.

Before

After

# Octal Literals

Screenshot

Code

new Date(2023,10,01);

Warning Message

WARNING: Program failed to compile

SyntaxError: Octal literals are not allowed in strict mode.

Solution

Reason

The new Javascript does not accept numbers written with a leading zero, eg 01 or 02.

These are known as Octals, and were a common source of confusion.

ie 08 and 09 are invalid, and 010 translates to 8 in decimal.

This was a source of bugs, so Octals are disallowed as a blanket policy.

Before

After

# Problems with Omori Library

similar errors are seen as:   ReferenceError: something is not defined

Screenshot

Error Message

ReferenceError: results_best is not defined

Solution

This requires a root upgrade for a newer version of this library.

Contact support to arrange a full root upgrade.

Reason

We have tightened up "global scoping" rules for better coding practices.

In Version 5, scripts imported via require.mx() could access global variables defined in the main calculation code.

This is bad practice and is no longer allowed.

# Table Column Widths

Note that the fixed-width font (used for numbers) has changed to the newest Microsoft font: "Cascadia Mono".
As a result, the width of columns and text might be different to before, and column widths may need to be adjusted.
Depending on your operating system, you may have been using Courier New or (more likely) Consolas in the past.