feat(QueryBuilder): Add a reorder method

reorder clears the existing configured order by statements for the query and then adds the passed in order by statements to the query
coldbox-modules · Jul 22, 2020 · 69d6c5d · 69d6c5d
1 parent 50b7c3c
commit 69d6c5d
Show file tree

Hide file tree

Showing 6 changed files with 55 additions and 0 deletions.
diff --git a/models/Query/QueryBuilder.cfc b/models/Query/QueryBuilder.cfc
@@ -1868,6 +1868,36 @@ component displayname="QueryBuilder" accessors="true" {
         return this;
     }
 
+    /**
+     * Clears the currently configured orders for the query.
+     * Then it adds the passed in orders to the query.
+     *
+     * @column    The name of the column(s) to order by.
+     *            An expression (`builder.raw()`) can be passed as well.
+     *            An array can be passed with any combination of simple values,
+     *            array, struct, or list for each entry in the array
+     *
+     *            An example with all possible value styles:
+     *                column = [
+     *                    "last_name",
+     *                    [ "age", "desc" ],
+     *                    { column = "favorite_color", direction = "desc" },
+     *                    "height|desc"
+     *                ];
+     *            The column argument can also just accept a comman delimited list
+     *            with a pipe ( | ) as the secondary delimiter denoting the direction
+     *            of the order by. The pipe delimiter is also used when parsing the
+     *            column argument when it is passed as an array and the entry in the
+     *            array is a pipe delimited string.
+     * @direction The direction by which to order the query.  Accepts "asc" OR "desc". Default: "asc". If column argument is an array this argument will be used as the default value for all entries in the column list or array that fail to specify a direction for a speicifc column.
+     *
+     * @return    qb.models.Query.QueryBuilder
+     */
+    public QueryBuilder function reorder( required any column, string direction = "asc" ) {
+        clearOrders();
+        return orderBy( argumentCollection = arguments );
+    }
+
     /*******************************************************************************\
     |         UNION functions                                                       |
     \*******************************************************************************/

diff --git a/tests/resources/AbstractQueryBuilderSpec.cfc b/tests/resources/AbstractQueryBuilderSpec.cfc
@@ -1365,6 +1365,15 @@ component extends="testbox.system.BaseSpec" {
                                 }, orderByClearOrders() );
                             } );
 
+                            it( "can reorder a query", function() {
+                                testCase( function( builder ) {
+                                    builder
+                                        .from( "users" )
+                                        .orderBy( [ "last_name", "favorite_color" ] )
+                                        .reorder( "age" );
+                                }, reorder() );
+                            } );
+
                             it( "as pipe delimited strings", function() {
                                 testCase( function( builder ) {
                                     builder

diff --git a/tests/specs/Query/MySQLQueryBuilderSpec.cfc b/tests/specs/Query/MySQLQueryBuilderSpec.cfc
@@ -426,6 +426,10 @@ component extends="tests.resources.AbstractQueryBuilderSpec" {
         return "SELECT * FROM `users`";
     }
 
+    function reorder() {
+        return "SELECT * FROM `users` ORDER BY `age` ASC";
+    }
+
     function orderByPipeDelimited() {
         return "SELECT * FROM `users` ORDER BY `last_name` DESC, `age` ASC, `favorite_color` DESC";
     }

diff --git a/tests/specs/Query/OracleQueryBuilderSpec.cfc b/tests/specs/Query/OracleQueryBuilderSpec.cfc
@@ -435,6 +435,10 @@ component extends="tests.resources.AbstractQueryBuilderSpec" {
         return "SELECT * FROM ""USERS""";
     }
 
+    function reorder() {
+        return "SELECT * FROM ""USERS"" ORDER BY ""AGE"" ASC";
+    }
+
     function orderByPipeDelimited() {
         return "SELECT * FROM ""USERS"" ORDER BY ""LAST_NAME"" DESC, ""AGE"" ASC, ""FAVORITE_COLOR"" DESC";
     }

diff --git a/tests/specs/Query/PostgresQueryBuilderSpec.cfc b/tests/specs/Query/PostgresQueryBuilderSpec.cfc
@@ -435,6 +435,10 @@ component extends="tests.resources.AbstractQueryBuilderSpec" {
         return "SELECT * FROM ""users""";
     }
 
+    function reorder() {
+        return "SELECT * FROM ""users"" ORDER BY ""age"" ASC";
+    }
+
     function orderByPipeDelimited() {
         return "SELECT * FROM ""users"" ORDER BY ""last_name"" DESC, ""age"" ASC, ""favorite_color"" DESC";
     }

diff --git a/tests/specs/Query/SqlServerQueryBuilderSpec.cfc b/tests/specs/Query/SqlServerQueryBuilderSpec.cfc
@@ -426,6 +426,10 @@ component extends="tests.resources.AbstractQueryBuilderSpec" {
         return "SELECT * FROM [users]";
     }
 
+    function reorder() {
+        return "SELECT * FROM [users] ORDER BY [age] ASC";
+    }
+
     function orderByPipeDelimited() {
         return "SELECT * FROM [users] ORDER BY [last_name] DESC, [age] ASC, [favorite_color] DESC";
     }