Working with Lists

FML allows you to use a special type of reference called a List to track sequences of information.

Creating Lists

A list can be defined as a local reference and may contain strings, numbers, or sequences of numbers.  Items in a list are separated by a comma, except for sequences which use an ellipse (...) to define a consecutive range.

 
#set ($names = ["George", "John", "Paul", "Ringo"]
#set ($numbers = [10, 20, 30, 40, 50]
#set ($consecutive_numbers = [100..200])
 

 

Many standard FML references are actually lists.  For example, $Values is a list of Value references, each representing a variable in the model.  $ScoreList is a list of Score refererences, sorted in order of score.  Some of these standard references are keyed lists, meaning that items can be retrieved using a special key.  (such as the variable name).  Others are paged lists, meaning that only a page of information is displayed at a time.

Looping through all Items in a List

There are two ways of using items in a list.  The most common way is to loop through each item with a #foreach directive.  The second is to access individual items in the list with the get( number ) method.

Here's a quick way of using #foreach to display a variable over all model steps.  You can extend this example to create tables of simulation results.

 
#set ($StepList = [0..$Run.EndStep])
 

#foreach($step in $StepList)
Sales at step $step: $Values.get('Sales').getResultFormatted($step)
#end
 

 

Results:

 
Sales at step 0: $100,121
Sales at step 1: $130,233
Sales at step 2: $129,517
Sales at step 3: $70,333
Sales at step 4: $45,421
Sales at step 5: $22,343
 

 

Accessing an Individual Item in a List

You can access an individual item with the method get.  The first element in a list is always 0.

For example:

 
#set( $VariableList = ["Price", "Sales", "Revenue"] )
#set( $TimeList = [1..52] )

## Display first element in Variable List
$VariableList.get(0)<BR>
 

## Display 27th element in Time List
$TimeList.get(26)

 

 

will display the following in HTML:

 
Price

27
 

 

Example: Using Local References to Display the Month

You can use FML local references and math functions to display the current month in your simulation. Below is the FML code that should appear in your HTML to calculate the current month.  (note the use of the List method get and the $Lib.integer )

Example model:

 
#This model runs in months from 0 to 60 months, or five years.

M StartTime = 0
M EndTime = 60

 

 

Example FML for listing out simulated month and date, starting in the present year.

 
#This model runs in months from 0 to 60 months, or five years.

M StartTime = 0
M EndTime = 60

V Sales = 50

 

 

Example FML for calculating the month and year (page is named index.htm):

 
<html>
<body>

## Calculate month and year

#set ($month =["January", "February", "March", "April", "May",
"June", "July", "August", "September", "October", "November", "December"] )

#set ($monthcalc = $Run.SimStep % 12)

#set ($year = $Run.SimStep / 12 + $Lib.integer($Formatter.date($Today, "yyyy")))

## Print out month and year
$month.get($monthcalc) $year <BR>

<A HREF="index.htm?FD_action=step">Advance Simulation</A>

</body>

</html>                 

 

 

The line $month.get($monthcalc) $year will print something like: "August 2006" on your web page.

Determining the List Size

You can determine the list size with the method size().  This is often useful in #if statements to display alternate text if a list is empty.  For example, you might want to display a message if no scores are available.  Another way of checking for an empty list is to use the method empty().

 
#if ( $ScoreList.empty() )
no scores have been posted
#else
There are $ScoreList.size() scores posted.  Here they are:

...

#end
 

 

Adding New Items to Lists

You can add new items to the end of a List with the method add.  (This only works for standard lists, not keyed lists or paged lists).  

 
#set($musicals = ["Showboat", "Music Man", "My Fair Lady"]
$musicals.add("Sweeney Todd")
 

#foreach ($m in $musicals)
$m
#end
 

 

Result:

 
Showboat
Music Man
My Fair Lady
Sweeney Todd
 

 

Keyed Lists

A Keyed List is a special kind of a list in which each item can be accessed via a string key with the method get ( string ).  Sometimes this is referred to as a hash, a map or an associative array.  $Values is a keyed list, and so is $Messages.  Only the standard references can be keyed lists; it is not possible to create a keyed list as a local reference.

To demonstrate, let's look at $Values.  This list contains a Value reference for each variable and array segment in the model.  You can access an individual value by providing the name of the variable as the key, or use #foreach to loop through them all.  For example:

 

The current simulated result for Sales is: $Values.get('Sales').Result.

There are $Values.size() variables and array segments in your model.

Here's a list of all the variables in the model:
#foreach($v in $Values)
$v.Label
#end
 

 

This will produce results similar to the following:

 
The current simulated result for Sales is: $121,331.

There are 5 variables and array segments in your model.

Here's a list of all the variables in the model:
Cost
Price
Profit
Revenue
Sales
 

 

Paged Lists

A Paged List is used to display a large amount of information one page at a time.  Both $ScoreList and $UserScoreList are paged lists.  Only standard references can be paged list; it is not possible to create a paged list as a local reference.

Paged lists have special properties that provide information helpful in displaying the page and navigation controls.  To actually navigate from page to page you will need to use special URL parameters.  You can also use standard List methods and properties such as get, empty, and size.  Not all of these properties are needed to created a user-friendly Next/Previous paged display, but they are intended to allow you maximum flexibility in designing the display to fit the needs of your application.

For more information on displaying a list of high scores, read the article below:

How to Create a High Score List

DisplayRows

The maximum number of rows displayed on a page.  (typically 10).  This may not be the same as the actual number of rows displayed (there may not be enough rows).  This might be changed by using the URL parameter FD_display_rows.  If set to -1, all rows are being displayed.

Example FML statement:

$ScoreList.DisplayRows

FirstRowIndex

The index number of the first row displayed in the page, starting at 1 for the first of all the rows.  This is always equal to 1 plus RowOffset.  For example, if the list is showing the second page and DisplayRows is 10, this will be 11.

Example FML statement:

Displaying $ScoreList.FirstRowIndex to $ScoreList.LastRowIndex of $ScoreList.TotalRows

HasNext

A true/false value indicating if there is a next page.  Use this to hide/show the "Next" button.

Example FML statement:

#if($ScoreList.HasNext) link to next page #end

HasPrevious

A true/false value indicating if there is a previous page.  Use this to hide/show the "Previous" button.

Example FML statement:

#if($ScoreList.HasPrevious) link to previous page #end

LastRowIndex

The index number of the last row displayed in the page, with a count of for the first row.  This is always equal to size() plus RowOffset.  For example, if the list is showing the second page, DisplayRows is 10, and 5 rows are showing, this will be 16.

Example FML statement:

Displaying $ScoreList.FirstRowIndex to $ScoreList.LastRowIndex of $ScoreList.TotalRows

NextOffset

The value of the RowOffset for the next page.  Use this in a Next hyperlink to set the FD_row_offset URL parameter.

Example FML statement:

#if($ScoreList.HasNext) <A href="score.htm?FD_row_offset=$ScoreList.NextOffset">Next</A> #end

PageCount

The total number of pages.  

Example FML statement:

Displaying page $ScoreList.PageIndex of $ScoreList.PageCount

PageIndex

The current page number, starting at 1.

Example FML statement:

Displaying page $ScoreList.PageIndex of $ScoreList.PageCount

PreviousOffset

The value of the RowOffset for the previous page.  Use this in a Previous hyperlink to set the FD_row_offset URL parameter.

Example FML statement:

#if($ScoreList.HasPrevious) <A href="score.htm?FD_row_offset=$ScoreList.PreviousOffset">Next</A> #end

RowOffset

The number of rows this page is offset from the first page.  Starts at 0 for the first page.  Set by the FD_row_offset URL parameter (assuming this value is within the actual number of rows).  You can use the RowOffset with $foreachCount to display the row number in a list.

Example FML statement:

 

#foreach ($Score in $ScoreList)
#set($rowindex = $foreachCount + $ScoreList.RowOffset)

Row $rowindex: The score for $Score.Run.EndUser.LoginId is $Score.Score

#end
 

 

Example results:

 

Row 1: The score for jsmith is $111,214
Row 2: The score for wmiller is $55,222
Row 3: The score for ajones is $14,121
 

 

SourceList

A reference to the full list of rows that the paged list is based on.  It's recommended for checking any properties of the entire list, but it's recommended to use the paged list itself whenever possible.

Example FML statement: (returning the 56th element of the entire list)

$ScoreList.SourceList.get(55)

TotalRows

The total number of rows.

Example FML statement:

Displaying $ScoreList.FirstRowIndex to $ScoreList.LastRowIndex of $ScoreList.TotalRows