Units for Wordpress

Give users control over their measurements.

Save your data once and display it in multiple units on-the-fly. All instances of the selected unit are instantly updated and saved.

Download

Try it Out*

*Selections are saved – try refreshing your page after changing a unit.

Download

Convert Any Type of Unit

Add and edit new units of measurements at any time

Using Units

Units is a WordPress plugin designed for theme developers. Its primary function is to provide front-end users with a quick way to customize their preferred units of measurement, while storing only one value in the database.


Requirements

Units requires PHP version 5.3.2 or above, and WordPress version 3.8 or above. The plugin will not install on setups that do not meet the minimum requirements.


 Installation

  1. Upload the units directory to the wp-content/plugins/ directory
  2. Activate the plugin through the Plugins menu in WordPress
  3. Visit the plugin settings to add units of measurement
  4. Use the unit_switcher() template function or shortcode to display the switcher

Adding Units

Any number of units may be added under Settings > Units.

Primary vs Alternate Units

The primary unit is the “parent”, and the unit that database values should be stored in. To add a primary unit, click the “+” button to the far right of the unit box. Alternate units will be available choices to convert from the primary unit. All fields are required when adding primary and alternate units: the unit name (plural), the unit singular name, and conversion formula.

Conversion Formulas

To add a conversion formula, substitute the primary unit with an uppercase “X” to equal the alternate unit. Do not include any spaces, and group equations together using parenthesis. The following functions may be used in formulas:

*, +, -, /, sinh, cosh, tanh, abs, acosh, asinh, atanh, exp, log10, deg2rad, rad2deg, sqrt, ceil, floor, round, π, pi

As an example, if the primary unit is set in feet, and an alternate unit of inches is added, the formula would be saved as X*12.

Unit Settings

Add as many units/alternate units as needed.


Template Usage

To display the unit dropdown within a theme file, you may do so using a function call. The function and its available parameters are outlined below.

the_unit_switcher($value, $primary_unit, $round);
  • $value
    (string) (required) The stored unit value. Numbers should be stored in the primary unit value.
  • $primary_unit
    (string) (required) The primary unit the value is stored as.
  • $round
    (int) (optional) Number of decimal places to round the numbers to.
    default 2

An alternate function is available for retrieving the dropdown as a variable:

get_unit_switcher($value, $primary_unit, $round);

Usage Example

In the following example, we’ll use a length stored using an advanced custom field with a value of 12 and field name as ‘length’. In our case, the primary unit is feet.

unit_switcher( get_field('length'), 'feet', 2 );

In our case, we have the following alternate units listed under Settings > Unit Switcher: inches, centimeters, yards, & miles. The following dropdown will display:

Shortcode

The following shortcode is available:

[unit_switcher value="" unit="" round=""]

Additional Options

Save User Selection

Options include none, session, & cookie. Defaults to none.

Display Options

The plugin CSS and Javascript may be disabled if desired. Please note, the scripts are required for the plugin to function. If you are combining and minifying your theme scripts, it may be helpful to disable the plugin scripts. The css and scripts are available to copy and paste if disabled.

The plugin uses the Bootstrap Dropdown jQuery plugin for dropdown functionality. If you are already using this plugin in your theme, you may omit this.

Unit Switcher for WordPress General Settings

Optionally save user selections using sessions or cookies to give users a consistent experience


FAQ

Does this plugin work with WPML?
Not currently. There are plans to add WPML compatibility.

How can I contribute?
If you are a polygot and would like to include a translation, submit a pull request in the Github project or send a message in the support form below.

 

Crafted with pride in WordPress