Templates and styling

Templates in hacks are responsible for the appearance of the displayed pages. It supports working with the structure files themselves, their CSS and JS files and pictures. Within the MVC model, they are most similar to "views".

Style file structure

Four folders for files are available in the styling part of the hack. They are controlled by the corresponding buttons in the "Files" section of the hack editor.

tpl - "Templates", responsible for TPL structure files.
css - "Styles", CSS styling files.
js - "Scripts", JavaScript files.
img - "Images", images for CSS files.

Including styles and scripts

To connect a style or script, they are used from the name without extension. If your file is called style.css just use style, for script.min.js use script.min .

Adding script from hack:

$core->hack->(name)->js( $name );

Adding style from hack::

$core->hack->(name)->css( $name );

Adding system script:

$core->site->js( $name );

Adding system style:

$core->site->css( $name );

Adding a ready set:

$core->site->set( $name )

Available sets include: jquery, adminlte, select2. Sets are recommended to be connected before the header is drawn.

Template engine functions

How the templating engine works is described in the "Templates" section of the design documentation. Hack templates are managed in the "Templates" section by clicking the "Files" button.

The template is included as a named document entity. Most often, the name body is used for the body, which we will give in the examples. The header uses the name header, the footer name is footer. You can use any name for the part you're working with, just make sure it always comes as the first parameter to the function.

Preparing the template for work:

$core->hack->(name)->tpl( 'body', 'my-template-file' );

Specifying the main parameters with a key-value array:

$core->tpl->vars( 'body', [ 'foo' => 'bar', 'peace' => 'deathz' ] );

Adding a block, parameters - by key-value array:

$core->tpl->block( 'body', 'blockname', [ 'myvar' => 'myvalue' ] );

Blocks can have a nested name. If there is a two block in the one block, use the title separated by a dot: one.two.

Render the specified part and show it to the user:

$core->tpl->output( 'body' );

Useful functions

These functions are not directly related to the template engine, but are used for correct styling.

$core->site->header()

Displays the top of the site with menus and navigation.

$core->site->footer()

Displays the bottom of the site. After the call, it is recommended to execute $core->stop() to stop the work.

$core->site->bc( $name, $url = false )

Adds an item named $name and a link $url to the breadcrumb navigation bar. If no reference is given, just the name is given. The last added element is used as the title of the page.

$core->site->pt( $title )

Sets the title of the page to $title instead of the last breadcrumb element added.

$core->u( (string|array) $url, $param = false )

Generates a link by string or array of elements in $url. If there is an array or string $param, adds a string of GET parameters.

Implementation example

The classic template rendering implementation looks like this:

$core->site->bc( $core->lang['proxy_h'], $core->u('proxy-list') );
$core->site->header();

$core->hack->proxy->tpl( 'body', 'proxy-list' );

$core->tpl->vars( 'body', [
 'name' => $core->lang['name'],
 'status' => $core->lang['status'],
 'noitems' => $core->lang['noitems'],
]);

if ( $proxy ) foreach ( $proxy as $p ) {
  $core->tpl->block( 'body', 'item', [
    'name' => $p['proxy_name'],
    'status' => $core->lang['proxy_status'][$p['proxy_status']],
  ]);
} else $core->tpl->block( 'body', 'noitems' )

$core->tpl->output( 'body' );
$core->site->footer();
$core->stop();

Overriding system templates

You can replace system templates not only in styles, but also in hacks. To do this, you need to create templates with the same name that is used in the system.

The list of overridden templates is specified in the initialization array with the tpl key. It should contain the names of the template files without the extension.

Example:

return [
  /* other initialization commands */
  'tpl' => [ 'analytics-main', 'analytics-lead' ]
];