Forio Macro Language Syntax

Forio Macro Language, or FML, is used with HTML to create web pages for your simulation. FML statements are used to insert text into a web page that is is then sent to the user's browser.

Introduction to Forio Macro Language

FML is composed of References, Directives, and URL Parameters/Form Fields.  All references and directives are case-sensitive. So $Run.SimTime will provide the current simulation time, but $run.simtime will return an error.  URL parameters and form fields are not case sensitive and may be in upper, lower, or a mix of upper and lower case.

Forio Broadcast checks all files that end with the following extensions for FML:

All other files are passed through verbatim (any accidental FML statements will be ignored).  Typically, these files will be images (*.jpg, *.jpeg, *.gif), and Cascading Style Sheets (*.css), although this is true for all files not in the list above.

References

A reference begins with a dollar sign ($) and is a collection of information that can be inserted into a page.  For example $Run contains general info about the state of the simulation and $User contains information about the currently logged in user.  

A reference contains both Properties and Methods.  A reference with a property simply inserts a value into the text.  Both of the following are references with properties, and respectively refer to the current time of the simulation and the first name of the currently logged in user.

$Run.SimTime

$User.FirstName

A method is a function that inserts a value based on an argument.  For example, the following inserts into the text the value "20.00", that is the nunber 20 with two decimal places.

$Formatter.number(20,"#0.00")

A reference may be undefined.  For example $Trial is only defined if a trial run is in progress.  See the section Displaying Simulation Information to learn how to check if a reference is defined.

Some references are actually lists of references.  For example, $Values is a list of references containing all the calculated numbers in the model and $ScoreList is a list of references containing the high scores.  You can access specific items in the list with get, e.g. $Values.get('Sales') or $ScoreList.get(0).  This returns the individual Value reference for the model variable Sale and the Score reference for the highest scoring run.  You can also loop over all the items in a list (e.g. to display a list of high scores) with #foreach.  See the sections Working with Lists and #forEach loops for more details.

Just to confuse matters further, some reference properties are also references.  For example, $User.Runs returns a list of Run references, one for each simulation run done by the current user.

A few special tool references have only methods.  For example, $Formatter is a reference that contains a number of special purpose methods which help to format numbers and dates.

Summary of FML References

Directives

A directive begins with a "#" sign and controls the processing of a page.  

Control Directives such as #if and #foreach control what information is shown by conditionally displaying text or looping over a section of text.

Macro Directives such as #LineGraph and #Link include special HTML that is useful to make the simulation run smoothly.  In this case #LineGraph inserts a special image tag which retrieves a line graph, and #Link includes special Javascript code that saves decision values when the user goes to a new page.

Include Directives are used to include text from other files into the current page.

Summary of FML Directives

URL Parameters and Form Fields

Two ways of sending information and commands to Forio Broadcast are URL parameters and form fields.

A URL parameter is a key and value appended to the end of a URL.  The page name is followed by a question mark, '?'.  Then each key and value are listed, with an ampersand, '&', separating the parameters.The easiest way to explain this is to show an example:

http://forio.com/simulation/carfactory?FD_rand=1234&FD_action=step

This URL contains two URL parameters and indicates that Broadcast should advance the model one step.

Form fields are included in a form and submitted with a POST request when the user clicks submit.  The following form field is identical to the FD_action parameter above:

<input type="hidden" name="FD_action" value="step">

While all URL parameters can be expressed as form fields, not all form fields can be expressed as a URL parameter.  In particular, form fields used to send information (such as decisions or text messages) must be submitted as a field within a form.

Summary of URL Parameters and Form Fields

Comments

Comments allow you to write descriptions in your FML code that will not be shown on the users web page. Comments are a useful way of reminding yourself and explaining to others what your FML statements are doing.

Below is an example of a comment in FML.

A single line comment begins with ## and finishes at the end of the line.

For example, this FML code:

will produce the following HTML output:

Finally, you can do a block of comments by starting the comments with #* and ending the comments with *#.  For example this FML contains a comment block:

and will produce the following output: