Skip to content

MvFUNCTION#

A function is a sub-section of code executed by a call to the function name. MivaScript contains many built in functions like toupper(string). This tag lets you create your own user defined functions.

Syntax
<MvFUNCTION NAME = "string_literal"
            PARAMETERS = "variable_list"
            STANDARDOUTPUTLEVEL = "html, text, compresswhitespace">

            <MvFUNCTIONRETURN VALUE = "{ expression } | literal"> 
</MvFUNCTION>

User defined functions enable you to write re-usable code that can be called on to perform operations at any point in your program, by calling the function within an expression. Even if a function is only called once in your program, moving the code out of the main body of the program and replacing it with a function call still helps to make the program more ‘modular’, easier to read and debug. A function may output HTML to the screen, perform database I/O or optionally return a value.

Attributes#

Attribute Description
NAME Literal function name, defines the name that will be used to call the function.
PARAMETERS (Optional) Comma separated list of variable names, assigned without any variable prefix; (parameter variables are always local) and optionally the keyword var (variable by reference).
STANDARDOUTPUTLEVEL (Optional) Keywords: html, text, compresswhitespace. Specifies what displays in the browser. If empty, output is suppressed unless explicitly output using the <MvEVAL> tag.
- html: Default. HTML is output to the browser.
- text: Default. Text is output to the browser.
- compresswhitespace: Eliminates extra whitespace (spaces, tabs, new lines) from MivaScript output.
ERROROUTPUTLEVEL (Optional) Keyword: runtime. Runtime errors display in the browser. If empty, error output is suppressed. If omitted, defaults to runtime.

Parameters#

Examine the PARAMETERS attribute above and compare it with the add call in the <MvASSIGN> tag:

add(l.subtotal, l.shipping_charges)
  • The value in l.subtotal is passed as num1.
  • The value in l.shipping_charges is passed as num2.

Parameters are assigned in order and are local to the function, unless marked var (see below).

Passing Variables by Reference#

By appending var to a parameter, you pass the variable itself (by reference) instead of its value, so any changes inside the function affect the original variable. This is efficient for arrays and structures.

<MvASSIGN NAME="l.count" VALUE="{ Category_Products_Load(l.category_id, l.products var) }">

<MvFUNCTION NAME="Category_Products_Load"
            PARAMETERS="category_id, products var"
            STANDARDOUTPUTLEVEL="">
    <!-- Open database files and populate a structured array l.products[n]:field1, etc. -->
    <MvFUNCTIONRETURN VALUE="{ l.product_count }">
</MvFUNCTION>

Variable Scope#

Local variables and parameters (l.varname) exist only within the function. The same local name can be used outside without conflict.

Calling Functions#

You can invoke functions in several contexts:

<MvASSIGN NAME="g.result" VALUE="{ IsURL('http://www.google.com/') }">

<MvEVAL VALUE="{ IsURL('http://www.google.com/') }">

<MvIF EXPR="{ IsURL('http://www.google.com/') }">
    This is Google.
<MvELSE>
    Hey, you’re not Google…
</MvELSE>
</MvIF>

Returning from Functions#

Use <MvFUNCTIONRETURN> to exit a function and optionally return a value. If no return is needed, you can omit it.

<MvFUNCTIONRETURN VALUE="{ l.product_count }">

<MvFUNCTIONRETURN>

Function Libraries#

Functions are often stored in external compiled “library” files. Call them via <MvEVAL> or <MvDO>, using square-bracket notation for file references:

<MvEVAL EXPR="{ [ 'myfunctions.mvc' ].IsURL('http://www.google.com/') }">

Uncompiled libraries can be included at compile time with <MvINCLUDE>:

<MvINCLUDE FILE="../library/myfunctions.mv">

Important Considerations#

  • Function definitions are read at compile time but not executed until called.
  • Text arguments must be in single quotes: e.g. func1(1,2,'banana').
  • Defining parameters is optional; you may manipulate globals directly.
  • Built-in functions operate like user-defined ones but generally run faster.
  • Recursive calls are limited (default depth 23 in Mia and Empresa; configurable via maxfunctiondepth).

Examples#

A function can appear anywhere in your program and can be called from anywhere. They do not need to be physically encountered by the compiler before calling them—you can forward-reference functions. Functions can be simple or complex, may call nested functions, and can even recursively call themselves (though you must avoid infinite loops).

This function adds two numbers together. It is called within <MvASSIGN>, just like a built-in function.

<MvFUNCTION NAME="add" PARAMETERS="num1, num2" STANDARDOUTPUTLEVEL="html,text">
    <MvIF EXPR="{ l.num1 OR l.num2 }">
        <MvFUNCTIONRETURN VALUE="{ l.num1 + l.num2 }">
    </MvIF>
    <MvFUNCTIONRETURN VALUE="0">
</MvFUNCTION>

<MvASSIGN NAME="l.grand_total" VALUE="{ add(l.subtotal, l.shipping_charges) }">