Migrate RightAlignComparableNumericalFields

4 files changed, 53 insertions, 0 deletions

diff --git a/documentation/articles/RightAlignComparableNumericalFields.asciidoc b/documentation/articles/RightAlignComparableNumericalFields.asciidoc
new file mode 100644
index 0000000000..4f835ead59
--- /dev/null
+++ b/documentation/articles/RightAlignComparableNumericalFields.asciidoc
@@ -0,0 +1,52 @@
+[[right-align-comparable-numeric-fields]]
+Right-align comparable numeric fields
+-------------------------------------
+
+In the table below, the various numerical fields are kind of hard to
+compare and easy misinterpret, because of the alignment of the values:
+
+image:img/table1.png[Table with left alignment]
+
+By right-aligning numerical fields, the values become easier to compare
+and less prone to misinterpretation, since the least significant digits
+are vertically aligned:
+
+[source,java]
+....
+Table tblExpenses = new Table();
+tblExpenses.setContainerDataSource(expensesData);
+tblExpenses.setColumnAlignment("cost", Table.Align.RIGHT);
+tblExpenses.setColumnAlignment("vat", Table.Align.RIGHT);
+....
+
+image:img/table2.png[Table with right alignment]
+
+This effect is of course ruined if the formats of these fields are
+different, such as different number of decimals. Make sure that you’re
+using the same format for fields that should be easy to compare.
+
+Even though this example was of a table, the same principles also apply
+to input fields. Right-aligning a text field indicates to the user that
+a numerical value is expected, and makes multiple numerical fields in
+the same form easier to compare. To do this, you’ll need to set up a
+custom theme for your application (which you’ll probably end up doing at
+some point anyway), set a custom stylename to the field, such as
+_“numerical”_ or _“right-aligned”_...
+
+[source,java]
+....
+TextField tfExpensesLodging = new TextField(“Lodging”);
+tfExpensesLodging.addStyleName(“numerical”);
+....
+
+...and get your hands dirty with a bit of CSS:
+
+[source,css]
+....
+.v-textfield.numerical {
+  text-align: right;
+}
+....
+
+Note that right-aligning non-comparable numerical fields, such as
+product IDs or ISBNs is kind of pointless, and probably best to avoid.
diff --git a/documentation/articles/contents.asciidoc b/documentation/articles/contents.asciidoc
index 176e5d51c0..860244cd23 100644
--- a/documentation/articles/contents.asciidoc
+++ b/documentation/articles/contents.asciidoc
@@ -69,5 +69,6 @@ are great, too.
 - link:ChangingThemeOnTheFly.asciidoc[Changing theme on the fly]
 - link:MarkRequiredFieldsAsSuch.asciidoc[Mark required fields as such]
 - link:PackagingSCSSOrCSSinAnAddon.asciidoc[Packaging SCSS or CSS in an add-on]
+- link:RightAlignComparableNumericalFields.asciidoc[Right-align comparable numerical fields]
 - link:CreatingAUIExtension.asciidoc[Creating a UI extension]
 - link:CreatingAThemeUsingSass.asciidoc[Creating a theme using Sass]
diff --git a/documentation/articles/img/table1.png b/documentation/articles/img/table1.png
new file mode 100644
index 0000000000..d319f883d5
--- /dev/null
+++ b/documentation/articles/img/table1.png
diff --git a/documentation/articles/img/table2.png b/documentation/articles/img/table2.png
new file mode 100644
index 0000000000..590f8dadca
--- /dev/null
+++ b/documentation/articles/img/table2.png