11.3. Layouts

A layout is an HTML file that provides markup that determines the overall look of a page. A layout is used to implement headers and footers, specify stylesheets and scripts to use, and define where content and regions are to exist. Layout files can contain PHP code. Place layouts in the layouts folder, within the theme's folder.

Perforce Chronicle requires layout files to contain, at a minimum, the following prescribed PHP code:

<?= $this->doctype() ?>
<!-- Emit the appropriate document type declaration necessary for correct parsing
     of the page in many browsers -->

<html xmlns="http://www.w3.org/1999/xhtml">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

<!-- Emit the current page title, which is action or content-specific. -->
<?= $this->headTitle() ?>

<!-- Configure the Dojo theme used by Chronicle -- see Note 1 below. -->
<?= $this->dojo() ?>

<!-- Emit the JavaScript required by Chronicle, enabled modules, and scripts
     declared in theme.ini -->
<?= $this->headScript() ?>

<!-- Emit any link tags, typically to specify CSS stylesheets required by
     Chronicle and enabled modules -->
<?= $this->headLink() ?>

<!-- Emit any inline blocks of CSS style declarations, required by Chronicle
     and enabled modules -->
<?= $this->headStyle() ?>


<!-- Assign Dojo's Claro theme class to body, as well as classes related to
     the current layout, module, controller, and action. See Note 2 below. -->
<body class="claro
 <?= $this->layout()->getLayout() ?>
 <?= $this->request()->getModuleName() ?>-module
 <?= $this->request()->getControllerName() ?>-controller
 <?= $this->request()->getActionName() ?>-action">

<!-- Displays the Chronicle toolbar when a user is logged in -->
<?= $this->siteToolbar() ?>

<!-- Displays Growl-style notifications to alert the user to completed actions,
     warnings, and error messages. -->
<?= $this->notifications() ?>

<!-- Emit the markup for the current page, either a content entry or module-specific
     output produced by a view script. -->
<?= $this->layout()->content ?>

[Note] Note 1

Chronicle uses the Dojo JavaScript Toolkit and its Claro theme for its user interface. If an alternate Dojo theme is desired, edit this line. Be advised that switching to another Dojo theme can affect the Chronicle user interface, because other Dojo themes might make different assumptions about the markup available for styling.

[Note] Note 2

To facilitate targeted CSS styling, the body tag must specify the CSS style name identifying the current layout, module, controller, and action, separated by single spaces.

Perforce Chronicle - Release: 2012.2/486814