Using RMScript

Why Use RMScript?

Instead of writing all your macros in a template, you can store them in one or more separate RMScript (ReportMagic Script) files which you then call from the template. Separating instructions (macros) from presentation makes it easier to view how the formatting and graphics are laid out in your template.

Also, using script files can help with reuse across multiple templates or a sequence of macros in the same template.

Tip: Remember filenames are case-sensitive - myfile.rmscript is not the same as MyFile.rmscript

RMScript or In the Template?

Move all macros that collect data or manipulate data to RMScripts
Put graph and text output macros in RMScripts, as you can execute the RMScript from anywhere in the template
If you want a quick table and don't mind how it looks, use Table macros in RMScripts otherwise keep tables in the template with macros in the cells so it's easier tweak column widths
Keep macros that result in a graph or produce text output in the template so you can position them exactly
Use the [File.Execute:] macro in an RMScript file to call another file, and therefore breaking up large scripts into multiple files
Whenever you want to print just text from an RMScript file, always use a String macro. Text outside of a macro is unlikely to be printed.

Writing your RMScript File

For easy readability and color highlighting, write RMScript in Visual Studio Code using the RMScript extension. To install:

If you haven't already, download Visual Studio Code.
Go to the Visual Studio Code Marketplace
In the Extensions search box, type ReportMagic Script.
Click to view and read about the package then click Install.
With the Extension installed, Visual Studio Code automatically adds end brackets and quotes as well as providing color highlighting to identify missing items.

Calling an RMScript File

To call a file from an input template:

Ensure the RMScript file is in the same input folder as the template.
Use the [File.Execute:] macro in your template, for example:
[File.Execute: fileName=demo.rmscript]

When a file is called, ReportMagic:

Finds and loads the file into memory
Removes whitespace (space and tab characters) at the start of each line
From the results, removes any lines that start with "//" (commented lines)
Removes all newline characters
Inserts the resulting text into the report template in place of the[File.Execute:]macro, leaving the cursor at the start of the inserted text
Continues with report template processing

The whitespace, commented line and newline removal means that your RMScript files can be nicely structured and more readable as a result.

Testing an RMScript File

Use Report Studio to test your files.

In Files, upload your files to a folder.
From Files, double-click the file.
or
From Report Studio, from the File menu, click Open and navigate to the relevant file.
Report Studio opens in Code mode. Tip: Always use Code mode when testing.
Try running the file.
Note: When a macro will not work in Report Studio, this is indicated on the macro's Help page.

What Are run.rmscript Files?

To produce output of any kind, you usually need a DOCX or PPTX input template. However, if only want to produce Excel output, you use a special type of RMScript file whose name ends in run.rmscript , In this case, you can run the run.rmscript without a DOCX or PPTX template - but only to produce XLS output.

The run.rmscript file would contain macros that write to XLS
Using run.rmscript files can be useful when testing your rmscripts
Search for worksheet in the help and you will find all the macros that either read or write to xlsx
A run.rmscript file will automatically be run when a Schedule runs, so ensure you have XLSX output selected for that Schedule)

Using RMScript Guard Comments

When placed at the top of an RMScript, BEFORE the first non-comment line (including blank lines), "Guard comments" can be used to ensure that conditions are true at the start and end of an RMScript file.

These comments are checked when the [File.Execute:] macro is used with:

In Guard Comments being checked before processing the RMScript
Out Guard Comments being checked at the end of processing the RMScript

If a condition fails, the Schedule will stop.

For example:

// This RMScript takes the ClientName and gets the list of client devices

// In: isSet('ClientName') && typeOf(ClientName) == 'String' && length(ClientName) > 0

// In: !isSet('DeviceList')

// Out: isSet('DeviceList') && typeOf('DeviceList') == 'JArray'

Almost any condition can be used, including ClientName == 'ThisCompany'

See https://github.com/panoramicdata/PanoramicData.NCalcExtensions for the list of functions that can be used in conditions.

Example RMScript files

The following RMScript files are equivalent. Note that although the second version is longer, it is much easier to read, which is important for code maintenance:

First version

[:The First;The Second;The Last,=>Items][ForEach: values={Items},=>Value][:{Value}][If: condition=`'{Value}'!='The Last'`][: `, `][EndIf: ][EndForEach:]

Second version

// Set up the variable

The First;

The Second;

The Last,

=>Items

]

// Print out the items in a list, comma separated

[ForEach: values={Items},=>Value]

   [:{Value}]
   // Add a comma and a space
   [If: condition=`'{Value}'!='The Last'`]

[:`, `]

[EndIf: ]

[EndForEach:]

Example run.rmscript file

Note that you should run this file from a Schedule, not Report Studio, since [File.Execute:] and [File.LoadObject:] cannot be run in Report Studio.

//Load json file

[File.LoadObject:

fileName=`questions.json`,

=>Questions

]

[File.Execute: fileName=format-questions.rmscript]

//create xls output

[=: `list(list('Topic','Question','Option'))`, =>QuestionsXls]

[ForEach: values={Questions}, =>Topic;Description;Answer]

[=: `list(Topic,Description,Answer)`, =>Row]

[List.Add: value=`{=Row}`, =>QuestionsXls]