Sort folder contents by a custom field

1. What you'll see

   You want the documents inside a folder to display in a deliberate, hand-picked order — services, references, FAQ entries — instead of alphabetically by filename, and you want editors to set that order by dragging rows in the Docly folder view rather than typing numbers. Or: you have a sort field, but the published page still lists the documents by name, or in the wrong order, 1, 10, 11, 2, 3 instead of 1, 2, 3 … 10, 11.

2. What's actually happening

   A folder's listing in the Docly UI is driven by its folder properties — the .docly file that sits inside the folder (schema Published folder or Folder). Two properties control the columns:

   • SpecifyCustomColumns — set to true to add your own columns to the listing.
   • CustomColumns — an array of column definitions.

   Each column is an object with four fields:

   • Title — the column header shown in the listing.
   • Formula — the name of a field in each document's Document block, optionally wrapped in one converter. It is not a JavaScript expression: Order reads the field as it is stored, and parseInt(Order) reads it as a number. The converters are cint/parseInt (whole number), clng, cdbl, cdec/parseFloat (decimal), cdate (date), and image/thumb (show an embedded image). An empty formula uses the column's Title as the field name.
   • Sorting — shown as Sort list by in the dialog, with four choices: "No" shows the value as a plain column; "Ascending" and "Descending" list the folder by this column, lowest or highest first, with no dragging; "Sortable" lists the folder by this column and turns on drag-and-drop ordering (see below).
   • ROWID — a unique id for the column row.

   What "Sortable" does. As soon as one column is Sortable, the folder view lists the documents by that column and the rows become draggable — grab a row by its icon at the left of the name and drop it where it belongs. On drop, Docly writes a new value into the field the formula reads on every document in the folder, numbered 1, 2, 3 … in the new order, and saves them all. Folders without a Sortable column cannot be reordered by dragging. The folder type alone does not turn it on.

   Three consequences follow from that:

   • The order lives in the documents, not in the folder. The documents' schema must have the field (typically Order or SortOrder), and the formula must name it. If it names a field the documents lack, the column is empty and nothing sorts.
   • Every drag rewrites the field and the modified date on all documents in the folder. Hand-set gaps like 10, 20, 30 do not survive the first drag.
   • The Docly UI and the published page are sorted separately. The drag only stores the numbers; your template has to sort by the same field, as a number, or the website keeps its own order.
3. What to do

   1. Give the documents a field to sort on. Add a number field such as Order (or SortOrder) to the schema of the documents that go in the folder. You do not have to fill it in by hand — the first drag numbers every document.

   2. Declare a Sortable column in the folder properties. In the Docly UI: open the folder's menu → Properties → the Properties tab → check Specify custom columns and add a column whose Column / formula reads the field, with Sort list by set to Sortable (see Changing folder schema and properties and Setting up custom columns). The result in the folder's .docly file:

   {
     "SpecifyCustomColumns": true,
     "CustomColumns": [
       {
         "Title": "Order",
         "Formula": "parseInt(Order)",
         "Sorting": "Sortable",
         "ROWID": "col-order"
       }
     ],
     "CustomColumns_type": "CustomColumns"
   }

   The ROWID can be any unique string — a GUID, or a readable slug like col-order. Editing the .docly file in place is safe; it keeps the schema binding.

   If the order should simply follow the value and nobody needs to drag, choose Ascending or Descending instead.

   3. Drag to set the order. Open the folder in Docly and drag the rows by their icon. The column shows 1, 2, 3 … afterwards, and the documents are saved straight away.

   4. Sort the same way in the template. The published page does not inherit the folder view's order. List the documents sorted by the same field, as a number:

   #for(let item of docly.sort(docly.getFiles("faq"), "Order", "parseInt")) {#
     ...
   #}#

   5. Use parseInt() for numbers — in the column formula and in the template. parseInt(Order) sorts 1, 2, 3 … 10; a bare Order stored as text sorts 1, 10, 11, 2.

   6. Optional extras. CustomColumns is an array, so you can show a plain category beside the sortable column. Only the first column with a sort setting other than "No" decides the order, so give the others "No":

   "CustomColumns": [
     { "Title": "Kategori",  "Formula": "Kategori",        "Sorting": "No",       "ROWID": "col-kategori" },
     { "Title": "Sortering", "Formula": "parseInt(Order)", "Sorting": "Sortable", "ROWID": "col-order" }
   ]

   Set HideFilenameColumn to true to drop the default filename column when your custom columns already describe each row.

   Live examples set up exactly this way on www.dops.no: /referanser, /tjenester and /faq sort on Order, /råd-og-tips on SortOrder. See also Editing Docly documents programmatically for the rules on editing .docly files safely.

Last reviewed 23 Oct 2026