Merge pull request #286 from jenkinsci/type-aware-sort

Add new generic `DetailedCell` to provide type aware sorting

Author: uhafner

pom.xml

@@ -21,6 +21,7 @@
     <revision>1.12.1-1</revision>
     <changelist>-SNAPSHOT</changelist>
 
+    <json-unit-assertj.version>2.35.0</json-unit-assertj.version>
     <module.name>${project.groupId}.datatables</module.name>
   </properties>
 
@@ -64,6 +65,18 @@
 
     <!-- Test Dependencies -->
 
+    <dependency>
+      <groupId>net.javacrumbs.json-unit</groupId>
+      <artifactId>json-unit-assertj</artifactId>
+      <version>${json-unit-assertj.version}</version>
+      <scope>test</scope>
+      <exclusions>
+        <exclusion>
+          <groupId>org.ow2.asm</groupId>
+          <artifactId>asm</artifactId>
+        </exclusion>
+      </exclusions>
+    </dependency>
     <dependency>
       <groupId>io.jenkins.plugins</groupId>
       <artifactId>plugin-util-api</artifactId>
@@ -213,6 +226,9 @@
           <packages combine.children="append">
             <package>io.jenkins.plugins.datatables</package>
           </packages>
+          <excludes>
+            <exclude>.*DetailedCell.*</exclude>
+          </excludes>
           <entryPointClassPackage>io.jenkins.plugins.datatables.assertions</entryPointClassPackage>
         </configuration>
       </plugin>

src/main/java/io/jenkins/plugins/datatables/TableConfiguration.java

@@ -6,7 +6,6 @@
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.annotation.JsonSerialize;
-import io.jenkins.plugins.datatables.options.SelectStyle;
 
 /**
  * Provides a configuration for the whole DataTable. This is merged with a default configuration in table.js.
@@ -162,4 +161,52 @@ public String getConfiguration() {
     @JsonSerialize
     private static class EmptyConfigObject {
     }
+
+    /**
+     * The possible values of the <a href="https://datatables.net/reference/option/select.style">select.style</a> option,
+     * which is used for enabling the selection for datatables and setting its style (the default is {@link #OS}.
+     *
+     * @author Florian Orendi
+     */
+    public enum SelectStyle {
+        /**
+         * Selection can only be performed via the API.
+         */
+        API("api"),
+
+        /**
+         * Only a single item can be selected, any other selected items will be automatically
+         * deselected when a new item is selected.
+         */
+        SINGLE("single"),
+
+        /**
+         * Multiple items can be selected. Selection is performed by simply clicking on the items to be selected.
+         */
+        MULTI("multi"),
+
+        /**
+         * Operating System (OS) style selection.
+         * This is the most comprehensive option and provides complex behaviours such as ctrl/cmd clicking
+         * to select / deselect individual items, shift clicking to select ranges
+         * and an unmodified click to select a single item.
+         */
+        OS("os"),
+
+        /**
+         * A hybrid between the {@link #OS} style and {@link #MULTI},
+         * allowing easy multi-row selection without immediate de-selection when clicking on a row.
+         */
+        MULTI_SHIFT("multi+shift");
+
+        private final String style;
+
+        SelectStyle(final String style) {
+            this.style = style;
+        }
+
+        public String getStyle() {
+            return style;
+        }
+    }
 }

src/main/java/io/jenkins/plugins/datatables/TableModel.java

@@ -69,7 +69,10 @@ public String getTableConfigurationDefinition() {
     /**
      * A column value attribute that provides a {@code display} and {@code sort} property so that a JQuery DataTables
      * can use different properties to sort and display a column.
+     *
+     * @deprecated use the generic class {@link DetailedCell}
      */
+    @Deprecated
     public static class DetailedColumnDefinition {
         private final String display;
         private final String sort;
@@ -97,4 +100,38 @@ public String getSort() {
             return sort;
         }
     }
+
+    /**
+     * A table cell that provides a {@code display} and {@code sort} property so that a JQuery DataTables
+     * can use different properties to sort and display a column.
+     *
+     * @param <T> the type of the sort column
+     */
+    public static class DetailedCell<T> {
+        private final String display;
+        private final T sort;
+
+        /**
+         * Creates a new {@link DetailedCell}.
+         *
+         * @param display
+         *         the value that should be used to display the cell
+         * @param sort
+         *         the value that should be used to sort the cell
+         *
+         * @see <a href="https://datatables.net/reference/option/columns.type">DataTables Column Types</a>
+         */
+        public DetailedCell(final String display, final T sort) {
+            this.display = display;
+            this.sort = sort;
+        }
+
+        public String getDisplay() {
+            return display;
+        }
+
+        public T getSort() {
+            return sort;
+        }
+    }
 }

src/main/java/io/jenkins/plugins/datatables/options/SelectStyle.java

@@ -1,8 +1,9 @@
 package io.jenkins.plugins.datatables;
 
-import io.jenkins.plugins.datatables.options.SelectStyle;
 import org.junit.jupiter.api.Test;
 
+import io.jenkins.plugins.datatables.TableConfiguration.SelectStyle;
+
 import static io.jenkins.plugins.datatables.TableConfigurationAssert.*;
 
 /**

src/test/java/io/jenkins/plugins/datatables/TableConfigurationTest.java

@@ -0,0 +1,28 @@
+package io.jenkins.plugins.datatables;
+
+import org.junit.jupiter.api.Test;
+
+import io.jenkins.plugins.datatables.TableModel.DetailedCell;
+
+import static net.javacrumbs.jsonunit.assertj.JsonAssertions.*;
+
+/**
+ * Tests the class {@link TableModel}.
+ *
+ * @author Ullrich Hafner
+ */
+class TableModelTest {
+    @Test
+    void shouldCreateStringSortingCell() {
+        DetailedCell<String> cell = new DetailedCell<>("Display", "Sort");
+
+        assertThatJson(cell).isEqualTo("{display: \"Display\", sort: \"Sort\"}");
+    }
+
+    @Test
+    void shouldCreateIntSortingCell() {
+        DetailedCell<Integer> cell = new DetailedCell<>("Display", 123);
+
+        assertThatJson(cell).isEqualTo("{display: \"Display\", sort: 123}");
+    }
+}