Re-use Elements

use

The use element allows reusing elements into the SVG. There are specific configuration calling methods .x(), .y(), .width(), .height(), etc. The .href() method enables the reference on the element to be reused.

How the reference must be absolutely unique into the browser DOM and can have a collision between two or more SVG included on the same page, Graphery SVG provides an internal not duplicated id for each element. This unique identification can be access with the methods .id() (return the id) and .ref() (return # and the id concatenated).

In this example, we have defined only one circle and nine use referenced to the first circle. Each use has a .x() than translate the used element. When the circle changes, all use change because those are linked.

<div id="example1"></div>
<button id="example1button">change color</button>
<script type="module">
  import gySVG from 'https://cdn.graphery.online/svg/1.0.0/module/index.js';

  const svg = gySVG().viewBox(0, 0, 100, 20).width(100).height(20);
  const dot = svg.add('circle').cx(5).cy(10).r(4).fill('red');
  for(let column = 10; column < 100; column += 10) {
    svg.add('use').href(dot.ref()).x(column);
  }
  svg.attachTo('#example1');

  document.querySelector('#example1button').addEventListener('click',() => {
    dot.fill(dot.fill() === 'red' ? 'blue' : 'red');
  });
</script>

<svg viewBox="0,0,100,20" width="100" height="20">
  <circle id="gySVGObjectpchlqkop388" cx="5" cy="10" r="4" fill="red"></circle>
  <use href="#gySVGObjectpchlqkop388" x="10"></use>
  <use href="#gySVGObjectpchlqkop388" x="20"></use>
  <use href="#gySVGObjectpchlqkop388" x="30"></use>
  <use href="#gySVGObjectpchlqkop388" x="40"></use>
  <use href="#gySVGObjectpchlqkop388" x="50"></use>
  <use href="#gySVGObjectpchlqkop388" x="60"></use>
  <use href="#gySVGObjectpchlqkop388" x="70"></use>
  <use href="#gySVGObjectpchlqkop388" x="80"></use>
  <use href="#gySVGObjectpchlqkop388" x="90"></use>
</svg>

defs

If you want to define an element, but don't need to show it directly, you can use "defs" as a group of elements that have not been rendered in the SVG. It constitutes a group of non-visible definitions useful for use in other sites.

We can change the previous example and put the initial circle into the defs element.

<div id="example2"></div>
<script type="module">
  import gySVG from 'https://cdn.graphery.online/svg/1.0.0/module/index.js';

  const svg  = gySVG().viewBox(0, 0, 100, 20).width(100).height(20);
  const defs = svg.add('defs');
  const dot  = defs.add('circle').cx(5).cy(10).r(4).fill('red');
  for(let column = 0; column < 100; column += 10) {
    svg.add('use').href(dot.ref()).x(column);
  }
  svg.attachTo('#example2');
</script>

<svg viewBox="0,0,100,20" width="100" height="20">
  <defs>
    <circle cx="5" cy="10" r="4" fill="blue" id="gySVGObjecto2ddnuh2718"></circle>
  </defs>
  <use href="#gySVGObjecto2ddnuh2718" x="0"></use>
  <use href="#gySVGObjecto2ddnuh2718" x="10"></use>
  <use href="#gySVGObjecto2ddnuh2718" x="20"></use>
  <use href="#gySVGObjecto2ddnuh2718" x="30"></use>
  <use href="#gySVGObjecto2ddnuh2718" x="40"></use>
  <use href="#gySVGObjecto2ddnuh2718" x="50"></use>
  <use href="#gySVGObjecto2ddnuh2718" x="60"></use>
  <use href="#gySVGObjecto2ddnuh2718" x="70"></use>
  <use href="#gySVGObjecto2ddnuh2718" x="80"></use>
  <use href="#gySVGObjecto2ddnuh2718" x="90"></use>
</svg>

symbol

If you want to reuse a group of shapes, you can group them into a symbol element. It's very similar to a g, but is not rendered directly and needs a use element to show its content. The symbol are usually created within defs, have own .viewBox() bound reference, and its size is defined by .width() and .height(). Additionally, you can define the symbol's point as a reference for positioning with .refX() and .refY().

<div id="example4"></div>
<script type="module">
  import gySVG from 'https://cdn.graphery.online/svg/1.0.0/module/index.js';

  const svg    = gySVG().viewBox(0, 0, 100, 20).width(100).height(20);
  const symbol = svg.add('defs').add('symbol').viewBox(0, 0, 10, 10).width(10).height(10);
  const dot    = symbol.add('circle').cx(5).cy(5).r(5).fill('red');
  symbol.add('line').x1(0).y1(5).x2(10).y2(5).stroke('blue').stroke_width(2);
  symbol.add('line').x1(5).y1(0).x2(5).y2(10).stroke('blue').stroke_width(2);
  for(let column = 0; column < 100; column += 20) {
    svg.add('use').href(symbol.ref()).x(column).y(10);
  }
  svg.attachTo('#example4');
</script>

<svg viewBox="0,0,100,20" width="100" height="20">
  <defs>
    <symbol viewBox="0,0,10,10" width="10" height="10" id="gySVGObjectbkqjmu4hieg">
      <circle cx="5" cy="5" r="5" fill="red"></circle>
      <line x1="0" y1="5" x2="10" y2="5" stroke="blue" stroke-width="2"></line>
      <line x1="5" y1="0" x2="5" y2="10" stroke="blue" stroke-width="2"></line>
    </symbol>
  </defs>
  <use href="#gySVGObjectbkqjmu4hieg" x="0" y="10"></use>
  <use href="#gySVGObjectbkqjmu4hieg" x="20" y="10"></use>
  <use href="#gySVGObjectbkqjmu4hieg" x="40" y="10"></use>
  <use href="#gySVGObjectbkqjmu4hieg" x="60" y="10"></use>
  <use href="#gySVGObjectbkqjmu4hieg" x="80" y="10"></use>
</svg>

marker

The elements path, line, polyline, and polygon accept markers at the beginning, at the end, and vertices. These markers are commonly used to easily include dots, arrows, and other graphic elements on the shapes.

The markers are usually created within defs, although they are not visualized by themselves. They have their own .viewBox(), and their size is defined by .markerWidth() and .markerHeight(). It is also possible to define with .refX(), and .refY() the marker's point will be used as a reference for positioning into shape's points.

Finally, the .orient() method indicates how a marker is rotated when it is placed at its position on the shape. It can be 'auto', 'auto-start-reverse', and an angle value.

You can define the markets into a path with the methods .marker_mid(), .marker_start (), and .marker_end(). All these methods receive the structure url(#id) with the unique id defines on the marker.

<div id="example3"></div>
<script type="module">
  import gySVG from 'https://cdn.graphery.online/svg/1.0.0/module/index.js';

  const svg  = gySVG().viewBox(0, 0, 110, 110).width(100).height(100);
  const defs = svg.add('defs');
  const dot  = defs.add('marker').viewBox(0, 0, 10, 10).refX(5).refY(5)
      .markerWidth(8).markerHeight(8);
  dot.add('circle').cx(5).cy(5).r(5).fill('red');

  const square = defs.add('marker').viewBox(0, 0, 10, 10).refX(5).refY(5)
      .markerWidth(10).markerHeight(10);
  square.add('rect').x(0).y(0).width(10).height(10).fill('red');

  const arrow = defs.add('marker').viewBox(0, 0, 10, 10).refX(5).refY(5)
      .markerWidth(10).markerHeight(10).orient('auto-start-reverse');
  arrow.add('path').fill('red').d.M(0, 0).L(10, 5).L(0, 10).z();

  svg.add('polyline')
      .points([[5, 30], [25, 60], [45, 25], [65, 90], [85, 50], [105, 80]])
      .stroke('black').fill('none')
      .marker_mid(dot.url()).marker_start(square.url()).marker_end(arrow.url());

  svg.attachTo('#example3');

</script>

<svg viewBox="0,0,110,110" width="100" height="100">
  <defs>
    <marker viewBox="0,0,10,10" refX="5" refY="5" markerWidth="8" markerHeight="8"
            id="gySVGObjectnfjbsoa5gm8">
      <circle cx="5" cy="5" r="5" fill="red"></circle>
    </marker>
    <marker viewBox="0,0,10,10" refX="5" refY="5" markerWidth="10" markerHeight="10"
            id="gySVGObjectdbib2st4eo8">
      <rect x="0" y="0" width="10" height="10" fill="red"></rect>
    </marker>
    <marker viewBox="0,0,10,10" refX="5" refY="5" markerWidth="10" markerHeight="10"
            orient="auto-start-reverse" id="gySVGObjectpmfike9qjdg">
      <path fill="red" d="M0,0L10,5L0,10z"></path>
    </marker>
  </defs>
  <polyline points="5,30,25,60,45,25,65,90,85,50,105,80" stroke="black" fill="none"
            marker-mid="url(#gySVGObjectnfjbsoa5gm8)" 
            marker-start="url(#gySVGObjectdbib2st4eo8)"
            marker-end="url(#gySVGObjectpmfike9qjdg)"></polyline>
</svg>

gySVG provides an internal not duplicated id for each element, and you can get this with .url(). It returns url(#id). This method simplifies using the unique id when it is necessary to include the url() pseudo-function.