Содержание

Template Layouts
- Layout Markup
- Customizing an Output Layout

Template Layouts

An InstantCMS template, as a common entity (synonyms - theme, skin), consists of a common layout (there can be more than one) and output files-templates.

A common layout is the main template of all site pages and contains the <html>, <head> and <body> tags. The templates of components and widgets are output inside it. By default, the engine uses two layouts: main.tpl.php for the site and admin.tpl.php for the Control panel.

/templates/default/main.tpl.php
/templates/default/admin.tpl.php

Layout Markup

When creating a layout markup, you create a basic frame for your theme. Let’s consider an example. The simplest layout can be as follows:

main.tpl.php

<!DOCTYPE html>
<HTML>
<head>
    <title><?php $this->title(); ?></title>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <?php $this->addMainCSS("templates/{$this->name}/css/theme-layout.css"); ?>
    <?php $this->addMainCSS("templates/{$this->name}/css/theme-modal.css"); ?>
    <?php $this->addMainJS("templates/{$this->name}/js/jquery.js"); ?>
    <?php $this->addMainJS("templates/{$this->name}/js/jquery-modal.js"); ?>
    <?php $this->addMainJS("templates/{$this->name}/js/core.js"); ?>
    <?php $this->addMainJS("templates/{$this->name}/js/modal.js"); ?>
    <?php if (cmsUser::isLogged()){ ?>
        <?php $this->addMainJS("templates/{$this->name}/js/messages.js"); ?>
    <?php } ?>
    <?php $this->head(); ?>
</head>
<body id="<?php echo $device_type; ?>_device_type">
    <div id="layout">
        <?php if (!$this->site_config->is_site_on){ ?>
            <div id="site_off_notice">
                <?php printf(ERR_SITE_OFFLINE_FULL, href_to('admin', 'settings', 'siteon')); ?>
            </div>
        <?php } ?>
        <header>
            <div class="widget_ajax_wrap" id="widget_pos_header">
                <?php $this->widgets('header', false, 'wrapper_plain'); ?>
            </div>
        </header>
        <?php if($this->hasWidgetsOn('top')) { ?>
            <nav>
                <div class="widget_ajax_wrap" id="widget_pos_top">
                    <?php $this->widgets('top', false, 'wrapper_plain'); ?>
                </div>
            </nav>
        <?php } ?>
        <div id="body">
            <?php
                $messages = cmsUser::getSessionMessages();
                if ($messages){
                    ?>
                    <div class="sess_messages">
                        <?php
                            foreach($messages as $message){
                                echo $message;
                            }
                        ?>
                    </div>
                    <?php
                }
            ?>
            <section>
                <div class="widget_ajax_wrap" id="widget_pos_left-top">
                    <?php $this->widgets('left-top'); ?>
                </div>
                <?php if ($this->isBody()){ ?>
                    <article>
                        <?php if ($this->site_config->show_breadcrumbs && $core->uri && $this->isBreadcrumbs()){ ?>
                            <div id="breadcrumbs">
                                <?php $this->breadcrumbs(array('strip_last'=>false)); ?>
                            </div>
                        <?php } ?>
                        <div id="controller_wrap">
                            <?php $this->body(); ?>
                        </div>
                    </article>
                <?php } ?>
                <div class="widget_ajax_wrap" id="widget_pos_left-bottom">
                    <?php $this->widgets('left-bottom'); ?>
                </div>
            </section>
            <aside>
                <div class="widget_ajax_wrap" id="widget_pos_right-top">
                    <?php $this->widgets('right-top'); ?>
                </div>
                <div class="widget_ajax_wrap" id="widget_pos_right-center">
                    <?php $this->widgets('right-center'); ?>
                </div>
                <div class="widget_ajax_wrap" id="widget_pos_right-bottom">
                    <?php $this->widgets('right-bottom'); ?>
                </div>
            </aside>
 
        </div>
        <footer>
            <ul>
                <li id="info">
                    <span class="item">
                        <?php echo LANG_POWERED_BY_INSTANTCMS; ?>
                    </span>
                    <span class="item">
                        <?php echo LANG_ICONS_BY_FATCOW; ?>
                    </span>
                </li>
                <li id="nav">
                    <div class="widget_ajax_wrap" id="widget_pos_footer">
                        <?php $this->widgets('footer', false, 'wrapper_plain'); ?>
                    </div>
                </li>
            </ul>
        </footer>
    </div>
</body>
</HTML>

The file should be encoded in UTF-8.

Here is the default simplified template markup for InstantCMS. In this file, all methods of the cmsTemplate class object are available via $this.

As we see, this layout contains the frame of basic (and possible) blocks of all site pages. Let’s consider in detail.

<head> block

The main parameters of pages are output here: title, linked styles and scripts, meta tags.

The $this→title(); method outputs the page title set by a controller.

The $this→head(); method outputs all head tags that are specified for the page with the help of the corresponding methods of linking of CSS, JavaScript and other tags. To link anything you need, use them above the current method’s request. It is important to link via engine methods, in this case, your linked styles and/or scripts will participate in compression and minification according to the CMS Options.

$device_type variable

This variable may contain three values: desktop, mobile, tablet. This will conditionally indicate a device from which a user accessed the site. desktop - desktop users, mobile - mobile device users, tablet - tablet users.

$this->site_config variable

This is an array of general site settings. It is usually used to check if the site or debugging is enabled, accordingly, it is used to display relevant messages.

As we know, widgets are Information Blocks on different pages. Learn about custom widget development on this page

In the page layout context, there are two important methods for widgets:

$this→hasWidgetsOn('position');
$this→widgets('position');

The hasWidgetsOn method helps to detect enabled widgets at a position or positions and for the Current Page.

$has_top = $this->hasWidgetsOn('top_position');
// will return true, if at least one widget at this position and for the current page is available for output

To the method, you can pass several positions separated by commas:

$has_top = $this->hasWidgetsOn('top_center', 'top_right');
// will return true, if at least one widget is available for output at one of the two positions

The widgets method types all widgets at this position. The method has three parameters:

$this->widgets('position', $is_titles, $wrapper);

Use the second and the third parameters to show or hide the widget title and the title of a widget wrapper correspondingly. These parameters will overlap similar parameters specified in the widget. For example, write the following, if you want to hide the titles of widgets at this position and use wrapper_plain.tpl.php as a template:

$this->widgets('position', false, 'wrapper_plain');

Output of information messages

Information messages are messages about successful operations, information messages and error messages, for example, about errors in a form. Insert the following code in any part of the template to output them:

<?php
// we get all messages
$messages = cmsUser::getSessionMessages();
// if there are messages
if ($messages){ ?>
    <div class="sess_messages">
        <?php
            // we sort and output them
            foreach($messages as $message){
                echo $message;
            }
        ?>
    </div>
<?php } ?>

"Breadcrumbs" output

Breadcrumbs - a navigation element through site sections showing a path from the root directory to the page currently viewed by a user.

<?php if ($this->site_config->show_breadcrumbs && $core->uri && $this->isBreadcrumbs()){ ?>
	<div id="breadcrumbs">
		<?php $this->breadcrumbs(array('strip_last'=>false)); ?>
	</div>
<?php } ?>

In this construction, we check if breadcrumbs are enabled in the settings $this→site_config→show_breadcrumbs, we are not on the main page $core→uri and breadcrumbs are not empty $this→isBreadcrumbs(). If the conditions are met, we output the panel.

$this->breadcrumbs(array('strip_last'=>false));

An array of settings is passed to the method’s parameter, the default options are as follows:

array(
    'home_url'   => href_to_home(), // main page url
    'template'   => 'breadcrumbs',  // a template in which the HTML-layout of breadcrumbs is generated
    'strip_last' => true            // Check to hide the last element of the chain
);

By default, the breadcrumbs generation template is found at the path /templates/default/assets/ui/breadcrumbs.tpl.php.

Page body output

The $this→body(); method types the page’s «body», i.e. the results of the current component’s work. At the moment of output, the body is already generated .

The $this→isBody() method checks if there is anything to output on the page.

Language constants

If a template has a custom language file, all its constants are available in the layout. The language file can be located at the path /system/languages/LANGUAGE/templates/TEMPLATE_TITLE.php.

Customizing an Output Layout

The layout is switched in the component’s controller in the following way:

cmsTemplate::getInstance()->setLayout('admin');

or so, which is equivalent or preferable if this action is performed in the controller’s context:

$this->cms_template->setLayout('admin');

The setLayout($layout_name) method switches the layout for the current request.

If a component uses a custom layout (or several layouts), when switching a theme, a new theme should contain the same name layouts, otherwise, the component will be incompetible with the thеme.

Learn custom layout’s title in the following way:

$current_layout = $this->cms_template->getLayout();

The Inheritance Mechanism is applicable to the layout files too.

Back to the section's table of contents

Документация InstantCMS