11.4. View Scripts

A view script is a file containing HTML markup and, optionally, PHP code. The markup produced by a view script is included within the current layout, so the view script usually represents only a portion of a page. Perforce Chronicle uses view scripts for almost all markup generation, so an understanding of how a view script is selected during request processing helps theme designers to customize the markup selectively. For detailed information, please see the Zend Framework Programmer's Reference Guide.

All non-resource requests made to Chronicle are dispatched through modules. A module is a collection of configuration, controllers, resources, view scripts, and other assets that can embody a significant amount of functionality in Chronicle. A controller is a specific collection of programmed logic that is divided into actions. An action is programmed logic contained in a method, designed to service a specific request.

For example, when a request is made to Chronicle to display a particular piece of content, via a URL such as http://cms-host/content/index/view/id/123, Chronicle dispatches execution of code to the viewAction() method in the IndexController that exists in the content module, which attempts to retrieve the content entry with the id 123.

When markup is to be generated, Chronicle first checks the current theme for a view script matching the current module, controller, and action, and if one is found, it is used. Otherwise, Chronicle uses the module's view script for markup generation. For a theme to customize the markup for the example request, it needs to provide a view script in the following folder structure:

views/
   content/          - represents the content module.
      index/         - represents the IndexController in the content module.
         view.phtml  - represents the viewAction() method in the index controller.

	View Scripts Should Not Include Business Logic
	Any available PHP capabilities can be used in a view script. However it is strongly recommended that business logic not be located in the view; business logic ideally exists in a model, but may also be included in the controller/action.

11.4.1. Partial View Scripts

Sometimes the same markup needs to be used multiple times. For example, you might need to display contact information for multiple content types. To generate markup independent of model, controller and method, you create a partial view script in the views folder; for example:

views/
   contact_info.phtml

To generate the markup in the partial view script, use the following PHP code in the view script where you want the output to appear:

<?= $this->partial('contact_info') ?>

For more information about partial view scripts, refer to the Zend Framework documentation.

11.4.2. Content Entry View Scripts

A specific content entry can have its own view script, enabling you to override the presentation. Entry-specific view scripts must be named and located as follows. Note that the identifier specific for a content entry must be included in the filename of the view script.

views/
   content/                         - represents the content module.
      index/                        - represents the IndexController in the content module.
         view-entry-example.phtml   - represents the view script for the example content entry.

11.4.3. Content Type View Scripts

A Chronicle content type can have its own view script, enabling you to override the default presentation. Content type view scripts must be named and located as follows. Note that the identifier specified for a content type must be included in the filename of the view script.

views/
   content/                       - represents the content module.
      index/                      - represents the IndexController in the content module.
         view-type-example.phtml  - represents the view script for the example content type.

11.4.4. The Default Content View Script

When a content entry is to be displayed and it does not match an entry-specific or content type-specific view script, the default view.phtml view script is used.

11.4.5. View Script Notes

A content view script must produce the desired markup for presentation, as well as suitable markup so that the content can be edited by users in the web browser. Chronicle uses view helpers to produce editor-specific markup.

If per-element markup is not required, the view script can enclose the entire content entry in markup as follows:

... surrounding markup ...
<?= $this->contentEntry() ?>
... surrounding markup ...

If individual elements in a content entry require custom markup, use the approach illustrated in the following example:

... markup ...
<?= $this->contentEntry()->open() ?>
... markup ...
<?= $this->contentEntry()->element('title') ?>
... markup ...
<?= $this->contentEntry()->element('sidebar') ?>
... markup ...
<?= $this->contentEntry()->element('body') ?>
... markup ...
<?= $this->contentEntry()->close() ?>
... markup ...

The open() call retrieves the content entry and returns markup that is suitable for making the content editable. The element() calls retrieve the specified element from the content entry and returns the markup suitable for making that specific element editable. The close() call closes the content entry, freeing resources, and returns markup to complete any block-level markup to complete the editable context.

To ensure that a displayed element cannot be edited by users, use the following approach:

<?= $this->entry->getDisplayValue('title') ?>