> For the complete documentation index, see [llms.txt](https://artistro08.gitbook.io/tailor-starter-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://artistro08.gitbook.io/tailor-starter-documentation/pages/blocks/creating-blocks.md). # Creating Blocks ## Introduction Adding blocks should stem from your child theme and be included in your seeds so that the original theme structure can be restored if needed. Follow the [Seeding Themes](https://docs.octobercms.com/3.x/cms/themes/seeding-themes.html) documentation to seed your alterations to the blocks. You can edit the blueprints directly in the `app/blueprints` folder, but it's not recommended if you plan on updating the theme. From this point forward, it is assumed that you are creating blueprints in your seeds folder and seeding it from there. ## Adding Your block to The Builder ### Adding your block to the `builder` and `columns` group To add your block to the builder group, you'll first need to create your own mixin content blocks within the `seeds/blueprints/content/mixins/builder/` folder. The following assumes you created a `custom_block` folder inside the above folder. This folder should contain the following files #### `custom_block_column.yaml` Used for the [Section ](/tailor-starter-documentation/pages/blocks/section.md)builder column blocks 
uuid: #Your Unique UUID
handle: Content\CustomBlockColumn
type: mixin
name: Custom Block Column
fields:
  column_header:
    type: mixin
    label: Column Header
    source: Content\ColumnHeader
  common_fields:
    type: mixin
    source: Content\CustomBlockCommonFields
  hr_1:
    type: ruler
  column_options:
    type: mixin
    source: Content\ColumnOptions
#### `custom_block_common.yaml` Common fields used within the [Section ](/tailor-starter-documentation/pages/blocks/section.md)& [Column Blocks](/tailor-starter-documentation/pages/blocks/section.md#section-column-blocks) ```yaml uuid: #Your Unique UUID handle: Content\CustomBlockCommonFields type: mixin name: Common Event Fields fields: #Your Fields Here... ``` #### `custom_block.yaml` Used for to create a Top Level Section block 
uuid: #Your Unique UUID
handle: Content\CustomBlock
type: mixin
name: Events
fields:
  section_header:
    type: mixin
    source: Content\SectionHeader
  common_fields:
    type: mixin
    source: Content\CustomBlockCommonFields
  advanced_content:
    type: mixin
    source: Content\AdvancedFields
    label: Advanced Settings
    tab: Advanced
Once you've created your custom block blueprint files, you'll need to add them to the Section and Column areas which are in the [`builder.yaml`](https://github.com/artistro08/tailor-starter/blob/main/seeds/blueprints/content/mixins/builder/builder.yaml) and [`section.yaml`](https://github.com/artistro08/tailor-starter/blob/main/seeds/blueprints/content/mixins/builder/section/section.yaml) blueprint files respectfully #### `builder.yaml` ```yaml uuid: 78650dea-607e-4c63-bde8-2364cb786072 handle: Content\Builder type: mixin name: Builder fields: builder: type: repeater label: Builder displayMode: builder span: adaptive prompt: Add a Block groups: #... custom_block: name: Custom Block icon: icon-toggle-on description: Your Custom Block Description titleFrom: title useTabs: true fields: hero: type: mixin source: Content\CustomBlock ``` #### `section.yaml` ```yaml uuid: 1be4d611-a49d-11ed-9116-3a678152e91c handle: Content\Section type: mixin name: Section fields: section_header: type: mixin source: Content\SectionHeader tab: General reverse_columns_on_mobile: label: Reverse Columns on Mobile comment: Useful if you have content that needs to be stacked a different way on a phone. type: switch tab: General hr_1: type: ruler tab: General columns: label: Content type: repeater commentAbove: Create content for this section. Each content block uses it's own column. Max of 4 per section. span: full displayMode: builder tab: General groups: #... custom_column_block: name: Custom Block icon: icon-toggle-on description: Your Custom Block Description titleFrom: title fields: custom_column_block: type: mixin source: Content\CustomBlock #... ``` Once done, you should see your block within the builder after you run: ```bash php artisan october:migrate ``` ## Displaying Block Content Awesome, your block is in the builder. Now it's time to render it's content. You'll need to create some partials under `builder/sections` and `builder/columns` to prep the content for rendering. #### `builder/sections/custom_block.htm` 
<{{ section.html_tag == "default" ? "section" : section.html_tag }} 
        {{ section.html_anchor|length ? 'id="' ~  section.html_anchor  ~ '"' }}
        class="{% if section.css_classes|length %}
                    {% for class in section.css_classes|split(',') %}
                        {{ class ~ ' ' }}
                    {% endfor %}
               {% endif %}
               {{ section.style == 'light' ? 'bg-light' }} 
               {{ section.style == 'dark' ? 'bg-dark text-white' }} 
               {{ section.disable_top_spacing == true ? 'pt-0' : "pt-4" }} 
               {{ section.disable_bottom_spacing == true ? 'pb-0' : "pb-4" }}"
>
    <div class="{{ section.container_style }}">
        Hello World!
    </div>
</{{ section.html_tag == "default" ? "section" : section.html_tag }}>
> The snippet above includes all the extra Advanced Tab content to get you started. Next up, creating the column block #### `builder/columns/custom_block.htm` ```twig Hello World! ``` > The columns block doesn't depend on any content inside of it, so you can initialize it without any extra content ### Adding the blocks to the pages Now that you've created the blocks, time to reference them in their respective sections #### `builder/items.htm` 
{# ... #}
{# Custom Block #}
{% if section.content_group == 'custom_block' %}
    {% partial 'builder/sections/hero' section=section %}
{% endif %}
#### `builder/sections/section.htm` 
    {# ... #}
    <div class="{{ section.container_style }}">
        <div class="row row-cols-lg-{{ section.columns|length }} row-cols-1 mx-auto {{ section.reverse_columns_on_mobile ? 'flex-lg-row flex-column-reverse' }}">
            {% for column in section.columns %}
                <div class="col {{ column.disable_bottom_spacing == true ? 'mb-0' : 'mb-5' }} {{ column.position }} {{ column.width|length ? "col-lg-" ~ column.width : '12' }}">
                    
                    {# ... #}

                    {# Custom Column Group #}
                    {% if column.content_group == "custom_block" %}
                        {% partial 'builder/columns/form' column = column %}
                    {% endif %}
                    
                    {# ... #}
                </div>
            {% endfor %}
        </div>
    </div>
That's it! You've successfully created a custom block. It's a good idea to use folders to organize all your custom blocks. [^1]: References the column block header to keep consistent with the other blocks [^2]: Common Fields that you use throughout the section and column blocks [^3]: References the column grid options for the Bootstrap Column Grid [^4]: References the [Advanced Tab](/tailor-starter-documentation/pages/blocks/section/advanced-tab.md) fields used throughout the sections [^5]: Reference the group name that you added earlier in the `builder.yaml` file [^6]: Pass in the `section` variable if you need that content available in the partials you made earlier [^7]: Reference the group name that you added earlier in the `section.yaml` file [^8]: Pass in the `column` variable if you need that content available in the partials you made earlier --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://artistro08.gitbook.io/tailor-starter-documentation/pages/blocks/creating-blocks.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.