Getting Started

You can integrate with CalcXML's calculators in one of three ways:

  • Hyperlinks which you place on your web site.
  • XML passed using HTTP POST where you create and host the calculator input and result pages.
  • Standard SOAP-based web service calls where you create and host the calculator input and result pages.

The following document provides a quick tutorial on the second two options, XML passed using HTTP POST and Standard SOAP-based web services --> Integrating With CalcXML's Web Services. (HTML version here).

Integrating Via Hyperlinks

CalcXML calculators are available as hyperlinks which you place on your web site. When clicked, these calculator hyperlinks can open in:

  • A new popup window
  • A standard iframe
  • An auto-sizing iframe
  • A shadow box

You can see examples of these different implementation options by looking at our client showcase.

You can control the look-and-feel of the calculator input and result pages using a css stylesheet file. We provide our base stylesheet and you can modify it as much as you like. Once you are happy with it, we'll load it up on our servers and use it for all of your hyperlinked calculators. You can also host the stylesheet on your own servers if desired and make changes to it whenever needed without having to get our support team involved. NOTE: Our support team typically gets stylesheet changes done within a 24-hour period. You can also have your company logo appear on the calculator pages.

Information and help on modifying the stylesheet to customize your calculator pages is available here.

Sample stylesheet available here.

What Can You Customize?

  • Anything related to style in the css file. (Colors, fonts, alignment, buttons, etc.)
  • The text of the calculator title, introductory paragraph, and disclaimer.
  • The images used for the submit, help and other buttons. NOTE: Images are not required for some buttons as they can be controlled via styling in the css file.
  • The default values that appear in the input fields when the calculator page first displays. This is done using querystring parameters passed in on the URL like this: http://www.calcxml.com/calculators/be-a-millionaire?currentAge=22
  • The width of the chart that is returned as part of the results. This can be handy if you need a smaller chart. This is done using querystring parameters passed in on the URL like this: http://www.calcxml.com/calculators/be-a-millionaire?chartWidth=300. Click the Submit button on the page that is displayed to see the chart. NOTE: Chart height is set automatically by the system and cannot be overridden.
  • Whether the values entered into the calculator get stored as cookies on the user's computer. When enabled, this will prepopulate the calculator with the last used data when the user opens the calculator page again. NOTE: This requires that the user have cookies enable.
  • Whether http or https links are used.
  • A banner across the bottom of the calculator page promoting anything you'd like. Examples would be:
    • a hyperlinked image
    • a small iframe which contains content from your site
    • marketing text
    • any html
  • Reset and Edit buttons can be shown if desired. Reset sets all input field values to our standard default values. Edit returns the user to the top of the page to allow editing of the input values.
  • Whether the charts are flash-based or image-based (gif/jpg). This is done using a querystring parameter passed in on the URL like this. Valid values are "flash" and "image": http://www.calcxml.com/calculators/be-a-millionaire?chartLibrary=image
  • NEW FEATURE: Recommendations, or "calls to action", can be defined and displayed on the results page on a per-calculator basis. Along with this functionality comes the ability to specify the criteria for each recommendation. The criteria are based on the user's input values.

Integrating Via Web Services

The real strength of CalcXML's calculators is the fact that they are available as web services, giving you complete control over every aspect of the user interface. You create and host the calculator input and result pages. If desired, you can store user entered data, gather traffic statistics, gather lead generation data, or whatever else you like. You are in control.

You will need an IT staff in order to integrate using our web services, but rest assured, the integration is still quite simple for those familiar with web services. The documentation that follows will give you everything you need to have a successful web service integration.

XML Schema Definition Files

The xml documents that you create and send to CalcXML's calculator engines will contain the input values for the various calculators. These xml documents must conform to a certain template, or schema. In other words, the names of the parameters, the allowed ranges of values, the overall structure of the document, etc., must adhere to a schema. The xml documents that you receive in response to your calculator requests from CalcXML's calculator engines will also conform to a schema.

If you are not familiar with xml schemas, you may want to search the internet and do a little research before diving into the integration process.

Best viewed with an XSD editor, like Altova XMLSpy
calcxmlRequest.xsd
calcxmlResponse.xsd
dataTable.xsd
pieChart.xsd (Image charts)
xyChart.xsd (Image charts)
flashChart.xsd (Animated Flash charts)

List of all input schema files
List of all output schema files

Sample XML request and response documents
Sample Request (chartType="image")
Sample Response (chartType="image")
Sample Request (chartType="flash")
Sample Response (chartType="flash")

NOTE: All of the sample implementations of our calculators provide a way to view the raw xml request and response going back and forth. To see this information, append "?showXml" to the end of the URL. For example http://www.calcxml.com/calculators/loan-payment-calculator?showXml. After filling in the the input fields and clicking "Submit" the xml request and response will be shown at the bottom of the page. There will also be a few new controls at the top of the page that you can adjust and see how it affects the results.

Web Services API

CalcXML's calculators are divided up into 13 categories. Each calculator has unique input parameters. This web-based API documentation lets you see the details behind every calculator, providing helpful documentation and links to all relevant schemas for each calculator.

API documentation - Nicely formatted and indexed API (Application Programming Interface) documentation for our web services.
Web Service end points (wsdl files) - A listing of the URLs used for consuming CalcXML's web services.
Web Service Client - Java jar file with associated dependencies. You can use this client to connect and consume web services or you can create your own. NOTE: For Java implementations only.

SOAP Documentation
Many development environments will handle the creation of the SOAP envelope for you. However, if you will be creating it manually, you may want to review the information contained at the link below.

SOAP Envelope Documentation

Dynamic HTML

We realize that many web applications now days call for dynamic html, pulling in content from a variety of sources. One of those sources may be a calculator input form. For this reason, we have included in our schemas all the necessary information for you to dynamically create calculator input and output forms using an xsl stylesheet. In fact, all of our sample implementations have been created using xml files and an xsl stylesheet!

Each calculator has an xml document we call a transform file. The transform file is "transformed" to a jsp file using an xsl stylesheet. You are welcome to use our xsl stylesheet as is, or as a guide to create your own. You are also welcome to use our transform files to create your own based on the schema files for the calculators.

XSL Stylesheet This stylesheet creates jsp pages for our sample implementations using the transform files below.
Transform files These files are transformed into jsp pages using the XSL Stylesheet above.
Schema for transform files The transform files conform to this schema.

Internationization/Localization

CalcXML calculators can be used in any country and language. By passing in a country code and language, you tell the CalcXML calculator engine how to format the monetary amounts which will be returned. The Flash and image charts that are created are also formatted appropriately, including chart title and axis labels.

This functionality is available when integrating via web services as well as when integrating via hyperlinks. As described above, web services gives you the ability to create and host the calculator pages while hyperlinks provides a quicker time to market.

Language Codes Use the ISO 639-1 alpha-2 codes.
Country Codes Use the ISO 3166-1 alpha-2 codes.

Flash Chart Documentation

The Flash charts that are returned as part of the response can be customized to your liking. There are a variety of attributes in the request which allow for this customization. For our complete Flash chart documentation, click here.

Percentage/Rate Values

Many of the calculators have percentage or rate values as inputs. The calculator engines require all such values to be the actual decimal equivalent value. For example a rate of 5% should be passed to the calculator as 0.05, a rate of 100% should be passed as 1.0, etc.

XML Request Submitter

This is a simple tool that lets you submit an XML request to our calculator engines in order to test your XML. Paste your <calcxmlRequest> into the box below and then click Submit. The response will open in a new window.
(A sample request has already been included below.)

Get started now.

Sign up