===========================
Using controllers and views
===========================

-------
General
-------

After routing is performed, the controller takes care of the actual code
to execute for the request. Because we want to implement some basics for
every request that gets processed you should inherit from our base
classes to ensure basic functionality such as authorisation and CSRF
protection.

Controllers are placed in the directory /usr/local/opnsense/mvc/app/controllers/<Vendor\_name>/<Module\_name>/
and should use the standard Phalcon naming conventions, suffix Controller.php on
every class file and suffix Action on all action methods.

For a detailed description of how Controllers work in Phalcon, please
look at the Phalcon documentation at http://docs.phalconphp.com/en/latest/reference/controllers.html

----------------------
View based controllers
----------------------

For rendering standard pages we have chosen to use Volt templates, the
base controller to inherit from in this case is
OPNsense\\Base\\ControllerBase and should take care of binding a
template to the controller. Every template automatically receives
standard features (such as the menu system).

The wireframe for implementing a single action should look like this:

.. code-block:: php

    <?php
        public function indexAction()
        {
           // address some variables to pass through the view
            $this->view->my_variable1 = 'test 1';
            $this->view->my_variable2 = 'test 2';
           // pick a template
            $this->view->pick('SampleVendor/Sample/index');
        }

And the volt template SampleVendor/Sample/index.volt could contain something like:

.. code-block:: html

      the contents of my_variable1 => <b> {{ my_variable1 }} </b> <br>
      the contents of my_variable2 => <b> {{ my_variable2 }} </b> <br>

A full example can be found in the OPNsense\\Sample controller
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
---------------------

For API calls a separate class is used to derive from, which implements
a simple interface to handle calls. The main difference with the view
controllers is that an action should return a named array containing
response data instead of picking a template.

A simple index controller to echo a request back looks like this:

.. code-block:: php

    class TestController extends ApiControllerBase
    {
        /**
         * @return array
         */
        public function echoAction()
        {
            if ($this->request->hasPost("message")) {
                $message = $this->request->getPost("message");
            } else {
                $message = " " ;
            }
     
            return array("message" => $message);
        }
    }

When placed inside the API directory of Vendor/Sample can be called by sending a
post request to /api/sample/test/echo, using jQuery:

.. code-block:: javascript

            $.ajax({
                type: "POST",
                url: "/api/sample/test/echo",
                success: function(data){
                    alert(data.message) ;
                },
                data:{message:"test message"}
            });


.. Tip::

    OPNsense ships with two standard controllers to incorporate default action scenario's, such as mutating models
    and restarting services. These can be found in our repository `here <https://github.com/opnsense/core/blob/master/src/opnsense/mvc/app/controllers/OPNsense/Base/>`__
    and are named :code:`ApiMutableModelControllerBase`, :code:`ApiMutableServiceControllerBase`. Both extend :code:`ApiControllerBase`
    as described in this chapter. The mutable model controller is explained in more detail in :doc:`using grids <../examples/using_grids>`, the
    service controller is explained in :doc:`api enable services <../examples/api_enable_services>`


--------------------------------------------------
Searchable recordsets
--------------------------------------------------

The tip in the previous chapter described how to use grids when using models, but in some cases there are datasets
without being bound to a model. For example when traversing legacy data or gathering system statistics.

For this reason we added the method :code:`searchRecordsetBase()` in :code:`ApiControllerBase`.
Using this method offers the ability to hook a recordset into the same search functionality as being available
in model grids.

The following parameters are being offered:

==================  ===========================================================================================
Name                Description
==================  ===========================================================================================
$records            array as record set, e.g. [ ['id' => '1'], ['id' => '2'], ... ]
$fields             Optional list of fields when not all data should be returned
$defaultSort        Optional default sort order (fielndname in recordset)
$filter_funct       Optional pluggable filter function, which is call with the record in question
$sort_flags         Default set to :code:`SORT_NATURAL | SORT_FLAG_CASE`
==================  ===========================================================================================

.. Note::

    In order to filter sets on fields, make sure all records contain the requested field. Currently it's not possible
    to omit fields when being sorted.


Implementing this into your own controller should be as simple as:

.. code-block:: php

    class TestController extends ApiControllerBase
    {
        /**
         * @return array
         */
        public function searchAction()
        {
            $records = [];
            $records[] = ['id' => '1', 'description' => 'test 1'];
            $records[] = ['id' => '2', 'description' => 'test 2'];
            $records[] = ['id' => '3', 'description' => 'test 3'];
            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']
            );
        }
    }