WellTech Calculators API

WellTech Calculators are easily integrated into your web page, and requiring only a moderate level of HTML and JavaScript knowledge. Styling the calculator interface is left to you.

Prerequisite: A WTC_proxy.php file necessitates PHP support (v4 minimum) on the web server, though the presentation to the user does not. No PHP programming experience is required.

AJAX-PROXY Interface

The WellTech Calculator API only requires adding a handful of HTML on the target web page (where the calculator form and results are displayed), and uploading two files to your web site - our standard WTC.js and WTC_Proxy.php file.

Using AJAX technology allows you to request information from a web server (our calculator, in this case) without refreshing the current web page, which can be helpful if a page refresh would be costly in time or distracting to the user. Only a small portion of the web page - the calculator result - is updated as a result of the call. WellTech has chosen this method both for it's benefits to the user as well as for simplicity's sake.

For security reasons, browsers do not allow cross-domain AJAX calls, so instead of your web page querying the WellTech calculator directly via AJAX, a local proxy is used. This is the WTC_Proxy.php file referred to earlier, that is simply copied to your website application directory.

You include a small HTML form on the target web page where the user enters or selects values for all the calculator's required parameters, like the BMI Calculator example below. When the form's submit button is clicked, the JavaScript function WTC_ajax() is called, which initiates the AJAX call to the WTC_Proxy.php file.

The AJAX call passes the calculator name and all the form parameters. Then the proxy page itself queries the WellTech server (not via AJAX this time) for it's XML results. The proxy page then returns the results and all the original parameters in well-structured JSON format to the client's page.

After eval'ing the JSON to a JavaScript object, the results are available as, for example:

obj.results.bmi   // the returned BMI value
obj.parameters.username   // a form field value not used by the calculator but passed through anyhow
obj.error[0][key]   // an error string returned from the calculator

Then, the client-side script WTC_displayResults populates the DOM with those results.

Configuration

There are only three things that need modified to fit a WellTech calculator to your web page. The first two involve changes to the WTC.js file. The first is to set the location of the WTC_proxy.php file. The default value is fine if the file is in the same location as the web page file that references it.

//
// --- CONFIGURATION SECTION ---
//
var proxy = "WTC_proxy.php"; // Set this to the relative file name of the proxy

The second thing is to handle the response from the calculator. The displayResults function is where you interpret the results from the calculator, either displaying an error message or the returned results. The WellTech calculators return all of the originally passed form parameters - even those that are not needed by the calculator - so you can reference them too.

//
// --- CUSTOMIZE THIS FUNCTION FOR YOUR PURPOSES ---
//
// Display the results on the web page
// "obj" is an object that contains the calculator results and passed parameters
// e.g. obj.results.bmi, or obj.parameters.username, or obj.error[0][key]
//
function displayResults(obj)
{
  var displayString = "";
    // Errors are returned in an array
    for (i=0; i<obj.errors.length; i++)
      for (key in obj.errors[i])
      {
        //displayString += key + ": ";
        displayString += obj.errors[i][key] + "<br>";
      }
    displayString += "</span>";
  }
  else
  }
    displayString += "blue'>" + obj.parameters.name + ", your BMI value was calculated ";
    displayString += "to be " + obj.results.bmi + ", putting you in the ";
    displayString += "<b>" + obj.results.category + "</b> category.</span>";
  }
  document.getElementById('bmiResult').innerHTML = displayString;
}

The last thing to modify is your web page, by adding a reference to the WTC.js file, and to insert the calculator form template, styled according to your preference. First include:

<script type="text/javascript" src="WTC.js"></script>

A sample form is shown below. Note that the name of the calculator is included in the form (see the sidebar above for appropriate values). This way, you can have multiple calculators on a page. You'll need to modify the JavaScript function above to check obj.parameters.calculator and handle each calculator's results differently.

<form>
<input type='hidden' name='calculator' value='bmi'>
<table>
  <tr>
    <th colspan='2'>BMI Calculator</th>
  </tr>
  <tr>
    <td>Name</td>
    <td><input type='text' name='name'></td>
  </tr>
  <tr>
    <td>Weight (lbs)</td>
    <td><input type='text' name='wtlbs'></td>
  </tr>
  <tr>
    <td>Height (ft/in)</td>
    <td><input type='text' name='htft'> / <input type='text' name='htin'></td>
  </tr>
  <tr>
    <td></td>
    <td><input type='submit' value='Calculate!' onclick='return WTC_ajax(this)'/></td>
  </tr>
</table>
</form>
Result: <span id='bmiResult' />

Put it all together and you come up with something like this: