An inputfield and fieldtype for the ProcessWire CMS to enter dimensions (length, width and height) of an object and to calculate area and volume automatically.
This fieldtype was inspired by the amazing fieldtype "Fieldtype Dimensions" by SOMA, which was introduced in 2013 but is probably no longer available - so it's time for a relaunch. This new fieldtype comes with some additional features.
- PHP>=8.0.0
- ProcessWire>=3.0.212
This inputfield/fieldtype lets you enter 2 or 3 dimension values (length, width, height) of an object (e.g. a product) and calculates and stores the volume and the area too. All the dimension values including area and volume are fully searchable. A real-life example would be a product page where you want to display the product dimensions.
- Calculates area and volume automatically, and these values are fully searchable too (besides the other dimensions)
- Easy-to-use API for outputting various formats of the dimensions (raw value from the database, value including unit, value including label)
- Less code in templates to output the values
- Only one additional database table instead of multiple tables for storing the 5 values (length, width, height, area, volume)
- Nicely configurable one-line user interface in the backend
- Multiple configuration settings in the backend to adapt the inputfield to your needs
Below you can see what the inputfield looks like as a 2- or 3-dimensional input.
Below you will find the properties to output the dimension values on the frontend. Please replace "fieldname" with the name of your field. Each dimension is stored in its own column of the database.
According to the database columns shown in the previous image, there is a property for each dimension, which outputs the dimension including the unit (e.g. cm) as set in the field configuration. So these properties always return a string (if output formatting is on, which is the default on the frontend).
echo $page->fieldname->length; // outputs e.g. 2 cm
echo $page->fieldname->width; // outputs e.g. 3 cm
echo $page->fieldname->height; // outputs e.g. 2 cm
echo $page->fieldname->area; // outputs e.g. 6 cm²
echo $page->fieldname->volume; // outputs e.g. 12 cm³
If you want to output the label of each dimension in front of the value too, you have to use the following property calls:
echo $page->fieldname->lengthLabel; // outputs e.g. Length: 2 cm
echo $page->fieldname->widthLabel; // outputs e.g. Width: 3 cm
echo $page->fieldname->heightLabel; // outputs e.g. Height: 2 cm
echo $page->fieldname->areaLabel; // outputs e.g. Area: 6 cm²
echo $page->fieldname->volumeLabel; // outputs e.g. Volume: 12 cm³
As you can see, you only have to add the word "Label" after the dimension name to output the dimension including the label.
If you want to get the raw values as they are stored inside the database, you have to use these property calls:
echo $page->fieldname->lengthUnformatted; // outputs e.g. 2
echo $page->fieldname->widthUnformatted; // outputs e.g. 3
echo $page->fieldname->heightUnformatted; // outputs e.g. 2
echo $page->fieldname->areaUnformatted; // outputs e.g. 6
echo $page->fieldname->volumeUnformatted; // outputs e.g. 12
As you can see, you only have to add the word "Unformatted" after the dimension name to output the raw value as an integer or a float.
If you need to output the unit (e.g. cm) on the frontend, you have to use the following property call:
echo $page->fieldname->unit; // outputs e.g. cm
This outputs the unit as a string (e.g. cm).
This fieldtype includes 2 useful additional render methods, which are described below.
This will render a formatted string containing all dimensions.
echo $page->fieldname->renderDimensions();
will produce, for example, the following output:
0.12 cm (L) * 0.35 cm (W) * 3.75 cm (H)
For further customization, you can pass 2 additional parameters inside the parentheses:
- The first one is for displaying the label (default is false).
- The second one is for the multiplication sign (default is "*").
echo $page->fieldname->renderDimensions(true, 'x');
will produce, for example, the following output:
Dimensions: 0.12 cm (L) x 0.35 cm (W) x 3.75 cm (H)
As you can see, the label will be displayed in front of the values and the multiplication sign has changed from "*" to "x".
This will render all dimensions, the area and the volume as an unordered HTML list.
echo $page->fieldname->renderAll();
will output, for example (shown as a list):
Dimensions: 3 cm (L) * 4 cm (W) * 2 cm (H)
Area: 12 cm²
Volume: 24 cm³
You can get the same result with this call, which uses the __toString() method:
echo $page->fieldname;
The renderAll() method also accepts the multiplication sign as a parameter (like the renderDimensions() method).
echo $page->fieldname->renderAll('x');
In this case, the default "*" is replaced by "x".
Dimensions: 3 cm (L) x 4 cm (W) x 2 cm (H)
Area: 12 cm²
Volume: 24 cm³
As written in the introduction, all the dimensions are fully searchable. Here are 3 examples of how to query them.
The dimensions can be used in selectors like:
$pages->find("fieldname.width=120");
or
$pages->find("fieldname.height>=100, fieldname.length<120");
or
$pages->find("fieldname.volume>=1000");
As written above, there are several configuration settings, which can be changed on a per-field basis.
- Set the type (2- or 3-dimensional)
- Set the size unit, which is shown in the label of each input (default is cm)
- Set the max number of decimals (default is 2, max is 10)
- Show/hide a hint telling the user how many decimals are allowed
Type, size unit and number of decimals are settings of the fieldtype and are the same for all templates. Only the hint can be changed per template.
If the type is changed from 3 to 2 dimensions, height and volume of all pages will be set to 0.
If the number of decimals is changed, the database schema will be updated automatically. Area and volume are stored with 2 and 3 times the number of decimals, so no precision is lost in the calculation.
For example, with 2 decimals:
- length, width, height: decimal(14,2)
- area: decimal(28,4)
- volume: decimal(41,6)
Reducing the number of decimals rounds all existing values.
In addition, a small script prevents the user from entering more decimals into the inputs than set in the configuration of this fieldtype. For example, if you set the number of decimals to 2, the user cannot enter more than 2 decimals.
This fieldtype supports multiple languages and includes German translation files by default.
The decimal separator of the output can be translated too (e.g. "," in German): translate the string "." with the context "Decimal separator" in the file ObjectDimensions.php.
The folder tests contains unit tests (PHPUnit) and integration tests (WireTests). The tests are not part of the
downloaded module (see .gitattributes); they are only available in the GitHub repository.
The unit tests run without a database and without booting ProcessWire. They only need the ProcessWire core files of
the installation the module is placed in (site/modules/FieldtypeObjectDimensions -> wire).
cd site/modules/FieldtypeObjectDimensions
composer install
vendor/bin/phpunit
On Windows, use vendor\bin\phpunit. If the module is not placed inside a ProcessWire installation, set the path
to the wire directory in the environment variable PW_WIRE_PATH (see phpunit.xml).
The database tests (schema update, migration) are skipped by default. To run them, create an empty test database
and set PW_TEST_DB_DSN, PW_TEST_DB_USER and PW_TEST_DB_PASS in phpunit.xml.
Never use the database of your website, because the tests create and drop tables.
The integration tests run inside a real ProcessWire installation with the WireTests module (ProcessWire 3.0.274 or higher). They test saving and loading via the page API, selectors, the required check in a form, changes of the field configuration, the upgrade from version 1.2.2, MySQL strict mode, cloning, repeaters and the German translation.
Only use a copy of your website or a fresh installation, because the tests create a field, a template and pages. Run the following commands from the root directory of the ProcessWire installation:
php index.php modules install WireTests
php index.php test site/modules/FieldtypeObjectDimensions/tests/WireTests/FieldtypeObjectDimensions.test.php
The repeater test is skipped if FieldtypeRepeater is not installed; the translation test is skipped if there is no language besides the default language.
- Download the module and place the folder named "FieldtypeObjectDimensions" in /site/modules/.
- In the admin control panel, go to Modules. At the bottom of the screen, click the "Check for New Modules" button.
- Now scroll to the module FieldtypeObjectDimensions and click "Install". The required module InputfieldObjectDimensions will be installed automatically.
- Create a new field with the fieldtype "ObjectDimensions".
Please note: During the installation, a fieldtype and an inputfield are installed automatically with one click. If you want to uninstall this module, you have to uninstall the fieldtype and the inputfield separately.