mirror of
https://github.com/opnsense/docs.git
synced 2025-12-13 08:34:32 -06:00
257 lines
9.7 KiB
ReStructuredText
257 lines
9.7 KiB
ReStructuredText
===========================
|
||
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 following naming conventions, suffix Controller.php on
|
||
every class file and suffix Action on all action methods.
|
||
|
||
----------------------
|
||
Class structure
|
||
----------------------
|
||
|
||
Most components inherit from a set of standard controllers, which are specified in the diagram below including their primary
|
||
usage scope (/ui or /api)
|
||
|
||
|
||
.. image:: ../images/Controller_class_hierarchy.svg
|
||
:width: 100%
|
||
|
||
|
||
----------------------
|
||
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 :
|
||
https://docs.phalcon.io/latest/volt/
|
||
|
||
|
||
---------------------
|
||
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 :code:`getForm()` method itself merely passes the structure to the 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 ["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']
|
||
);
|
||
}
|
||
}
|