Developer Integration Information :: from Financial Calculators, Inc dba CalcXML

Getting Started

You can integrate with CalcXML's calculators in several different ways:

Hyperlinks which you place on your web site.
Embedded Using Javascript (AJAX).
Facebook.
REST web service calls where you create and host the calculator input and result pages.
XML passed using HTTP POST where you create and host the calculator input and result pages.
SOAP web service calls where you create and host the calculator input and result pages.

The following document provides a quick tutorial on the the HTTP POST option as well as a bit about SOAP 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:

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.)
Most of the text on the calculator input page, including the calculator title, introductory paragraph(s), field labels, 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 With Embedded Javascript (AJAX)

The embedded calculator works by making an AJAX call, which then loads the desired calulator into a <div>. To place an embedded calculator on your site, add the embed code where you want the calculator to appear. Here is a sample of the embed code:

<script type='text/javascript' src='https://code.jquery.com/jquery-2.2.1.min.js' type='text/javascript'></script>
<script type='text/javascript' src='https://ajax.googleapis.com/ajax/libs/jqueryui/1.11.4/jquery-ui.min.js' type='text/javascript'></script>
<script type='text/javascript' src='http://www.calcxml.com/scripts/tipped/comboTipped.js' type='text/javascript'></script>
<script type='text/javascript' src='http://cdnjs.cloudflare.com/ajax/libs/jquery-ajaxtransport-xdomainrequest/1.0.2/jquery.xdomainrequest.min.js'></script>
<script type='text/javascript' src='http://www.calcxml.com/scripts/loadCalc.js?calcTarget=sav01&embed=2&skn=62'></script>
<div id='calc' style='padding-top: 10px;'></div>

Integrating With Facebook

Integrating with Facebook requires the use of our Facebook app. This allows you to add a page tab to your Facebook page. To add our app to your page, use this link: https://www.facebook.com/dialog/pagetab?app_id=662673750485391&redirect_uri=https://www.calcxml.com/calculators/facebookConverter. To complete the integration, we will need the page ID of your page. To retrieve your page ID, log in to the admin account for your Facebook page. On the Pages section, click on your page. When it loads, the URL in your browser will have a number at the end. For example, https://www.facebook.com/pages/CalcXML/161488132854. That number is your page ID. Once we have that number, we can enable the calculator or multiple calculators for your Facebook page. Page admins can also set a name and image for the app.

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.

REST 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.

REST API documentation - Each calculator is represented in the API documents here. Sample URL, requests and parameters are shown. Both JSON and XML are supported data transfer options.

SOAP 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.

SOAP API documentation - Nicely formatted and indexed API (Application Programming Interface) documentation for our web services.
SOAP Web Service end points (wsdl files) - A listing of the URLs used for consuming CalcXML's web services.
SOAP 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

SOAP XML Request Submitter

This is a simple tool that lets you submit a SOAP 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.)

<?xml version="1.0" encoding="UTF-8"?>
<calcxmlRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://host2.calcxml.com/schema/1.3/calcxmlRequest.xsd" username="guest" password="water" responseType="html" chartLibrary="flash" returnDataTable="true" language="en" countryCode="US" version="1.3" returnRelevantLinks="false">
	<flashChart>
		<threeD>1</threeD>
		<chartWidth>500</chartWidth>
		<chartHeight>300</chartHeight>
		<chartAttributes>
			<attribute name="caption" value="Chart Title"/>
			<attribute name="xAxisName" value=""/>
			<attribute name="numberPrefix" value="$"/>
			<attribute name="bgColor" value="FFFFFF"/>
			<attribute name="showBorder" value="1"/>
			<attribute name="borderColor" value="B8AF76"/>
			<attribute name="borderThickness" value="1"/>
			<attribute name="canvasBgColor" value="E6E3CF"/>
			<attribute name="palette" value="2"/>
		</chartAttributes>
	</flashChart>
	<dataTable>
		<cssClassName>simpletable</cssClassName>
	</dataTable>
	<calcInput includeInResponse="false">
		<det03>
			<loanAmount>5000.0</loanAmount>
			<interestRate>0.05</interestRate>
			<termMonths>60</termMonths>
			<amortization>2</amortization>
		</det03>
	</calcInput>
</calcxmlRequest>

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.

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.