--- title: "blocks" doc_type: static doc_category: static doc_version: v20270301 source_url: html: 'https://developer.shopline.com/docs/online-store-3-0-themes/theme-structure/blocks' md: 'https://developer.shopline.com/docs/online-store-3-0-themes/theme-structure/blocks.md' --- # blocks The `blocks` directory contains definitions for blocks that can be added to [sections](https://developer.shopline.com/docs/online-store-3-0-themes/theme-structure/sections.md?lang=en). Each block has its own configuration and can be reused within sections. There are three types of blocks: - **Public blocks**: can be used by any section or block. - **Private blocks**: can only be used within the specific section they belong to. - **App block**: created by apps to extend theme capabilities. * * * ## Directory structure{#nrysG} Each block in the `blocks` directory must include an `.html` file and can have optional `.css` and `.js` files. ```plain blocks ├── product │ ├── card.css │ ├── card.js │ └── card.html └── heading.html ``` The `blocks` directory can be located in two places: - **Theme root directory**: stores public blocks. - **Section directory**: stores private blocks specific to the section. * * * ## Public blocks{#fz4un} Public blocks are stored in the theme root directory and can be accessed by any section or block. ```html ... sections blocks └── product ├── card.css ├── card.js └── card.html templates ... ``` The following is an example of how the public block `product/card` is used in the `featured-collection` section: ```html
{{#blocks}} {{#if forblock.type == "product/card"}} {{#var products_pagination = section.settings.collection | get_product_pagination(4) /}} {{/if}} {{/blocks}}
{{#schema}} { "name": "featured-collection", "settings": { "type": "collection", "id": "collection", "label": "collection" }, "blocks": [ { "type": "product/card", "limit": 1 } ] } {{/schema}} ``` In the above example: 1. The [blocks](https://developer.shopline.com/docs/sline/tag/blocks.md) tag is used in a loop to access the [forblock](https://developer.shopline.com/docs/sline/object/forblock.md) object for conditionally rendering different types of blocks. 2. For the block of type `product/card`, the [get\_product\_pagination](https://developer.shopline.com/docs/sline/filter/get-product-pagination.md) filter retrieves paginated information of the products using `section.settings.collection`. 3. The products from `products_pagination.list` are then iterated over to render each product using the `product/card` block. In scenarios where no custom rendering of block content or parameter passing is needed, the [content](https://developer.shopline.com/docs/sline/tag/content.md) tag can be used for direct rendering, as shown in the following example. ```html
{{#content "blocks" /}}
{{#schema}} { "name": "button-group", "blocks": [ { "type": "button", "limit": 2 } ] } {{/schema}} ``` * * * ## Private blocks{#FUTwL} For certain sections, it is essential to isolate proprietary functionalities into distinct blocks. This enables merchants to configure them independently within the theme editor. Such blocks are designated as private blocks and are restricted for use solely within the section they are defined. The files for private blocks are stored within a `blocks` directory, which is situated inside the respective section's directory. ```plain sections ├── blog ├── blocks │ ├── articles.css │ └── articles.html └── blog.html ``` When incorporating private blocks within a section, prefix the block file names with a `$` symbol to denote that they are private blocks. ```html
{{#blocks}} {{#if forblock.type == "$articles" /}} {{#block blog=section.settings.blog /}} {{/if}} {{/blocks}}
{{#schema}} { "name": "blog", "settings": [ { "type": "blog", "id": "blog", "label": "blog" } ], "blocks": [ { "type": "$articles", "limit": 1 } ] } {{/schema}} ``` * * * ## Nested blocks{#GCJPg} Blocks can be nested within sections and other blocks, providing the theme editor with greater configurational flexibility. > **Caution** > > The maximum number of nesting levels that can be displayed by the theme editor is 6. Taking the aforementioned private blocks as an example, consider nesting a public `article/card` block within the `articles` block. Use the [props](https://developer.shopline.com/docs/sline/object/props.md) object in the block to retrieve passed parameters: ```html {{#var articles_pagination = props.blog | get_article_pagination(10) /}} {{#var articles = articles_pagination.list /}} {{#schema}} { "name": "articles", "blocks": [ { "type": "article/card", "limit": 1 } ] } {{/schema}} ``` * * * ## App Block{#ahXtm} The app block is a way to extend the theme through a SHOPLINE App, allowing merchants to add extensions in the theme editor. These app extensions will ultimately be presented on the theme pages. For detailed information, refer to [Integrate apps with themes](https://developer.shopline.com/docs/online-store-3-0-themes/integrate-apps-with-themes/theme-app-extension/overview.md). * * * ## Schema{#NEBCP} Blocks support the addition of a [schema](https://developer.shopline.com/docs/sline/tag/schema.md) tag in which various attributes of a block can be defined, such as the block's name. The attributes supported by a block schema are consistent with those supported by the section schema. For more details, refer to [Section schema](https://developer.shopline.com/docs/online-store-3-0-themes/theme-structure/sections.md?lang=en#Fc76g). To access the values configured in a block, use the object `block.settings`. See the following example: ```html {{#var articles_pagination = props.blog | get_article_pagination(10)/}} {{#var articles = articles_pagination.list/}}

{{ block.settings.title }}

{{#schema}} { "name": "articles", "settings": [ { "type": "text", "id": "title", "label": "Title" } ], "blocks": [ { "type": "article/card", "limit": 1 } ] } {{/schema}} ```