Adding Templates

Templates define the structure of store pages in Bagisto Visual. They control how sections are arranged and rendered inside the main layout.

Templates can be created using multiple formats:

• Blade templates (.blade.php) — simple static content or basic Blade directives
• JSON/YAML templates (.json or .yaml) — fully dynamic, section-driven layouts for the Visual Editor
• PHP templates (.visual.php) — programmatic templates with IDE support and type safety

At this stage, we will start with a Blade template for simplicity.

Creating a Blade Template

Blade templates are simple files that contain the page content. They are injected into the layout through @visual_layout_content.

To create a homepage template:

1. Create a new file:

resources/views/templates/index.blade.php

2. Add the following example content:

<div class="text-center py-12">
  <h1 class="text-4xl font-bold">Welcome to Awesome Theme</h1>
  <p class="mt-4 text-lg text-gray-600">Your new store is ready to be customized.</p>
</div>

This content will be rendered inside your theme’s default layout.

There is no need to use @extends or @section.

Viewing the Template

Once the template file is created:

• Visit your store homepage in the browser.
• You should see the header and footer rendered from the layout.
• The page body will display the content from index.blade.php.

At this stage, no sections are included yet. Templates are static until sections are added.

JSON, YAML, and PHP Templates

Bagisto Visual also supports creating templates using JSON, YAML, or PHP files. These templates enable merchants to visually edit pages, add sections dynamically, and control page structure without touching code.

JSON/YAML Templates

Use .json or .yaml files for simple, declarative template definitions:

{
  "sections": {
    "hero": {
      "type": "visual-hero",
      "settings": {
        "image" => "https://example.com/banner.jpg"
      }
    }
  },
  "order": ["hero"]
}

PHP Templates (.visual.php)

For more complex templates with IDE support and type safety, use .visual.php files:

<?php

use BagistoPlus\Visual\Support\TemplateBuilder;
use Themes\AwesomeTheme\Presets\HeroBanner;

return TemplateBuilder::make()
    ->section('hero', HeroBanner::class)
    ->section('featured-products', 'visual-featured-products', fn($section) => $section
        ->properties([
            'heading' => 'Featured Products',
            'nb_products' => 4,
        ])
    )
    ->order(['hero', 'featured-products']);

Benefits of PHP templates:

• ✅ IDE autocomplete and type checking
• ✅ Import and use preset classes directly
• ✅ Use PHP variables, loops, and conditionals
• ✅ Better refactoring support

The structure and behavior of template formats are explained in:

• JSON & YAML Templates - Declarative templates
• PHP Templates - Programmatic templates with IDE support

In the next chapter, we will cover:

• How to create sections
• How to use sections inside templates to build dynamic pages

For now, starting with a simple Blade template is sufficient to initialize your theme.

Summary

• Templates define page content and are rendered inside layouts.
• Blade templates are static and easy to start with.
• JSON/YAML/PHP templates enable full dynamic editing and will be introduced after learning about sections.
• PHP templates (.visual.php) provide IDE support and type safety.
• Templates must be placed in resources/views/templates/.

Read more about available default templates

Next Steps

• Adding Sections