Creating custom template

Attention! We strongly recommend first to learn more about Sites module REST documentation to understand how the module functions (with REST available in Bitrix24 Self-hosted editions). View this documentation as useful source when working with Bitrix24 Self-hosted editions and find out more details about API and only REST is not enough.

We attempted to provide maximum details on template handling in this chapter. However, we recommend you to study thew section Site Design Template in Bitrix Framework course.

Module settings allow changing Sites24 module main template called landing24 or changing template for specific site. It's recommended to use this method only when you have depleted all features of system template update and you are aware that it will require a lot of time and effort in detailing, including further support. On the other hand, such approach can be useful for copying standard template and implementing significant updates (for example, for optimization).

Such level of modifications means fully discontinuing use of system templates and blocks. Find more details below.

How to create your own custom Site24 template?.

Layout has several required criteria:
- template must done in Bootstrap4 (not specific for version below 4)
- layout must be separated in blocks. There should be no distortions when such blocks are switched and moved, etc.
- layout and scripts must have addressing by ID attribute, because each block can be allocated on the page several times
Now you can proceed to creating a template basis. To do this, just copy the required files from the catalog /bitrix/templates/landing24 into your catalog, located nearby.
Copy the following files:
- description.php (specify name of your new template)
- header.php (no changes required)
- footer.php (no changes required)
- template_styles.css (no changes required, with required styles for site and pages: header, footer, sidebar)
Note, that "no changes required" means no additional changes are required when copying a file, but you can tailor it specifically for your own objectives. Some markers inside files are used for displaying important management elements (for example, counters).

Retrieved template code (your catalog name) must be written in module settings. It can be general for all sites, or for a specific site.
After that, you are continuing to work with your catalog. Copy all files required for your layout (scripts, styles, fonts, images, sprites, etc.) into your catalog, i. e. all that is required for correct operation of a specific site.
Connect scripts and styles of your template into site template by all canons (styles on top, scripts below).
Attention! You need to receive a visually empty template, without any visible layouts, applied on all pages. Further action depends on you aligning layout via blocks used by editor to compile the pages. Each such block is a "piece" of html, stylistically dependant on the site template.
Because you are creating a custom template, then standard layout-dependent blocks won't work in them. It's recommended to create a configuration file in your template and disable system blocks (bitrix) in the disable_namespace key.
```
   'disable_namespace' => [
      'bitrix'
   ],
```
When you want to exclude absolutely all namespaces except your own, specify a whitelist and only then the listed spaces will be displayed. Previous parameter will be ignored.
```
   'enable_namespace' => [
      'local'
   ],
```

Template cannot exist without themes. You need to create a minimum single theme using a handler (link contains clarifications on what is a theme). Use this handler to disable all existing themes in the system. For example, such as:

$eventManager = \Bitrix\Main\EventManager::getInstance();
$eventManager->addEventHandler('landing', 'onGetThemeColors',
   function(\Bitrix\Main\Event $event)
   {
      $result = new \Bitrix\Main\Entity\EventResult;
      $colors = $event->getParameter('colors');

      $colors = [];

      $colors['mytheme1'] = array(
         'name' => 'My theme 1',
         'color' => '#cdcdcd',
         'base' => true
      );
      $colors['mytheme2'] = array(
         'name' => 'My theme 2',
         'color' => '#373737',
         'base' => true
      );

      $result->modifyFields(array(
         'colors' => $colors
      ));

      return $result;
   }
);

Because you create a fully separate template, there is no guarantee that third-party applications will operate correctly on it. Due to this, site and page templates and partner blocks registered via REST. To display blocks and templates you need, register them with parameter site_template_id = #your_main_template_code#. Find more details in template registration and block registration.
Most likely you will also need to connect your own custom icon libraries or remove standard ones from installation. However, there is an option to copy all style files of icon libraries into your main template. In this case you may find useful this icon library chapter.

Other

The "Top" button can be enabled in the site settings. Enabled option adds g-upper-show class to the body tag. Script works with this class by dynamically adding the button.

Displayed button can be implemented in your template or script sourced from system template by path:/bitrix/templates/landing24/assets/js/helpers/go_to_init.js.

Also, there is an option to re-define "Top" button display via the hook display handler (hook code UP).