Introduction

To use the template engine files of pages to be processed PHP (as a rule, have the extension .php).

Pages can be simple, consisting of one file with the HTML and PHP code.

But to take full advantage of the engine will require the separation of code (HTML and PHP), at least two files. The main file should contain an object representation of the page - the class. In the second file - Page Layout (HTML).

File with page layout should have the same name as the class file, but with the .html.php extension.

In addition, each page can have the resources localization, which should be located in .json files.

Contents

Content blocks

Content for blocks of content must be placed in tags: <php:Content />. Name of the block is specified in the parameter ID.

<php:Content ID="markerName">
  Contents of the block here.
  Acceptable use any tag, 
  server code and 
  user controls.
</php:Content>

All that is outside of the <php:Content /> tags will be ignored.

This text will be ignored becauseIt is located outside the <php:Content /> block.

<php:Content ID="MainContent">
  This text will be output in the place <php:MainContent/>.
</php:Content>

This text will be ignored becauseIt is located outside the <php:Content /> block.

You can specify blocks of content for non-existent markers in the template. Using this feature, you can dynamically change the template file and output on a single page output blocks that are defined only in the included template.

The following example shows two templates. In the first defined block <php:MainContent/>, in the second two blocks : <php:MainContent/> and <php:RightPanel/>. The page is defined content for both blocks. When using the template Layout1.php client receives only the contents of the block <php:MainContent/> (see Result #1). When using template Layout2.php, the client will be given a specific content for both blocks (see Result #2).

<!DOCTYPE html>
<html>
  <head>
    <title></title>
  </head>
  <body>
    <div class="container">
      <php:MainContent/>
    </div>
  </body>
</html>
<!DOCTYPE html>
<html>
  <head>
    <title></title>
  </head>
  <body>
    <div class="container">
      <div class="col-md-10">
        <php:MainContent/>
      </div>
      <div class="col-md-2">
        <php:RightPanel/>
      </div>
    </div>
  </body>
</html>
<php:Content ID="MainContent">
  Content for MainContent.
</php:Content>

<php:Content ID="RightPanel">
  Content for RightPanel.  
</php:Content>
<!DOCTYPE html>
<html>
  <head>
    <title>Default</title>
  </head>
  <body>
    <div class="container">
      Content for MainContent.
    </div>
  </body>
</html>
<!DOCTYPE html>
<html>
  <head>
    <title>Default</title>
  </head>
  <body>
    <div class="container">
      <div class="col-md-10">
        Content for MainContent.
      </div>
      <div class="col-md-2">
         Content for RightPanel. 
      </div>
    </div>
  </body>
</html>

If on one page will be located several blocks with the same identifier, it will use the last block. It is not recommended, because it will affect the performance.

<php:Content ID="MainContent">
  This text will be processed, but will not be displayed, because below is a second block with identifier MainContent.
</php:Content>

<php:Content ID="MainContent">
  This text will display in place <php:MainContent/>.
</php:Content>

Simple pages

Simple pages consist of a single file containing HTML code and blocks of content, and may also contain directives, user controls and any server-side code.

Simple pages can be useful for output static content, when it is not require control the process of building a page on the server.

To use the template engine, is necessary to include the file global.php to the page, and also call the the processing by command App::Magic().

<?php 
require_once 'global.php';
\Nemiro\App::Magic();
?>

The following example shows the implementation of a simple page that generates content for the <php:MainContent/>. The directive #Page contains a reference to the template file, and also title of the page (<title />).

<?#Page Layout="~/Layouts/_Layout.php" Title="Simple page"?>

<php:Content ID="MainContent">
  <h2>Hello world!</h2>
</php:Content>

<?php 
require_once 'global.php';
Nemiro\App::Magic();
?>

Simple pages do not provide access to the object representation of the page and have limited functionality for managing templates and user controls.

Separation PHP and HTML

To use all the features, it is recommended to separate the HTML and PHP.

In the main page file is created class. The class name must match the name of the page file (without extension). The markup must be in a file with the extension .html.php.

For example, there is a page index.php:

<?php
require_once 'global.php';

class Index extends \Nemiro\UI\Page
{

}

\Nemiro\App::Magic();
?>

The markup must be placed in the file index.html.php. The following example shows the possible contents of the index.html.php.

<php:Content ID="MainContent">
  <h2>Hello world!</h2>
</php:Content>

This model reduces the mixing of server and client code, and allows you to fully control the process of the page building.

The class of page can contain any public properties and functions that can be used in the code markup through the keyword $this. For example, the base class \Nemiro\UI\Page has the Title property, which contains the title of the current page and can be outputed to the page as follows:

<php:Content ID="MainContent">
  <h2>Title: <?=$this->Title?></h2>
</php:Content>

About Page class.

Only PHP code

Allowed does not create files of markup. In this case, the page will only consist of the class, and blocks of content must be built programmatically.

For example, the index.php file can have the following content.

<?php
require_once 'global.php';

class Index extends \Nemiro\UI\Page
{

  function Load()
  {
    $this->Title = 'The page without markup';
    $this->Content['MainContent'] = 'Any content for MainContent.';
  }

}

\Nemiro\App::Magic();
?>

But this method is rarely used, since in most cases it is not convenient.

Directives

Directive <?#Page ?>

Directive <?#Page ?> allows to override default parameters of the page initialization. (config.php).

Directive located at the top of the HTML page, parameters are written in the style attribute of tags HTML/XML. For example: <?#Page Title="Page title" Layout="~/Layouts/_Layout.php" ?>

Supported parameters presented in the following table.

Parameter Value type Description
Layout String Contains the path to the template file to be used in the build of the page.
Title String Contains html-page title (<title></title>).
Optimized Boolean Enables optimization of the resulting html-code of the page.
Cache Boolean Enables caching of the page.
Culture String Sets the culture (language) for the page. For example: ru, en.

The following example illustrates the use of the <?#Page ?> for to set the title of the page and activation the optimization of HTML.

<?#Page Title="Title" Optimized="true" ?>

<php:Content ID="MainContent">
  Hello world!
</php:Content>

The <?#Page ?> directive actual for a simple pages.

Directive <?#Register ?>

Directive <?#Register ?> allows to register the necessary user controls.

The <?#Register ?> accept four parameters, the list of which is presented in the following table.

Parameter Value type Description
Src String Required. The path to the main file of the control.
TagPrefix String Required. Prefix the name of the control that will be used when placing an instance of an element on the page.
TagName String Required. Name of the control to be used when placing an instance of an element on the page.
ClassName String Optional. Specifies the class name of the element. For example, user control file Message.php, the ClassName by default Message.

The number <?#Register ?> directives on one page is not limited.

The following example shows how to use the directive <?#Register ?> for registration on the page user controls Message and TabControl, and their subsequent use.

<?#Register Src="~/Controls/Message.php" TagPrefix="php" TagName="Message"?>
<?#Register Src="~/Controls/TabControl.php" TagPrefix="php" TagName="TabControl"?>

<php:Content ID="MainContent">
  Hello world!
  <php:Message Type="success" Content="Success!" />
  <php:TabControl>
    <php:Items>
      <php:TabItem Key="Tab1" Title="Attention">
        Controls TabControl and Message is not WebForms.PHP,
        the controls are made specifically for the demo site.
</php:TabItem>
      <php:TabItem Key="Tab2" Title="But...">
        If you wish, you can use these elements into your own projects, 
        just copy the files from the folder /Controls.
        Please note, Bootstrap3 is required.
      </php:TabItem>
    </php:Items>
  </php:TabControl>
</php:Content>
<!DOCTYPE html>
<html>
  <head>
    <title>Default</title>
  </head>
  <body>
    <div class="container">
      <!--Start MainContent-->
        Hello world!

        <!--Start Message-->
        <div class="alert alert-success">Success!</div>
        <!--End Message-->

        <!--Start TabControl-->
        <ul class="nav nav-tabs" role="tablist">
          <li class="active">
            <a href="#Page_TabControl1_Tab1" aria-controls="Page_TabControl1_Tab1" role="tab" data-toggle="tab" aria-expanded="false">
              Attention
            </a>
          </li>
          <li>
            <a href="#Page_TabControl1_Tab2" aria-controls="Page_TabControl1_Tab2" role="tab" data-toggle="tab" aria-expanded="true">
              But...
            </a>
          </li>
        </ul>
        <div class="tab-content">
          <div role="tabpanel" class="tab-pane" id="Page_TabControl1_Tab1">
            
        Controls TabControl and Message is not WebForms.PHP,
        the controls are made specifically for the demo site.

          </div>
          <div role="tabpanel" class="tab-pane" id="Page_TabControl1_Tab2">
            
        If you wish, you can use these elements into your own projects, 
        just copy the files from the folder /Controls.
        Please note, Bootstrap3 is required.
      
          </div>
        </div>
        <!--End TabControl-->
      <!--End MainContent-->
    </div>
  </body>
</html>

Class Page

Class \Nemiro\UI\Page (hereinafter Page) - this basic class that is responsible for building a pages.

From the Page class must be inherited (extends) classes of all pages.

If a page has no class, it will use the default instance of the Page.

The following code shows a variant of the page Forum class inheritance from the base class Page.

<?php
require_once 'global.php';

class Forum extends \Nemiro\UI\Page
{

}

\Nemiro\App::Magic();
?>

Properties

The Page class has the following public properties.

Property Value type Description
Optimized Boolean Gets or sets the mode to optimize the resulting html-code of the page.
Programmatically change the value of this property can be in the event handler PreLoad или Load.
Cache Boolean Gets or sets the cache mode of the page.
Programmatically change the value of this property can be in the event handler PreLoad.
Layout String Gets or sets the path to the template file.
Programmatically change the value of this property can be in the event handler PreLoad.
Encode String Gets or sets the page encoding.
Programmatically change the value of this property can be in the event handler PreLoad.
Culture String Gets or sets the code of culture (language) for the page. For example: ru, en.
Programmatically change the value of this property can be in the event handler PreLoad or Load.
Title String Gets or sets the page title (<title></title>).
Programmatically change the value of this property can be in the event handler PreLoad or Load.
Content Collection (key=value) Collection blocks of content of the page; where the key is a name (identifier) of the block, the value - is content.
Programmatically change the value of this property can be in the event handler PreLoad or Load.
For example: $this->Content['MainContent'] = 'Content for MainContent.';
Meta Collection (key=value) Gets or sets the meta tags of the page.
Programmatically change the value of this property can be in the event handler PreLoad or Load.
For example: $this->Meta['DESCRIPTION'] = 'Page description.';, output:
<meta name="DESCRIPTION" content="Page description." />.
For keywods and description you can use SetDescription and SetKeyWords methods.
For example: $this->SetDescription('Page description.');
Scripts String Array An array of links to client scripts to be included in the page.
Programmatically change the value of this property can be in the event handler PreLoad or Load.
Controls Collection (key=value) Collection controls; where the key - control identifier (ID), value - control instance.
Programmatically change the value of this property can be in the event handler Load.
Note that through this collection can not get direct access to the control instance, it is only possible to determine the values of the properties of the elements that will be created during the building of the page. Also through this collection can not access the public methods of the control.
Resources Collection (key=value) Collection of localization resources; where the key - the name of the resource, the value - localized string.
Programmatically change the value of this property can be in the event handler Load.

All public properties are available for the descendant classes, ie classes of pages.

To avoid conflicts, the names of the custom properties should not overlap with the names of the properties of the base class.

Events

The Page class has three events that can be processed.

PreLoad

The PreLoad event occurs after page initialization and before the start of the HTTP-headers output, loading template and resources.

In the PreLoad event handler you can change the path to the template file and add a new HTTP headers.

You can not control the resources localization in this event, but you can change the current culture.

The following example shows how to change the link to the template file in the event PreLoad handler.

<?php
require_once 'global.php';

class Index extends \Nemiro\UI\Page
{

  function PreLoad()
  {
    $this->Layout = '/example.html';
  }

}

\Nemiro\App::Magic();
?>

Load

The Load event occurs before building data for output.

In handler of this event, you can change the page title, meta tags, a list of client-side scripts, content and change values of the user controls properties.

The following example shows how to change the page title and add a description of the page.

<?php
require_once 'global.php';

class Index extends \Nemiro\UI\Page
{

  function Load()
  {
    $this->Title = 'New title';
    $this->SetDescription('New description.');
  }

}

\Nemiro\App::Magic();
?>

LoadComplete

The LoadComplete event occurs after data output.

In handler of this event, you can be notified of the page creation.

<?php
require_once 'global.php';

class Index extends \Nemiro\UI\Page
{

  function LoadComplete()
  {
    echo 'The page is created and outputed!';
  }

}

\Nemiro\App::Magic();
?>

Localization

For localization of pages can be be used local and global resources.

Local Resources - a text file with the extension .json. The file names (without extensions) must contain the name of the main page file. The file names must contain the code of culture (language), for which resources is designed.

For example, for page index.php may be the following resource files: index.json - the default resources, index.en.json - for English, index.ru.json - for Russain, index.de.json - for German etc.

The scope of local resources also applies to templates and user controls.

Read more.