Manifest File

A manifest is the description of a block in the form of an array. The block markup defines how it looks, while the manifest defines what can be changed in it:

• editable elements in the block markup
• styles available in the editor
• additional attributes
• connected resources

For standard Bitrix24 blocks, the manifest is located in the .description.php file next to the block. An app passes the manifest of its own block at registration — in the manifest parameter of the landing.repo.register method.

The examples on this page are written as a PHP array, as in .description.php. In a REST call, the same set of keys is passed as a JSON object: the manifest parameter is declared with the object type.

The manifest is needed for two tasks: when you build your own block and when you modify someone else's block via REST. In the second case, the manifest shows which selectors the modification methods accept: nodes from nodes, cards from cards, attributes from attrs, and styles from style.

How to Retrieve the ManifestHow to Retrieve the Manifest

• landing.block.getmanifestfile — the original manifest of a template by block code, 01.big_with_text for example
• landing.block.getmanifest — the manifest of a block already placed on a page, with service fields and substituted translations

Examine a manifest on a standard block: retrieve the list of templates using the landing.block.getrepository method, and then request the manifest of the required block by its code. Call parameters for landing.block.getmanifestfile:

{
            "code": "01.big_with_text"
        }
        

A manifest does not always have to be written. If you take a ready-made Bitrix24 block and change only the values of its nodes and attributes, go straight to the methods of the Working with Blocks section.

Example of a Manifest FileExample of a Manifest File

$manifest = [
            'block' => [
                'name' => 'Text and Image in Two Columns',
                'section' => ['text_image', 'columns'],
                'type' => ['page', 'store', 'knowledge', 'group'],
                'dynamic' => false,
                'description' => 'Block with a title, text, button, and image',
            ],
            'cards' => [
                '.landing-block-card' => [
                    'name' => 'Column',
                    'label' => ['.landing-block-node-title'],
                ],
            ],
            'nodes' => [
                '.landing-block-node-title' => [
                    'name' => 'Title',
                    'type' => 'text',
                ],
                '.landing-block-node-text' => [
                    'name' => 'Text',
                    'type' => 'text',
                ],
                '.landing-block-node-button' => [
                    'name' => 'Button',
                    'type' => 'link',
                ],
                '.landing-block-node-image' => [
                    'name' => 'Image',
                    'type' => 'img',
                    'dimensions' => [
                        'maxWidth' => 1200,
                        'maxHeight' => 1200,
                    ],
                    'allowInlineEdit' => false,
                    'useInDesigner' => true,
                ],
            ],
            'style' => [
                'block' => [
                    'type' => ['block-default'],
                ],
                'nodes' => [
                    '.landing-block-card' => [
                        'name' => 'Column',
                        'type' => ['columns', 'animation'],
                    ],
                    '.landing-block-node-title' => [
                        'name' => 'Title',
                        'type' => ['typo', 'heading'],
                    ],
                    '.landing-block-node-text' => [
                        'name' => 'Text',
                        'type' => 'typo',
                    ],
                    '.landing-block-node-button' => [
                        'name' => 'Button',
                        'type' => 'button',
                    ],
                    '.landing-block-node-image' => [
                        'name' => 'Image',
                        'type' => ['box'],
                    ],
                ],
            ],
            'attrs' => [
                '.landing-block-node-text' => [
                    [
                        'name' => 'Display Mode',
                        'type' => 'dropdown',
                        'attribute' => 'data-view',
                        'items' => [
                            ['name' => 'Short', 'value' => 'short'],
                            ['name' => 'Full', 'value' => 'full'],
                        ],
                    ],
                ],
            ],
            'assets' => [
                'css' => ['https://example.com/landing/custom-block.css'],
                'js' => ['https://example.com/landing/custom-block.js'],
                'ext' => ['landing_form'],
            ],
        ];
        

Manifest KeysManifest Keys

The block manifest consists of a set of keys. Each key corresponds to a specific part of the block description. Multiple keys are used within a single manifest.

The manifest itself is an optional parameter of the landing.repo.register method: without it the block will be registered, but there will be nothing to edit in it. The minimum working set for your own block is nodes with the editable elements. The other keys are added as needed.

Key blockKey block

The block key defines the basic properties of the block. For a block that an app registers with the landing.repo.register method, the name, the description, and the catalog sections are taken from the fields.NAME, fields.DESCRIPTION, and fields.SECTIONS fields rather than from here: for such a block, only type, subtype, and subtype_params are read from the block key.

Fields of the key:

• name — the name of the block
• section — the section or array of sections in the block catalog. Current section codes can be obtained using the method landing.block.getrepository
• dynamic — indicates whether a standard block supports dynamic mode. By default the key is not set, and the block can be used as dynamic. Only an explicit false value prohibits the mode
• subtype — subtype of the special block, a single value or an array. If there are several values, the handlers are applied in turn and each one extends the manifest. Which subtypes exist: Special Blocks
• subtype_params — subtype parameters. Each scenario has its own: they are listed on the scenario page in the Special Blocks section
• type — type of the site where the block is available. Supported site types:
  • page — regular sites and landing pages
  • store — stores
  • smn — service type for the "Sites24" section in BUS
  • knowledge — knowledge bases
  • group — knowledge bases for social network groups
  • vibe — the Bitrix24 main page

The page value automatically adds the smn type to the block as well. If the type key is not set, the block is considered common and will be available in all site types. To remove a block from the catalog, pass the string null or an empty string in type — such a block is hidden.

Key nodesKey nodes

The nodes key describes elements that can be edited as content. CSS selectors are used to specify nodes. It is recommended to choose clear structural classes as selectors, for example, with the prefix landing-block-node-.

The same selector can be used in different blocks. However, it is better to avoid a node selector matching a card selector within the same block: the system does not check this at registration, but in the editor it becomes unclear what exactly is being edited.

In nodes, the keys are the selectors of editable elements, and the values specify the node label, its type, and additional parameters. The type of the node determines how the element will be edited in the interface and in which format its value is retained.

There are eight main node types, from text and images to maps and embedded components. The list of types, their fields, and markup examples: Node Types.

Key cardsKey cards

The cards key describes cards. Cards are used for repeatable content, such as lists of services, employees, or gallery items.

In cards, the keys are the selectors of repeatable elements. The basic description fields are:

• name — the name of the card in the settings form
• label — a node selector or an array of selectors the card title in the list is assembled from

The other fields — presets, grouping, and action restrictions — belong to the extended scheme and are covered in the Extended Description of Cards article.

Recommendations:

• use separate selectors for cards and nodes
• use clear structural classes, such as landing-block-card-*
• do not mix cards of different selectors in one common parent without an advanced card scheme

If the cards are menu items and separate settings are needed for the root and child levels, use the key menu instead of cards.

Key styleKey style

The style key defines which style settings are available in the editor.

When changing the appearance of blocks, CSS classes are usually modified rather than the inline style attribute of nodes. For example, when changing text size, the system may replace the conditional class g-font-size-12 with g-font-size-16, rather than directly writing font-size into style.

Structure:

• style.block — styles for the entire block
• style.nodes — styles for individual elements within the block by CSS selectors

The style groups and the parameters each of them opens in the editor are listed below. An individual parameter code can also be passed in type, columns, animation, display, background, or border-radius for example.

The set of groups and the parameters within each group are extensible: they depend on the connected style manifests and the product version.

There is no separate animation key in the manifest — animation is connected as a style parameter. For it to work properly:

• the node must have the class js-animation
• in style, the type animation must be specified for this node
• if necessary, you can immediately add an effect class, for example, fadeIn

Key attrsKey attrs

The attrs key describes additional block settings whose values are retained in DOM attributes of the elements, data-view="short" for example.

For every setting, the name of the DOM attribute is set in the attribute field and the type of the field in the editor is set in the type field — from a text field and a dropdown list to a palette, an image picker, and a dynamic data source. The attrs key is described in four places of the manifest: at the root, inside style.nodes, inside style.block, and inside cards. The place determines which editor form the field appears in.

The full list of types, their fields, and the places of description: Attributes.

Key menuKey menu

The menu key is used when a multi-level menu with separate settings for root and child items is needed. For the choice between this key and cards, see the Key cards section.

Example of a multi-level menu:

'menu' => [
            '.landing-block-node-menu' => [
                'item' => '.landing-block-node-menu-item',
                'name' => 'Menu',
                'root' => [
                    'ulClassName' => 'landing-block-node-menu navbar-nav',
                    'liClassName' => 'landing-block-node-menu-item nav-item',
                    'aClassName' => 'landing-block-node-menu-link nav-link',
                ],
                'children' => [
                    'ulClassName' => 'landing-block-node-menu navbar-nav',
                    'liClassName' => 'landing-block-node-menu-item nav-item',
                    'aClassName' => 'landing-block-node-menu-link nav-link',
                ],
                'nodes' => [
                    '.landing-block-node-menu-link' => [
                        'name' => 'Link',
                        'type' => 'link',
                    ],
                ],
            ],
        ]
        

Main fields:

• the key of the array .landing-block-node-menu — selector for the root <ul>
• item — selector for <li> elements
• name — name of the menu in the interface
• root — classes for the root level of the menu:
  • ulClassName for the <ul> container
  • liClassName for <li> items
  • aClassName for <a> links
• children — classes for child levels of the menu:
  • ulClassName for nested <ul>
  • liClassName for nested <li>
  • aClassName for <a> links in child items
• nodes — editable elements within the menu item, such as a link

Multiple multi-level menus can be described in a single manifest, meaning multiple root selectors in menu.

Key assetsKey assets

The assets key defines the JS and CSS resources that are connected when adding a block to the page.

• css — external CSS files
• js — external JS files
• ext — Bitrix24 core extensions

If the same file is already included by another block, it will not be added again. There is no need to list the extension dependencies: Bitrix24 connects them itself.

The extensions that blocks use:

There is also the landing.widgetvue extension — it serves the Vue widgets on the Bitrix24 main page. It is not specified in assets.ext: the handler of the widgetvue subtype assembles assets, nodes, and style for the block itself.

If the script uses libraries loaded by the core, it is better to wrap the initialization in BX.ready(...) to ensure the code runs after system connections:

BX.ready(function () {
            // the extensions from assets.ext are already connected here
        });
        

Keys lang_original and langKeys lang_original and lang

The lang_original and lang keys define the localization of labels in the block manifest.

• lang_original — the original language of the phrases in the manifest
• lang — a set of translations by language

Recommendations:

• set lang_original according to the actual language of the manifest
• use the same phrase keys in lang as in the original manifest

Only the values of name keys are translated. For the list of such labels, see Which Labels Are Translated.

More details: Block Localization.

Permissions and LimitationsPermissions and Limitations

Scope: landing

Who can execute the method: depending on the method

Limitations:

• the manifest of a standard Bitrix24 block cannot be changed via REST. The landing.block.* methods modify a placed block, not the description of its template
• the markup of your own block is passed separately from the manifest — in the fields.CONTENT field of the landing.repo.register method. The selectors from nodes, cards, and attrs have to exist in that markup, otherwise there is nothing for the setting to bind to
• only the core extensions available in the block environment are connected in assets.ext

Continue Your LearningContinue Your Learning

• Node Types
• Attributes
• Extended Description of Cards
• Localization of the Block
• Special Blocks: Scenario Overview
• Interactive Blocks: Scenario Overview
• Get the Manifest File of the Block landing.block.getmanifestfile
• Add a Custom Block to the Repository landing.repo.register