### Install Bagisto Visual Debut Theme

Source: https://visual.bagistoplus.com/introduction/getting-started

Installs the default starter theme package for Bagisto Visual.

```bash
composer require bagistoplus/visual-debut
```

--------------------------------

### Install Bagisto Visual Package

Source: https://visual.bagistoplus.com/introduction/getting-started

Installs the core Bagisto Visual package using Composer.

```bash
composer require bagistoplus/visual
```

--------------------------------

### Publish Bagisto Visual Debut Theme Assets

Source: https://visual.bagistoplus.com/introduction/getting-started

Publishes the assets for the Bagisto Visual Debut theme.

```bash
php artisan vendor:publish --tag=visual-debut-assets
```

--------------------------------

### Configure Composer for Bagisto Visual

Source: https://visual.bagistoplus.com/introduction/getting-started

Ensures the alpha version of Bagisto Visual can be installed properly by setting minimum stability and preferring stable versions in composer.json.

```json
"minimum-stability": "dev",
"prefer-stable": true
```

--------------------------------

### Publish Bagisto Visual Assets

Source: https://visual.bagistoplus.com/introduction/getting-started

Publishes the necessary assets for Bagisto Visual to prepare the store for theme customization.

```bash
php artisan vendor:publish --tag=visual-assets
```

--------------------------------

### Generate Custom Bagisto Visual Section

Source: https://visual.bagistoplus.com/introduction/getting-started

Creates a new custom section with a PHP class and a Blade file, allowing developers to define custom settings and layout.

```bash
php artisan visual:make-section MyBanner
```

--------------------------------

### Required Files for Bagisto Layout Setup

Source: https://visual.bagistoplus.com/building-theme/adding-layouts

Lists the essential files that must be created and present for the Bagisto Visual layout setup to function correctly, including the default layout and its associated header and footer components.

```text
resources/views/layouts/default.blade.php
resources/views/components/header.blade.php
resources/views/components/footer.blade.php
```

--------------------------------

### Customer Login Form Example

Source: https://visual.bagistoplus.com/core-concepts/templates/available

A Blade section example for the Login Template, demonstrating a form for customer email and password input with a login submission button.

```blade
<section>
  <h2>Customer Login</h2>

  <form method="POST" action="{{ route('shop.customer.session.create') }}">
    @csrf
    <input type="email" name="email" placeholder="Email" required />
    <input type="password" name="password" placeholder="Password" required />
    <button type="submit">Login</button>
  </form>
</section>
```

--------------------------------

### Install Bagisto Visual Theme via Composer

Source: https://visual.bagistoplus.com/building-theme/create-theme

After generating a theme, this Composer command installs it into the Bagisto project. The theme is automatically configured using Composer's local repository system, making it immediately available for use without needing to publish the package to a remote server.

```bash
composer require themes/awesome-theme
```

--------------------------------

### Search Template Results Display Example

Source: https://visual.bagistoplus.com/core-concepts/templates/available

A Blade section example for the Search Template, demonstrating how to retrieve the search query from the request and display results using a Livewire component.

```blade
@php
  $query = request()->get('term');
@endphp

<h2>Results for "{{ $query }}"</h2>

@livewire('search-results', ['term' => $query])
```

--------------------------------

### Product Template Details Display Example

Source: https://visual.bagistoplus.com/core-concepts/templates/available

An example Blade snippet for a section within the Product Template, demonstrating how to display product name, short description, and price using the `$product` variable.

```blade
@if (isset($product))
  <h1>{{ $product->name }}</h1>

  <p>{{ $product->short_description }}</p>

  <p>Price: {{ core()->currency($product->price) }}</p>
@endif
```

--------------------------------

### Example Bagisto Visual Template Files by Type

Source: https://visual.bagistoplus.com/core-concepts/templates/overview

This example lists various template files found within the `/templates/` directory, illustrating how different page types (homepage, product, category, cart, etc.) are associated with specific template formats (Blade, JSON, YAML).

```plaintext
/templates/
├── index.blade.php       # Homepage template
├── product.json          # Product page
├── category.json         # Category page
├── cart.yaml             # Cart page
├── checkout.yaml         # Checkout page
├── page.yaml             # CMS pages
├── search.json           # Search results page
```

--------------------------------

### Basic Header Blade Component Example

Source: https://visual.bagistoplus.com/building-theme/adding-layouts

Illustrates a simple Blade template for the `header.blade.php` component, containing basic navigation links.

```blade
<header>
  <nav>
    <a href="/">Home</a>
    <a href="/products">Products</a>
    <a href="/contact">Contact</a>
  </nav>
</header>
```

--------------------------------

### Basic Footer Blade Component Example

Source: https://visual.bagistoplus.com/building-theme/adding-layouts

Illustrates a simple Blade template for the `footer.blade.php` component, displaying a copyright notice.

```blade
<footer>
  <p>&copy; {{ date('Y') }} Your Company Name</p>
</footer>
```

--------------------------------

### Index Template Basic Section Example

Source: https://visual.bagistoplus.com/core-concepts/templates/available

A simple Blade section example for the Index Template, demonstrating a basic welcome message when no specific variables are automatically exposed to sections.

```blade
<section>
  <h1>Welcome to our Store!</h1>
</section>
```

--------------------------------

### Full Home Page JSON/YAML Template Example

Source: https://visual.bagistoplus.com/core-concepts/templates/json-template

Provides a comprehensive example of a JSON or YAML template for a home page, demonstrating how multiple sections (hero, category list, featured products, newsletter) are defined with their respective settings and blocks, and ordered for display.

```JSON
{
  "sections": {
    "hero": {
      "type": "visual-hero",
      "settings": {
        "image": "https://images.unsplash.com/photo-1441984904996-e0b6ba687e04",
        "size": "medium"
      },
      "blocks": {
        "heading": {
          "type": "heading",
          "settings": {
            "heading": "Talk about your brand"
          }
        },
        "text": {
          "type": "subheading",
          "settings": {
            "subheading": "Share details about your store"
          }
        },
        "button": {
          "type": "button",
          "settings": {
            "text": "Browse store",
            "link": "/",
            "style": "secondary"
          }
        }
      }
    },
    "category-list": {
      "type": "visual-category-list",
      "settings": {
        "heading": "Shop by category"
      },
      "blocks": {
        "category-1": {
          "type": "category",
          "settings": {
            "category": 2
          }
        },
        "category-2": {
          "type": "category",
          "settings": {
            "category": 3
          }
        }
      }
    },
    "featured-products": {
      "type": "visual-featured-products",
      "settings": {
        "heading": "Featured products",
        "product_type": "featured",
        "nb_products": 4
      }
    },
    "newsletter": {
      "type": "visual-newsletter"
    }
  },
  "order": ["hero", "category-list", "featured-products", "newsletter"]
}
```

```YAML
sections:
  hero:
    type: visual-hero
    settings:
      image: https://images.unsplash.com/photo-1441984904996-e0b6ba687e04
      size: medium
    blocks:
      heading:
        type: heading
        settings:
          heading: Talk about your brand
      text:
        type: subheading
        settings:
          subheading: Share details about your store
      button:
        type: button
        settings:
          text: Browse store
          link: /
          style: secondary

  category-list:
    type: visual-category-list
    settings:
      heading: Shop by category
    blocks:
      category-1:
        type: category
        settings:
          category: 2
      category-2:
        type: category
        settings:
          category: 3

  featured-products:
    type: visual-featured-products
    settings:
      heading: Featured products
      product_type: featured
      nb_products: 4

  newsletter:
    type: visual-newsletter

order:
  - hero
  - category-list
  - featured-products
  - newsletter
```

--------------------------------

### Install Theme Prerequisite

Source: https://visual.bagistoplus.com/building-theme/adding-sections/creating-section

Before generating sections within a specific theme, ensure the theme package is already installed in your project using Composer. This command adds the theme to your project's dependencies.

```bash
composer require themes/awesome-theme
```

--------------------------------

### Page Template Content Display Example

Source: https://visual.bagistoplus.com/core-concepts/templates/available

An example Blade snippet for a section within the Page Template, demonstrating how to display the title and content of the `$page` variable.

```blade
@if (isset($page))
  <h1>{{ $page->title }}</h1>

  <div>{!! $page->content !!}</div>
@endif
```

--------------------------------

### Clone Bagisto Visual Starter Theme

Source: https://visual.bagistoplus.com/building-theme/create-theme

This command allows developers to start with a pre-built base theme instead of a blank one. It clones the official Bagisto Visual starter theme into the specified local packages directory, providing a complete working foundation that can be customized freely.

```bash
git clone https://github.com/bagistoplus/visual-debut packages/Themes/YourThemeName
```

--------------------------------

### Minimal Bagisto Visual Blade Layout Example

Source: https://visual.bagistoplus.com/core-concepts/layouts

This Blade template provides a minimal working example of a Bagisto Visual layout. It demonstrates the essential structure including HTML boilerplate, the `@stack('styles')` directive for CSS, `@visual_layout_content` for dynamic page content, and `@stack('scripts')` for JavaScript injection.

```blade
<!DOCTYPE html>
<html lang="{{ app()->getLocale() }}">
<head>
  @stack('styles')
</head>
<body>

  <main>
    @visual_layout_content
  </main>

  @stack('scripts')
</body>
</html>
```

--------------------------------

### Define Theme Settings in PHP

Source: https://visual.bagistoplus.com/core-concepts/settings/theme-settings

An example `settings.php` file demonstrating how to define an array of setting groups, including color, font, and social media link settings using `BagistoPlus\Visual\Settings` classes.

```php
<?php

use BagistoPlus\Visual\Settings;

return [
  [
    'name' => 'Light Scheme Colors (default)',
    'settings' => [
      Settings\Color::make('light_background_color', 'Background')
        ->default('#ffffff')
        ->info('Default page color. Used for main page background and large content areas'),

      Settings\Color::make('light_primary_color', 'Primary')
        ->default('#92400e')
        ->info('Main brand color. Used for buttons and key elements'),

      // More color settings...
    ],
  ],
  [
    'name' => 'Typography',
    'settings' => [
      Settings\Font::make('heading_font', 'Heading Font')
          ->default('Inter'),

      Settings\Font::make('body_font', 'Body Font')
          ->default('Roboto'),
    ],
  ],
  [
    'name' => 'Social Media Links',
    'settings' => [
      Settings\Text::make('facebook_url', 'Facebook URL')
        ->default('https://www.facebook.com'),

      Settings\Text::make('instagram_url', 'Instagram URL')
        ->default('https://www.instagram.com'),

      Settings\Text::make('youtube_url', 'YouTube URL')
        ->default('https://www.youtube.com'),

      Settings\Text::make('tiktok_url', 'TikTok URL')
        ->default('https://www.tiktok.com'),

      Settings\Text::make('twitter_url', 'X/Twitter URL')
        ->default('https://www.x.com'),

      Settings\Text::make('snapchat_url', 'Snapchat')
        ->default('https://www.snapchat.com'),
    ],
  ],
];
```

--------------------------------

### Generate Bagisto Visual Theme with Default Vendor

Source: https://visual.bagistoplus.com/building-theme/create-theme

This command scaffolds a new theme named 'Awesome Theme' using the default 'Themes' vendor namespace. It creates the necessary directory structure and files for a new Bagisto Visual theme, simplifying the initial setup process.

```bash
php artisan visual:make-theme "Awesome Theme"
```

--------------------------------

### List Customer Orders (Blade)

Source: https://visual.bagistoplus.com/core-concepts/templates/available

Provides two Blade examples for displaying a list of customer orders. One uses a Bagisto datagrid component for dynamic rendering, and the other demonstrates a minimal manual fetch and loop through authenticated customer's orders.

```blade
<section>
  <h2>My Orders</h2>

  <x-shop::datagrid :src="route('shop.customers.account.orders.index')" />
</section>
```

```blade
<section>
  <h2>My Orders</h2>

  @foreach (auth('customer')->user()->orders as $order)
    <div class="order-summary">
      <p>Order #{{ $order->id }} placed on {{ $order->created_at->format('M d, Y') }}</p>
      <p>Total: {{ core()->currency($order->base_grand_total) }}</p>

      <a href="{{ route('shop.customer.orders.view', $order->id) }}">View Details</a>
    </div>
  @endforeach
</section>
```

--------------------------------

### Custom Theme Vendor Path Example

Source: https://visual.bagistoplus.com/building-theme/create-theme

This text snippet shows the resulting directory path when a custom vendor name is provided during theme generation. The theme files will be placed under `src/Packages/MyVendor/AwesomeTheme/`, reflecting the custom namespace.

```text
src/Packages/MyVendor/AwesomeTheme/
```

--------------------------------

### Example Blade Template Content

Source: https://visual.bagistoplus.com/building-theme/adding-templates

This Blade template provides a simple HTML structure with a welcome message, intended to be rendered inside the theme's default layout. It demonstrates basic static content for a Bagisto Visual page, without needing `@extends` or `@section` directives.

```blade
<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>
```

--------------------------------

### Blade Template Error Handling Example

Source: https://visual.bagistoplus.com/core-concepts/templates/available

An example Blade snippet demonstrating how to display a generic error message if an `$errorCode` variable is set, typically used for basic error page rendering.

```blade
@if (isset($errorCode))
  <h1>Error {{ $errorCode }}</h1>

  <p>Sorry, something went wrong.</p>
@endif
```

--------------------------------

### Display Customer Profile Information (Blade)

Source: https://visual.bagistoplus.com/core-concepts/templates/available

An example Blade section to display the authenticated customer's first name, last name, and email. It also includes a link to the profile editing page.

```blade
<section>
  <h2>My Profile</h2>

  <p>Name: {{ auth('customer')->user()->first_name }} {{ auth('customer')->user()->last_name }}</p>
  <p>Email: {{ auth('customer')->user()->email }}</p>

  <a href="{{ route('shop.customer.profile.edit') }}">Edit Profile</a>
</section>
```

--------------------------------

### Default Theme Vendor Path Example

Source: https://visual.bagistoplus.com/building-theme/create-theme

This text snippet illustrates the default directory path for a newly generated theme when no custom vendor is specified. The theme files are located under `src/Packages/Themes/AwesomeTheme/`, using the system's default theme namespace.

```text
src/Packages/Themes/AwesomeTheme/
```

--------------------------------

### Example HTML Output for ColorScheme Application

Source: https://visual.bagistoplus.com/core-concepts/settings/types

Illustrates the resulting HTML structure when a `ColorScheme` is applied in a Blade template. The `data-color-scheme` attribute is crucial for scoping CSS styles based on the selected scheme.

```html
<div data-color-scheme="light">
  <!-- ... -->
</div>
```

--------------------------------

### Use Semantic HTML Examples

Source: https://visual.bagistoplus.com/building-theme/best-practices/accessibility

Illustrates the importance of using semantic HTML tags like <h2>, <a>, and <li> instead of generic <div> or <span> elements to convey structure and purpose, improving accessibility and SEO.

```HTML
| Instead of...             | Use...                         |
| ------------------------- | ------------------------------ |
| `<div class="title">`     | `<h2>`                         |
| `<span class="link">`     | `<a href="#">`                 |
| `<div class="list-item">` | `<li>` inside `<ul>` or `<ol>` |
```

--------------------------------

### JavaScript: Advanced Live Updates with Visual.handleLiveUpdate()

Source: https://visual.bagistoplus.com/building-theme/adding-sections/integrating-editor

Provides an example of using the Visual.handleLiveUpdate() JavaScript API for more complex live update scenarios. It demonstrates how to define mappings for section and block-level settings, specifying targets and update types (text, attribute) within a visual:editor:init event listener.

```JavaScript
@visual_design_mode
    @pushOnce('scripts')
        <script>
            document.addEventListener('visual:editor:init', () => {
                window.Visual.handleLiveUpdate('{{ $section->type }}', {
                    // handle update of section level settings
                    section: {
                        title: { target: 'h2', text: true },
                        image: { target: 'img', attr: 'src' }
                    },
                    blocks: {
                        // handle update of block settings
                        announcement: {
                            text: { target: 'p', text: true }
                        }
                    }
                });
            });
        </script>
    @endPushOnce
@end_visual_design_mode
```

--------------------------------

### Forgot Password Form Example

Source: https://visual.bagistoplus.com/core-concepts/templates/available

A Blade section example for the Forgot Password Template, demonstrating a form to request a password reset link with email input and submission button.

```blade
<section>
  <h2>Forgot your password?</h2>

  <form method="POST" action="{{ route('shop.customer.forgot-password.store') }}">
    @csrf
    <input type="email" name="email" required placeholder="Your email" />
    <button type="submit">Send Reset Link</button>
  </form>
</section>
```

--------------------------------

### Display Customer Reviews in Blade Template

Source: https://visual.bagistoplus.com/core-concepts/templates/available

Example Blade template code to iterate through and display a customer's product reviews. It shows how to access product name, rating, and review comments from the `$reviews` collection.

```blade
<section>
  <h2>My Reviews</h2>

  @foreach ($reviews as $review)
    <div class="review-item">
      <p><strong>{{ $review->product->name }}</strong></p>
      <p>Rating: {{ $review->rating }} / 5</p>
      <p>{{ $review->comment }}</p>
    </div>
  @endforeach
</section>
```

--------------------------------

### Semantic Button Styling with Color Tokens

Source: https://visual.bagistoplus.com/building-theme/best-practices/styling

Example of styling a button using semantic color tokens (`bg-primary`, `text-on-primary`) for background and text. This approach ensures the button's appearance adapts seamlessly to different color schemes defined in the system.

```blade
<button class="bg-primary text-on-primary px-4 py-2 rounded">
  Add to Cart
</button>
```

--------------------------------

### Semantic Alert Styling with Color Tokens

Source: https://visual.bagistoplus.com/building-theme/best-practices/styling

Example of styling an alert box using semantic color tokens (`bg-warning`, `text-on-warning`) for background and text. This ensures the alert's visual style is consistent with the overall theme and adapts to different color schemes.

```blade
<div class="bg-warning text-on-warning p-4 rounded">
  Please check your shipping details.
</div>
```

--------------------------------

### Basic PHP Section Class for Bagisto Visual

Source: https://visual.bagistoplus.com/core-concepts/sections

This example demonstrates how to create a basic PHP section class in Bagisto Visual. It extends `BladeSection` and defines configurable settings like text, link, and colors using Bagisto Visual's settings API, which are then accessible in the Blade view.

```php
namespace Themes\YourTheme\Sections;

use Bagisto\Visual\Section\BladeSection;
use Bagisto\Visual\Settings\Text;
use Bagisto\Visual\Settings\Link;
use Bagisto\Visual\Settings\Color;

class AnnouncementBar extends BladeSection
{
    protected static string $view = 'shop::sections.announcement-bar';

    public static function settings(): array
    {
        return [
            Text::make('text', 'Banner text')
                ->default('Welcome to our store!'),

            Link::make('link', 'Banner link'),

            Color::make('background_color', 'Background color')
                ->default('#4f46e5'),

            Color::make('text_color', 'Text color')
                ->default('#ffffff'),
        ];
    }
}
```

--------------------------------

### Define Sections in JSON and YAML Templates

Source: https://visual.bagistoplus.com/building-theme/adding-sections/using-section

Examples of defining sections, including their type, settings, and nested blocks, within both JSON and YAML template files. This structure allows for dynamic content management and customization of section properties.

```json
{
  "sections": {
    "announcement-bar": {
      "type": "awesome-theme::announcement-bar",
      "settings": {
        "text": "Free shipping on all orders",
        "background_color": "#facc15",
        "text_color": "#000000"
      },
      "blocks": {
        "first": {
          "type": "announcement",
          "settings": {
            "text": "Extended returns until Jan 31"
          }
        },
        "second": {
          "type": "announcement",
          "settings": {
            "text": "Free delivery on orders over $50"
          }
        }
      }
    }
  },
  "order": ["announcement-bar"]
}
```

```yaml
sections:
  announcement-bar:
    type: awesome-theme::announcement-bar
    settings:
      text: Free shipping on all orders
      background_color: '#facc15'
      text_color: '#000000'
    blocks:
      first:
        type: announcement
        settings:
          text: Extended returns until Jan 31
      second:
        type: announcement
        settings:
          text: Free delivery on orders over $50

order:
  - announcement-bar
```

--------------------------------

### Display Customer Order Details (Blade)

Source: https://visual.bagistoplus.com/core-concepts/templates/available

An example Blade section for rendering the complete details of a customer's order, including order ID, date, total, and a list of ordered items. It accesses order data via the `$order` variable.

```blade
<section>
  <h2>Order #{{ $order->id }}</h2>

  <p>Order Date: {{ $order->created_at->format('M d, Y') }}</p>

  <p>Total: {{ core()->currency($order->base_grand_total) }}</p>

  <h3>Items:</h3>
  <ul>
    @foreach ($order->items as $item)
      <li>{{ $item->name }} × {{ $item->qty_ordered }}</li>
    @endforeach
  </ul>
</section>
```

--------------------------------

### Semantic Card Styling with Color Tokens

Source: https://visual.bagistoplus.com/building-theme/best-practices/styling

Example of styling a card component using semantic color tokens (`bg-surface`, `text-on-surface`, `text-secondary`, `text-neutral`). This ensures the card's background, text, and headings are consistent with the theme and adapt to different color schemes.

```blade
<div class="bg-surface text-on-surface p-6 rounded shadow">
  <h3 class="text-secondary">Your Benefits</h3>
  <ul class="text-neutral list-disc ml-4">
    <li>Free shipping</li>
    <li>Easy returns</li>
  </ul>
</div>
```

--------------------------------

### Bagisto Visual Theme Section and Block Configuration Fields

Source: https://visual.bagistoplus.com/core-concepts/templates/json-template

Defines the configurable fields used when structuring sections and blocks within Bagisto Visual themes, detailing their purpose, whether they are required, and providing examples. Blocks are optional for sections.

```APIDOC
Fields:
  <section-id>:
    Required: No
    Description: Unique ID or handle used in the template (e.g., `hero`, `category-list`).
  <section-type>:
    Required: Yes
    Description: Slug of the section to render (e.g., `visual-hero`, `visual-featured-products`).
  <block-id>:
    Required: No
    Description: Unique ID of the block.
  <block-type>:
    Required: Yes
    Description: Type of the block to render as defined in the section blocks() config.
  <blocks-order>:
    Required: No
    Description: An array of block IDs, ordered as they should be rendered. The IDs must exist in the `blocks` object.
  <setting-id>:
    Required: No
    Description: ID of the settings defined in the section/block settings config.
  <setting-value>:
    Required: No
    Description: Value of the setting.
```

--------------------------------

### Display Customer Wishlist Items in Blade Template

Source: https://visual.bagistoplus.com/core-concepts/templates/available

Example Blade template code to display items from a customer's wishlist. It demonstrates how to access product names and provide a link to remove items from the wishlist.

```blade
<section>
  <h2>My Wishlist</h2>

  @foreach (auth('customer')->user()->wishlist_items as $item)
    <div class="wishlist-item">
      <p>{{ $item->product->name }}</p>
      <a href="{{ route('shop.customer.wishlist.remove', $item->id) }}">Remove</a>
    </div>
  @endforeach
</section>
```

--------------------------------

### PHP: Defining Repeatable Blocks for Visual Editor Sections

Source: https://visual.bagistoplus.com/building-theme/adding-sections/defining-section-schema

This PHP snippet illustrates how to define a repeatable content block using Block::make for a section in the BagistoPlus Visual Editor. Blocks enable merchants to add dynamic content structures like announcements, and this example shows how to embed settings within a block definition.

```php
use BagistoPlus\Visual\Sections\Block;
use BagistoPlus\Visual\Settings\Text;

Block::make('announcement')
    ->settings([
        Text::make('text', 'Message')->default('Extended returns until Jan 31'),
    ])
```

--------------------------------

### Access Theme Settings in Blade Templates

Source: https://visual.bagistoplus.com/core-concepts/settings/theme-settings

An example of how to access theme settings, such as `light_background_color`, within a Blade template using the `$theme->settings` object.

```blade
<body style="background-color: {{ $theme->settings->light_background_color }};">
    <!-- Storefront content -->
</body>
```

--------------------------------

### Define HTML Wrapper for Bagisto Visual Section

Source: https://visual.bagistoplus.com/building-theme/adding-sections/section-attributes

HTML wrapper using a simplified Emmet-style syntax. Defaults to `section`. The example shows how `section#announcement-bar>div.container` results in a specific HTML structure.

```php
protected static string $wrapper = 'section#announcement-bar>div.container';
```

```html
<section id="announcement-bar">
  <div class="container">
    <!-- Section blade view content -->
  </div>
</section>
```

--------------------------------

### Integrate Static Header and Footer in Blade Layout

Source: https://visual.bagistoplus.com/building-theme/adding-sections/using-section

Full example demonstrating how to include static header and footer sections within a `default.blade.php` layout file. These sections are rendered at fixed locations and are ideal for layout-bound elements that should always be present.

```blade
<!DOCTYPE html>
<html lang="{{ app()->getLocale() }}">
<head>
    <title>Awesome Theme</title>
    @bagisto_vite(['resources/assets/css/app.css', 'resources/assets/js/app.js'], 'awesome-theme')
</head>
<body>

    <visual:section name="awesome-theme::header" />

    <main>
        @visual_layout_content
    </main>

    <visual:section name="awesome-theme::footer" />

</body>
</html>
```

--------------------------------

### Blade: Binding Multiple Settings to a Single Element

Source: https://visual.bagistoplus.com/building-theme/adding-sections/integrating-editor

Illustrates how to apply multiple live update bindings to a single HTML element using a fluent interface in Blade. This example binds both text content and an attribute (href) to different settings, allowing for comprehensive dynamic updates.

```Blade
<a
  href="{{ $section->settings->link_url }}"
  {{ $section->liveUpdate()
      ->text('link_text')
      ->attr('link_url', 'href') }}>
  {{ $section->settings->link_text }}
</a>
```

--------------------------------

### Define ColorSchemeGroup in Theme Settings (PHP)

Source: https://visual.bagistoplus.com/core-concepts/settings/types

Example of defining a `ColorSchemeGroup` in your theme's `config/settings.php` file. This registers a set of named color schemes, each with a label and a collection of color tokens, acting as the central registry for theme colors editable by the merchant.

```php
use BagistoPlus\Visual\Settings\ColorSchemeGroup;

return [
    ColorSchemeGroup::make('color_schemes', 'Color Schemes')
        ->schemes([
            'light' => [
                'label' => 'Light',
                'tokens' => [
                    'background' => '#ffffff',
                    'on-background' => '#111827',
                    'primary' => '#4f46e5',
                    '...'
                ],
            ],
            'dark' => [
                'label' => 'Dark',
                'tokens' => [
                    'background' => '#111827',
                    'on-background' => '#f9fafb',
                    'primary' => '#6366f1',
                    '...'
                ],
            ],
        ]),
];
```

--------------------------------

### Avoid Hardcoded Colors in Layout

Source: https://visual.bagistoplus.com/building-theme/best-practices/styling

Provides an example of an anti-pattern: using inline styles with hardcoded hex values. This practice is strongly discouraged as it bypasses the color system, breaking compatibility with defined color schemes and hindering theme adaptability.

```blade
<div style="background-color: #f3f4f6; color: #333;">
  <p>This will break compatibility with color schemes.</p>
</div>
```

--------------------------------

### Bagisto Visual Checkbox Setting Type Definition and Usage

Source: https://visual.bagistoplus.com/core-concepts/settings/types

Shows how to define a boolean toggle setting using `Checkbox::make` in PHP, demonstrating how to set a default value. If unspecified, the default is `false`. Also provides an example of conditionally rendering content in a Blade template based on the checkbox's state.

```php
use BagistoPlus\Visual\Settings\Checkbox;

public static function settings(): array
{
    return [
        Checkbox::make('show_banner', 'Show Banner')
            ->default(true),
    ];
}
```

```blade
@if ($section->settings->show_banner)
    <div class="banner">
        <!-- Banner content here -->
    </div>
@endif
```

--------------------------------

### Bagisto Visual Theme Configuration File (config/theme.php)

Source: https://visual.bagistoplus.com/building-theme/create-theme

This PHP snippet shows the typical content of the `config/theme.php` file, which defines core metadata and configuration for a Bagisto Visual theme. It includes properties for code, name, version, author, asset paths, and ViteJS settings, crucial for theme identification and asset management.

```php
<?php

return [
    "code" => "awesome-theme",
    "name" => "Awesome Theme",
    "version" => "1.0.0",
    "author" => "Your Company Name",
    "assets_path" => "public/themes/shop/awesome-theme",
    "views_path" => "resources/themes/awesome-theme/views",
    "preview_image" => "public/themes/shop/awesome-theme/preview.png",
    "documentation_url" => "https://yourdomain.com/docs/themes/awesome-theme",

    "vite" => [
        "hot_file" => "awesome-theme-vite.hot",
        "build_directory" => "themes/awesome-theme/dist",
        "package_assets_directory" => "resources/assets"
    ]
];
```

--------------------------------

### File Paths for Header and Footer Blade Components

Source: https://visual.bagistoplus.com/building-theme/adding-layouts

Defines the recommended directory paths for creating reusable `header.blade.php` and `footer.blade.php` components within a Bagisto Visual theme.

```text
resources/views/components/header.blade.php
resources/views/components/footer.blade.php
```

--------------------------------

### Bagisto Visual Theme Directory Structure

Source: https://visual.bagistoplus.com/building-theme/create-theme

This text snippet outlines the complete directory structure of a freshly generated Bagisto Visual theme. It details the purpose of key folders like `config`, `resources`, `src`, and important files such as `package.json` and `composer.json`, providing a clear overview of the theme's organization.

```text
AwesomeTheme/
├── config/
│   ├── settings.php           # Global theme settings (colors, fonts, social links, etc.)
│   └── theme.php              # Main theme metadata (name, author, version)
├── resources/
│   ├── assets/
│   │   └── images/
│   │       └── theme-preview.png # Theme preview image
│   └── views/
│       ├── components/         # Blade components used inside sections
│       ├── layouts/            # Main layouts (default.blade.php, account.blade.php)
│       ├── sections/           # Blade views for each section
│       └── templates/          # Page templates (Blade, JSON, or YAML)
├── src/
│   ├── Sections/               # PHP classes defining sections and blocks
│   │   ├── ExampleSection.php
│   │   └── ...
│   └── ServiceProvider.php     # Registers the theme into Bagisto Visual
├── package.json                # Frontend dependencies and build scripts
├── composer.json               # PHP package metadata for autoloading
├── tailwind.config.js          # TailwindCSS configuration (optional)
├── vite.config.ts              # ViteJS configuration for assets
└── README.md                   # Theme documentation (optional)
```

--------------------------------

### Render Image with Dynamic Alt Text in Blade Template

Source: https://visual.bagistoplus.com/building-theme/best-practices/accessibility

Example of rendering an <img> tag in a Blade template, dynamically setting its `src` and `alt` attributes from section settings for accessibility.

```Blade
<img src="{{ $section->settings->image }}" alt="{{ $section->settings->alt }}">
```

--------------------------------

### Including Blade Components with `x-shop::` Namespace

Source: https://visual.bagistoplus.com/building-theme/adding-layouts

Demonstrates the standard Blade component syntax for including header and footer components using the `shop::` namespace, which is automatically registered for theme views.

```blade
<x-shop::header />
<x-shop::footer />
```

--------------------------------

### Create Blade Template File Path

Source: https://visual.bagistoplus.com/building-theme/adding-templates

This snippet shows the recommended file path for creating a new Blade template for a homepage in Bagisto Visual. This file will contain the static content for the page.

```text
resources/views/templates/index.blade.php
```

--------------------------------

### Generate Bagisto Visual Theme with Custom Vendor

Source: https://visual.bagistoplus.com/building-theme/create-theme

This command allows customizing the vendor namespace for the new theme. The theme 'Awesome Theme' will be generated under the specified 'MyVendor' namespace, which is useful for organizing themes under different brand or client namespaces.

```bash
php artisan visual:make-theme "Awesome Theme" --vendor="MyVendor"
```

--------------------------------

### Generate a Livewire Section using Artisan

Source: https://visual.bagistoplus.com/building-theme/adding-sections/creating-section

Use the `--livewire` flag with the `visual:make-section` Artisan command to create a Livewire-based section. This generates a class that extends `LivewireSection` and includes a Livewire component stub, suitable for dynamic UI components.

```bash
php artisan visual:make-section AnnouncementBar --livewire --theme=awesome-theme
```

--------------------------------

### Create Accessible Error Messages in Blade

Source: https://visual.bagistoplus.com/building-theme/best-practices/accessibility

Example of an accessible error message in a Blade template that combines visual cues (color), an icon (<svg>), and descriptive text (<span>) to convey meaning, rather than relying on color alone.

```Blade
<div class="bg-danger text-on-danger flex items-center gap-2">
  <svg ... aria-hidden="true" />
  <span>Error: Please enter your email address</span>
</div>
```

--------------------------------

### Basic Default Blade Layout Structure

Source: https://visual.bagistoplus.com/building-theme/adding-layouts

Provides a foundational Blade template for the `default.blade.php` layout, including standard HTML structure, meta tags, asset loading via `@bagistoVite`, and placeholders for header, main content, and footer components.

```blade
<!DOCTYPE html>
<html lang="{{ app()->getLocale() }}">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Awesome Theme</title>

    @bagistoVite(['resources/assets/css/app.css', 'resources/assets/js/app.js'])

    @stack('meta')
    @stack('styles')
</head>
<body>

    <x-shop::header />

    <main>
        @visual_layout_content
    </main>

    <x-shop::footer />

    @stack('scripts')

</body>
</html>
```

--------------------------------

### File Path for Default Blade Layout

Source: https://visual.bagistoplus.com/building-theme/adding-layouts

Specifies the recommended directory path for creating the `default.blade.php` layout file within a Bagisto Visual theme.

```text
resources/views/layouts/default.blade.php
```

--------------------------------

### Recommended Semantic Class Usage for Layout

Source: https://visual.bagistoplus.com/building-theme/best-practices/styling

Illustrates the recommended approach for applying color system tokens using semantic CSS classes (e.g., `bg-surface`, `text-on-surface`). This method ensures that UI elements are consistent and theme-compatible, adapting automatically to different color schemes.

```blade
<div class="bg-surface text-on-surface p-6 rounded">
  <h2 class="text-secondary">Section Title</h2>
  <p class="text-neutral">Section body content goes here.</p>
</div>
```

--------------------------------

### Register Sections by Discovering a Directory

Source: https://visual.bagistoplus.com/building-theme/adding-sections/creating-section

Manually register sections located outside the default discovery paths by specifying a directory using `Visual::discoverSectionsIn()`. For sections within packages, a vendor prefix can be added to prevent naming conflicts and ensure proper identification.

```php
Visual::discoverSectionsIn(base_path('modules/Shared/Sections'));
```

```php
Visual::discoverSectionsIn(
    base_path('modules/Shared/Sections'),
    'vendor-prefix'
);
```

--------------------------------

### Define and Use Product Selector in Bagisto Visual

Source: https://visual.bagistoplus.com/core-concepts/settings/types

Illustrates how to define a product dropdown selector using `BagistoPlus\Visual\Settings\Product` in PHP settings and how to conditionally render a product card in a Blade template based on the selected product.

```php
use BagistoPlus\Visual\Settings\Product;

public static function settings(): array
{
    return [
        Product::make('featured_product', 'Featured Product'),
    ];
}
```

```blade
@if ($section->settings->featured_product)
    <x-shop::product-card :product="$section->settings->featured_product" />
@endif
```

--------------------------------

### Register a Single Section Class

Source: https://visual.bagistoplus.com/building-theme/adding-sections/creating-section

Manually register a specific section class using `Visual::registerSection()`. For sections belonging to theme packages, it's crucial to include a vendor prefix to ensure unique identification and prevent conflicts if multiple themes define sections with the same slug.

```php
Visual::registerSection(\App\Custom\Sections\PromoBanner::class);
```

```php
Visual::registerSection(
    \Themes\AwesomeTheme\Sections\AnnouncementBar::class,
    'awesome-theme'
);
```

--------------------------------

### Color Scheme Definition and Application

Source: https://visual.bagistoplus.com/building-theme/best-practices/styling

Describes how color schemes are defined and applied within Bagisto Visual themes, enabling multiple visual styles and merchant control. Schemes are defined using the ColorSchemeGroup setting type and applied via a 'data-color-scheme' attribute.

```APIDOC
ColorScheme:
  Definition:
    - Defined by theme using ColorSchemeGroup setting type.
    - Each scheme includes:
      - key: Unique identifier (e.g., `default`, `dark`, `highlight`)
      - label: Display name in Visual Editor
      - semantic_tokens: Complete set of all color roles
  Application:
    - `default` (or first) scheme applies to entire page.
    - Sections can override global scheme using ColorScheme setting.
    - Applied via `data-color-scheme` attribute, scoping CSS variables.
  Constraints:
    - Every scheme must define a value for all documented color roles to ensure compatibility.
```

--------------------------------

### Product Template File Location

Source: https://visual.bagistoplus.com/core-concepts/templates/available

The file path for the Product Template, used to display the details of a single product.

```plaintext
/theme/resources/views/templates/product.json
```

--------------------------------

### Edit Customer Address Form (Blade)

Source: https://visual.bagistoplus.com/core-concepts/templates/available

Provides a Blade template example for a form allowing customers to update their shipping or billing address. The form uses POST and PUT methods, includes CSRF protection, and fields for address lines, city, state, postcode, and phone number.

```blade
<section>
  <h2>Edit Address</h2>

  <form method="POST" action="{{ route('shop.customer.address.update', $address->id) }}">
    @csrf
    @method('PUT')

    <input type="text" name="address1[0]" value="{{ $address->address1[0] }}" placeholder="Address" required />
    <input type="text" name="city" value="{{ $address->city }}" placeholder="City" required />
    <input type="text" name="state" value="{{ $address->state }}" placeholder="State" required />
    <input type="text" name="postcode" value="{{ $address->postcode }}" placeholder="Postal Code" required />
    <input type="text" name="phone" value="{{ $address->phone }}" placeholder="Phone" required />

    <button type="submit">Update Address</button>
  </form>
</section>
```

--------------------------------

### Index Template File Location

Source: https://visual.bagistoplus.com/core-concepts/templates/available

The file path for the Index Template, which serves as the homepage of the storefront.

```plaintext
/theme/resources/views/templates/index.yaml
```

--------------------------------

### APIDOC: BagistoPlus\Visual\Sections\Block Class Reference

Source: https://visual.bagistoplus.com/building-theme/adding-sections/defining-section-schema

This API documentation details the `Block` class used for defining repeatable content structures in the BagistoPlus Visual Editor. It outlines the parameters required for block creation and available configuration methods, including `limit` for maximum instances and `settings` for block-specific fields.

```APIDOC
BagistoPlus\Visual\Sections\Block Class:

Parameters for Block::make():
  type: (string) - Internal identifier (e.g., `announcement`, `feature`)
  name: (string, optional) - Display name shown in the editor UI. If omitted, defaults to the title-cased version of the type (e.g., 'testimonial' → 'Testimonial').

Configuration Methods:
  limit(int): Sets the maximum number of blocks of this type that can be added (default: 16).
  settings(array): Defines the setting fields for the block, similar to section settings.
```

--------------------------------

### Blade Template to Display Customer Downloadable Products

Source: https://visual.bagistoplus.com/core-concepts/templates/available

Provides a Blade template to list downloadable products that a customer has purchased. It iterates through the customer's downloadable products and offers a direct download link for each item.

```Blade
<section>
  <h2>My Downloadable Products</h2>

  @foreach (auth('customer')->user()->downloadable_products as $download)
    <div class="downloadable-item">
      <p>{{ $download->name }}</p>
      <a href="{{ route('shop.customer.downloadable.download', $download->id) }}">Download</a>
    </div>
  @endforeach
</section>
```

--------------------------------

### PHP: Defining Default Data for Visual Editor Sections

Source: https://visual.bagistoplus.com/building-theme/adding-sections/defining-section-schema

This PHP snippet demonstrates how to set the initial state for a section in the BagistoPlus Visual Editor using the $default static property. It defines default values for section settings and pre-populates blocks, ensuring the section is immediately functional and visually populated when added.

```php
protected static array $default = [
    'settings' => [
        'text' => 'Welcome to our store',
        'background_color' => '#facc15',
        'text_color' => '#000000',
    ],
    'blocks' => [
        ['type' => 'announcement', 'text' => 'Extended returns until Jan 31'],
        ['type' => 'announcement', 'text' => 'Free shipping on orders over $50'],
    ],
];
```

--------------------------------

### Bagisto Visual Text Setting Type Definition and Usage

Source: https://visual.bagistoplus.com/core-concepts/settings/types

Demonstrates how to define a single-line text input setting using `Text::make` in PHP, including `default` and `placeholder` attributes. Also shows how to display the setting's value in a Blade template.

```php
use BagistoPlus\Visual\Settings\Text;

public static function settings(): array
{
    return [
        Text::make('title', 'Heading')
            ->default('Welcome to our store')
            ->placeholder('Enter heading here...'),
    ];
}
```

```blade
@if ($section->settings->text)
    <h1>{{ $section->settings->text }}</h1>
@endif
```

--------------------------------

### Define and Use CMS Page Selector in Bagisto Visual

Source: https://visual.bagistoplus.com/core-concepts/settings/types

Shows how to define a CMS page dropdown selector using `BagistoPlus\Visual\Settings\CmsPage` in PHP settings and how to create a link to the selected CMS page in a Blade template.

```php
use BagistoPlus\Visual\Settings\CmsPage;

public static function settings(): array
{
    return [
        CmsPage::make('policy_page', 'Policy Page'),
    ];
}
```

```blade
@if ($section->settings->policy_page)
    <a href="{{ route('cms.page', $section->settings->policy_page->url_key) }}">
        {{ $section->settings->policy_page->page_title }}
    </a>
@endif
```

--------------------------------

### Optimizing Data Preparation for Blade Templates

Source: https://visual.bagistoplus.com/building-theme/best-practices/performance

Highlights the importance of preparing data in the controller layer (PHP) before passing it to Blade views. This avoids expensive operations like database queries or complex filtering directly within Blade loops, which can significantly degrade view rendering performance.

```php
return [
    'products' => Product::limit(4)->get(),
];
```

```blade
@foreach (Product::all() as $product)
```

--------------------------------

### Bagisto Visual Setting Type Attributes API Reference

Source: https://visual.bagistoplus.com/core-concepts/settings/types

Comprehensive API documentation for various setting types in Bagisto Visual, detailing standard attributes applicable to all settings and specific attributes for Text, Textarea, and Radio types. This includes unique identifiers, labels, default values, helper text, placeholders, and options for selection fields.

```APIDOC
Standard Setting Attributes:
  id: The unique identifier for the setting. (Required)
  label: The text label shown to merchants. (Required)
  default: The default value assigned to the field. (Optional)
  info: Optional helper text shown below the field. (Optional)

Text Setting Type Additional Attribute:
  placeholder: A placeholder value for the input. (Optional)

Textarea Setting Type Additional Attribute:
  placeholder: A placeholder value for the textarea. (Optional)

Radio Setting Type Additional Attribute:
  options: Array of options formatted as 'value' => 'Label' or [ 'value' => ..., 'label' => ... ]. (Required)
```

--------------------------------

### Bagisto Visual Editor Live Update Blade Directives

Source: https://visual.bagistoplus.com/building-theme/adding-sections/integrating-editor

Documentation for Blade directives that enable instant, client-side updates for section settings in the Bagisto Visual editor, avoiding full page re-renders. These helpers inject metadata for the editor to update the live preview.

```APIDOC
$section->liveUpdate() / $block->liveUpdate():
  ->text(string $settingId)
    Description: Updates the element's textContent whenever the specified setting changes.
    Example: <h1 {{ $section->liveUpdate()->text('heading') }}>\n  {{ $section->settings->heading }}\n</h1>
  ->html(string $settingId)
    Description: Updates the element's innerHTML with the new setting value.
    Example: <div {{ $section->liveUpdate()->html('html_content') }}>\n  {!! $section->settings->html_content !!}\n</div>
  ->outerHtml(string $settingId)
    Description: Replaces the entire element (outerHTML) with the setting value.
    Example: <div {{ $section->liveUpdate()->outerHtml('html_block') }}>\n  {!! $section->settings->html_block !!}\n</div>
  ->attr(string $settingId, string $attributeName)
    Description: Updates the specified HTML attribute (e.g. src, href, alt) with the setting value.
    Example: <img\n  src="{{ $section->settings->image }}"\n  {{ $section->liveUpdate()->attr('image', 'src') }}>
```

--------------------------------

### PHP: Defining Section Settings for Visual Editor

Source: https://visual.bagistoplus.com/building-theme/adding-sections/defining-section-schema

This PHP snippet demonstrates how to define configurable settings for a section within the BagistoPlus Visual Editor. Using Text::make, Link::make, and Color::make, it specifies fields like text, call to action link, background, and text colors that appear in the section's configuration panel.

```php
use BagistoPlus\Visual\Settings\Color;
use BagistoPlus\Visual\Settings\Link;
use BagistoPlus\Visual\Settings\Text;

public static function settings(): array
{
    return [
        Text::make('text', 'Text')->default('Free shipping on all orders'),
        Link::make('link', 'Call to Action'),
        Color::make('background_color', 'Background')->default('#facc15'),
        Color::make('text_color', 'Text Color')->default('#000000'),
    ];
}
```

--------------------------------

### Responsible Image Loading and Sizing in Blade

Source: https://visual.bagistoplus.com/building-theme/best-practices/performance

Illustrates best practices for image loading in Blade templates. This includes adding `loading="lazy"` for images not immediately visible on first render and defining `width` and `height` attributes to prevent layout shifts (CLS) and improve page rendering performance.

```blade
<img
  src="{{ $section->settings->image }}"
  alt="{{ $section->settings->alt }}"
  width="800"
  height="400"
  loading="lazy"
/>
```

--------------------------------

### Reviews Template File Location

Source: https://visual.bagistoplus.com/core-concepts/templates/available

Specifies the file path for the Reviews Template within the theme resources, indicating where the template definition can be found.

```plaintext
/theme/resources/views/templates/account/reviews.yaml
```

--------------------------------

### Bagisto Visual Theme Folder Structure

Source: https://visual.bagistoplus.com/core-concepts/architecture

This snippet illustrates the standard directory layout for a Bagisto Visual theme, showing where different components like views, layouts, sections, templates, and PHP classes for custom sections are located.

```plaintext
/theme/
├── resources/
│   ├── views/
│       ├── components/     # Custom Blade or Livewire components
│       ├── layouts/        # Layouts (default layout is mandatory)
│       ├── sections/       # Section Blade files
│       ├── templates/      # Page templates (JSON, YAML, or Blade)
├── src/
│   ├── Sections/           # PHP classes for custom sections
```

--------------------------------

### Basic JSON/YAML Template Structure for Bagisto Visual

Source: https://visual.bagistoplus.com/core-concepts/templates/json-template

Illustrates the fundamental structure of a JSON or YAML template, showing the 'sections' object for defining page components and the 'order' array for their rendering sequence.

```JSON
{
  "sections": {
    "hero": {
      "type": "visual-hero",
      "settings": {
        "image": "https://example.com/banner.jpg",
        "size": "medium"
      }
    }
  },
  "order": ["hero"]
}
```

```YAML
sections:
  hero:
    type: visul-hero
    settings:
      image: https://example.com/banner.jpg
      size: medium

order:
  - hero
```

--------------------------------

### Login Template File Location

Source: https://visual.bagistoplus.com/core-concepts/templates/available

The file path for the Login Template, which displays the customer login form.

```plaintext
/theme/resources/views/templates/auth/login.blade.php
```

--------------------------------

### Define Image Setting for Bagisto Section in PHP

Source: https://visual.bagistoplus.com/building-theme/best-practices/accessibility

Shows how to define an image setting using `Image::make` within a Bagisto section's configuration in PHP.

```PHP
Image::make('image', 'Hero Image')
```