> For the complete documentation index, see [llms.txt](https://docs.siteadministrator.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.siteadministrator.com/developer-guide/the-basics/views.md).

# 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
<?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.

```php
$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.

```php
// 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.

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

**members\_user\_list.php (sub view)**

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

**Result**

```markup
<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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.siteadministrator.com/developer-guide/the-basics/views.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.