Creating a municipality map of Portugal with Raphael.js

Last year I found out about a rule in the Portuguese tax code that allows local councils to give back a small percentage of the taxes to be collected back to their residents. This was seen as a measure to incentivize people to move or stay in poorer regions, which probably suffer from a shortage of jobs and services. This was a common practice in medieval times, with incentives as big as a more lax treatment in possible crimes among them1. Of course back then the risk of an Eastern invasion by a Spanish monarch was very much in the day-to-day thinking of our rulers. One can speculate that if in 2018 all the Portuguese people live by the coast is the East still Portugal? I suppose if enough Irish speakers moved there it could be claimed as part of Ireland! But I diverge.

Coming from one of the poorest regions of Portugal myself, I wondered if the “right” places were the ones indeed taking advantage of this measure and trying to attract people to live there. After a bit of research, I found that my local town didn’t use this measure but some neighbouring places did. I searched for a map so that I could visualize where this was happening and by how much (municipalities can give back up to 5% of the tax to the be collected). I didn’t find any so I thought I would create one.

GitHub project
Step 1 – Creating a municipality map in svg

This was more of a search operation than a creative one. I needed an SVG map that I could manipulate in something like JavaScript in order to load some data dynamically, such as the tax information for each council. I found one map on Wikipedia under a Creative Commons license that I could change for my purpose since it contained some errors and missed some information such as three councils. This map is not perfect because it’s missing the 30 councils that make up the archipelagos of Madeira and Açores and instead just represents the archipelago as a whole. For the purpose of this exercise, it will suffice.

Step 2 – Creating a Javascript map with Raphael.js

In order to create an interactive map, I used Raphael, a JavaScript library that allows using vector maps as JavaScript objects. Armed with the SVG data and with a way to create objects from it I started by following an online tutorial that taught me with a quick way to create a map. The hardest part was actually mapping (no pun intended) the vector data to the correct councils in an array. The SVG map didn’t have the right names, sometimes, and also didn’t have all of the councils. This left me with the time-consuming option of manually copying the data into the array.

After some time I had a map that correctly represented all of the councils with names and real borders. In order to use this in JavaScript I created a file, concelhosSVG.js , and I created the following:

The MAP_WIDTH  and MAP_HEIGHT  variables allow us to define a size to work with. The mapContainer  variable will be used in the map div in our HTML file to display the actual map. The map  variable represents the Raphael object on which we will make our manipulations. 

Finally, we define concelhosSVG which will hold an index with the name of the council and the path to append to our map variable. 

In Raphael we can use the SVG path syntax which basically allows us to start with an M  (move to) and add coordinates until we issue a Z  for ending the path.

Step 3 – Adding our map to html

Now that we have a map we can create a simple HTML page to include the map. 

I’ve gone ahead and added a simple style to our CSS file

And here’s the result

Portugal Council Map using Raphael.js
Step 4 – Adding our tax information

Now that we have a map, albeit a very ugly one, let’s add our tax information. This information is public and you can get it from the Portuguese Revenue website

We’ll create a new JavaScript file called concelhosIRS.js  and we’ll create an array inside it with all the information needed.

Step 5 – Styling our map with the tax information

Finally, we just need to syle our map based on this information. In order to do that we’ll create a new JavaScript file named main.js  and we’ll add the following code to it.

We’ll start by adding our initial style, our style when hovering the mouse over a council and the style for each of the tax brackets. I chose to create six tax brackets between 0% and 5%. The councils that don’t offer any tax benefit will not have a colour and will just show as grey.

Next, we add a function to change the styling based on the tax benefit that the council provides.

And we wrap everything together by adding our main code that initialises the map colours and adds our event listeners for when we hover our mouse over a council and move out.

Final result and notes

After a few updates to our HTML file, we end up with the following map.

Final map with colours
Final map with colours

Much nicer right?

You can find all the source code on GitHub if you want to take a look or try it out for yourself.

I’ll throw some additional notes just so you’re aware of them:

  • I have not used councils for Azores and Madeira as I couldn’t find any usable SVG for them. I also suspect they would be tiny to select, as some councils in the continent already are. The tax data for them are mapped in concelhosIRS.js though.
  • I have used global variables for the tax data and the Raphael map. I did this because it was a learning exercise for me around Raphael and SVG and not programming. Global variables are fine to use in very small projects such as this tutorial but you shouldn’t use them in any production code or larger collaborative projects. Start here and do your own research.
  • A shout out to Andy Fitch who also has a nice tutorial on this subject.

 

 


Also published on Medium.

  1. http://repositorio.ul.pt/bitstream/10451/10602/1/ulsd067625_td_vol_1.pdf (pp.133-134)

Leave a Reply

Your email address will not be published. Required fields are marked *