Views

View Locations

SiteAdmin Module Views

SiteAdmin modules provide default view files so you can install and use the modules without having to build the UI from scratch. These files are located in {root}/siteadmin/modules/sa/{module}/views. You should never edit a core module's views directly. Instead, either extend the module or make a theme view.

Application Module Views

Application modules either extend an existing Siteadmin module, or introduce new functionality to the application. The views for an application module are located in {root}/siteadmin/modules/{application}/{module}/views.

You should only use an application module to extend a view when you are also adding/changing the data in the view's corresponding controller. For strictly aesthetic changes, make a theme view instead.

Theme Views

Theme views are used to change the HTML markup of a Siteadmin module's view. These views should not be used to extend application modules, because such modules are normally project specific and are readily available for you to edit without affecting other applications.

Order of Rendering

When you attempt to render a HTML view, the application will search for that template in each of the locations listed in the previous section.

Consider attempting to render the members_user_list view. In the controller, you might see something like this:

<?php
class MembersController extends controller {
    public function listUsers() {
        $view = new View('master', 'members_user_list');
        // <implementation code>
        return $view;
    }
}

Directory Structure

├───Modules
│    ├───{Theme Directory}
│    │    └───Members
│    │       └───src
│    │           └───views
│    │             │ members_user_list.php
│    │             │ ...
│    └───sa
│        └───member
│            └───src
│                └───views
│                  │ members_user_list.php
│                  │ ...
├───Themes
     └───{Theme Directory}
          └───views
               │ members_user_list.php
               │ ...

The template system will first check the theme views directory for a file named members_user_list.php. If not found, the application module views folder will be checked. Lastly, the Siteadmin module views will be checked. If the file is not found in any of the three locations, an error will be thrown.

In this case, the view exists inside of theme views, so it will be rendered. The members_user_list.php file located elsewhere will not be used.

Accessing Controller Data

All views have access to a $self variable, which contains the context for the view. From this context, you can access data passed from the controller. There are two ways to access the data:

The 'Data' Property

Controller data can be accessed directly through the view's data array.

$self->data['user_id']

<a name="accessing-dynamic-variables"></a>

Dynamic Variables

Controller data is passed in key/value pairs. The key is parsed as a PHP variable which, like $self can also be accessed from the view.

// The key 'user_id' exists in the view's controller method.
echo $user_id;

Subviews

It is recommended to separate a monolithic view into many subviews. Once your subviews have been created, you can embed them in a parent template.

dashboard.php (parent view)

Assume the variable $members is passed down from the controller.

<div class="dashboard">
    <div class="members">
        <?= $self->subview('members_user_list.php', array('members' => $members)) ?>
    </div>
</div>

members_user_list.php (sub view)

<ul>
    <?php foreach($members as $member) { ?>
    <li>
        <!-- member information -->
    </li>
    <?php } ?>
}
</ul>

Result

<div class="dashboard">
    <div class="members">
        <ul>
            <li><!-- member information --></li>
            ...
        </ul>
    </div>
</div>

Conventions

Naming Conventions

Views

A view file must be prefixed with the name of the module it belongs to, followed by a short description of its contents.

catalog_product_list.php

In the example above, catalog is the module, and product_list describes the content of the view.

Subviews

Subviews share a similar naming convention with regular views, but must also be prefixed with an underscore.

_catalog_product_list.php

Creating Reusable Views

A view is not restricted to any one controller method. It can be used in other areas of an application as well. There are a few conventions to follow to ensure views are maintainable and reusable.

1. Short Views - Avoid creating large, monolithic views. Identify the components of a view, and divide them into sub-views.

2. Avoid Passing Objects - An application will likely contain data with similar fields, which might be appropriate to be reused in a subview. Consider a user's home address and a catalog shipping address. Both data sets contain similar fields, such as street, city, state, etc. If you were to create a view which expects a saMemberAddress object, it would be difficult to use that same view with a ShippingAddress object. Instead, you should create a view that expects street, city, and state fields (instead of an object), so that single view can be used by both data types.