View Models

The concept of a view model in SiteAdmin is derived from Microsoft's .NET framework. Though in comparison, SA's implementation is varied. Their purpose is to prevent excessive code bloat in application controllers. As mentioned in the controller documentation, a controller method should only contain logic for receiving and responding to requests. Business logic, such as querying/constructing data or performing calculations should be handled elsewhere. A ViewModel is that elsewhere.
File Location
View models reside inside of specific modules.
{application root}/siteadmin/modules/{vendor}/{module}/ViewModels/
The ViewModel Interface
All view models must implement the \sa\application\IViewModel interface.
Method
Returns
Description
__construct(array $data)
n/a
The $data parameter will contain any data initially passed from the parent view.
getXssSanitationExcludes()
array
Constructs and a returns an array of keys, where each key corresponds to the name of a public property in the view model. Any fields in the returned list of keys will not be sanitized for XSS content.
Your First ViewModel
View Model Class
<?php
use sa\application\IViewModel;
​
class ShippingOptionsListViewModel implements IViewModel {
    public $defaultOptions;
    public $heading;
    private $shippingOptions;
    
    public function __construct(array $data) {
        $this->defaultOptions = $data['default_options'];
        $this->heading = $data['shipping_heading'];
        $this->shippingOptions = null;
    }
    
    public function getShippingOptions() {
        if ($this->shippingOptions != null) {
            return $this->shippingOptions;
        }
        
        $options = array();
        // <get shipping options>
        return $options;
    }
    
    public function getXssSanitationExcludes() {
        return array('defaultOptions', 'heading');
    }
}
Scope of Public Properties
When binding a view model to a subview, its public properties will made available in the subview's global scope. For example, the view model's properties defaultOptions and heading may be accessed in the subview as so,
{module}/views/_shipping_options_list.php
<h1><?= $heading ?></h1>
​
<?php
foreach($defaultOptions as $option) {
    // do something
}
?>
A view model's public properties are generally reserved for constants or default values. It is not recommended to populate these values by performing business logic in the constructor. For business logic, use the view model's helper methods instead.
Notice both public properties are included in the getXssSanitzationExcludes() method. Any public properties will be excluded from XSS sanitizing step.
Scope of Private Properties
As you might expect, the view model's private properties will not be exposed to the view. In addition, private methods are not affected by the getXssSanitizationExcludes() method!.
Helper Methods
In the previous example, the getShippingOptions method is exposed as a helper method. This is where complex business operations are performed, such as fetching data from a repository or constructing data structures.
Binding the View Model
There are two ways you can use your view models in an application. The general rule of thumb is to use the subviews method with controllers which respond with HTML templates. Use the direct controller method for controllers which respond with JSON, XML, or any other non-template response.
Subviews
For controller methods that respond with HTML content, it is best practice to create a parent view, then populate it with subviews which are bound to view models.
To encourage this practice, it is not possible to directly bind a view model to a parent view.
Binding view model to subview
parent_view.php
<?= $self->subViewWithModel('_shipping_options_list', 'ShippingOptionsListViewMo
del', $data) ?>
Parameter
Type
Description
$view
string
The name of the sub view to render.
$viewModel
string
The view model to bind to the view.
$data
array
The parent view's data.
<a name="accessing-in-subview"></a>
Accessing view model in subview
Once a view model has been bound to a subview, a $viewmodel variable becomes available in the subview's context. This variable holds the view model's instance. It is used to access helper methods within the view model.
_shipping_options_list.php
<h1><?= $heading ?></h1>
​
<ul>
    <?php
    foreach($viewmodel->getShippingOptions as $option) {
        // render option
    }
    ?>
</ul>
Directly in Controller Method
Some controller methods respond with JSON or XML rather than a HTML template. These types of responses don't have views, so binding a view model to a subview is not possible. Instead, the view models should be used directly.

Views

Models & Doctrine ORM

Last modified 4yr ago

Method	Returns	Description
`__construct(array $data)`	n/a	The `$data` parameter will contain any data initially passed from the parent view.
`getXssSanitationExcludes()`	array	Constructs and a returns an array of keys, where each key corresponds to the name of a public property in the view model. Any fields in the returned list of keys will not be sanitized for XSS content.

Parameter	Type	Description
`$view`	string	The name of the sub view to render.
`$viewModel`	string	The view model to bind to the view.
`$data`	array	The parent view's data.