MvASSIGNARRAY#

Defines a multi-dimension array or structure using <MvASSIGNARRAY> and/or <MvASSIGN>.

Syntax

<MvASSIGNARRAY NAME = "string: {  expression } | literal }"
               VALUE = "{ expression } | literal }">
    <MvDIMENSION INDEX = "1">
    <MvDIMENSION INDEX = "2">
    <MvMEMBER NAME = "code">
</MvASSIGNARRAY>

Arrays and structures are used to store multiple values in a single variable. They can consist of a simple indexed list of values or more complex spreadsheet- or database-like structures. If you think of a single-dimension array as a simple numbered list, a two-dimensional array can be thought of as a spreadsheet with numbered rows and columns. MivaScript provides flexible tools for creating even more complex data structures. Arrays can also be assigned using <MvASSIGN>; often the resulting code is shorter, but there is no functional difference between the two forms.

Attributes#

Attribute	Description
`NAME`	(Required) The name assigned to the variable.
`VALUE`	The value assigned to the variable name.
`Sub Tags`	`<MvDIMENSION>` and `<MvMEMBER>`.
`<MvDIMENSION INDEX = "numeric: { expression } \\| literal">`	Declares the index of the array in `NAME` that will receive the `VALUE`.
`<MvMEMBER NAME = "{ string: { expression } \\| literal }">`	Declares sub-variable name in a structure.

No other tags than <MvDIMENSION> or <MvMEMBER> are allowed between <MvASSIGNARRAY> and </MvASSIGNARRAY>. MivaScript arrays are fully multi-dimensional (up to the limits of the system). If a value is assigned to an index or member that did not previously exist, the entry will be created.

If a value is assigned to an array without specifying an index, the array will be destroyed and the variable will revert to a simple variable. Likewise, if a value is assigned to an element that previously contained more dimensions, the values in the extra dimensions will be destroyed and replaced with the single value.

Two Dimensional Array#

A tabular representation of the array declared below could look like this:

	Column 1	Column 2
Row 1	100	200
Row 2	300	400

result: 300

<MvASSIGNARRAY NAME = "l.coordinates" VALUE = "{ 100 }">
    <MvDIMENSION INDEX = "1">
    <MvDIMENSION INDEX = "1">
</MvASSIGNARRAY>

<MvASSIGNARRAY NAME = "l.coordinates" VALUE = "{ 200 }">
    <MvDIMENSION INDEX = "1">
    <MvDIMENSION INDEX = "2">
</MvASSIGNARRAY>

<MvASSIGNARRAY NAME = "l.coordinates" VALUE = "{ 300 }">
    <MvDIMENSION INDEX = "2">
    <MvDIMENSION INDEX = "1">
</MvASSIGNARRAY>

<MvASSIGNARRAY NAME = "l.coordinates" VALUE = "{ 400 }">
    <MvDIMENSION INDEX = "2">
    <MvDIMENSION INDEX = "2">
</MvASSIGNARRAY>

<MvEVAL EXPR="{ l.coordinates[2][1] }">

Structured Arrays#

It’s often more convenient to refer to tabular data by name rather than number. Structures are name-based collections of variables.

	First	Last	Title
Row 1	Fox	Mulder	Special Agent
Row 2	Dana	Skully	Special Agent
Row 3	Walter	Skinner	Assistant Director

Result: Assistant Director

<MvASSIGNARRAY NAME = "l.agents" VALUE = "Fox">
    <MvDIMENSION INDEX = "1">
    <MvMEMBER NAME = "First">
</MvASSIGNARRAY>

<MvASSIGNARRAY NAME = "l.agents" VALUE = "Mulder">
    <MvDIMENSION INDEX = "1">
    <MvMEMBER NAME = "Last">
</MvASSIGNARRAY>

<MvASSIGNARRAY NAME = "l.agents" VALUE = "Special Agent">
    <MvDIMENSION INDEX = "1">
    <MvMEMBER NAME = "Title">
</MvASSIGNARRAY>

...

<MvEVAL EXPR="{ l.agents[3]:title }">

Evaluation#

Array elements can be accessed by specifying an array index in square brackets: { l.array[n] }. Members are specified using the colon prefix: { l.email:subject }.

If an array is evaluated with no specified index, MivaScript will return a comma-separated list (e.g. value,value…), with sub-arrays at a particular index displayed as values delimited by parentheses.

Results: 100,200,300,400

<MvEVAL EXPR="{ l.coordinates }">

Results: Fox,Mulder,Special Agent etc.

<MvEVAL EXPR="{ l.agents }">

While Loops#

Looping through arrays inside <MvWHILE> tags—either for assigning values or displaying results—is where they show their true power. This example illustrates several important techniques at once. Study it carefully. The variables g.names and g.abbr contain lists of literal data. Frequently, we deal with data from a database or external files that we want to read into an array or structure. NOTE: Loops are not limited to positive increments. You can display your array in reverse order if desired.

Create the Array

<MvCOMMENT> Create a dataset </MvCOMMENT>
<MvASSIGN NAME="g.names"
    VALUE="January,February,March,April,May,June,July,August,September,October,November,December">
<MvASSIGN NAME="g.abbr"
    VALUE="Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec">

<MvCOMMENT> Convert the data to an array structure. </MvCOMMENT>
<MvASSIGN NAME="g.posn" VALUE="{ 1 }">
<MvWHILE EXPR="{ g.posn LE 12 }">
    <MvASSIGN NAME="g.month" INDEX="{ g.posn }" MEMBER="name"       VALUE="{ gettoken(g.names, ',', g.posn) }">
    <MvASSIGN NAME="g.month" INDEX="{ g.posn }" MEMBER="abbr"       VALUE="{ gettoken(g.abbr, ',', g.posn) }">
    <MvASSIGN NAME="g.month" INDEX="{ g.posn }" MEMBER="first_date" VALUE="{ g.month[g.posn]:name $ ' 1, ' $ s.tm_year }">

    <MvCOMMENT> Next item </MvCOMMENT>
    <MvASSIGN NAME="g.posn" VALUE="{ g.posn + 1 }">
</MvWHILE>

Note

The first_date member contains the formatted date for each month (e.g. January 1, 2010)

Once loaded, loop through the array again to display it. In this example we populate an HTML <select> dropdown box.

Output the Array

<select name="Starting_Month">
    <MvASSIGN NAME="g.posn" VALUE="{ 1 }">
    <MvWHILE EXPR="{ g.posn LE 12 }">
        <option value="{ g.month[g.posn]:abbr }">
            <MvEVAL EXPR="{ g.month[g.posn]:first_date }">
        </option>
        <MvASSIGN NAME="g.posn" VALUE="{ g.posn + 1 }">
    </MvWHILE>
</select>

Results

<select name="Starting_Month">
<option value="Jan">January 1, 2010</option>
<option value="Feb">February 1, 2010</option>
<option value="Mar">March 1, 2010</option>
<option value="Apr">April 1, 2010</option>
<option value="May">May 1, 2010</option>
<option value="Jun">June 1, 2010</option>
<option value="Jul">July 1, 2010</option>
<option value="Aug">August 1, 2010</option>
<option value="Sep">September 1, 2010</option>
<option value="Oct">October 1, 2010</option>
<option value="Nov">November 1, 2010</option>
<option value="Dec">December 1, 2010</option>
</select>

Arrays in HTML Forms#

The interaction between a web page and MivaScript is most often through an HTML form. Embedded arrays can simplify form processing.

<form method="post" action="color_options.mvc">
    <input type="hidden" name="option[1]" value="red">
    <input type="hidden" name="option[2]" value="orange">
    <input type="hidden" name="option[3]" value="yellow">
    <input type="hidden" name="option[4]" value="green">
    <input type="hidden" name="option[5]" value="blue">
    <input type="hidden" name="option[6]" value="magenta">
    <input type="hidden" name="option[7]" value="violet">
</form>

When submitted to a MivaScript program, it will receive the array as g.options[n] that can be processed in a while loop.