Witholding Calculation Tutorials

Here we take you through the first steps in using TaxControls in your application.

Set Up The Environment

Download the .NET component from here.

Several methods can be used to compile and execute code on the .NET platform, including Microsoft's Visual Studio .NET, and the Mono project. For this tutorial, we will use the command-line tools available with Visual Studio.

Open a command-line window by selecting Start | Run... from the Windows desktop. When the Run dialog box opens, type 'cmd' in the input field, then click 'OK'.
Type the following at the resulting command prompt:
```
vsvars32.bat
```
which is installed with Visual Studio .NET.
Type the following line to ensure that your environment is set up correctly:
```
csc /?
```
You should see the help information for the C# compiler on the console.

Instantiate the TaxControls object

Create and test the object. In file named 'Instantiate.cs', enter the following:

 using System;
 using TaxControls;
 class Test{
 public static void Main(){
 CTaxControl tc = new CTaxControl();
 Console.WriteLine(tc.SoftwareVersion);
 }
 }

Compile the code at the command prompt by executing the following:
```
 csc /reference:TaxControls.dll Instantiate.cs
```
Run the program by typing:
```
 Instantiate
```
The program should print a version number on the console.

Compute a withholding amount

Enter the following code in a file named 'Compute.cs':

 using System;
 using TaxControls;
 class Test{
 public static void Main(){
 CTaxControl tc = new CTaxControl();
 tc.DataFilename = "demo.tax";
 tc.SelectedTax = "fit";
 tc.Earnings = 5000.00;
 Console.WriteLine(tc.TaxAmount());
 }
 }

Compile the code at the command prompt by executing the following:
```
 csc /reference:TaxControls.dll Compute.cs
```
Run the program by typing:
```
 Compute
```
The program should print a withholding amount on the console.

List all tax names

Enter the following code in a file named 'List.cs':

 using System;
 using System.Collections;
 using TaxControls;
 class Test{
 public static void Main(){
 CTaxControl tc = new CTaxControl();
 tc.DataFilename = "demo.tax";
 Taxes txs = tc.Taxes
 IEnumerator inr = txs.GetEnumerator();
 while(inr.MoveNext()){
 Tax t  = (Tax) inr.Current;
 Console.WriteLine(t.Name);
 }
 }
 }

Compile the code at the command prompt by executing the following:
```
 csc /reference:TaxControls.dll List.cs
```
Run the program by typing:
```
 List
```
The program should print many tax names on the console.

List state tax names

Enter the following code in a file named 'States.cs':

 using System;
 using System.Collections;
 using TaxControls;
 class Test{
 public static void Main(){
 CTaxControl tc = new CTaxControl();
 tc.DataFilename = "demo.tax";
 Taxes txs = tc.Taxes
 IEnumerator inr = txs.GetEnumerator();
 while(inr.MoveNext()){
 Tax t  = (Tax) inr.Current;
 if (t.TaxType == "S")
 Console.WriteLine(t.Name);
 }
 }
 }

Compile the code at the command prompt by executing the following:
```
 csc /reference:TaxControls.dll States.cs
```
Run the program by typing:
```
 States
```
The program should print the state tax names on the console.

Look up taxes for a ZIP code

Enter the following code in a file named 'Zips.cs':

 using System;
 using TaxControls;
 class Test{
 public static void Main(){
 CTaxControl tc = new CTaxControl();
 tc.DataFilename = "demo.tax";
 String s = tc.TaxNamesForZip(44139, 44145);
 Console.WriteLine(s);
 }
 }

Compile the code at the command prompt by executing the following:
```
 csc /reference:TaxControls.dll Zips.cs
```
Run the program by typing:
```
 Zips
```
The program should print a comma-delimited string of tax names on the console. Note that Federal and Social Security taxes apply regardless of ZIP code, and are not returned by TaxNamesForZip().

Set up the Environment

Download the Java component from here.
Set up the classpath.
To use the TaxControl component, your classpath must include both the 'bigloo_u.zip' and 'TaxControls.jar' files.
- On Windows Set the classpath to .;bigloo_u.zip;TaxControls.jar
- On Unix/Linux/OSX Set the classpath to .:bigloo_u.zip:TaxControls.jar
For example, this command would compile the demo on Windows:
```
 javac -classpath .;bigloo_u.zip;TaxControls.jar Demo.java
```
This command would run the demo (again on Windows)
```
 java -classpath .;bigloo_u.zip;TaxControls.jar Demo
```

Note: Some versions of Eclipse may not correctly recognize bigloo_u.zip as a jar file. As a workaround, you can rename the file to 'bigloo_u.jar' and adjust the classpath accordingly.

Instantiate the TaxControls object

Create and test the object. In a file named 'Instantiate.java', enter the following:

 import com.boondocks.taxcontrols.TaxControl;
 public class Instantiate{
 public static void main(String[] args){
 TaxControl tc = new TaxControl();
 tc.showAboutBox();
 }
 }

Compile the code at the command prompt by executing the following:

 javac -classpath .;bigloo_u.zip;TaxControls.jar Instantiate.java

Run the program by typing:
```
 java -classpath .;bigloo_u.zip;TaxControls.jar Instantiate
```
You should see an About box similar to the following:
End the program by clicking OK .

Compute a withholding amount

Enter the following code in the file 'Compute.java':

 import com.boondocks.taxcontrols.TaxControl;
 import com.boondocks.taxcontrols.TaxControlException;
 public class Compute{
 public static void main(String[] args){
 TaxControl tc = new TaxControl();
 tc.setDataFilename("demo.tax");
 tc.setEarnings(5000.0);
 try{
 System.out.println(tc.getTaxAmount());
 } catch (TaxControlException e){
 e.printStackTrace();
 }
 }
 }

This minimal code chooses the tax table data file, sets the earnings per pay period to $5000, and computes the tax. Default values were taken for YTDEarnings ($0), Exemptions (0), FilingStatus (0 = Single), and PayPeriodsPerYear (12 = monthly).

Compile the code at the command prompt by executing the following:
```
 javac -classpath .;bigloo_u.zip;TaxControls.jar Compute.java
```
Run the program by typing:
```
 java -classpath .;bigloo_u.zip;TaxControls.jar Compute
```
You should see the computed Federal income tax print out on the console.

List all tax names

Enter the following code in the file 'List.java':

 import com.boondocks.taxcontrols.TaxControl;
 import com.boondocks.taxcontrols.Taxes;
 import com.boondocks.taxcontrols.Tax;
 import com.boondocks.taxcontrols.TaxControlException;
 import java.util.Enumeration;
 public class List{
 public static void main(String[] args){
 TaxControl tc = new TaxControl();
 tc.setDataFilename("demo.tax");
 try{
 Taxes txs = tc.getTaxes();
 for (Enumeration e = txs.elements();e.hasMoreElements();){
 Tax t = (Tax)e.nextElement();
 System.out.println(t.getName());
 }
 } catch (TaxControlException e){
 e.printStackTrace();
 }
 }
 }

Compile the code at the command prompt by executing the following:
```
 javac -classpath .;bigloo_u.zip;TaxControls.jar List.java
```
Run the program by typing:
```
 java -classpath .;bigloo_u.zip;TaxControls.jar List
```
You should see the names of many taxes print out on the console, in no particular order.

List state tax names

Enter the following code in the file 'States.java':

 import com.boondocks.taxcontrols.TaxControl;
 import com.boondocks.taxcontrols.Taxes;
 import com.boondocks.taxcontrols.Tax;
 import com.boondocks.taxcontrols.TaxControlException;
 import java.util.Enumeration;
 public class States{
 public static void main(String[] args){
 TaxControl tc = new TaxControl();
 tc.setDataFilename("demo.tax");
 try{
 Taxes txs = tc.getTaxes();
 for (Enumeration e = txs.elements();e.hasMoreElements();){
 Tax t = (Tax)e.nextElement();
 if (t.getTaxType().equals("S"))
 System.out.println(t.getName());
 }
 } catch (TaxControlException e){
 e.printStackTrace();
 }
 }
 }

Compile the code at the command prompt by executing the following:
```
 javac -classpath .;bigloo_u.zip;TaxControls.jar States.java
```
Run the program by typing:
```
 java -classpath .;bigloo_u.zip;TaxControls.jar States
```
You should see the names of many taxes print out on the console, in no particular order.

Look up taxes for a ZIP code

Enter the following code in the file 'Zip.java':

 import com.boondocks.taxcontrols.TaxControl;
 import com.boondocks.taxcontrols.Taxes;
 import com.boondocks.taxcontrols.Tax;
 import com.boondocks.taxcontrols.TaxControlException;
 import java.util.Enumeration;
 public class Zip{
 public static void main(String[] args){
 TaxControl tc = new TaxControl();
 tc.setDataFilename("demo.tax");
 try{
 // Employee lives and works in Ohio:
 Taxes txs = tc.getTaxesForZip(44139, 44145);
 for (Enumeration e = txs.elements();e.hasMoreElements();){
 Tax t = (Tax)e.nextElement();
 System.out.println(t.getName());
 }
 } catch (TaxControlException e){
 e.printStackTrace();
 }
 }
 }

Compile the code at the command prompt by executing the following:
```
 javac -classpath .;bigloo_u.zip;TaxControls.jar Zip.java
```
Run the program by typing:
```
 java -classpath .;bigloo_u.zip;TaxControls.jar Zip
```
You should see the names some local or state taxes print on the console. Note that Federal and Social Security taxes apply regardless of ZIP code, and are not returned by TaxNamesForZip().

Set up the Environment

All that is needed for PHP tables is a web server capable of serving up PHP5 files. If you plan to use the 'taxNamesForZip' function (see below), then your PHP installation must have the PDO module, with a sqlite driver.

The PHP demo should be unzipped into a directory under the document root of the web server. The 'taxes.php' file should be included in your app page:

 <?php
 include_once('taxes.php');
 ...
 ?>

Instantiate the TaxControls object

Rather than a single TaxControls object, the PHP table supplies an array of instantiated tax objects, returned by the function 'taxList()'. This array has a key value of the tax name, pointing to the instantiated object:

 <?php
 include_once('taxes.php');
 $taxlist = taxList();
 // federal income tax:
 $t = $taxlist['FIT'];
 ?>

Compute a withholding amount

You don't need a tax object or taxList() to perform a calculation. Just call the top-level compute function:

 <?php
 include_once('taxes.php');
 $amt = compute('FIT',  // tax name
 2000,  // gross earnings
 0,  // ytd earnings
 $filingSingle,  // filing status (0=single)
 0,  // exemptions
 0,  // state exemptions
 12);  // pay periods per year (12=monthly)
 ?>

List all tax names

The taxList() function returns an array of all the tax objects. Just iterate over the array to generate the list:

 ...
 foreach(taxList() as $key => $tax){
 print $tax->name;
 }
 ...

List state tax names

Filter the taxList() array, using only tax objects with type=='S':

 ...
 foreach(taxList() as $key => $tax){
 if ($tax->type=='S')
 print $tax->name;
 }
 ...

Look up taxes for a ZIP code

You can use the function 'taxNamesForZip' to get an array of suggested tax names for the employee:

 ...
 $workzip = 10001;
 $homezip = 7450;
 $taxlist = taxList();
 $a = taxNamesForZip($workzip, $homezip);
 foreach ($a as $taxname){
 $tax = $taxlist[$taxname]
 ...
 }
 ...

Note that Federal and Social Security taxes apply regardless of ZIP code, and are not returned by taxNamesForZip().

Set up the Environment

Install Docker. For a Windows host, see this page, for a Linux host, see this page for more information.

Run the container:

docker run -it --rm -p 8000:80 calibertechnology/taxserver

This will start the TaxServer container with port 8000 on the host pointing to the service's API overview page.

Instantiate the TaxControls object

TaxServer is a web service, and no TaxControls object is involved. To confirm that the service is running, open a browser on the PC hosting the docker container, and type:

 http://localhost:8000

If everything is up and running, You'll see the TaxServer home screen.

This web page provides a convenient interface for learning the TaxServer API. Your client application can be written in any language that can issue http requests.

Compute a withholding amount

In the browser's address bar, type:

 http://localhost:8000/taxamount/federal income tax&earnings=1000.00

Press Enter, and the browser should display the withholding amount for 'fit' (Federal Income Tax), given gross earnings of $1000 for the default pay period (Monthly).

List all tax names

In the browser's address bar, type:

 http://localhost:8000/taxes

Press Enter, and the browser should display the JSON array listing every tax name.

List state tax names

TaxServer provides a built-in method to filter taxes by their type, using the 'types' parameter:

 http://localhost:8000/taxes?types=S

However, to illustrate how you can filter based on any property, we'll implement this programmatically. Here the client code is written in PHP, but the API can be accessed from many languages.

First get a complete list of taxnames:

 <?php
 $all = json_decode(file_get_contents('http://localhost:8000/taxes'));
 ?>

Now, for each taxname, fetch the tax object and check its type:

 :
 if ($all->status == "ok") {
 foreach($all->value as $name){
 $taxname = rawurlencode($name);  // converts any spaces to '%20'
 $tax = json_decode(file_get_contents("http://localhost:8000/tax/$taxname"));
 if ($tax->status == "ok") {
 $props = $tax->value
 if ($props->taxtype == "S"){
 print "$props->name: $props->title\n";
 }
 }
 }
 }
 ?>

Look up taxes for a ZIP code

TaxServer does not implement the TaxNamesForZip method. Instead, consider using the TaxQuery Docker container, which provides similar results using employees' workplace and residence addresses.