From 51a8ab63b08b286acfc2d313f76562d231bb8f26 Mon Sep 17 00:00:00 2001
From: Ad Schellevis <ad@opnsense.org>
Date: Sun, 9 Aug 2020 14:20:40 +0200
Subject: [PATCH] Development: add some view help, work in progress for
 https://github.com/opnsense/docs/issues/241

---
 source/development/frontend.rst               |  2 +
 source/development/frontend/controller.rst    | 50 +++++++++++++++++++
 .../development/frontend/view_js_helpers.rst  | 37 ++++++++++++++
 3 files changed, 89 insertions(+)
 create mode 100644 source/development/frontend/view_js_helpers.rst

diff --git a/source/development/frontend.rst b/source/development/frontend.rst
index ecc7b248..b9babba4 100644
--- a/source/development/frontend.rst
+++ b/source/development/frontend.rst
@@ -12,3 +12,5 @@ The OPNsense frontend is implemented with `PHP/Phalcon <https://en.wikipedia.org
    frontend/models
    frontend/routing
    frontend/controller
+   frontend/view_js_helpers
+   
diff --git a/source/development/frontend/controller.rst b/source/development/frontend/controller.rst
index f8e37bc2..8c04734f 100644
--- a/source/development/frontend/controller.rst
+++ b/source/development/frontend/controller.rst
@@ -56,6 +56,56 @@ directory.
 More information on how to write Volt pages can be found here :
 http://docs.phalconphp.com/en/latest/reference/volt.html
 
+---------------------
+User forms
+---------------------
+
+When designers need forms for users to input data, they can use the :code:`getForm()` method on our standard controller
+to feed a simple xml file as definition for the template engine to use. The example section contains a step by step
+guide how to use these.
+
+The getForm() method itself merily passes the structure to thew view, which can use this information to render
+forms on page load (statically).
+In our standard layout `partials <https://github.com/opnsense/core/blob/master/src/opnsense/mvc/app/views/layout_partials/form_input_tr.volt>`__ we offer some different record types which we will detail below:
+
+
+**Attributes**
+
+============  ===========================================================================================
+Name          Description
+============  ===========================================================================================
+id            unique id of the attribute
+type          type of input or field. For a list of valid types, use the Type table below
+label         attribute label (visible text)
+size          size (width in characters) attribute if applicable
+height        height (length in characters) attribute if applicable
+help          help text
+advanced      property "is advanced", only display in advanced mode
+hint          input control hint
+style         css class(es) to add, helps identifying items easier using jQuery selectors
+width         width in pixels if applicable
+allownew      allow new items (for list) if applicable
+readonly      if true, input fields will be readonly
+============  ===========================================================================================
+
+
+**Types**
+
+==================  ===========================================================================================
+Name                Description
+==================  ===========================================================================================
+header              Header row 
+text                Single line of text
+password            Password field for sensitive input. The contents will not be displayed.
+textbox             Multiline text box
+checkbox            Checkbox
+dropdown            Single item selection from dropdown
+select_multiple     Multiple item select from dropdown
+hidden              Hidden fields not for user interaction
+info                Static text (help icon, no input or editing)
+==================  ===========================================================================================
+
+
 ---------------------
 API based controllers
 ---------------------
diff --git a/source/development/frontend/view_js_helpers.rst b/source/development/frontend/view_js_helpers.rst
new file mode 100644
index 00000000..6a0fd950
--- /dev/null
+++ b/source/development/frontend/view_js_helpers.rst
@@ -0,0 +1,37 @@
+==============================
+View construction (and tools)
+==============================
+
+Although most of our code base is being processed server side, some things just require interaction on the
+clients machine for a fluent user experience.
+
+In this chapter we will try to explain some of the components we use when designing pages and how pages are usually constructed.
+
+--------------------------
+Layout
+--------------------------
+
+To ease reading of volt templates, we recommend using a fixed layout when creating templates.
+The base of our rendered page always contains the standard `layout <https://github.com/opnsense/core/blob/master/src/opnsense/mvc/app/views/layouts/default.volt>`__
+which is hooked via our standard frontend controller.
+
+Below you will find the sections and their order, which we will describe briefly.
+
+.. code-block:: html
+
+    {#
+      {1} Copyright notice
+    #}
+    <script>
+    $( document ).ready(function() {
+      {2} UI code
+    });
+    </script>
+    {3} page html
+    {{ partial("layout_partials/base_dialog",...)}}  {4} dialog forms (see getForm())
+
+
+#.   The copyright block, 2 clause BSD with the authors on top
+#.   Javascript code which belongs to this page
+#.   HTML code, usually starts with some :code:`<div>` containers and uses standard Bootstrap 3 layouting
+#.   When forms are used, these are placed last, these will be generated to the client as standard html code