# Guide to using Custom Widgets with Excel

Steps to build a custom pie chart and geo mapping widget.

June 20, 2022

## Building a custom Pie Chart

**Note:** Though Pie Charts are a commonly requested visualization, we don't really recommend using them for a [variety of reasons](/content/blog/pie-charts/index.html).

To create a Pie Chart using Custom Widgets with Excel, follow these steps:

## Step 1: Create the Excel spreadsheet with XML tags

1. Navigate to the [Geckoboard API Docs](https://developer-custom.geckoboard.com/#pie-chart).
2. Select **XML** from the top left drop down as this format works best for this method of creating Custom Widgets.
3. Navigate to the **Pie Chart** widget and copy the XML example at the right of the screen, or copy it from the following code block:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<root>
 <item>
 <value>100</value>
 <label>May</label>
 <color>13699c</color>
 </item>
 <item>
 <value>160</value>
 <label>June</label>
 <color>198acd</color>
 </item>
 <item>
 <value>300</value>
 <label>July</label>
 <color>60b8ec</color>
 </item>
 <item>
 <value>140</value>
 <label>August</label>
 <color>a4d7f4</color>
 </item>
</root>
```

4. Paste the XML example into cell `A1` of a blank Excel spreadsheet.
5. Format the spreadsheet so that each XML tag is in its own cell. The data between each set of tags should also be in its own cell:

6. Now it's time to change the example data in between the XML tags to your own data.

## Tip

To add another Pie Chart segment, copy and paste everything from `<item>` to `</item>`, making sure that the `</root>` tag stays at the very end of your file.

## Step 2: Save and upload your file

1. Go to **File > Save As**. Give your file a meaningful name and change the File Format to **Tab Delimited Text (`.txt`)**.
2. Choose an online location to save your Excel file to and click **Save**.
3. You'll be prompted with the message shown below. Click **Continue**.
4. Make a note of the public URL of the `.txt` file you just saved, as you'll need it for the next step.

## Step 3: Create a Custom Widget in Geckoboard

1. From your Geckoboard dashboard, click Add widget.
2. Navigate to **Custom Widgets** and select **Pie Chart**.
3. Specify your desired widget **Title**.
4. Leave the method as **Polling**.
5. In the **URL Data feed** field, paste the URL of the `.txt` file you just created and saved in Step 2.
6. Click Add widget.

6. View the resulting Pie Chart, shown below in both our Dark and Light themes.

## Step 4: Update the data and the Custom Widget

1. From Excel, go to **File > Open**.
2. Open your `.txt` file from the online location where you saved it in Step 2.
3. Excel's **Text Import Wizard** will appear. Click **Finish** straight away without going through the steps.
4. Update the data in your file as necessary.
5. Go to **File > Save**.
6. When prompted by the popup message that appears, click **Continue**.
7. Your Geckoboard Pie Chart dashboard will immediately reflect the changes you just made.

# Building a Custom Mapping Widget

The Custom Mapping widget provides a way to display geographical locations as points on a map. Each Mapping widget is configured for a particular region of the world, include the entire world map. Points that are located outside the bounds of the chosen region will simply be ignored.

Locations may be specified as:

- Latitude/Longitude pairs.
- City names.
- Hostnames.
- IP addresses.

To create a Custom Mapping Widget with Excel, follow these steps:

## Step 1: Create the Excel spreadsheet with XML tags

1. Navigate to the [Geckoboard API Docs](https://developer-custom.geckoboard.com/#map).
2. Select **XML** from the top left drop down.
3. Navigate to the **Mapping** widget and copy the XML example at the right of the screen, or copy it from the following code block:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<root>
 <points>
 <point>
 <city>
 <city_name>London</city_name>
 <country_code>GB</country_code>
 </city>
 <size>10</size>
 </point>
 <point>
 <city>
 <city_name>San Francisco</city_name>
 <country_code>US</country_code>
 <region_code>CA</region_code>
 </city>
 </point>
 <point>
 <latitude>51.526263</latitude>
 <longitude>-0.092429</longitude>
 <color>d8f709</color>
 </point>
 <point>
 <latitude>-33.94336</latitude>
 <longitude>18.896484</longitude>
 </point>
 <point>
 <host>geckoboard.com</host>
 </point>
 <point>
 <ip>178.125.193.227</ip>
 </point>
 </points>
</root>.
```

4. Paste the XML example into cell `A1` of a blank Excel spreadsheet.
5. This example gives all the possible options for entering locations: latitude/longitude pairs, city names, hostnames or IP addresses.

Decide on the method(s) you'd like to use and delete the rest from `<point>` to `</point>`.
6. Format the spreadsheet so that each XML tag is in its own cell. The data between each set of tags should also be in its own cell:

7. Now it's time to change the example data in between the XML tags to reflect your own data.

## Tip

To add another point to the map, copy and paste everything from `<point>` to `</point>`, making sure that the `</points>` and `</root>` tags stay at the very end of your file.

## Step 2: Save and upload your file

1. Go to **File > Save As**. Give your file a meaningful name and change the File Format to **Tab Delimited Text (`.txt`)**.
2. Choose an online location to save your Excel file to and click **Save**.
3. You'll be prompted with the message shown below. Click **Continue**.
4. Make a note of the public URL of the `.txt` file you just saved, as you'll need this in the next step.

## Step 3: Create a Custom Mapping Widget in Geckoboard

1. From your Geckoboard dashboard, click Add widget.
2. Navigate to **Custom Widgets** and select **Mapping.**
3. Specify your desired widget **Title**.
4. Leave the method as **Polling**.
5. In the **URL Data feed** field, paste the URL of the `.txt` file you just created and saved in Step 2.
6. Click Add widget.

6. View the resulting Mapping Widget, shown below in both our Dark and Light themes.

## Step 4: Update the data and the Custom Widget

1. From Excel, go to **File > Open**.
2. Open your `.txt` file from the online location where you saved it in Step 2.
3. Excel's **Text Import Wizard** will appear. Click **Finish** straight away without going through the steps.
4. Update the data in your file as necessary (in this example we've changed the color and size information).
5. Go to **File > Save**.
6. When prompted by the popup message that appears, click **Continue**.
7. Your Geckoboard Mapping widget will immediately reflect the changes you just made.