From e88821a9e1a578c96584d0b36e4d1d82d8668623 Mon Sep 17 00:00:00 2001
From: Ad Schellevis <ad@opnsense.org>
Date: Sun, 17 Mar 2024 19:51:39 +0100
Subject: [PATCH] development - add csv import/export helpers. closes
 https://github.com/opnsense/docs/issues/541

---
 source/development/frontend/controller.rst    | 37 +++++++++++++++++++
 .../development/frontend/view_js_helpers.rst  | 35 ++++++++++++++++++
 2 files changed, 72 insertions(+)

diff --git a/source/development/frontend/controller.rst b/source/development/frontend/controller.rst
index 1c012f49..529297c2 100644
--- a/source/development/frontend/controller.rst
+++ b/source/development/frontend/controller.rst
@@ -207,3 +207,40 @@ Implementing this into your own controller should be as simple as:
             return $this->searchRecordsetBase($records);
         }
     }
+
+
+--------------------------------------------------
+Easy csv export/import helpers
+--------------------------------------------------
+
+In order to export or import csv structured data, some helpers are available to ease these operations.
+The :code:`ApiControllerBase` adds a simple recordset export method (:code:`exportCsv()`)
+and :code:`ApiMutableModelControllerBase` contains a method to import data (:code:`importCsv()`).
+
+When data is being exported from a model using an :code:`ArrayField` type, the :code`asRecordSet()` method can be used
+to extract the data easily.
+
+The smallest functional example to download a file from a controller implemented with :code:`ApiMutableModelControllerBase`
+would look like:
+
+.. code-block:: php
+
+    public function downloadAction()
+    {
+        $this->exportCsv($this->getModel()->path->to->items->asRecordSet());
+    }
+
+Feeding data back into the model:
+
+.. code-block:: php
+
+    public function uploadReservationsAction()
+    {
+        if ($this->request->isPost() && $this->request->hasPost('payload')) {
+            return $this->importCsv(
+                'path.to.items',
+                $this->request->getPost('payload'),
+                ['my_key']
+            );
+        }
+    }
diff --git a/source/development/frontend/view_js_helpers.rst b/source/development/frontend/view_js_helpers.rst
index c928e73b..665fcbb7 100644
--- a/source/development/frontend/view_js_helpers.rst
+++ b/source/development/frontend/view_js_helpers.rst
@@ -311,6 +311,41 @@ property of the table, which offers the ability to show an alert after changes.
     requests or responses as being exchanged with the server. The available options are described `here <http://www.jquery-bootgrid.com/Documentation#table>`__
 
 
+----------------------------
+$.SimpleFileUploadDlg
+----------------------------
+
+The simple file upload dialog can be used to select a file and upload it to a specified endpoint.
+
+To define a button sending data to `/api/path/to/import_controller`, the following code could be used:
+
+.. code-block:: html
+
+    <button
+        id="upload"
+        type="button"
+        data-title="Import"
+        data-endpoint='/api/path/to/import_controller'
+        class="btn btn-xs"
+    ><span class="fa fa-fw fa-table"></span></button>
+
+
+.. Note::
+
+    The structure of this :code:`POST` contains a :code:`payload` and a :code:`filename` property.
+
+Initializing this button could be done using:
+
+.. code-block:: php
+
+    $("#upload").SimpleFileUploadDlg();
+
+
+.. Tip::
+
+    The :code:`SimpleFileUploadDlg` action supports an :code:`onAction` handler similar to the one described in :code:`$.SimpleActionButton`
+
+
 OPNsense settings
 .......................