Mahalle Boyamaca User Guide

MinibüslerMahalle Boyamaca is a single page, html/js application that lets the user to generate thematic maps. The final output is a bunch of image files colored thematically.

Generating Shapes


The canvas of the top left corner of the screen is where the user can draw the shapes (geometries). Drawing a shape consists of specifying the points on the border of the shape. It is possible to drag and drop a base image from the file system (any image file format, i.e.; jpg, png, bmp etc) to this canvas. What is being displayed on this canvas can be panned and zoomed in/out with mouse. Left clicking and dragging the mouse  on the canvas is how a user can pan. For zooming, mouse wheel can be used.

Left clicks with the mouse on the canvas without dragging is the way to put new points for a shape. No shape is being displayed unless the initial two points of the shape is specified. In order to finalize the drawing of a shape the user need to press the ‘C’ key on the keyboard. This action pops up the dialog for naming the shape.

A named shape is listed on the right side of the panel that contains the canvas. With this list, the user can edit or delete a shape. Pressing the delete button on an item in the list pops up the confirmation dialog for the deletion. Pressing the edit button on an item in the list does two things:

  1. The item is removed from the list.
  2. The shape is turned back into edit mode. The user can add more points to the shape, can remove present points and has the chance to change the name of it.

Whenever there is a need to delete the last point specified for a shape when in edit mode, the user can press the ‘Esc’ key on the keyboard. This action removes the last point added for the shape being drawn. Currently, this  is the only way to edit a geometry. There is no keyboard interaction other than ‘C’ and ‘Esc’ keys.

When making thematic maps, there usually is a need to draw shapes next to each other, sharing edge(s). Mahalle Boyamaca displays the shapes drawn with little circles on the points clicked to define the border of a shape. When drawing a second shape that is needed to be drawn adjacent to the first one, simply clicking close to the circles that defines the border to be shared is required. Mahalle Boyamaca automatically snaps these clicks to the circles if they are close enough. By zooming in to the location of the circles that defines the edges to be shared, the user can make sure if the click was snapped to the circle.

Providing Thematic Values For Shapes

Determining the shape of an item is one aspect of generating thematic maps. In order for a map to be thematic, there is a need to attribute each such shape with a value. Mahalle Boyamaca expects an excel file (an xls file to be more specific, there is no xlsx support currently) for such values.

The second box next to where the drawing is made is a droppable place, where the user is expected to drag and drop an excel file containing the thematic values of the shapes.

The format of the excel file is;excelFormat

With a single excel file, values for more than one image can be given. Each line (row) of the excel file corresponds to an output image.

There are a couple of things to notice for this format;

  1. Only one and the first worksheet is used.
  2. The content of the sheet MUST begin at the first row (1) and at the first column (A). Only the first cell (A1) must be empty.
  3. The names given to shapes must be at the first row starting with column B. It is CASE SENSITIVE. So the exact name given to the shape must be used in the excel file.

With shapes drawn and an excel file containing the thematic values for the shapes is provided, it is possible to generate images. But most of the time the desired result can not be achieved without some settings.


All the settings about Mahalle Boyamaca is under the collapsable panel named ‘Settings’. It is physically divided into two parts:

Thematic Settings


This part of the settings is where the user determines

  • the colors to be used,
  • the label for the color boxes that are going to be displayed below each image produced
  • and the thematic interval for each such thematic color.

colorChangingThe first two settings are trivial. By clicking on the colored boxes, the user accesses a color palette where he/she can choose another color. The associated text can be changed directly.

The third part is, determining the thematic intervals. The values to be used here changes from business to business. A user can enter intervals such as, 0-20.00, 20.01 – 40.00, 40.01 – 60.00, 60.01 – 80.00, 80.01 – 100.00. The thematic values given in the excel file should lie in one of the given interval otherwise the associated shape would not be drawn. By default the step of the controls for these values is set to 0.1 . But values with more significant digits can be entered as well. The important thing to take into account is that the intervals should not overlap, even by a single value. For example, 0-20, 20-40. For this instance, for a thematic value of 20, either of the colors can be used.

Image Settings

relativeSizeThe first part of image settings is where the user sets the relative extra width and height of the image.

To study these variables in an example, lets say that the total width and height of the shapes drawn be 327 px and 225 px respectively. With the first part of the image setting have values %20, %50, %95 and %80 as given in the image above, the total width and height of the images would be 801 px and 450 px. There would be  0.50 * 327 = 163 empty pixels on the left, 0.95 * 327 = 311 empty pixels on the right, 0.20 * 225 = 45 empty pixels on the top and 0.80 * 225 = 180 empty pixels on the bottom of the image. The shapes would be drawn between these regions. A sample output image is displayed below with the values studied above.



Another part of the image settings is the table where the user can enter values for parameters for label alignment. The labels considered here are the numbers displayed on the shapes. Especially for shapes that are concave, the labels sometimes are placed out of the boundaries of the shape.


With parameters for label alignment, the user is able to change the location of the labels. There are three number boxes for each item added to the table of parameters for label alignment. The first one is the identifying number of the shape. The other two are the displacement amounts of the location of the label. The X parameter is used to displace the label to the right or to the left and the Y parameter is used to displace the label to the top or to the bottom.

For example, with values [1, -85, 800] entered for the [No, X, Y] fields, the output image changes into the one below:concaveShapesDisplaced

For each such shape where its label need to be relocated, an entry to the parameters for label alignment table should be added and set.

Legend Settings

By default Mahalle Boyamaca enumerates the shapes drawn and displays them with labels enumerated starting with 1. It also displays a legend on the top right side of the image listed vertically that contains the name and the themaic numeric value of the shapes. The first three parameters of the Legend Settings is for this part of the image. The first two is to relocate the list. The values denotes the pixel values of the top left corner of the list. The default values are (-100,100). The origin of these parameters is the top right corner of the image. So, in order to display this list, the X parameter must always be lower than zero (since both Turkish and English are written from left to right). If a user would like not to display this legend, giving positivie value for the X parameter suffices. The third parameter is used to determine the font size of this list.

Similar to the previous list, the color legend is displayed at the bottom of the image. It is displayed as small color boxes and labels attributing them. Setting the colors to be used and the associated texts are discussed in Thematic Settings section. The first three parameters for color legend are exacly same as the three parameters of the previous list. The only difference being the origin of the displacement is the lower left corner of the image this time. Thus the Y value must be lower than zero in order the color legend to be drawn. If a user would like not to display the color legend, giving positive value for the Y parameter suffices. The third one is used to determine the font size of the associated text’s font.

The forth Color Box Size parameter is used to determine the size of the color boxes to be drawn. Each box is a square so providing a single numeric value suffices.

The fifth Extra Space Around Boxes parameter is used to put extra spaces around the color boxes and their associated texts. It enables to display them more discreetly.

Although listed under the Legend Settings, the last two parameters are irrevelant of the legends.

The Label Font Size parameter is used to determine the font size of the labels displayed on the shapes.

Scale Factor Parameter

The last parameter, Scale Factor is a different kind of parameter.

Without this parameters, the shapes are always drawn as big as they are generated. When the base image used has a high resolution, the output images becomes big as well. Similary, having very small shapes yields images with irelevantly large legends.

With Scale Factor parameter, the user can enlarge or diminish the size of the shapes to be drawn. With the default value of 1, the shapes would be drawn as big as they were generated. With a Scale Factor of 2, they would be drawn twice as big as they are. With a Scale Factor of 0.25, they would be drawn quarter the size they are.


Notice: Any changes to either thematic or image settings can be effective if and only if Save Settings button is pressed after doing the necessary changes.

Previewing and Downlading the Results

The Preview button is below the area where the excel file is dropped. When clicked, if the necessary data is provided (the excel file and at least one shape) a pop-up window appears where the first resulting image to be downloaded is displayed. This is the only way to see the effects of the changes made in the settings area. There is a Save button at the footer of the Preview Popup  Dialog. When the final form of the images to be generated is reached, clicking this button initiates the downloads of all the resulting images.

Save / Load

Mahalle Boyamaca is an html/js application that has no server-side at all. All code runs on the client browser and any data produced is again in client side. If the application page is refreshed or closed, the data produced and the setting determined are lost. It may be the case that a project in Mahalle Boyamaca would not be finished in one go. The Save / Load panel exists to overcome such problems.

The Save / Load panel at the bottom of the secreen has nothing to do with downloading the final image files. It contains two button Save and Load. When Save button is clicked, the download of a file (setting.json) is initiated. This file contains all the information necessary to come to the state when the Save button is clicked. Clicking Load button, on the other hand, opens a dialog to select a file in the file system. Selecting a file downloaded by clicking the Save button is the way to get back to the state when the Save button is clicked.

Save / Load can be used to save the state of the project in order to continue later.It can also be used to share the project among different users. Sending the downloaded setting file and the excel file that contains thematic values to another party suffices. This information sharing can be carried out with e-mails or by other means. Mahalle Boyamaca has no feature to do that.

Making Your Static HMTL/Js Application Multilingual with i18next

i18next is a very rich ecosystem, has lots of options/possibilities for internalization/localization. This article will cover just a little portion of its capabilities that were enough to make Mahalle Boyamaca multilingual.

Mahalle Boyamaca is a static hmtl/js application with which one can generate thematic maps. If it were a server-side coded application, internalization would have been fairly easier. I had the chance to try GetText for such a task, I remember coming accross others, too.

For Mahalle Boyamaca, there were two types of text that needed to be multilingual; static text in html and text that is displayed on some conditions which resides in javascript code.

It is stated that it would be possible to use i18next without jquery, but since MahalleBoyamaca uses jquery, i did not bother with how it would be done. The first thing to do is to include the scripts;

Then we need to initialize i18next. A possible place would be the begining of jquery document ready;



The initialization code is mostly self explanatory. The only part that needs further explation is the resources part. The structure and some of the content of rsc object is as below:

Clearly one can add more than 2 languages in the resources. Moreover the content of every language does not need to be loaded to the client, the resources for each language can be kept in the server as a seperate file and loaded when necessary- i18next has that capability- but it is outside the scope of this article. Since there were just 2 languages that Mahalle Boyamaca need to support and there are just 29 expressions that are to be translated, the resources of Mahalle Boyamaca is kept in the js file.

After determining what to be translated and included in the resource object (or file if need be), the next and only thing to do is to mark the items that are going to be affected.

For static html tags, adding the attribute data-i18n with the key defined in the resource section is required:

translates into

Drag and drop the base image to the box below

For items where the value attribute is needed to be set, the format i18next uses is:

translates into

This format can be used to set any attribute value necessary.

For the js part, the translation function is called explicitly:

For items that require a parametrized structure, in the resource section, the part that is to be parametrized is written within two curly braces:

and the translation function is called with the parameter object:

This sums up pretty much everything required to make Mahalle Boyamaca multilingual.

Later on, it is decided that it would be better if the user can change the language. The language flags are added to the top right corner of the page. When clicked, the same page is called with the get parameter ‘lang’ set to either of the language values; ‘en’ or ‘tr’ : URL?lang=en.

Then the initialization part of i18next is changed so as to make use of the parameter provided if there is any:


Making Thematic Maps with Mahalle Boyamaca

Mahalle Boyamaca is out on the stage.

It is a very simple application trying to solve a simple problem; making thematic maps.

There are a couple of very popular applications like ArcGIS, NetCAD to do this task. Mahalle Boyamaca has capabilities nowhere near of those, yet it is here. So, why? Why develop something that at best imitates the functionalities of those big applications?

  • Most valuable aspect of it is, one may argue, Mahalle Boyamaca is free, as in speech. Source code can be reached easily, although not found worthed to be shared on GitHub or alike.
  • It is a web application obviously, you do not need to find an installable. As long as dottilde survives, Mahalle Boyamaca will be here.
  • Its development was fairly easy. More than development it was a craftsmenship experience, putting bits and pieces together. The developer found it amusing to utilize the wonderfully crafted libraries, such as:


  1. Bootstrap CSS
  2. Bootstrap Colorpicker
  3. XlsJs
  4. BootboxJs
  5. Jquery.Noty

Kudos to those who have contributed to these lovely libraries.

  • Mahalle Boyamaca currently has no server-side code running at all. All content/code is downloaded to the client as soon as the application page loads. With the development tools of a browser, all source code can be obtained.  Having no server side code also means you should not refresh the page if you are in the middle of a work. Some sort of state saving is implemented but again in client side.
  • Even if noone else is going to use it, the developer knows at least one person is going to, it was crafted for a fellow company.
  • The developer had liked to experiment with the capabilities of HTML 5 canvas element.

One of the core requirements of this application is to be able to pan and zoom in/out of images displayed on an HTML Canvas.

Fortunately, there were others who have dealt with the same problem before. I would like to thank @S2am for bringing this question to the spotlight and @Phrogz for answering it throughly (If I could vote more, I would have voted hundreds). His answer was the basis of this core functionality of Mahalle Boyamaca.

In other articles, an informal user guide is going to be presented, some rant about making a static html/js application multilingual is going to be made.