View source for Extension:Graph/Interactive Graph Tutorial/de

<languages />
__NOTOC__
{{outdated}}
<span lang="en" dir="ltr" class="mw-content-ltr">In this tutorial we will create an interactive graph that will display historical fertility rates per country, with a slider to pick the year, and a map to show rate distribution around the world.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">If you want to investigate the source code of this graph only, it's [[Special:MyLanguage/Extension:Graph/Demo/HistoricalFertilityRates|available as a separate wiki page]]. Use [[Special:GraphSandbox|Interactive Graph Sandbox]] for experimentations.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">You might also be interested in the [https://github.com/vega/vega/wiki complete Vega documentation].</span>

{{:Extension:Graph/Graph:Historical_Fertility_Rates}}

<span lang="en" dir="ltr" class="mw-content-ltr">Move the slider to change the year, and hover the mouse over countries to read the rate.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Try it !</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Drawing Shapes ==
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">We start with drawing a few elements ([https://github.com/vega/vega/blob/825bfaba6ccfe3306183df22b8c955a07bb30714/docs/docs/marks.md marks]).</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The graph code is surrounded by the <syntaxhighlight lang=html inline><graph mode=interactive>...</graph></syntaxhighlight> tag, even though the graph is not yet interactive.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Open [[Special:GraphSandbox|Interactive Graph Sandbox]] and copy the following code without the &lt;graph> tag to experiment.</span>

<small><span lang="en" dir="ltr" class="mw-content-ltr">Hint: Use "edit source" to copy the graph spec to the [http://vega.github.io/vega-editor/?mode=vega Vega Editor] for experimentation.</span></small>

{|
| {{:Extension:Graph/Interactive Graph Tutorial/1}}
| [[:Extension:Graph/Interactive Graph Tutorial/1|Siehe den Quellcode]]
|}
<syntaxhighlight lang="json">
{
  // We want to use Vega 2, and specify image size
  "version": 2, "width": 300, "height": 80,
  // Set padding to the same value on all sides
  "padding": 12,
  // By default the background is transparent
  "background": "#edf1f7",
  "marks": [
    {
      // Draw a horizontal line
      "name": "scrollLine",
      "type": "rule",
      "properties": {
        "enter": {
          "x": {"value": 0},
          "y": {"value": 40},
          "x2": {"value": 300},
          "stroke": {"value": "#000"},
          "strokeWidth": {"value": 2}
        }
      }
    },
    {
      // Draw a triangle shape with a hover effect
      // naming objects allows us to reference them later
      "name": "handle",
      "type": "path",
      "properties": {
        "enter": {
          "x": {"value": 200},
          "y": {"value": 40},
          // path syntax is the same as SVG's path tag
          "path": {"value": "m-5.5,-10l0,20l11.5,-10l-11.5,-10z"},
          "stroke": {"value": "#880"},
          "strokeWidth": {"value": 2.5}
        },
        "update": {"fill": {"value": "#fff"}},
        // Change fill color of the object on mouse hover
        "hover": {"fill": {"value": "#f00"}}
      }
    }
  ]
}
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
== ''isDragging'' signal ==
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">To make our handle object dragable, we first need to figure out if it was clicked or not.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">For that, lets add a [https://github.com/vega/vega/blob/d0b886881bd27da626b0d33f2db23bd17f6f4277/docs/docs/signals.md signal] that becomes true when an object is clicked (isDragging), and a text mark to show (debug) the result:</span>

{|
| {{:Extension:Graph/Interactive Graph Tutorial/2}}
| [[:Extension:Graph/Interactive Graph Tutorial/2|<span lang="en" dir="ltr" class="mw-content-ltr">see source code</span>]]
|}
<syntaxhighlight lang="json">
"signals": [
  {
    "name": "isDragging",
    "init": false,
    "streams": [
      {"type": "@handle:mousedown","expr": "true"},
      {"type": "mouseup","expr": "false"}
    ]
  },
],

// in "marks"
  {
    "name": "debugIsDragging",
    "type": "text",
    "properties": {
      "enter": {
        "x": {"value": 250},
        "y": {"value": 0},
        "fill": {"value": "black"}
      },
      "update": {"text": {"signal": "isDragging"}}
    }
  }
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
== ''handlePosition'' signal ==
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Now that we know when the object is being dragged, we add a <code>mousemove</code> signal that only changes its value when isDragging signal is true.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">We also attach the new signal to the handle's "x" coordinate via "update" section:</span>

{|
| {{:Extension:Graph/Interactive Graph Tutorial/3}}
| [[:Extension:Graph/Interactive Graph Tutorial/3|<span lang="en" dir="ltr" class="mw-content-ltr">see source code</span>]]
|}
<syntaxhighlight lang="json">
// in "signals"
  {
    "name": "handlePosition",
    "init": 200,
    "streams": [
      {
        "type": "mousemove[isDragging]",
        "expr": "eventX()"
      }
    ]
  }

  // add in "marks"
  {
    "name": "handle",
    ...
    "update": {
      "x": {"signal": "handlePosition"},
      ...
    },
  },
  {
    "name": "debugHandlePosition",
    "type": "text",
    "properties": {
      "enter": {
        "x": {"value": 250},
        "y": {"value": 14},
        "fill": {"value": "black"}
      },
      "update": {"text": {"signal": "handlePosition"}}
    }
  }
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Scaling Handle Position signal ==
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Having pixel position of the handler is not very good - we would much rather have a position that is meaningful to our graph, e.g. a year.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Vega [https://github.com/vega/vega/blob/825bfaba6ccfe3306183df22b8c955a07bb30714/docs/docs/scales.md scales] provide a useful mechanism for converting between our data (e.g. years) and the screen coordinates, and back (invert).</span>
<span lang="en" dir="ltr" class="mw-content-ltr">In this step, we add "yearsScale" linear scale for values 1960..2013, mapping it to the whole width of the graph (excluding padding).</span>
<span lang="en" dir="ltr" class="mw-content-ltr">We also add a new scaledHandlePosition signal that translates from the mouse X position to the meaningful value in years.</span>
 
{|
| {{:Extension:Graph/Interactive Graph Tutorial/4}}
| [[:Extension:Graph/Interactive Graph Tutorial/4|Siehe den Quellcode]]
|}
<syntaxhighlight lang="json">
// add "scales" root value:
  "scales": [
    {
      "name": "yearsScale",
      "type": "linear",
      "zero": false,
      "domain": [1960, 2013],
      "range": "width"
    }
  ],

// in "signals", add:
    {
      "name": "scaledHandlePosition",
      "expr": "handlePosition",
      "scale": {"name": "yearsScale","invert": true}
    }

  // add in "marks"
    {
      "name": "debugScaledHandlePosition",
      "type": "text",
      "properties": {
        "enter": {
          "x": {"value": 250},
          "y": {"value": 28},
          "fill": {"value": "black"}
        },
        "update": {"text": {"signal": "scaledHandlePosition"}}
      }
    }
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Year value cleanup ==
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">As you might have noticed, the handle could be moved beyond the length of our graph, producing incorrect results.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Also, the scaled value is not an integer that we expect of the year value.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">To fix this, we can introduce one more post-processing signal called "currentYear" to convert it to an integer and limit it to the needed range.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">We also initialize it to a reasonable value, and we tie both the "yearLabel" and the position of the handle bar back to this value.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Note that the handle's position needs to be in screen coordinates, so we have to use the "yearsScale" to convert the value back:</span>

{|
| {{:Extension:Graph/Interactive Graph Tutorial/5}}
| [[:Extension:Graph/Interactive Graph Tutorial/5|Siehe den Quellcode]]
|}
<syntaxhighlight lang="json">
    // New signal:
    {
      "name": "currentYear",
      "init": 2000,
      "expr": "clamp(parseInt(scaledHandlePosition),1960,2013)"
    }

    // Update yearLabel mark:
    // New mark to draw the year
    {
      "name": "yearLabel",
      "type": "text",
      "properties": {
        "enter": {
          "x": {"value": 0},
          "y": {"value": 25},
          "fontSize": {"value": 32},
          "fontWeight": {"value": "bold"},
          "fill": {"value": "steelblue"}
        },
        "update": {"text": {"signal": "currentYear"}}
      }
    },

    // Update handle mark:
    {
      "name": "handle",
      "properties": {
        "update": {
          "x": {"scale": "yearsScale","signal": "currentYear"}
        },
      }
    }
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Final cleanup ==
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Now we can remove all the debugging marks.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">We also don't need separate handlePosition and scaledHandlePosition signals because scaling can happen in the same step:</span>

{|
| {{#tag:graph|{{:Extension:Graph/Interactive Graph Tutorial/6/code}}|mode=interactive}}
| [[:Extension:Graph/Interactive Graph Tutorial/6|Siehe den Quellcode]]
|}
{{#tag:syntaxhighlight|{{:Extension:Graph/Interactive Graph Tutorial/6/code}}|lang=json}}

<span id="Next_Step"></span>
== Nächster Schritt ==

<div lang="en" dir="ltr" class="mw-content-ltr">
Please continue to [[Special:MyLanguage/Extension:Graph/Interactive Graph Tutorial 2|part 2]]
</div>

[[Category:Tutorials{{#translation:}}]]
[[Category:Extension:Graph{{#translation:}}]]