Gauge

Gauge Layout
Gauge App Methods
Gauge Parameters
Gauge Methods & Properties
Gauge Events

DOM Events
App and Gauge Instance Events

Gauge Auto Initialization
Examples

Framework7 comes with Gauge component. It produces nice looking fully responsive SVG gauges.

Gauge Layout

Because Gauge SVG is generated by JavaScript its HTML layout is as simple as possible:

<!-- Gauge element -->
<div class="gauge"></div>

Gauge App Methods

Now we need to create/initialize the Gauge. Let's look at related App methods to work with Gauge:

app.gauge.create(parameters)- create Gauge instance

parameters - object. Object with gauge parameters

Method returns created Gauge's instance

app.gauge.destroy(el)- destroy Gauge instance

el - HTMLElement or string (with CSS Selector) or object. Gauge element or Gauge instance to destroy.

app.gauge.get(el)- get Gauge instance by HTML element

el - HTMLElement or string (with CSS Selector). Gauge element.

Method returns Gauge's instance

app.gauge.update(parameters)- update/rerender Gauge SVG according to passed parameters

parameters - object. Object with gauge parameters

Method returns gauge value

Gauge Parameters

Now let's look at list of available parameters we need to create Gauge:

Parameter	Type	Default	Description
el	HTMLElement string		Gauge element. HTMLElement or string with CSS selector of gauge element. Generated SVG will be inserted into this element
type	string	circle	Gauge type. Can be `circle` or `semicircle`
value	number	0	Gauge value/percentage. Must be a number between `0` and `1`
size	number	200	Generated SVG image size (in px)
bgColor	string	transparent	Gauge background color. Can be any valid color string, e.g. `#ff00ff`, `rgb(0,0,255)`, etc.
borderBgColor	string	#eeeeee	Main border/stroke background color
borderColor	string	#000000	Main border/stroke color
borderWidth	string	10	Main border/stroke width
valueText	string	null	Gauge value text (large text in the center of gauge)
valueTextColor	string	#000000	Value text color
valueFontSize	string	31	Value text font size
valueFontWeight	string	500	Value text font weight
labelText	string	null	Gauge additional label text
labelTextColor	string	#888888	Label text color
labelFontSize	string	14	Label text font size
labelFontWeight	string	400	Label text font weight
on	object		Object with events handlers. For example: `var gauge = app.gauge.create({ el: '.gauge', value: 33, valueText: '33%', on: { beforeDestroy: function () { console.log('Gauge will be destroyed') } } })`

Gauge Methods & Properties

So to create Gauge we have to call:

var gauge = app.gauge.create({ /* parameters */ })

After that we have its initialized instance (like gauge variable in example above) with useful methods and properties:

Properties
gauge.app	Link to global app instance
gauge.el	Gauge HTML element
gauge.$el	Dom7 instance with gauge HTML element
gauge.svgEl	Gauge generated SVG HTML element
gauge.$svgEl	Dom7 instance with generated SVG HTML element
gauge.params	Gauge parameters
Methods
gauge.update(parameters)	Update/rerender gauge SVG element according to passed parameters. It accepts object with same parameters required for gauge initialization. You can pass only parameters that needs to be updated, e.g. `var gauge = app.gauge.create({ value: 0.5, // ... }); // and when we need to update rendered SVG based on new value: gauge.update({ value: 0.6, });`
gauge.destroy()	Destroys gauge instance
gauge.on(event, handler)	Add event handler
gauge.once(event, handler)	Add event handler that will be removed after it was fired
gauge.off(event, handler)	Remove event handler
gauge.off(event)	Remove all handlers for specified event
gauge.emit(event, ...args)	Fire event on instance

Gauge Events

Gauge will fire the following DOM events on gauge element and events on app and gauge instance:

DOM Events

Event	Target	Description
gauge:beforedestroy	Gauge Element<div class="gauge">	Event will be triggered right before Gauge instance will be destroyed

App and Gauge Instance Events

Gauge instance emits events on both self instance and app instance. App instance events has same names prefixed with gauge.

Event	Arguments	Target	Description
beforeDestroy	(gauge)	gauge	Event will be triggered right before Gauge instance will be destroyed. As an argument event handler receives Gauge instance
gaugeBeforeDestroy	(gauge)	app

Gauge Auto Initialization

If you don't need to use Gauge API and your Gauge is inside of the page and presented in DOM on moment of page initialization then it can be auto initialized with just adding additional gauge-init class, and specifying all parameters with data- attributes:

<!-- Add gauge-init class, and specify parameters in data- attributes -->
<div
  class="gauge gauge-init my-gauge"
  data-type="circle"
  data-value="0.44"
  data-value-text="44%"
  data-value-text-color="#ff9800"
  data-border-color="#ff9800"
></div>

In this case if you need to access automatically created Gauge instance you can use the app.gauge.get app method:

var gauge = app.gauge.get('.my-gauge');

gauge.update({
  value: 0.9,
});

Examples

<template>
  <div class="page">
    <div class="navbar">
      <div class="navbar-bg"></div>
      <div class="navbar-inner">
        <div class="title">Gauge</div>
      </div>
    </div>
    <div class="page-content">
      <div class="block block-strong text-align-center">
        <div class="gauge demo-gauge"></div>
        <p class="segmented segmented-raised">
          <a href="#" class="button" data-value="0">0%</a>
          <a href="#" class="button" data-value="25">25%</a>
          <a href="#" class="button" data-value="50">50%</a>
          <a href="#" class="button" data-value="75">75%</a>
          <a href="#" class="button" data-value="100">100%</a>
        </p>
      </div>
      <div class="block-title">Circle Gauges</div>
      <div class="block block-strong">
        <div class="row">
          <div class="col text-align-center">
            <div class="gauge gauge-init"
              data-type="circle"
              data-value="0.44"
              data-value-text="44%"
              data-value-text-color="#ff9800"
              data-border-color="#ff9800"
            ></div>
          </div>
          <div class="col text-align-center">
            <div class="gauge gauge-init"
              data-type="circle"
              data-value="0.12"
              data-value-text="$120"
              data-value-text-color="#4caf50"
              data-border-color="#4caf50"
              data-label-text="of $1000 budget"
              data-label-text-color="#f44336"
              data-label-font-weight="700"
            ></div>
          </div>
        </div>
      </div>
      <div class="block-title">Semicircle Gauges</div>
      <div class="block block-strong">
        <div class="row">
          <div class="col text-align-center">
            <div class="gauge gauge-init"
              data-type="semicircle"
              data-value="0.3"
              data-value-text="30%"
              data-value-text-color="#f44336"
            ></div>
          </div>
          <div class="col text-align-center">
            <div class="gauge gauge-init"
              data-type="semicircle"
              data-value="0.5"
              data-value-text="30kg"
              data-value-text-color="#e91e63"
              data-border-color="#e91e63"
              data-label-text="of 60kg total"
            ></div>
          </div>
        </div>
      </div>
      <div class="block-title">Customization</div>
      <div class="block block-strong">
        <div class="row">
          <div class="col text-align-center">
            <div class="gauge gauge-init"
              data-type="circle"
              data-value="0.35"
              data-value-text="35%"
              data-value-text-color="#4caf50"
              data-value-font-size="51"
              data-value-font-weight="700"
              data-border-width="20"
              data-border-color="#4caf50"
              data-border-bg-color="#ffeb3b"
            ></div>
          </div>
          <div class="col text-align-center">
            <div class="gauge gauge-init"
              data-type="circle"
              data-value="0.67"
              data-value-text="$670"
              data-value-text-color="#000"
              data-border-color="#ff9800"
              data-label-text="of $1000 spent"
              data-label-text-color="#4caf50"
              data-label-font-weight="800"
              data-label-font-size="12"
              data-border-width="30"
            ></div>
          </div>
        </div>
        <br />
        <div class="row">
          <div class="col text-align-center">
            <div class="gauge gauge-init"
              data-type="semicircle"
              data-value="0.5"
              data-value-text="50%"
              data-value-text-color="#ffeb3b"
              data-value-font-size="41"
              data-value-font-weight="700"
              data-border-width="10"
              data-border-color="#ffeb3b"
            ></div>
          </div>
          <div class="col text-align-center">
            <div class="gauge gauge-init"
              data-type="semicircle"
              data-value="0.77"
              data-border-color="#ff9800"
              data-label-text="$770 spent so far"
              data-label-text-color="#ff9800"
              data-label-font-weight="800"
              data-label-font-size="12"
            ></div>
          </div>
        </div>
      </div>
    </div>
  </div>
</template>
<script>
  export default (props, { $, $f7, $on }) => {
    $on('pageInit', () => {
      // Init top demo gauge
      var demoGauge = $f7.gauge.create({
        el: '.demo-gauge',
        type: 'circle',
        value: 0.5,
        size: 250,
        borderColor: '#2196f3',
        borderWidth: 10,
        valueText: '50%',
        valueFontSize: 41,
        valueTextColor: '#2196f3',
        labelText: 'amount of something',
      });

      // Change demo gauge on button click
      $('.button').on('click', function () {
        var value = $(this).attr('data-value');
        demoGauge.update({
          value: value / 100,
          valueText: value + '%'
        });
      });
    })
    return $render;
  }
</script>