Creating a block

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.

Creating a block

It's easy to create a block. All blocks are located on the disk at the path /bitrix/blocks/. Then, such blocks are split by so-called namespaces. You can create a namespace and add your block directly into it. Namespace is just a catalog inside /bitrix/blocks/.

Note: Also supports /local directory.

Block consists of the following files:

1. Main block body block.php, containing block layout, copied to database when adding the block to a page.
2. File .description.php, storing block manifest. To show block in repository, your namespace must contain a block name minimum.
3. Language files (according Bitrix Frameworklanguage file rules).
4. Optional files script.js/style.css, connected jointly with block and can support additional logic/visualization load.
5. Optional file preview.jpg, serving for illustrating a block in catalog.

These files are placed inside a folder with a specific name (it's recommended to use Latin alphabet, digits, "." and "-" characters). From this moment, folder name acts as block character code as well, written into database when adding a block to page. Please, proceed with caution.

Also, note that block's name must be unique within complete setup. For example, when a block about exists in the "bitrix" namespace and within a "my" namespace, only one block will exist in the system, specifically in the "my" namespace, because it's located lower than "bitrix" namespace. It's done especially to re-define standard blocks by developers. When such blocks are distributed by Marketplace, it's recommended to assign a partner's prefix to block names. Cloud REST does not have such conditions and is recommended as more universal variant for distribution.

Important! When adding a block (blocks), call for cache reset (or via admin interface in cache settings):

if (\Bitrix\Main\Loader::includeModule('landing'))
{
   \Bitrix\Landing\Block::clearRepositoryCache();
}

Important!"bitrix" namespace is a reserved and is uploaded via the Bitrix cloud service. It contains blocks that are not related to editor catalog and are provided as an example.

New block layout can be commissioned from a specialist, or use additional blocks from vendor.

Examples

Example of block.php file

<section class="landing-block">
    <div class="text-center g-color-gray-dark-v3 g-pa-10">
        <div class="g-width-600 mx-auto">
            <div class="landing-block-node-text g-font-size-12 ">
                <p>© 2017 All right reserved. Developed by
                <a href="#" class="landing-block-node-link g-color-primary">Bitrix24</p>
            </div>
        </div>
    </div>
</section>

Example of .description.php file

<?php
if (!defined('B_PROLOG_INCLUDED') || B_PROLOG_INCLUDED !== true)
{
   die();
}

use \Bitrix\Main\Localization\Loc;

return array(
   'block' =>
      array(
         'name' => Loc::getMessage('LANDING_BLOCK_32.'),
         'section' => array('image'),
      ),
   'cards' => array(),
   'nodes' =>
      array(
         '.landing-block-node-img-big' =>
            array(
               'name' => Loc::getMessage('LANDING_BLOCK_32.1'),
               'type' => 'img',
               'dimensions' => array('width' => 1440, 'height' => 960),
               'allowInlineEdit' => false,
            ), 
      ), 
);

Updating already added blocks

When you want to update a layout of already added page blocks, you need to modify the original block in repository, and then execute a code below. Please note, is a trial technology and requires additional testing on blocks you want to modify.

Self-hosted

Execute the code below and the system will process it automatically (code is not associated with added block, it exist separately).

if (\Bitrix\Main\Loader::includeModule('landing'))
{
   \Bitrix\Landing\Update\Block::register(
      '20.3.four_cols_fix_img_title_text'
   );
}

The update won't be instantaneous, it may take sometime.

REST

New parameter RESET has been added to fields of the registration method landing.repo.register. When passed as Y, already modified blocks will be updated after re-registering the block.

if (\Bitrix\Main\Loader::includeModule('landing'))
{
   \Bitrix\Landing\Update\Block::register(
      '20.3.four_cols_fix_img_title_text',//block ID
      $params
   );
}

Array of parameters stores selectors in keys that are modified when updated. Array contains two optional keys (new_class, remove_class):

$params = [
      '.landing-block-node-card-title' => [
         'new_class' => ['g-pr-0', 'g-pr-15--md', 'g-mb-8', 'g-mb-0--md'],  // add classes for selector landing-block-node-card-title

         'remove_class' => ['u-heading-v1__title', 'mb-0'],    // delete classes from selector landing-block-node-card-title

      ],
      '.landing-block-node-card-price' => [
         'new_class' => 'd-inline-block g-ml-0 g-ml-15--md',
      ],
]

If something went wrong and indexing must be cancelled:

if (\Bitrix\Main\Loader::includeModule('landing'))
{
   \Bitrix\Landing\Update\Block::unregister(
      '20.3.four_cols_fix_img_title_text'
   );
}

When testing on a specific block, first its updated:

if (\Bitrix\Main\Loader::includeModule('landing'))
{
   \Bitrix\Landing\Update\Block::executeStep([
      'ID' => 44148 // ID блока
   ], $count = 0, $limit = 1, $params = []);
}