Overview

Battery Gauge is a customizable Mendix widget for displaying battery levels, charging status, and other values as a battery-shaped indicator. Use it in device monitoring dashboards, IoT applications, and equipment status pages.

Configure the current value and maximum capacity to represent your data. Choose a horizontal or vertical orientation, then adjust the size, padding, and aspect ratio to suit your page layout. Optional animation and charging effects make changes easier to recognize.

Key features

• Display a value relative to a configurable maximum.
• Choose horizontal or vertical orientation.
• Adjust size, padding, and aspect ratio.
• Enable animation and charging effects.
• Bind widget properties to Mendix data.

Documentation

Battery Gauge

Typical usage scenario

Battery Gauge is a pluggable widget for Mendix web apps, built on react-battery-gauge. It displays a value relative to a maximum as a battery-shaped indicator. Bind the widget to attributes of a Mendix object to control its value, orientation, dimensions, animation and charging state without writing custom JavaScript.

Use it for:

- IoT dashboards that show battery levels received from connected devices.

- Equipment and asset pages that display remaining battery capacity.

- Electric vehicle or energy monitoring applications that already collect charging data.

- Status dashboards where a battery indicator helps users recognize remaining capacity.

The widget displays the data supplied by your app. It does not connect to devices, read the browser's battery status or retrieve live measurements. Implement those integrations and refresh behavior in your Mendix application.

Features and limitations

Features

- Current value and maximum value bound to Integer attributes.

- Horizontal and vertical orientation, with the indicator text kept horizontal.

- Configurable size, padding and aspect ratio through attributes.

- Optional animation on mount.

- Charging animation controlled by a Boolean attribute, with a configurable starting value.

- Configuration through the General property group in Studio Pro.

- SVG rendering through the bundled react-battery-gauge library.

Limitations

- Web pages only; native mobile pages are not supported.

- Requires a context object, normally supplied by a Data View. The widget has no independent data source.

- Value, maximum value and orientation require attribute bindings. The other bindings are optional, although binding chargingStartValue to an initialized Integer is recommended because of the issue described below.

- This is a display widget. It does not edit attributes, commit objects, trigger click actions, send alerts or poll for new data.

- Current and maximum values use Integer attributes; Decimal bindings are only available for aspectRatio.

- No dedicated properties for colors, threshold bands, icons or custom labels are exposed in this release.

- The page editor preview does not draw the gauge. Run the app to inspect its appearance.

- Version 1.0.1 has been checked with Studio Pro 10.24.17. Compatibility with other Mendix versions is not established by this release.

Dependencies

- Mendix Studio Pro 10.24.17 is the tested version for widget release 1.0.1.

- A Mendix entity and context object containing the configured attributes.

- react-battery-gauge is included in the widget package. App developers do not need to install it separately or run npm to use the MPK.

- No additional Marketplace module is required by the widget itself.

- The separate example page uses the Atlas_Core.Atlas_Default layout. The example module is not bundled in the widget MPK.

Installation

1. Download the widget from the Marketplace or the [1.0.1 GitHub release](https://github.com/bharathidas/Battery-Gauge/releases/tag/Version1.0.1).

2. Place mendix.BatteryGauge.mpk in your app's widgets folder if installing manually. When upgrading, replace the existing package instead of retaining a second package with the same widget ID.

3. In Studio Pro, choose App > Synchronize App Directory. Update existing widget instances if Studio Pro requests it.

4. Add a Data View to a web page and configure it to supply an object.

5. Place Battery Gauge inside the Data View and configure its attributes as described below.

6. Check the app for errors, run it and open the page to verify the gauge.

Configuration

1. Create an entity, for example BatteryStatus. A non-persistable entity is suitable for demonstration data; use your application's existing entity or integration model for real measurements.

2. Create the attributes in the following table. Attribute names are examples; bind your own attributes to the corresponding widget properties.

3. Supply an initialized object to the Data View. For a demonstration, use a microflow that creates the object, sets these values and returns it.

4. Open the widget properties. In General, bind value, max value and orientation to their attributes. Bind the optional properties you want to control. Explicitly bind chargingStartValue to an Integer initialized to 0.

5. Set Orientation to exactly horizontal or vertical. Only the exact value vertical selects the vertical layout; other values use horizontal.

6. Keep MaxValue greater than zero and Value between zero and MaxValue. Validate those constraints in the application rather than relying on the widget to reject invalid data.

7. Set positive Size and AspectRatio values. Size defaults to 300, aspectRatio to 0.52 and padding to 5 when usable values are not supplied. In this release, padding must be positive to override its default.

8. Set Animated to true to enable animation on mount. Set Charging to true to enable charging mode and provide a valid ChargingStartValue within the intended range.

9. Run the app. Test horizontal and vertical orientations, zero and maximum values, and charging on and off. Refresh the context object through your app when new measurements arrive.

Example: Value = 75 and MaxValue = 100 represents 75% capacity. Value = 27 and MaxValue = 90 represents 30% capacity.

Known bugs

None

Report issues at https://github.com/bharathidas/Battery-Gauge/issues

Frequently Asked Questions

Q: Does the widget automatically read a device's battery level?

A: No. Retrieve the measurement through your application or integration and provide it in the bound Value attribute.

Q: Does the maximum value have to be 100?

A: No. Use a positive maximum appropriate to your data. For example, a value of 27 with a maximum of 90 represents 30% capacity.

Q: How do I display the battery vertically?

A: Set the bound orientation String attribute to vertical. Use horizontal for a horizontal battery.

Q: Can users change the battery value through the gauge?

A: No. Use a separate input widget or application logic to update the bound attribute.

Q: Why does the widget not appear in the page editor?

A: This release does not draw the gauge in the Studio Pro preview. Configure the context and bindings, then run the app to see it.

Q: Why is charging not behaving as expected?

A: Check that Charging is true, MaxValue is positive and ChargingStartValue is bound and initialized. Do not leave the charging starting value empty.

Q: Can I remove all padding?

A: Not through a zero padding value in release 1.0.1. The wrapper treats zero as a request to use the default padding of 5.

Q: Can I change colors or add threshold alerts from widget properties?

A: This release does not expose those properties or events. Implement alerts in your application's logic.