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 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 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.
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.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:Controller data can be accessed directly through the view's data array.
$self->data['user_id']
<a name="accessing-dynamic-variables"></a>
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;
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>
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 share a similar naming convention with regular views, but must also be prefixed with an underscore.
_catalog_product_list.php
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 acatalog shipping address
. Both data sets contain similar fields, such as street, city, state, etc. If you were to create a view which expects asaMemberAddress
object, it would be difficult to use that same view with aShippingAddress
object. Instead, you should create a view that expectsstreet
,city
, andstate
fields (instead of an object), so that single view can be used by both data types.
Last modified 4yr ago