Using Web Controls for Mathcad
Calculation Server Web Authoring

About This Authoring Guide

The Mathcad Calculation Server enables Mathcad users to publish fully functional, calculating worksheets online, for other Mathcad users and non-users alike. Authoring documents is as simple as creating a Mathcad worksheet, then inserting Web Controls in place of key variables.

Anyone with a Web browser can view a worksheet and adjust inputs identified by the author. The Calculation Server then recalculates the worksheet and displays the results in the browser window.

This brief guide outlines the process for identifying and creating Web Control inputs and other formatting techniques to make Mathcad documents that are well-suited for Calculation Server use.

To make worksheets accessible online, files using Web Controls must be stored on a Mathcad Calculation Server. The Calculation Server is a separate product installed on a Microsoft Internet Information Services (IIS) Web server. The Mathcad Calculation Server includes a calculation engine that performs all operations required by a Web Controls-enabled worksheet.

Tutorial with Mathcad Web Controls

This tutorial presents the Mathcad Web Controls in the context of converting a standard worksheet to function as a Web document. It shows how to convert an existing Mathcad worksheet that calculates projectile motion based on several variables to a Web-ready worksheet. The tutorial also presents a number of best practices recommended for Mathcad users who want to create effective Web documents.

Click on the Before and After links to see the worksheet in different stages.

Worksheet Before

Worksheet After

To create a Mathcad Web Document:

Analyze the Worksheet

Analyze the Audience

Identify the Adjustable Parameters and Controls

Create the Controls

Decide When to Recalculate

Decide What to Show

Error Checking

Weave the Web

Analyze the Worksheet

Examine the worksheet. It is better to have fewer adjustable parameters than too many. Look over the worksheet to establish which values yield observable and informative changes in the results. The "projectile" example used here has three obvious adjustable parameters important to the physical understanding of the problem. Other examples of parameters that you may wish to convert to Controls are sizes, weights, coefficients, switches to include or not include parts of calculations, and so on.


If it is necessary for your audience to adjust more than 10 inputs, or if you want them to change inputs that are not numbers, the worksheet may not be amenable to conversion using Mathcad Web Controls. To be effective, the relationship between a limited number of inputs and the final results needs to be easily understood by the audience.

Tip: Consider using a Mathcad template intended for HTML or Web presentation because its layout and formatting may be more appropriate to the task than your original work. Copy required regions from the original worksheet into the template and be sure to change formatting by using Text Styles from the Format menu for consistency across pages.

Worksheet before

Worksheet after

Analyze the Audience

When you enhance a Mathcad worksheet with Web Controls and publish it on an intranet or the Internet, you greatly expand its audience. You are adding a large number of people, possibly not as expert in your field as you are, to the document's audience. It is a good idea to think about who is viewing and using your work. You may want to simplify or hide complex or more involved calculations because many people may be more interested in the results than in how they were achieved.

You may want to tell the story behind the worksheet, the reasons you created it, and why it is a useful tool. It is not enough to say that the tool is a good screwdriver or hammer; you might need to briefly explain why it is a good tool and how it works.

In the case of the sample worksheet, there was no preexisting description of the physics or mathematics involved in solving the equations of motion - it was just a scratchpad for working out the problem. Suppose we decide to direct the sheet towards students, who may not be familiar with the physics involved. The worksheet should then include the problem solved, the physical principles, and what sort of changes students should look for in the results as they change the inputs. Note the addition of text at the top and near the results graph.

Worksheet before

Worksheet after

Identify the Adjustable Parameters and Controls

Identify the set of parameters that you want to let people adjust. These should be recognizable variables that you can label clearly (such as Pipe Diameter, Height in meters, Coefficient of the Quadratic Term, and so forth). In the projectile document, the variables and their labels are Initial Speed, Initial Height, and Initial Angle. These labels are important not only for breaking down the process of converting the document, but also because they let the user know what sort of number to enter through the Web Control. Keep the labels brief and consider formatting them with a bold font, to stand out in the final document.

Web Controls:

Text box - allows typed entry (without validation or error checking)

Check box - allows selection of one of a group of choices

List box - allows selection of one of a list of scrolling choices

Radio button group - allows selection of one of a group of choices

Submit button - triggers recalculation if automatic updating is turned off

Think about how you want the readers to enter the value and choose a complementary type of control for each parameter. Will you only allow them to select from a range of values in a preset list? Or is there a continuous range of values that is appropriate?

If you want the reader to choose a size of pipe, and you know there is a common range of manufactured sizes of pipe that fit the application, those sizes could populate a drop-down list control. In the projectile worksheet, this kind of choice is appropriate for the initial angle input because increments of 10 degrees are fine enough to show the conceptual changes in the solution.

Text Box

Provide Text boxes when you want people to be able to enter a broader range of information in a more granular way, so they can enter their own values. A text box control usually needs an explanation of the appropriate range or suggested end limits. In the projectile worksheet, a text box for Initial speed with a note that reasonable initial speeds should be between 10 and 50 m/s is an appropriate control.

Radio Buttons and Check Boxes

Use radio buttons or check boxes when your parameter has only a few choices, and they are switch-like, (turn this part of the calculation on or off) or are used to select one of only a few tools or methods (cubic, quadratic, or linear endpoints). For the projectile document, you might make the initial height input a check box with choices "Start at ground level" or "Start 250 meters up a platform."

Tip: As a general rule, if you need more than one set of radio buttons or check boxes to set parameters, try to use just one type of control. You send your readers a clearer message if you consistently use one control or the other; not both.

Worksheet before

Worksheet after

Create the Controls

As you add Web Controls to the worksheet and delete or disable and hide the original input mechanism, you insert the control first and then apply a variable name. If you reverse the order, the option to insert the control will be grayed out.


First click the location within the worksheet where you want to insert the control. If possible, locate all the controls close together so the reader can see everything they need to adjust on one screen).


Next, pull down the Insert menu and select Control > Web Controls. The main Wizard screen is displayed:

Figure 1: The Web Control Setup Wizard walks you through the process of selecting and configuring each type of Web Control.


1. Select the type of control you want and click Next. The Wizard then displays the control's property sheet (below).

Figure 2: Each type of control has a different property sheet. This example, for a List/Combo box, controls the number of visible rows, the name and associated value of each entry, and whether the worksheet should recalculate automatically when the value changes.

2. Label the control if desired, and, if required, fill in the appropriate default values.


3. Click Finish to insert the control.


4. Assign the output of the control to a variable.

You should test controls as you insert them, as they contribute to the larger calculation. Keep your eye on the areas where results are displayed to ensure that the controls are functioning properly. You may wish to specifically display your controls' values to make sure they are behaving as you expect and to check the entries in the control's properties.


If you wish to use units in your calculations, you'll need to multiply the value of the variable defined by the control with the appropriate unit, as occurs in the projectile worksheet. You can either delete the original variable definitions at that point, or leave them in place and disable them. To disable a definition, right-click it and choose Disable Evaluation from the popup menu.

Worksheet before

Worksheet after

Decide When to Recalculate

Once you have the appropriate input variables set up as controls, decide whether you want users to see results as soon as they change a single control or adjust all the settings first and then see the result of their combination of changes. (If your worksheet resides on a Mathcad Calculation Server that serves many worksheets, or if you expect large numbers of people to work on it simultaneously, recalculating after adjusting a single parameter provides more efficient use of the server's calculation engine.)

To make individual changes be reflected immediately, open each control's property sheet and activate the Update on change check box.

To make multiple changes that are calculated simultaneously, deselect the Update on change check box on each control's property sheet. Then create a Submit button control. You need to assign the Submit button a variable name, but it does not impact on your worksheet The button does nothing while you work on the worksheet in Mathcad; it does not acquire a function until the worksheet is stored on the Calculation Server.

You may want to hide the variable names next to each control for better alignment on the final document and to simplify the worksheet for non-Mathcad users. To do so, right-click the control, and choose Hide Arguments.

Worksheet before

Worksheet after

What Do Readers Need to See?

Next, consider the portions of the calculation you wish a Web user to see. Mathcad equations, text regions, and graphs render to the Web browser as images, but you may not wish all portions of the calculations to be visible. It is best to keep Web documents to a single screen, and to use graphics and highlighted regions to point out that recalculation did take place when the inputs were changed.

Collapsed Areas

To preserve calculations but not display them, hide them in collapsed areas. To create a collapsed area, choose Area from the Insert menu, drag the area bars above and below the content you want to hide, and double-click on a bar to collapse the area.


In the projectile document, units were added to the variables entered through controls. They were hidden in a collapsed area because those operations are not central to the point of the calculation; they are just bookkeeping. The equations for height over time and final range are shown so that the reader can verify how the calculation is performed. Also, a final graphic shows changes in a very obvious way when the inputs are updated. The equations that set up the x values are hidden in a collapsed region because they are not directly relevant. The final values for the range and the maximum height — the answers to this problem — are highlighted in blue.

Tip: If you can't reasonably keep required inputs and outputs on a single screen, be sure to provide in-document hyperlinks to link readers down to the results. You can create region tags by right-clicking on the region and choosing Properties. On the display tab, fill in the Tag box; for example, "tagname." Then, create hyperlinked text in other locations by choosing Insert > Hyperlink, and link to #tagname.

Worksheet before

Worksheet after

Error Checking

Think carefully about what happens as users change the inputs to your document. Do the graphs continue to display properly? Do equations in your document show errors if the wrong sort of values are entered? How can you encourage people to enter reasonable values and show off the changes in the output most clearly?

In the projectile document, the graph has been set so it does not resize its axes, to emphasize the changes that are occurring. A short program has been added to check the value of vo, so it does not enter a range that will give confusing results on the graph. Try entering a value greater than 300 for velocity. The calculation halts (an error results for the value of R) and the associated error message displays. Look inside the collapsed region in projectile7.xmcd to see how this was done.

Worksheet before

Worksheet after

Weave the Web

The final step in development is adding links and navigation tools to your Web pages so readers can find their way around. Your site should be consistent with the look and navigation of any larger site that it is a part of. You may wish to add links to related pages and branding within your Mathcad document or wrap it with an external HTML template. Use the Insert > Hyperlink command to insert hyperlinks within a Mathcad document.

Templates

If you are creating many Mathcad documents as part of a large site structure, we recommend the use of external HTML templates to wrap your Mathcad documents. Templates ease the creation and maintenance of a site, allowing you to centralize structure and navigation into a single document. Depending on your organization's standards, you could consider adding a logo, contact and copyright information, the author's name and contact information, links to your organization's homepage, and so on. This current document is wrapped in a template that provides the header, footer, and navigation links within the authoring guide.

Template files are HTML files with certain comment lines that tell the Calculation Server where to insert Mathcad worksheet content. Template files are saved with an .MLT extension. Template files can include any valid HTML markup, such as

<img> tags, and image maps for navigating through your content,

<a> hyperlinks to HTML files,

<link> tags to cascading style sheets,

JavaScript to automatically generate links, create date stamps, or for any other functionality.

A Web Template file is saved with a .MLT extension and must include four sets of Mathcad-specific comment tags, in addition to whatever HTML markup you wish to appear in the final document. Here's an example, which you can modify in any text editor to create your own.

Tips:

  • You can create an HTML template file using any text editor or HTML-processing application. Just be sure to save with the .MLT extension and save the content as text-only.
  • Be sure to move any images, style sheets, JavaScript source files, or other files referenced by links in your template to a directory relative to your Mathcad file. Using a template with a Web-served Mathcad file is equivalent to moving the template file to the new working server directory.
  • HTML pages generated by the server have a feature which scrolls a document back to its previous position after recalculation. To preserve this functionality in templated documents, include the following handler in in the body tag: <body onload="onbodyload()">

Activating Your Templates

You can either test your templates by opening up the .MLT file in a Web browser, or you can use Calculation Server configuration settings to try the template in place around a Mathcad document. You could also use the template to save the document as HTML from Mathcad, with appropriate preferences set. See the Mathcad Author's Reference under the Help menu for more information on this approach.

To use templates, or set other preferences about how Mathcad worksheets are displayed in the browser window, you'll need to change configuration file settings. If you have appropriate permissions, you can do this with the Calculation Server administration tool. If not, you can still try it for a single document by modifying the query string for the document's URL.

http://[yourAppServerdomain/path/yourworksheet].xmcd?TemplatePath=[path\yourtemplate].mlt

For example, to use the sample template shown around the final projectile example document, we can link to the following URL:

http://mcs.ptc.com/mcs/documentation/EN/guide/projectile7.xmcd?TemplatePath=documentation\EN\Authoring_Guide\mwmtemplate.mlt

The template path is a file system path, not a URL, relative to the web application root (e.g. "c:\Inetpub\wwwroot\mcs"). If you set the template path with the administration tool, the directory must already exist.

If desired, you can also change the default settings for image type and font rendering when worksheets are displayed to the browser, either through the configuration files or through the URL. This allows you to use different settings for the same worksheet in different situations, as shown above.

The choices are

ImageFormat=png or ImageFormat=jpg

If you've chosen jpg, set ImageQuality=XX (between 1 and 100)

FontUnit=px (pixels) or FontUnit=pt (points)

TemplatePath=templates\mytemplate.mlt (if you are using a template)

Assign multiple attributes separated by an ampersand:

http://domain/mcs/worksheet.xmcd?ImageFormat=jpg&ImageQuality=70