Overview

Math Minion html pages provide a way to present customized input and result views.

As the name implies, HTML is used to format the view and javascript to manipulate the inputs and results. Therefore to make full use of this tool some familiarity with HTML and in some cases javascript is necessary, but quite a bit can be accomplished with knowledge of just a few basic tags and using Math Minion shortcuts.

In most cases though, the ability to simply set flags enabling the display of tools and tool notes on the model information view will be sufficient and html pages will not be necessary.

Input consists of a single formula that should return a string value containing the HTML to be displayed. This formula can be any valid Math Minion formula, but often simply consists of a single quote, followed by the desired HTML.

A <mm> HTML extension, as well as a supplied javascript function, mmpost, permit the page to interact with other Math Minion tools.

Formula Field

At the top of the information view is formula field that defines the HTML.

The formula it contains must return a string value comprised of the HTML code to display.

Rendered Page

The rendered HTML is displayed in a sandboxed iframe immediately below the formula field. Rendering in this way prevents malicious code in the tool from interacting directly with the main program code.

Printing the Page

At the top left of the rendered view there is a small non-scrolling printer icon and tapping on that will bring up a print dialog for printing the view.

The <mm> Tag

Special <mm> tags containing Math Minion formulas can be embedded within the HTML and these tags will be replaced with the results of evaluating the formulas before the HTML is rendered. For instance the code:

<mm>person[1,"weight"]</mm>

would be replaced with the string representing value of the first row of the "weight" column of the tool named person.

If the value isn't a scalar, then an HTML table will be inserted. The default HTML code formula used for a new html page contains the same CSS definitions as used in the model information view. These aim to make the table easier to read, but can of course be removed or modified to taste.

If the <mm> tag returns a tool reference, information about that will be be inserted into the page. For instance if there is a graph tool named myPlot, then

<mm>myPlot</mm>

would insert the SVG (Scalable Vector Graphics) code needed to reproduce the graph. If the tool is itself an html page tool, then it will be inserted in its entirety. A blank mm tag, i.e. <mm></mm> will insert the entire information view for the model containing the html page. In that case the html page itself should not have its display box checked.

For other tools, a representation of their results, often as a table, is inserted.

mmpost Function

A function named mmpost is automatically inserted into the HTML to be rendered. Javascript on the page can call this function to make input values on the page available as string parameters of the HTML page tool. These can then be accessed by other tools in the model to perform calculations.

The mmpost can also request values from the model, which will be returned in a call back function passed to mmpost. Special requests can also be used to trigger specific actions discussed below.

The mmpost function is defined with three arguments:

mmpost(inputs, requests, callBack)

Inputs Argument

This argument should be an array of strings, where each string is the id of some sort of HTML input element that has a value. The string value of each of those elements will become a parameter of the HTML page tool, with the id as the name.

For example the onClick handler for the Calculate button of the BMI page in this model looks like:

onClick="mmpost(['weight', 'height']);"

where weight and height are the ids of the text input fields where values are entered. For instance the input element for weight is:

<.input type="text" id="weight" value="<mm>$.weight</mm>" class="input">

Note that the value for the field uses a <mm> tag to get the previous value for weight. The dollar sign is the formula shorthand reference to the tool owning the formula, i.e. the HTML page itself. Any previous input of weight would have created a weight parameter for the tool because of the call to mmpost and that value will automatically be filled in when this tool is viewed again.

The height and weight are also used by the BMI expression in the BMICalc model to calculate the BMI. This is obviously a ludicrously complex way to calculate such a simple thing, but useful for illustration. The result is displayed on the HTML page with another <mm> tag:

<mm>BMICalc.BMI</mm>

So when a new weight is entered in the weight field and the Calculate button is pressed, mmpost reads the weight and height values and replaces the current weight and height parameters of the html page tool. This will cause all the tools that reference the HTML page to forget their results. The page will be rerendered, which will request the BMICalc.BMI value, which will in turn get the new weight and height and return a new BMI to be displayed.

These input parameters are retained by the MM HTML forms when sessions are saved, so the tool will always have the last inputs posted to it. If an empty array is passed to mmpost, then the previous inputs will be retained.

Requests & Callback

The mmpost function can also be used to directly request one or more formulas be evaluated. This is done by providing an object containing formulas as the request argument. These formulas will be evaluated and the function passed as the callback argument will be called with an argument consisting of a results object having the same keys as the request object with the associated values being the result of evaluating the corresponding formula.

In the code below, the second column of nMatrix is requested with the key mat. The callback function retrieves the result from result.mat and uses it to format lines that are used as the value of a textarea element.

<textarea id="results">
  placeholder
</textarea>
<script>
  const target = document.getElementById('results');
  mmpost([], {mat: 'nMatrix[0,2]'}, (result) => {
    const value = result.mat;
    const lines = [];
    let i = 1;
    for (const v of value) {
      lines.push(`row ${i++} = ${v}`);
    }
    target.value = lines.join('\n');
  });
</script>
					

Actions

A number of actions can be requested by passing specific action keys in the mmpost request object.

View - mm_view

A request with the key mm_view having a the name of another tool as a value will result in the information view and diagram selection switching to that tool.

Push - mm_push

A request with the key mm_push having a the name of another tool as a value will result in the information view for that tool being pushed over top the current one. Tapping the back button at the top left of the information view will switch back to the HTML page information view.

Adding Rows - mm_addrow

A request with the key mm_addrow having the name of a data table tool as a value will cause the data table to add a row to the table.

This is done after the HTML page has been updated with any inputs passed to mmpost. If the data table that is having the row added references these inputs either directly or indirectly in its initial value formulas, then the values of the new row can result from the inputs of the HTML page.

If you look at the HTML page named BMI in the Getting Started session, when the Record button on the page is tapped, the weight is passed in the input argument of mmpost and {mm_addrow: 'weight'} is passed as the request argument. No call back is supplied. The Initial Value formula for the Weight column of the table is:

{eval bmi.weight}

so the entered weight will be used in the the new row. In this case the weight parameter will be a string since it includes the unit, so the eval function is used to evaluate it as formulas.

Delete Rows - mm_deleterows

A request with a key mm_deleterows can be used to remove specified rows from a data table. The value associated with the key must itself be an object containing:

  • table: name of the data table
  • rows: an array of row numbers to delete

For instance to delete the last row of a table named weight, the following could be used:

{mm_deleterows: {table:'weight', rows: <mm>weight.nrow</mm>]},

Refresh - mm_refresh

When a Math Minion object calculates new values, it normally remembers those until one of its inputs changes or a new session is loaded.

However in some circumstances, such as an expression using the current date and time using the {now} function, you may want an object to forget its retained value and recalculate it. A mmpost request with a key mm_refresh having a tool name as its value will cause that tool to recalculate. For example:

mmpost({},{mm_refresh: 'todaysDate'})

Clear - mm_clear

The inputs included in an mmpost call remain as tool parameters until they are changed, but in some cases you may wish to remove all of these to start fresh. Calling mmpost with a request object containing a key mm_clear will do this. The value of the key is unimportant, but typically just true.

Update - mm_update

Calling mmpost with a request containing a key mm_update simply causes the HTML page to be redisplayed. This isn't often necessary, but might be combined with a mm_clear to redisplay the cleared page. It might look like:

mmpost({},{mm_clear: true, mm_update: true})

Load Session - mm_load

You may want to break some activities up into different sessions, but still be able to access them directly from the HTML page.

If a call to mmpost has a request with a key mm_load, an a session name as its value, then Math Minion will attempt to load a session with that name.

Load Session URL - mm_loadurl

If a call to mmpost has a request with a key mm_loadurl, an a web address as its value, then Math Minion will attempt to import a session from that address.

Web security protocols (specifically CORS) may prevent you from importing from servers you don't control and thus can't set the appropriate permissions on. However it should alway be possible to load from the server hosting Math Minion itself.

View URL - mm_viewurl

If a call to mmpost has a request with a key mm_viewurl, a new window will be opened with the contents of that URL.

Calc Engine Command - mm_cmd

The user interface for Math Minion talks to the calculation engine by sending text messages to it and receiving text messages back. The console view accessed by the button at the bottom of the information view allows you to manually enter commands and view the results. The Html Page tool also has an action which allows you to send commands to the engine.

For example the HTML code:

<button onClick=
  "mmpost([],{mm_cmd: '.money.formula set formula 0 dollar'})"
>
  Clear Money
</button>
					

would create a button that when pressed would set the formula of the expression money to 0 dollar.

See the HtmlPage model in Tools in the Getting Started session for a more complete example.

Note that the calculation engine runs in a separate process within your browser and no messages are sent to an external server.

Formula Parameters

Parameters that can be accessed in the form a.b where a is the tool name and b is the parameter.

Any input values posted to the object can be retrieved using their input names. Unless a value is just a number, it will be string value and have to be converted as appropriate.

The parameter html will return the final HTML code after any mm tag replacements.

If the html returned by the formula contains comments of the form

<!--begin_blockname-->

and

<!--end_blockname-->

Then a parameter block_blockname will return all the code between the two comments.

As long as they don't match any of the above, then:

  • html - a html code representation of the tool.
  • notes - the notes for the tool
  • myname - the name of the tool