====== Visual Placements ======

With the visual placements, respondents can mark positions on an image (e.g., on a map or on a figure) or place elements on an image.

**Background image:** First, upload the image on which positions can be marked or elements can be placed to the survey project ([[:en:create:media|Media Files in the Questionnaire]]). After that, you can select it as //Image (URL)// in the question of the type //Visual Placements//. When saving, SoSci Survey usually enters the //Image size// correctly.

===== Option 1: Marking Positions =====

If the respondents shall mark positions on the image, click //Add Symbol// in the navigation on the left. As //Symbol (image)//, select the marker that shall be used here. You can specify how many of these markers the respondents have to place in the image at least, and how many are allowed at most.

Also enter a //Description// for the kind of marker. It may be displayed to the respondents, for example, if different symbols are used or if you explicitly enable the legend.

**Note:** The marker is scaled relative to the background image. If the background image is very large (the image size in pixels is what matters here), the markers are displayed very small. Whether a //Legend// is displayed can be set in the tab //Markers//.

Optionally, you can //add further symbols//. This is useful if the respondents shall place different markers in the image, for example, positive and negative peculiarities.

===== Option 2: Placing Elements =====

If the respondents shall place different elements in the image, first upload images of these elements to the survey project ([[:en:create:media|Media Files in the Questionnaire]]).

Then use //Add Symbol// (in the navigation on the left) to create a symbol for each element. In each symbol, select the respective element as //Symbol (image)//. You may want to use //Min. number of markers// and //Max. number of markers// to specify that the element may be placed on the background image exactly once.

===== Defining Regions =====

By default, the respondents can place the symbols or elements anywhere in the image. In the tab //Regions//, you can define...

  * where the symbols may be placed or
  * for which regions SoSci Survey shall count the number of marked positions/placed elements.

Each region requires a //Description of the region// (which is displayed in the variable label and in the accessible display mode) and a //Region definition//. The definition comprises the shape (circle "circle", rectangle "rect", polygon "poly") and the pixel coordinates (top left = 0,0). The explanation directly in the form describes how exactly to specify this.

To define polygons, you can simply click in the preview of the background image at //Image and Regions// and thereby draw a shape. An input field "poly ..." is then displayed below the image. Copy this content into the field for the //Region definition//.

**Tip:** Define a region with the //definition// ''all'' as the last (or only) region, if you would like to allow markers anywhere in the image regardless of the other regions.


===== Data =====

The question type "Visual Placements" stores raw data and count data.

The raw data is a space-separated list stating at which position (pixels, measured from top left = 0,0) which symbol was placed. This may look as follows, for example:

    54,48,1 139,51,1 141,147,2

Here, symbol 1 was placed at the X-Y positions 54,48 and 139,51, and symbol 2 was placed at the X-Y position 141,147. In each case, the center of the placed symbol is given.

Another variable states which predefined regions each of these symbols falls into. For example

    2 1 1

Here, the first symbol was placed in the predefined region 2. The other two markers were placed in region 1.

Further variables contain the number of markers per region.


===== JavaScript =====

==== Reacting to Placing and Removing Markers ====

The HTML element of the question triggers a "change" event when a new marker is placed, or an existing marker is moved or removed. The following JavaScript code displays the events of the visual placements question ''GP01'' in the browser console by means of ''console.log()''.

<code javascript>
window.addEventListener("load", function() {
  s2.GP01.addEventListener("change", console.log);
});
</code>

The change event contains the following information in the property ''detail'':

  * ''%%"change"%%'' (string) -- The kind of change
    * ''%%"add"%%'' -- A marker was placed
    * ''%%"move"%%'' -- A marker was moved
    * ''%%"remove"%%'' -- A marker was deleted
  * ''%%"x"%%'' (int) -- The X coordinate of the marker (center), measured from the left
  * ''%%"y"%%'' (int) -- The Y coordinate of the marker (center), measured from the top
  * ''%%"symbol"%%'' (int) -- The number of the symbol (only relevant if multiple symbols were defined in the question)
  * ''%%"area"%%'' (int) -- The number of the region in which the marker is located (after moving, if applicable)
  * ''%%"markerID"%%'' (int) -- A unique number for the marker
  * ''%%"question"%%'' (string) -- The ID of the question
  * ''%%"markerIndex"%%'' (int) -- The index of the marker (changes if previous markers are removed)
  * ''%%"markerType"%%'' (int) -- Like ''%%"symbol"%%'' but shifted by -1 (counting from 0)


==== Restricting the Placement ====

The event ''"position"'' allows you to restrict the position of a marker. For this purpose, the called function can return an object with modified properties for ''x'' and ''y''.

The following JavaScript code would restrict the placement of markers to a horizontal line. This makes the visual placements work like a scale that allows multiple markers (multiple choice).

<code javascript>
window.addEventListener("load", function() {
  s2.GP01.addEventListener("position", function(pos) {
      pos.y = 50;
      return pos;
  });
});
</code>

With the following JavaScript code, only multiples of 30 pixels are possible as positions on a line.

<code javascript>
window.addEventListener("load", function() {
  s2.GP01.addEventListener("position", function(pos) {
      pos.y = 50;
      pos.x = Math.round(pos.x / 30) * 30;
      return pos;
  });
});
</code>


==== Reset Button ====

You can offer the respondents a button to remove all markers at once. If a text is specified in the method ''clear()'', this text is displayed along with the options "OK" and "Cancel".

<code html>
<div style="text-align: center; margin: 2em 0;">
    <button type="button" id="dropButton">Start all over again</button>
    <script>
    document.getElementById("dropButton").addEventListener("click", function() {
        s2.GP01.clear("Are you sure?");
    });
    </script>
</div>
</code>

''GP01'' must be replaced by the ID of the visual placements question here.