Cart subtotal: {{ core()->currency($cart->base_sub_total) }}
@endif ``` ## category The **Category Template** is used to display a list of products belonging to a specific category. It typically includes features like filters, sorting options, product grids, and category banners. Category templates support custom variants such as `category.sale`. Custom category templates receive the same `$category` variable as the default category template. ### Location ```plaintext /theme/resources/views/templates/category.json ``` ### Shared variables | Variable | Type | Description | | --------- | -------------- | ------------------------------------- | | $category | Category model | The currently viewed category object. | ### Example Example inside a section Blade file: ```blade @if (isset($category)){{ $category->name }}
{{ $category->description }}
@endif ``` ## checkout-success The **Checkout Success Template** displays the order confirmation page after a successful checkout. It shows the customer a summary of their completed order and any next steps or messages. ### Location ```plaintext /theme/resources/views/templates/checkout-success.yaml ``` ### Shared variables | Variable | Type | Description | | -------- | ----------- | ----------------------------------- | | $order | Order model | The recently placed order instance. | ### Example Example inside a section Blade file: ```blade @if (isset($order))Thank you for your order #{{ $order->id }}!
Total: {{ core()->currency($order->base_grand_total) }}
@endif ``` ## checkout The **Checkout Template** is used to display the checkout process, including customer information, shipping, and payment details. It typically shows a summary of the cart and allows customers to complete their purchase. ### Location ```plaintext /theme/resources/views/templates/checkout.yaml ``` ### Shared variables | Variable | Type | Description | | -------- | ---------- | ----------------------------------- | | $cart | Cart model | The current shopping cart instance. | ### Example Example inside a section Blade file: ```blade @if (isset($cart))Cart subtotal: {{ core()->currency($cart->base_sub_total) }}
Number of items: {{ $cart->items->count() }}
@endif ``` ## compare The **Compare Template** is used to display a side-by-side comparison of selected products. It allows customers to view product attributes and differences to help them make purchasing decisions. ### Location ```plaintext /theme/resources/views/templates/compare.json ``` ### Shared variables | Variable | Type | Description | | --------------------- | ----- | -------------------------------------------- | | $comparableAttributes | array | Attributes available for product comparison. | ### Example Example inside a section Blade file ```blade @if (!empty($comparableAttributes))Compare Products By:
-
@foreach ($comparableAttributes as $attribute)
- {{ $attribute['name'] }} @endforeach
Error {{ $errorCode }}
Sorry, something went wrong.
@endif ``` ## index The **Index Template** is used to display the homepage of the storefront. It typically features banners, featured collections, featured products, and custom landing page content. ### Location ```plaintext /theme/resources/views/templates/index.yaml ``` ### Shared variables There are **no specific shared variables** automatically passed to sections in the index template. Sections are responsible for fetching and displaying the homepage content themselves. ### Example Since no variable is automatically exposed, a typical section might look like: ```bladeWelcome to our Store!
{{ $page->title }}
{!! $page->content !!}
@endif
```
## product
The **Product Template** is used to display the details of a single product.
It includes the product title, description, images, price, reviews, and add-to-cart functionality.
Product templates support custom variants such as `product.gift-box`. Custom product templates receive the same `$product` variable as the default product template.
### Location
```plaintext
/theme/resources/views/templates/product.json
```
### Shared variables
| Variable | Type | Description |
| -------- | --------------- | ----------------------------------- |
| $product | `Product` model | The product currently being viewed. |
### Example
Example inside a section Blade file:
```blade
@if (isset($product))
{{ $product->name }}
{{ $product->short_description }}
Price: {{ core()->currency($product->price) }}
@endif ``` ## search The **Search Template** is used to display search results based on a customer’s query. It renders product listings that match keywords, tags, categories, or other filters. ### Location ```plaintext /theme/resources/views/templates/search.json ``` ### Shared variables There are **no specific shared variables** exposed automatically by the search template. Sections should retrieve search results using request query parameters or internal APIs. ### Example A simple section might handle search results like this: ```blade @php $query = request()->get('term'); @endphpResults for "{{ $query }}"
@livewire('search-results', ['term' => $query]) ``` ## auth/forgot-password The **Forgot Password Template** displays a form that allows users to request a password reset link. It is typically accessed from the login page if a user forgets their credentials. ### Location ```plaintext /theme/resources/views/templates/auth/forgot-password.blade.php ``` ### Shared variables There are **no shared variables** exposed by this template. ### Example ```bladeForgot your password?
Customer Login
Create an Account
Reset Your Password
Add New Address
My Addresses
@foreach (auth('customer')->user()->addresses as $address){{ $address->address1[0] }}, {{ $address->city }}
{{ $address->state }}, {{ $address->country }}
{{ $address->phone }}
EditMy Downloadable Products
@foreach (auth('customer')->user()->downloadable_products as $download){{ $download->name }}
DownloadEdit Address
Edit Profile
Order #{{ $order->id }}
Order Date: {{ $order->created_at->format('M d, Y') }}
Total: {{ core()->currency($order->base_grand_total) }}
Items:
-
@foreach ($order->items as $item)
- {{ $item->name }} × {{ $item->qty_ordered }} @endforeach
My Orders
My Orders
@foreach (auth('customer')->user()->orders as $order)Order #{{ $order->id }} placed on {{ $order->created_at->format('M d, Y') }}
Total: {{ core()->currency($order->base_grand_total) }}
View DetailsMy Profile
Name: {{ auth('customer')->user()->first_name }} {{ auth('customer')->user()->last_name }}
Email: {{ auth('customer')->user()->email }}
Edit ProfileMy Reviews
@foreach ($reviews as $review){{ $review->product->name }}
Rating: {{ $review->rating }} / 5
{{ $review->comment }}
My Wishlist
@foreach (auth('customer')->user()->wishlist_items as $item){{ $item->product->name }}
Removeeditor_attributes }} class="announcement-bar" style="background-color: {{ $section->settings->background_color }}; color: {{ $section->settings->text_color }}">
{{ $section->settings->text }}
```
✅ A `$section` object representing the section is automatically injected into each Blade view. Setting values can be accessed via `$section->settings`.
---
---
url: /core-concepts/regions.md
---
# Regions
Regions are **customizable zones shared across all templates** in your theme. They allow merchants to fully control shared areas like headers and footers through the Visual Editor—adding, removing, and rearranging sections without touching code.
## What Are Regions?
Regions are layout zones where sections can be placed and rendered. Think of them as placeholders in your layouts that can contain one or more sections. Common examples include:
* **Header** - Site navigation, logo, search, cart preview
* **Footer** - Company info, links, newsletter signup
Unlike page-specific templates, regions are **shared across your entire store**. When a merchant customizes the header region, those changes appear on every page that includes the header.
## Why Regions Matter
### The Problem with v1 (Single Static Section)
In Visual v1, shared elements like headers and footers were **single sections** that merchants could customize in the Visual Editor. However:
* Merchants could only configure the **one header section** provided by the developer
* They couldn't **add additional sections** to the header/footer zones (e.g., announcement bar above header)
* They couldn't **remove or reorder** multiple sections in these zones
* Adding new elements required a developer to modify the header section code
**Example v1 limitation**: If a merchant wanted to add a promotional announcement bar above the header, they needed a developer to either add it to the existing header section code or create a custom solution.
### The v2 Solution (Customizable Regions)
Regions make shared areas **fully customizable** through the Visual Editor by allowing **multiple sections** in header/footer zones. Merchants can:
* ✅ Add new sections to the header or footer region (announcement bars, promotional banners, etc.)
* ✅ Remove or hide existing sections
* ✅ Reorder sections visually within the region
* ✅ Configure each section's settings independently
* ✅ Create multiple header/footer variations
**Same example in v2**: Merchants can simply add an announcement bar section to the header region themselves—no code required. The header region can contain multiple sections that merchants manage.
## Region Structure
Each region has the following structure:
```json
{
"id": "header", // Required unique identifier (used in @visualRegion('header'))
"name": "Header", // Required display name (shown in editor)
"sections": { // Sections in this region
"announcement": {
"type": "visual-announcement-bar",
"settings": { ... }
},
"main-header": {
"type": "visual-header",
"settings": { ... },
"blocks": { ... },
"order": [ ... ]
}
},
"order": ["announcement", "main-header"] // Section render order
}
```
**Properties:**
| Property | Required | Description | Example |
| -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| **`id`** | Yes | Unique identifier used in the `@visualRegion('id')` directive to render the region | `"header"`, `"footer"` |
| **`name`** | Yes | Display name shown in the Visual Editor | `"Site Header"`, `"Main Footer"` |
| **`sections`** | No | Object containing sections that belong to this region. Each section follows the same structure as sections in templates (with `type`, `settings`, `blocks`, and `order` properties). See [Templates](./templates/overview.md) | See examples below |
| **`order`** | No | Array of section IDs defining render order. If not defined, sections are rendered in the order they appear in the `sections` object. | `["announcement", "main-header"]` |
## Defining Regions
Regions use the same formats as templates: **JSON**, **YAML**, or **PHP**.
### Method 1: JSON Format
Create a region file in `resources/views/regions/`:
```json
// resources/views/regions/header.json
{
"id": "header",
"name": "Header",
"blocks": {
"announcement-bar": {
"type": "@visual-debut/announcement-bar"
},
"main-header": {
"type": "@visual-debut/header",
"properties": {
"content_width": "container"
}
}
},
"order": ["announcement-bar", "main-header"]
}
```
### Method 2: YAML Format
```yaml
# resources/views/regions/footer.yaml
id: footer
name: Footer
blocks:
newsletter:
type: '@visual-debut/newsletter'
properties:
heading: 'Stay Connected'
main-footer:
type: '@visual-debut/footer'
properties:
content_width: 'container'
order:
- newsletter
- main-footer
```
### Method 3: PHP Format
PHP templates provide IDE support and type safety:
```php
id('header')
->name('Header')
->section('announcement-bar', '@visual-debut/announcement-bar')
->section('main-header', '@visual-debut/header', fn($section) => $section
->properties([
'content_width' => 'container',
])
->blocks([
PresetBlock::make('@visual-debut/group')
->id('container-logo')
->name('Logo')
->blocks([
PresetBlock::make('@visual-debut/logo')->name('Logo'),
]),
PresetBlock::make('@visual-debut/group')
->id('container-nav')
->name('Navigation')
->blocks([
PresetBlock::make('@visual-debut/header-nav')->name('Navigation'),
]),
])
)
->order(['announcement-bar', 'main-header']);
```
> \[!NOTE]
> The region filename should match the `id` property. For example, a region with `"id": "header"` should be saved as `header.json`, `header.yaml`, or `header.visual.php`.
## Using Regions in Layouts
Include regions in your layout files using the `@visualRegion()` directive:
```blade
@include('shop::partials.head')
'; } } ``` ### BladeBlock Uses Blade components instead of Blade views. Blade components allow you to leverage component features like slots, component attributes, and encapsulated logic. ```php use BagistoPlus\Visual\Block\BladeBlock; class Card extends BladeBlock { protected static string $view = 'shop::blocks.card'; // Points to a Blade component public static function settings(): array { return [ // Settings configuration ]; } } ``` The difference is that the view is treated as a Blade component rather than a simple template. ### LivewireBlock Blocks powered by Livewire for dynamic, interactive components. ```php use BagistoPlus\Visual\Block\LivewireBlock; class InteractiveBlock extends LivewireBlock { protected static string $component = 'shop.blocks.interactive-block'; // Livewire component methods } ``` ## Static Blocks Static blocks enable theme developers to have more control over the layout of their sections. They are called static blocks because they are **statically rendered** in Blade instead of dynamically rendered through the theme editor. By default, blocks are **dynamic** - merchants can add, remove, reorder, and duplicate them in the theme editor. Static blocks, however, are fixed in place by the developer. **Static blocks can be used in various scenarios:** * **Bring structure to the theme** - In cases where the theme design requires blocks that should not be moved or deleted by the merchant (e.g., a hero section title that must always appear, or an icon that must stay paired with text) * **Conditionally render blocks** - Show or hide blocks based on settings or logic (e.g., display a promotional banner only when enabled) * **Maintain layout control** - Ensure specific blocks remain in their intended positions **In all cases, static blocks maintain the flexibility to customize the settings.** Merchants can't move or delete static blocks, but they can still configure their appearance, content, and behavior through the settings panel. See [Static Blocks](/building-theme/adding-blocks/static-blocks) for implementation details. ## Container Blocks (Nesting) Some blocks can **accept child blocks**, enabling deep nesting and sophisticated layouts. These are called **container blocks**. **Examples of container blocks:** * **Columns**: Multi-column layouts with blocks in each column * **Tabs**: Tabbed content with blocks in each tab * **Accordion**: Collapsible sections with blocks inside * **Container**: Generic wrapper for grouping blocks Merchants can nest blocks up to 8 levels deep, creating complex layouts like: * Columns containing tabs, each tab containing images and testimonials * Accordions with product blocks and buttons inside * Multi-column hero sections with nested content See [Container Blocks](/building-theme/adding-blocks/container-blocks) for implementation details. ## Next Steps Ready to start working with blocks? Here's your learning path: 1. **[Creating a Block](/building-theme/adding-blocks/creating-block)**: Step-by-step guide to creating your first block 2. **[Block Attributes](/building-theme/adding-blocks/block-schema)**: Configure settings and nesting 3. **[Presets](/core-concepts/presets)**: Create quick-start templates for blocks 4. **[Static Blocks](/building-theme/adding-blocks/static-blocks)**: Render blocks in Blade templates 5. **[Container Blocks](/building-theme/adding-blocks/container-blocks)**: Build blocks that accept children --- --- url: /core-concepts/presets.md --- # Presets Presets provide pre-configured templates for both blocks and sections, allowing merchants to quickly add common variations without manual configuration. Think of them as "starter templates" or "quick-start options" that appear in the theme editor. You can define presets in two ways: * **Inline**: Using the `presets()` method directly in your block/section class * **Standalone**: Creating dedicated preset classes that extend `Preset` ## What Are Presets? When merchants add a block or section in the Visual theme editor, they can choose from a list of **presets** - pre-configured variations with different settings, layouts, and child blocks already set up.  ## Why Use Presets? ✅ **Faster setup** - Merchants get started quickly with sensible defaults ✅ **Better UX** - Guide merchants toward common patterns ✅ **Consistency** - Ensure brand-aligned variations ✅ **Discoverability** - Show what's possible with your blocks/sections ## Basic Presets Define presets by overriding the presets() method: ```php settings([ 'text' => t('your-theme::presets.primary_cta.text'), 'style' => 'primary', 'size' => 'large', ]), ]; } } ``` ## Preset Structure Each preset can have these properties: | Property | Type | Description | | ----------------- | ------ | ---------------------------------------------- | | `name` | string | **Required**. Display name in theme editor | | `description` | string | Optional description shown to merchants | | `icon` | string | Icon identifier (e.g., `heroicon-o-star`) | | `category` | string | Group presets into categories | | `previewImageUrl` | string | URL to preview image | | `settings` | array | Default settings values (block settings) | | `children` | array | Default child blocks (for containers/sections) | ### Example ```php use BagistoPlus\Visual\Support\Preset; use function BagistoPlus\Visual\t; public static function presets(): array { return [ Preset::make(t('your-theme::presets.alerts.success.name')) ->description(t('your-theme::presets.alerts.success.description')) ->icon('heroicon-o-check-circle') ->category(t('your-theme::presets.categories.alerts')) ->previewImageUrl('/images/presets/success-alert.png') ->settings([ 'message' => t('your-theme::presets.alerts.success.message'), 'type' => 'success', 'dismissible' => true, ]), Preset::make(t('your-theme::presets.alerts.error.name')) ->description(t('your-theme::presets.alerts.error.description')) ->icon('heroicon-o-x-circle') ->category(t('your-theme::presets.categories.alerts')) ->settings([ 'message' => t('your-theme::presets.alerts.error.message'), 'type' => 'error', 'dismissible' => true, ]), ]; } ``` ## Presets with Child Blocks Sections and container blocks can include pre-configured child blocks in their presets: ### Section Preset with Child Blocks ```php use BagistoPlus\Visual\Support\Preset; use BagistoPlus\Visual\Support\PresetBlock; use function BagistoPlus\Visual\t; public static function presets(): array { return [ Preset::make(t('your-theme::presets.hero_cta.name')) ->description(t('your-theme::presets.hero_cta.description')) ->icon('heroicon-o-photograph') ->category(t('your-theme::presets.categories.banners')) ->settings([ 'layout' => 'centered', 'background_color' => '#4f46e5', ]) ->blocks([ PresetBlock::make('heading') ->id('hero-title') ->settings([ 'text' => t('your-theme::presets.hero_cta.heading'), 'level' => 1, ]), PresetBlock::make('paragraph') ->id('hero-subtitle') ->settings([ 'text' => t('your-theme::presets.hero_cta.subtitle'), ]), PresetBlock::make('button') ->id('hero-cta') ->settings([ 'text' => t('your-theme::presets.hero_cta.button'), 'style' => 'primary', ]), ]), Preset::make(t('your-theme::presets.hero_signup.name')) ->description(t('your-theme::presets.hero_signup.description')) ->icon('heroicon-o-mail') ->category(t('your-theme::presets.categories.banners')) ->settings([ 'layout' => 'centered', ]) ->blocks([ PresetBlock::make('heading') ->settings(['text' => t('your-theme::presets.hero_signup.heading')]), PresetBlock::make('paragraph') ->settings(['text' => t('your-theme::presets.hero_signup.subtitle')]), PresetBlock::make('email-input'), PresetBlock::make('button') ->settings(['text' => t('your-theme::presets.hero_signup.button')]), ]), ]; } ``` ## PresetBlock API When defining child blocks in presets, use `PresetBlock::make()`: ```php use function BagistoPlus\Visual\t; PresetBlock::make('button') ->id('unique-id') // Semantic ID ->name(t('your-theme::presets.blocks.button.name')) // Display name in editor ->settings([...]) // Block settings values ->static() // Lock from editing ->children([...]) // Nested child blocks ->order(['id1', 'id2']) // Rendering order ``` ### Dynamic Sources in Presets Settings values in presets can use **dynamic sources** to resolve from runtime context: ```php PresetBlock::make('@awesome-theme/product-card') ->id('grid-card') ->static() ->settings([ 'productName' => '@product.name', // Resolves from context 'price' => '@product.price', 'image' => '@product.base_image.url', ]) ->children([ PresetBlock::make('@awesome-theme/product-image') ->settings([ 'src' => '@product.base_image.url', 'alt' => '@product.name', ]), PresetBlock::make('@awesome-theme/product-title') ->settings([ 'text' => '@product.name', 'url' => '@product.url', ]), ]) ``` The `@` prefix enables blocks to access: * Page context (variables passed from controllers) * Parent-shared data (via `share()` method) * Model properties using dot notation This is especially useful for static blocks that need to display different data based on loop context. **Learn more:** [Dynamic Sources](/core-concepts/dynamic-sources) ### PresetBlock Methods | Method | Description | | ----------------- | ----------------------------------------- | | `type(string)` | Block type (e.g., 'button', 'heading') | | `id(string)` | Unique semantic ID for the block | | `name(string)` | Custom display name in editor | | `settings(array)` | Block settings values | | `static(bool)` | Mark as static (non-editable by merchant) | | `children(array)` | Nested child blocks | | `order(array)` | Order of child block IDs | ## Reusable Preset Classes For reusable, shareable, or complex presets, you can define them as standalone classes instead of inline arrays. This approach is particularly useful for: * **Theme-wide presets** shared across multiple blocks/sections * **Complex configurations** with deep nesting * **Reusable templates** across different themes * **Version-controlled presets** maintained separately ### Creating a Standalone Preset Class Standalone preset classes extend `BagistoPlus\Visual\Support\Preset` and implement two key methods: ```php name(t('your-theme::presets.hero_banner.name')) ->description(t('your-theme::presets.hero_banner.description')) ->icon('heroicon-o-photograph') ->category(t('your-theme::presets.categories.banners')) ->settings([ 'layout' => 'centered', 'background_color' => '#4f46e5', 'padding' => 'large', ]) ->blocks([ PresetBlock::make('@your-theme/heading') ->id('hero-title') ->settings([ 'text' => t('your-theme::presets.hero_banner.heading'), 'level' => 1, 'color' => 'white', ]), PresetBlock::make('@your-theme/paragraph') ->id('hero-subtitle') ->settings([ 'text' => t('your-theme::presets.hero_banner.subtitle'), 'color' => 'white', ]), PresetBlock::make('@your-theme/button') ->id('hero-cta') ->settings([ 'text' => t('your-theme::presets.hero_banner.button'), 'style' => 'primary', 'size' => 'large', ]), ]); } } ``` ### Using PresetBlock Always use `PresetBlock` from the Visual package when defining child blocks in presets: ```php use BagistoPlus\Visual\Support\Preset; use BagistoPlus\Visual\Support\PresetBlock; use function BagistoPlus\Visual\t; public static function presets(): array { return [ Preset::make(t('your-theme::presets.hero_banner.name')) ->blocks([ PresetBlock::make('heading') ->settings(['text' => t('your-theme::presets.hero_banner.heading')]), PresetBlock::make('button') ->settings(['text' => t('your-theme::presets.hero_banner.button')]), ]), ]; } ``` The block type identifier can be: * **Simple name**: `'button'`, `'heading'` (for built-in or theme blocks) * **Namespaced**: `'@your-theme/button'`, `'@visual-debut/heading'` (explicit namespace) ### Example: Complex Nested Preset ```php name(t('your-theme::presets.feature_grid.name')) ->description(t('your-theme::presets.feature_grid.description')) ->category(t('your-theme::presets.categories.content')) ->settings([ 'layout' => 'grid', 'columns' => 3, ]) ->blocks([ // First feature PresetBlock::make('@your-theme/container') ->id('feature-1') ->settings(['alignment' => 'center']) ->children([ PresetBlock::make('@your-theme/icon') ->settings([ 'icon' => 'heroicon-o-lightning-bolt', 'size' => 'large', ]), PresetBlock::make('@your-theme/heading') ->settings([ 'text' => t('your-theme::presets.feature_grid.fast_shipping.title'), 'level' => 3, ]), PresetBlock::make('@your-theme/paragraph') ->settings([ 'text' => t('your-theme::presets.feature_grid.fast_shipping.text'), ]), ]), // Second feature PresetBlock::make('@your-theme/container') ->id('feature-2') ->settings(['alignment' => 'center']) ->children([ PresetBlock::make('@your-theme/icon') ->settings([ 'icon' => 'heroicon-o-shield-check', 'size' => 'large', ]), PresetBlock::make('@your-theme/heading') ->settings([ 'text' => t('your-theme::presets.feature_grid.secure_checkout.title'), 'level' => 3, ]), PresetBlock::make('@your-theme/paragraph') ->settings([ 'text' => t('your-theme::presets.feature_grid.secure_checkout.text'), ]), ]), // Third feature PresetBlock::make('@your-theme/container') ->id('feature-3') ->settings(['alignment' => 'center']) ->children([ PresetBlock::make('@your-theme/icon') ->settings([ 'icon' => 'heroicon-o-heart', 'size' => 'large', ]), PresetBlock::make('@your-theme/heading') ->settings([ 'text' => t('your-theme::presets.feature_grid.satisfaction.title'), 'level' => 3, ]), PresetBlock::make('@your-theme/paragraph') ->settings([ 'text' => t('your-theme::presets.feature_grid.satisfaction.text'), ]), ]), ]); } } ``` ### Organizing Preset Classes Store standalone preset classes in a dedicated directory: ``` your-theme/ └── src/ └── Presets/ ├── HeroBanner.php ├── FeatureGrid.php ├── TestimonialCarousel.php └── ClassicFooter.php ``` ### Registering Standalone Presets Bagisto Visual automatically discovers standalone preset classes from: * `app/Visual/Presets` * `packages/
{{ $section->settings->text }}
@endif ``` *** ### Textarea Multiline text input. Useful for longer descriptions or rich content areas. In addition to the standard attributes, Textarea type settings have the following attribute: | Attribute | Description | Required | | :------------ | :------------------------------------ | :------- | | `placeholder` | A placeholder value for the textarea. | No | ```php use BagistoPlus\Visual\Settings\Textarea; public static function settings(): array { return [ Textarea::make('description', 'Store Description') ->default('This is your store description.') ->placeholder('Write something about your store...'), ]; } ``` In Blade: ```blade @if ($section->settings->description){{ $section->settings->description }}
@endif ``` *** ### Checkbox Simple true/false toggle. Useful for enabling or disabling features. Checkbox settings do not have any additional attributes beyond the standard attributes, but support an alternative switch variant for a different visual style. ```php use BagistoPlus\Visual\Settings\Checkbox; public static function settings(): array { return [ Checkbox::make('show_banner', 'Show Banner') ->default(true), ]; } ``` #### Switch Variant Use the `asSwitch()` method to display the checkbox as a toggle switch instead of a standard checkbox: ```php Checkbox::make('enable_feature', 'Enable Feature') ->asSwitch() ->default(false), ``` In Blade: ```blade @if ($section->settings->show_banner) @endif ``` ::: info If `default` is unspecified, it defaults to `false`. ::: *** ### Radio Single option selection via radio buttons. Useful for choosing between predefined mutually exclusive options. In addition to the standard attributes, Radio type settings have the following attribute: | Attribute | Description | Required | | :-------- | :----------------------------------------------------------------------------------------- | :------- | | `options` | Array of options formatted as `'value' => 'Label'` or `[ 'value' => ..., 'label' => ... ]` | Yes | ```php use BagistoPlus\Visual\Settings\Radio; public static function settings(): array { return [ Radio::make('alignment', 'Alignment') ->options([ 'left' => 'Left', 'center' => 'Center', 'right' => 'Right', ]) ->default('center'), ]; } ``` Alternative format: ```php Radio::make('alignment', 'Alignment') ->options([ ['value' => 'left', 'label' => 'Left'], ['value' => 'center', 'label' => 'Center'], ['value' => 'right', 'label' => 'Right'], ]) ->default('center'); ``` In Blade: ```blade
{!! $section->settings->content !!}
@endif
@if ($section->settings->highlight)
{!! $section->settings->highlight !!}
@endif
```
***
### Font
Font picker input. Useful for allowing merchants to select fonts from the [Bunny Fonts](https://fonts.bunny.net/) catalog.
Font settings allow the merchant to select a web-safe font that is automatically loaded from Bunny Fonts.
```php
use BagistoPlus\Visual\Settings\Font;
public static function settings(): array
{
return [
Font::make('heading_font', 'Heading Font')->default('roboto'),
];
}
```
In Blade:
```blade
@if ($section->settings->heading_font)
@endif ``` This will render as: ```html
``` Additionally, you may use the following snippet to render any resources necessary to load the font ```blade @pushOnce('styles') {{ $section->settings->heading_font->toHtml() }} @endPushOnce ``` Will render: ```html ``` *** ### Icon Icon selection input. Useful for allowing merchants to choose an icon from the installed Blade Icon sets. Bagisto Visual ships with the [Lucide](https://lucide.dev/) icon set pre-installed by default. Developers can manually install and configure additional Blade Icons (like Heroicons, Tabler Icons, etc.) if needed. ```php use BagistoPlus\Visual\Settings\Icon; public static function settings(): array { return [ Icon::make('button_icon', 'Button Icon'), ]; } ``` In Blade: ```blade @if ($section->settings->button_icon) @svg($section->settings->button_icon, ['class' => 'w-6 h-6']) {!! $section->settings->button_icon->render(['class' => 'w-6 h-6']) !!} @endif ``` *** ### ColorScheme The `ColorScheme` setting allows merchants to choose a color scheme defined by the theme. Each color scheme is a named palette of colors (e.g., background, text, primary, etc.) and is defined in the theme using a `ColorSchemeGroup`. This setting is typically used in **section settings** to let the merchant apply predefined styles to specific areas of the storefront. *** > This setting **does not define color schemes** — it only lets the merchant pick one from those defined in the theme. *** ```php use BagistoPlus\Visual\Settings\ColorScheme; public static function settings(): array { return [ ColorScheme::make('color_scheme', 'Color Scheme') ->default('default'), ]; } ``` This creates a dropdown in the visual editor populated with all color schemes defined by the theme’s `ColorSchemeGroup`. **In Blade:** The recommended way to use the selected color scheme in your view is: ```blade
settings->color_scheme->attributes() !!}>
```
This will output:
```html
settings->heading_typography->attributes() }}> Welcome to our store
``` This outputs: ```htmlWelcome to our store
``` The `data-typography` attribute scopes typography CSS variables to this element. *** ### TypographyPresets The `TypographyPresets` setting type allows theme developers to define a **set of named typography presets** that merchants can reuse across multiple sections. Each typography preset is a collection of font properties (fontFamily, fontSize, lineHeight, etc.) that can be selected using a [Typography](#typography) setting. This is typically defined once in your theme's `config/settings.php` and is **editable by the merchant**. * Acts as the **central registry of available typography presets** * Enables consistency in text styling across sections * Supports responsive typography for fontSize and lineHeight * Merchants can add, edit, or remove presets in the theme editor #### Usage in `config/settings.php` ```php use BagistoPlus\Visual\Settings\TypographyPresets; return [ TypographyPresets::make('typography_presets', 'Typography Presets') ->presets([ 'heading' => [ 'fontFamily' => 'Inter', 'fontWeight' => '700', 'fontSize' => '2xl', 'lineHeight' => 'tight', 'fontStyle' => 'normal', 'letterSpacing' => 'normal', 'textTransform' => 'none', ], 'body' => [ 'fontFamily' => 'Inter', 'fontWeight' => '400', 'fontSize' => 'base', 'lineHeight' => 'normal', 'fontStyle' => 'normal', 'letterSpacing' => 'normal', 'textTransform' => 'none', ] ]), ]; ``` #### Generating CSS After defining typography presets, you must generate the CSS in your theme's layout file. This makes the typography styles available to all sections using the `Typography` setting. **Basic Usage:** ```blade {{-- layouts/default.blade.php --}} {{-- Load fonts from Bunny Fonts --}} @pushOnce('styles') @foreach ($theme->settings->typography_presets as $typography) {!! $typography->toHtml() !!} @endforeach @endPushOnce ``` This generates CSS for typography styles: ```css [data-typography='heading'] { --typography-font-family: 'Inter', sans-serif; --typography-font-style: normal; --typography-font-weight: 700; --typography-font-size: 1.5rem; --typography-line-height: 1.25; --typography-letter-spacing: 0em; --typography-text-transform: none; } [data-typography='body'] { --typography-font-family: 'Inter', sans-serif; --typography-font-style: normal; --typography-font-weight: 400; --typography-font-size: 1rem; --typography-line-height: 1.5; --typography-letter-spacing: 0em; --typography-text-transform: none; } ``` Render the font links for all typography presets once in your layout: ```blade {{ $theme->settings->typography_presets->fontLinks() }} ``` This generates HTML to load the configured font families from Bunny Fonts. When the same font is used across multiple presets, all configured weights and styles are grouped into one request: ```html ``` **With Custom Selectors:** You can also apply typography directly to HTML elements by passing a custom selector: ```blade ``` This generates CSS that applies to both the `data-typography` attribute AND the custom selector: ```css [data-typography='heading'], h1, h2, h3 { --typography-font-family: 'Inter', sans-serif; --typography-font-style: normal; --typography-font-weight: 700; --typography-font-size: 1.5rem; --typography-line-height: 1.25; --typography-letter-spacing: 0em; --typography-text-transform: none; } [data-typography='body'], p, li, td { --typography-font-family: 'Inter', sans-serif; --typography-font-style: normal; --typography-font-weight: 400; --typography-font-size: 1rem; --typography-line-height: 1.5; --typography-letter-spacing: 0em; --typography-text-transform: none; } ``` **Applying CSS Variables:** In your theme's CSS, apply the generated CSS variables to elements: ```css [data-typography] { font-family: var(--typography-font-family); font-style: var(--typography-font-style); font-weight: var(--typography-font-weight); font-size: var(--typography-font-size); line-height: var(--typography-line-height); letter-spacing: var(--typography-letter-spacing); text-transform: var(--typography-text-transform); } ``` #### Preset Format Each preset is an array with the following properties: | Property | Type | Description | Required | Values | | --------------- | ------------- | -------------------------------------- | -------- | -------------------------------------------------------------------------------------- | | `fontFamily` | string|null | Font family name | No | Any font family name | | `fontWeight` | string | Font weight | Yes | `100`, `200`, `300`, `400`, `500`, `600`, `700`, `800`, `900` | | `fontSize` | string|array | Font size token or responsive config | Yes | `xs`, `sm`, `base`, `lg`, `xl`, `2xl`, `3xl`, `4xl`, `5xl`, `6xl`, `7xl`, `8xl`, `9xl` | | `lineHeight` | string|array | Line height token or responsive config | Yes | `none`, `tight`, `snug`, `normal`, `relaxed`, `loose` | | `fontStyle` | string | Font style | Yes | `normal`, `italic` | | `letterSpacing` | string | Letter spacing token | Yes | `tighter`, `tight`, `normal`, `wide`, `wider`, `widest` | | `textTransform` | string | Text transform | Yes | `none`, `uppercase`, `lowercase`, `capitalize` | **Font Size Tokens:** | Token | CSS Value | Description | | ------ | --------- | ------------------ | | `xs` | 0.75rem | Extra small (12px) | | `sm` | 0.875rem | Small (14px) | | `base` | 1rem | Base size (16px) | | `lg` | 1.125rem | Large (18px) | | `xl` | 1.25rem | Extra large (20px) | | `2xl` | 1.5rem | 2x large (24px) | | `3xl` | 1.875rem | 3x large (30px) | | `4xl` | 2.25rem | 4x large (36px) | | `5xl` | 3rem | 5x large (48px) | | `6xl` | 3.75rem | 6x large (60px) | | `7xl` | 4.5rem | 7x large (72px) | | `8xl` | 6rem | 8x large (96px) | | `9xl` | 8rem | 9x large (128px) | **Line Height Tokens:** | Token | CSS Value | | --------- | --------- | | `none` | 1 | | `tight` | 1.25 | | `snug` | 1.375 | | `normal` | 1.5 | | `relaxed` | 1.625 | | `loose` | 2 | **Letter Spacing Tokens:** | Token | CSS Value | | --------- | --------- | | `tighter` | -0.05em | | `tight` | -0.025em | | `normal` | 0em | | `wide` | 0.025em | | `wider` | 0.05em | | `widest` | 0.1em | #### Responsive Typography Typography supports responsive configurations for `fontSize` and `lineHeight` using an array format with breakpoint keys: ```php TypographyPresets::make('typography_presets', 'Typography Presets') ->presets([ 'responsive-heading' => [ 'fontFamily' => 'Inter', 'fontWeight' => '700', 'fontSize' => [ '_default' => '2xl', // Default size 'mobile' => 'xl', // max-width: 639px 'tablet' => '2xl', // 640px - 1023px 'desktop' => '3xl', // min-width: 1024px ], 'lineHeight' => [ '_default' => 'tight', 'mobile' => 'snug', 'desktop' => 'tight', ], 'fontStyle' => 'normal', 'letterSpacing' => 'normal', 'textTransform' => 'none', ], ]); ``` **Breakpoints:** | Breakpoint | Media Query | Description | | ---------- | ---------------------------------------- | --------------- | | `_default` | (none) | Default value | | `mobile` | `max-width: 639px` | Mobile devices | | `tablet` | `min-width: 640px and max-width: 1023px` | Tablet devices | | `desktop` | `min-width: 1024px` | Desktop devices | Generated responsive CSS: ```css [data-typography='responsive-heading'] { --typography-font-size: 1.5rem; --typography-line-height: 1.25; } @media (max-width: 639px) { [data-typography='responsive-heading'] { --typography-font-size: 1.25rem; --typography-line-height: 1.375; } } @media (min-width: 1024px) { [data-typography='responsive-heading'] { --typography-font-size: 1.875rem; --typography-line-height: 1.25; } } ``` #### Behavior in the Theme Editor * Merchants can **add, edit, or remove** typography presets * Custom presets are assigned IDs like `typography-1`, `typography-2`, etc. * Theme-defined presets cannot be deleted (only custom ones can be removed) * Changes are immediately reflected in sections using the `Typography` setting #### Notes * Only one `TypographyPresets` setting should be defined per theme * Sections reference presets via the `Typography` setting, not directly * If no `TypographyPresets` is defined, `Typography` fields will not be functional * Load preset font families from Bunny Fonts with ` $theme->settings->typography_presets->fontLinks()` * Bunny Fonts is the only supported font provider. See the [Font](#font) setting type for more details on font loading *** ### Header Visual divider or label inside settings groups. Useful for organizing complex settings panels into meaningful sections. Unlike other settings, the Header type: * Does **not** require an `id` * Only needs a **label** (text that will be displayed as a title) * **Does not produce any setting data** (not available inside Blade) ```php use BagistoPlus\Visual\Settings\Header; use BagistoPlus\Visual\Settings\Color; use BagistoPlus\Visual\Settings\Text; public static function settings(): array { return [ Header::make('Design Options'), Color::make('background_color', 'Background Color') ->default('#ffffff'), Color::make('text_color', 'Text Color') ->default('#000000'), Header::make('Content Settings'), Text::make('heading', 'Heading Text') ->default('Welcome to our store'), Text::make('subheading', 'Subheading Text') ->default('Discover amazing products'), ]; } ``` > **Note:** Header settings are **only used inside the theme editor** to visually group fields. > They are not available inside Blade templates. --- --- url: /core-concepts/settings/theme-settings.md --- # Theme Settings ## Introduction Theme settings allow developers to define global customization options for a theme. These settings are available in the **Theme Editor** for merchants to modify things like colors, typography, social media links, and more. Theme settings are defined in a `settings.php` file located here: ```text theme/ ├── config/ │ └── settings.php ├── resources/ ├── src/ ├── ... ``` They provide a centralized way to control the visual style and key configuration of the entire storefront. ## File Structure Each theme settings file must return an **array of setting groups**. Each group contains: * `name`: The group title shown inside the theme editor. * `settings`: An array of Setting types (`Color`, `Text`, `Font`, etc.) available for merchants to configure. Example file: ```php t('awesome-theme::settings.groups.light_scheme'), 'settings' => [ Settings\Color::make('light_background_color', t('awesome-theme::settings.light_background_color')) ->default('#ffffff') ->info(t('awesome-theme::settings.light_background_color_info')), Settings\Color::make('light_primary_color', t('awesome-theme::settings.light_primary_color')) ->default('#92400e') ->info(t('awesome-theme::settings.light_primary_color_info')), // More color settings... ], ], [ 'name' => t('awesome-theme::settings.groups.typography'), 'settings' => [ Settings\Font::make('heading_font', t('awesome-theme::settings.heading_font')) ->default('Inter'), Settings\Font::make('body_font', t('awesome-theme::settings.body_font')) ->default('Roboto'), ], ], [ 'name' => t('awesome-theme::settings.groups.social_links'), 'settings' => [ Settings\Text::make('facebook_url', t('awesome-theme::settings.facebook_url')) ->default('https://www.facebook.com'), Settings\Text::make('instagram_url', t('awesome-theme::settings.instagram_url')) ->default('https://www.instagram.com'), Settings\Text::make('youtube_url', t('awesome-theme::settings.youtube_url')) ->default('https://www.youtube.com'), Settings\Text::make('tiktok_url', t('awesome-theme::settings.tiktok_url')) ->default('https://www.tiktok.com'), Settings\Text::make('twitter_url', t('awesome-theme::settings.twitter_url')) ->default('https://www.x.com'), Settings\Text::make('snapchat_url', t('awesome-theme::settings.snapchat_url')) ->default('https://www.snapchat.com'), ], ], ]; ``` Use Visual's `t()` helper for group names, labels, helper text, and default text that should adapt to the active locale until the merchant customizes it. `Text`, `Textarea`, and `RichText` settings are localized by default. Other setting types can opt in with `->localized()`. ## Accessing Theme Settings in Blade Theme settings are automatically injected into every view through the `$theme->settings` object. Example: ```blade ``` ## Best Practices * Always group related settings meaningfully for a better merchant experience. * Use informative labels and helper texts (`info()`) to guide merchants. * Provide sensible default values for each setting to ensure good first impressions. * Use consistent naming conventions (`light_primary_color`, `color_body_text`, etc.). --- --- url: /core-concepts/settings/conditional-visibility.md --- # Conditional Visibility You can show or hide settings based on other setting values using `visibleWhen()`. This creates a cleaner, more intuitive settings panel by only displaying relevant options. ## Basic Usage ```php Text::make('gridGap', 'Grid Gap') ->visibleWhen(fn($rule) => $rule->when('layout', 'grid')) ->default('1rem') ``` This setting will only be visible when the `layout` setting equals `'grid'`. ## Rule Methods The callback receives a `Rule` instance with these methods: ### when() Check if a field equals a value. ```php ->when(string $field, mixed $value) ``` **Example:** ```php ->visibleWhen(fn($rule) => $rule->when('layout', 'grid')) ``` ### whenNot() Check if a field does NOT equal a value. ```php ->whenNot(string $field, mixed $value) ``` **Example:** ```php ->visibleWhen(fn($rule) => $rule->whenNot('size', 'full')) ``` ### whenIn() Check if a field's value is in an array. ```php ->whenIn(string $field, array $values) ``` **Example:** ```php ->visibleWhen(fn($rule) => $rule->whenIn('layout', ['grid', 'flex'])) ``` ### whenNotIn() Check if a field's value is NOT in an array. ```php ->whenNotIn(string $field, array $values) ``` **Example:** ```php ->visibleWhen(fn($rule) => $rule->whenNotIn('alignment', ['left', 'right'])) ``` ### whenGt() / whenLt() Check if a field is greater than or less than a value. ```php ->whenGt(string $field, mixed $value) ->whenLt(string $field, mixed $value) ``` **Example:** ```php ->visibleWhen(fn($rule) => $rule->whenGt('columns', 1)) ``` ### whenTruthy() / whenFalsy() Check if a field is truthy or falsy. ```php ->whenTruthy(string $field) ->whenFalsy(string $field) ``` **Example:** ```php ->visibleWhen(fn($rule) => $rule->whenTruthy('showAdvanced')) ``` ## Complex Conditions Combine multiple conditions with AND/OR logic: ### Multiple AND Conditions Chain multiple `when()` calls for AND logic: ```php Select::make('justifyContent', 'Justify Content') ->visibleWhen(fn($rule) => $rule ->when('layout', 'grid') ->whenGt('columns', 1) ) ``` This setting is visible when `layout` is 'grid' AND `columns` is greater than 1. ### OR Logic Use the `or()` method for OR conditions: ```php Text::make('spacing', 'Spacing') ->visibleWhen(fn($rule) => $rule ->when('layout', 'grid') ->or(fn($r) => $r->when('type', 'image')) ) ``` This setting is visible when `layout` is 'grid' OR `type` is 'image'. ### Nested Logic Combine AND/OR for complex rules: ```php Select::make('borderRadius', 'Border Radius') ->visibleWhen(fn($rule) => $rule ->whenIn('layout', ['grid', 'flex']) ->whenTruthy('showAdvanced') ->or(fn($r) => $r->when('type', 'card')) ) ``` This setting is visible when: * (`layout` is 'grid' OR 'flex' AND `showAdvanced` is true) OR * (`type` is 'card') ## Real-World Examples ### Content Type Switcher ```php public static function settings(): array { return [ Select::make('contentType', 'Content Type') ->options([ 'image' => 'Image', 'video' => 'Video', 'text' => 'Text', ]) ->default('image'), Image::make('image', 'Image') ->visibleWhen(fn($rule) => $rule->when('contentType', 'image')), Text::make('videoUrl', 'Video URL') ->visibleWhen(fn($rule) => $rule->when('contentType', 'video')), Textarea::make('text', 'Text Content') ->visibleWhen(fn($rule) => $rule->when('contentType', 'text')), ]; } ``` ### Layout-Specific Options ```php public static function settings(): array { return [ Select::make('layout', 'Layout') ->options([ 'grid' => 'Grid', 'list' => 'List', 'masonry' => 'Masonry', ]) ->default('grid'), Range::make('columns', 'Columns') ->visibleWhen(fn($rule) => $rule->whenIn('layout', ['grid', 'masonry'])) ->min(1) ->max(6) ->default(3), Range::make('gap', 'Gap') ->visibleWhen(fn($rule) => $rule->when('layout', 'grid')) ->min(0) ->max(100) ->default(20), ]; } ``` ### Advanced Settings Toggle ```php public static function settings(): array { return [ Switch::make('showAdvanced', 'Show Advanced Settings') ->default(false), // Basic settings always visible Text::make('title', 'Title'), // Advanced settings only visible when toggle is on Range::make('maxWidth', 'Max Width') ->visibleWhen(fn($rule) => $rule->whenTruthy('showAdvanced')) ->min(200) ->max(1200), Select::make('animation', 'Animation') ->visibleWhen(fn($rule) => $rule->whenTruthy('showAdvanced')) ->options([ 'none' => 'None', 'fade' => 'Fade', 'slide' => 'Slide', ]), ]; } ``` ## Best Practices ### Keep Conditions Simple ```php // ✅ Clear and simple ->visibleWhen(fn($rule) => $rule->when('layout', 'grid')) // ❌ Overly complex ->visibleWhen(fn($rule) => $rule ->when('layout', 'grid') ->or(fn($r) => $r->when('layout', 'flex')) ->whenGt('columns', 2) ->or(fn($r) => $r->whenTruthy('force')) ) ``` ### Use Descriptive Field Names ```php // ✅ Clear field names ->visibleWhen(fn($rule) => $rule->when('showAdvancedOptions', true)) // ❌ Unclear field names ->visibleWhen(fn($rule) => $rule->when('flag', true)) ``` ### Provide Default Values Always set sensible defaults for conditionally visible settings, as they may be hidden when merchants first see the settings panel. ```php Text::make('gridGap', 'Grid Gap') ->visibleWhen(fn($rule) => $rule->when('layout', 'grid')) ->default('1rem') // ✅ Default provided ``` --- --- url: /core-concepts/dynamic-sources.md --- # Dynamic Sources Dynamic sources allow property values to be resolved from runtime context using `@path.to.value` syntax, enabling blocks and sections to access data from page variables, models, or parent-shared data. ## What Are Dynamic Sources? Dynamic sources provide a way to bind block properties to runtime data without hardcoding values. Instead of static property values, you use the `@` prefix followed by a path to reference data from: * **Page context** - Variables passed from controllers/views * **Parent blocks/sections** - Data shared via the `share()` method * **Models and objects** - Nested properties using dot notation * **Arrays and collections** - Indexed or keyed access **Static value** (hardcoded): ```json { "title": "iPhone 15 Pro", "price": 999 } ``` **Dynamic source** (runtime): ```json { "title": "@product.name", "price": "@product.price" } ``` At runtime, `@product.name` resolves to the actual product name from your context. ## Basic Syntax ### Simple Path Access a top-level context variable: ```json { "userName": "@user" } ``` ```php // Context return view('page', ['user' => 'John Doe']); // Resolves to $block->settings->userName; // "John Doe" ``` ### Dot Notation Navigate nested objects and arrays: ```json { "authorName": "@post.author.name", "authorEmail": "@post.author.email" } ``` ```php // Context $post = (object)[ 'author' => (object)[ 'name' => 'Jane Smith', 'email' => 'jane@example.com' ] ]; // Resolves to $block->settings->authorName; // "Jane Smith" $block->settings->authorEmail; // "jane@example.com" ``` ### Array Access Access array elements by index: ```json { "firstImage": "@product.images.0.url", "secondImage": "@product.images.1.url" } ``` ```php // Context $product = [ 'images' => [ ['url' => '/img1.jpg'], ['url' => '/img2.jpg'], ] ]; // Resolves to $block->settings->firstImage; // "/img1.jpg" $block->settings->secondImage; // "/img2.jpg" ``` ## Context Sources ### Page Context (Controller/View) Pass data from controllers or views to templates: ```php // ProductController.php public function show(Product $product) { return view('products.show', [ 'product' => $product, 'relatedProducts' => $product->related()->take(4)->get(), 'currency' => 'USD', ]); } ``` In your JSON/YAML template: ```yaml sections: - id: product-hero type: '@awesome-theme/product-hero' settings: name: '@product.name' price: '@product.price' description: '@product.description' currency: '@currency' ``` ### Parent Shared Data Parent blocks/sections share data with children using `share()`: ```php class ProductCard extends SimpleBlock { protected static array $accepts = [ '@awesome-theme/product-image', '@awesome-theme/product-title', '@awesome-theme/product-price', ]; public function share(): array { return [ 'product' => $this->block->settings->product ?? $this->context('product'), 'showPrices' => $this->block->settings->showPrices ?? true, ]; } } ``` Child blocks access shared data using `@` syntax in presets: ```php Preset::make('Product Card') ->blocks([ PresetBlock::make('@awesome-theme/product-image') ->settings([ 'src' => '@product.base_image.url', 'alt' => '@product.name', ]), PresetBlock::make('@awesome-theme/product-title') ->settings([ 'text' => '@product.name', ]), PresetBlock::make('@awesome-theme/product-price') ->settings([ 'amount' => '@product.price', 'show' => '@showPrices', ]), ]) ``` ## Using in Setting Defaults Dynamic sources can be used in setting defaults: ```php public static function settings(): array { return [ Text::make('productName', 'Product Name') ->default('@product.name'), Number::make('price', 'Price') ->default('@product.price'), Image::make('image', 'Image') ->default('@product.base_image.url'), ]; } ``` *** **Next:** [Templates Overview](/core-concepts/templates/overview) --- --- url: /building-theme/create-theme.md --- # Creating a New Theme Bagisto Visual makes it easy to create a new theme using a single command. ## Step 1: Generate a Theme To scaffold a brand new theme, run the following Artisan command: ```bash php artisan visual:make-theme "Awesome Theme" ``` By default, the theme will be placed under the `Themes` vendor namespace. *** ### Optional: Customize the Vendor Name You can also customize the vendor (namespace) if needed: ```bash php artisan visual:make-theme "Awesome Theme" --vendor="MyVendor" ``` This will generate the theme inside: ```text src/Packages/MyVendor/AwesomeTheme/ ``` If the `--vendor` option is not provided, it defaults to: ```text src/Packages/Themes/AwesomeTheme/ ``` ✅ This is useful if you're developing themes under different brand or client namespaces. ## Step 2: Theme Directory Structure Here’s what a freshly generated theme looks like: ```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/ │ ├── blocks/ # Blade views for blocks │ ├── 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/ │ ├── Blocks/ # PHP classes defining blocks │ │ ├── ExampleBlock.php │ │ └── ... │ ├── Sections/ # PHP classes defining sections │ │ ├── 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) ``` ✅ The `theme-preview.png` file will be used to visually represent your theme in the Theme Editor. ### Understanding Important Files #### `config/theme.php` Defines core metadata and configuration for your theme: ```php "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" ] ]; ``` #### `config/settings.php` Defines editable theme-level settings such as: * Colors * Fonts * Header and footer links * Social icons These settings are exposed in the Theme Editor and configurable by merchants. #### `resources/views/layouts/` Contains layout Blade files like `default.blade.php`. All pages render inside one of these layouts. #### `resources/views/templates/` Templates define full pages and reference a layout and a list of sections. They can be Blade, JSON, or YAML. #### `resources/views/sections/` Contains section Blade files. Each section is a reusable UI block that can be added to templates in the visual editor. ### Starting From a Starter Theme By default, the scaffold generates a **blank theme** with no layout, sections, or styles. If you prefer to start with a fully built base theme, you can clone the official Bagisto Visual starter theme: ```bash git clone https://github.com/bagistoplus/visual-debut packages/Themes/YourThemeName ``` Then, update the `composer.json` and `config/theme.php` files to reflect your own theme name and vendor. ✅ This gives you a complete, working theme based on Visual Debut, which you can customize freely — layout, colors, sections, templates, or styles. ## Step 3: Installing and Using the Theme Once the theme is generated, it is automatically configured inside your Bagisto project using Composer's local repository system. You can immediately install the theme by running: ```bash composer require themes/awesome-theme ``` ✅ No need to publish the theme package to Packagist or any remote server. You only need to publish the package if you intend to distribute or share it outside your current project. ## Step 4: Preview the Theme in Admin After installation, activate your theme in the admin panel: 1. Log into the Bagisto admin panel. 2. Go to **Bagisto Visual → Themes**. 3. You should see the newly installed theme listed. 4. Click on the **Preview** button to see a preview of the theme. 5. Optional: click of the **Customize** button to open the theme in visual editor. ✅ You can start working on your theme now. ## Next Steps Once your theme is generated, you can continue with: * [Adding Layouts](./adding-layouts.md) * [Creating Templates](./adding-templates.md) * [Creating Sections](./adding-sections/overview.md) * [Configuring Theme Settings](../core-concepts/settings/theme-settings.md) --- --- url: /building-theme/adding-layouts.md --- # Adding Layouts In Bagisto Visual, layouts define the **main HTML structure** of your pages. Layouts are Blade files that act as **wrappers** for all templates and sections. They typically include shared elements like the header, footer, meta tags, and asset loading. ## Creating the `default` Layout The most important layout file is **`default.blade.php`**. Create the file inside: ```text resources/views/layouts/default.blade.php ``` Example content for a basic `default.blade.php`: ```bladeWelcome to Awesome Theme
Your new store is ready to be customized.
@children
```
## presets
Defines pre-configured variations of the section that merchants can choose from when adding the section. Presets allow you to provide quick-start templates with predefined settings and blocks.
```php
use BagistoPlus\Visual\Support\Preset;
use BagistoPlus\Visual\Support\PresetBlock;
use function BagistoPlus\Visual\t;
public static function presets(): array
{
return [
Preset::make(t('awesome-theme::presets.hero.centered.name'))
->description(t('awesome-theme::presets.hero.centered.description'))
->settings([
'heading' => t('awesome-theme::presets.hero.centered.heading'),
'layout' => 'centered',
'background_color' => '#4f46e5',
])
->blocks([
PresetBlock::make('@awesome-theme/heading')
->id('hero-title')
->settings(['text' => t('awesome-theme::presets.hero.centered.heading'), 'level' => 1]),
PresetBlock::make('@awesome-theme/button')
->id('hero-cta')
->settings(['text' => t('awesome-theme::presets.hero.centered.cta'), 'style' => 'primary']),
]),
Preset::make(t('awesome-theme::presets.hero.image_left.name'))
->description(t('awesome-theme::presets.hero.image_left.description'))
->settings([
'heading' => t('awesome-theme::presets.hero.image_left.heading'),
'layout' => 'left',
]),
];
}
```
Presets support:
* `name()` - Display name in the preset picker
* `description()` - Optional description text
* `settings()` - Default settings values
* `children` - Pre-configured child blocks using PresetBlock
* `icon()` - Optional icon (SVG string)
* `category()` - Optional category for grouping
* `previewImageUrl()` - Optional preview image URL
For comprehensive documentation on creating presets with nested blocks, categories, and advanced features, see the [Presets Guide](../../core-concepts/presets.md).
## settings
Defines the configurable fields for the section that appear in the Visual Editor's settings panel.
```php
use BagistoPlus\Visual\Settings\Text;
use BagistoPlus\Visual\Settings\Color;
use BagistoPlus\Visual\Settings\Link;
use function BagistoPlus\Visual\t;
public static function settings(): array
{
return [
Text::make('heading', t('awesome-theme::sections.hero.heading'))
->default(t('awesome-theme::sections.hero.default_heading')),
Color::make('background_color', t('awesome-theme::sections.hero.background_color'))
->default('#4f46e5'),
Link::make('cta_link', t('awesome-theme::sections.hero.cta_link')),
];
}
```
### Dynamic Defaults
Settings can use **dynamic sources** to populate defaults from runtime context:
```php
use function BagistoPlus\Visual\t;
public static function settings(): array
{
return [
Text::make('productName', t('awesome-theme::products.name'))
->default('@product.name'),
Number::make('price', t('awesome-theme::products.price'))
->default('@product.price'),
Image::make('image', t('awesome-theme::products.image'))
->default('@product.base_image.url'),
];
}
```
The `@path.to.value` syntax resolves from page context (controller variables) or parent-shared data. **[Learn more about Dynamic Sources](/core-concepts/dynamic-sources)**
For all available setting types and their options, see the [Settings documentation](../../core-concepts/settings/types.md).
## enabledOn
Specifies which **templates** and **regions** this section can be added to.
```php
protected static array $enabledOn = [
'templates' => ['index', 'product', 'account/*'],
'regions' => ['header', 'footer'],
];
```
* `templates` - Array of template types where this section can be added (optional)
* `regions` - Array of region IDs where this section can be added (optional)
Both keys are optional. You can specify templates only, regions only, or both.
**Examples:**
Restrict to specific templates only:
```php
protected static array $enabledOn = [
'templates' => ['index', 'product'],
];
```
Restrict to specific regions only:
```php
protected static array $enabledOn = [
'regions' => ['header', 'footer'],
];
```
Restrict to both templates and regions:
```php
protected static array $enabledOn = [
'templates' => ['index', 'product'],
'regions' => ['header'],
];
```
Wildcards are supported in templates:
* `'account/*'` matches account/profile, account/addresses, etc.
* `'*'` matches all templates
**Default:** No restrictions (can be added anywhere)
## disabledOn
Specifies which **templates** and **regions** this section should be excluded from.
```php
protected static array $disabledOn = [
'templates' => ['checkout', 'auth/*'],
'regions' => ['sidebar'],
];
```
* `templates` - Array of template types to exclude this section from (optional)
* `regions` - Array of region IDs to exclude this section from (optional)
Both keys are optional. You can exclude from templates only, regions only, or both.
**Example:**
Exclude from checkout templates:
```php
protected static array $disabledOn = [
'templates' => ['checkout'],
];
```
`disabledOn` takes priority over `enabledOn` when both are specified.
**Default:** No exclusions
***
Next: [Writing the Section View](./writing-section-view.md)
---
---
url: /building-theme/adding-sections/writing-section-view.md
---
# Rendering a Section
Each section has an associated Blade view that defines how its settings and blocks are displayed. The view is automatically injected with a `$section` object.
## Accessing Data in the View
In your Blade file (e.g. `resources/views/sections/announcement-bar.blade.php`), use:
* `$section->settings` — for static fields defined in `settings()`
* `$section->children` — for accessing child blocks added by merchants
* `$section->editor_attributes` — for Visual Editor attributes (required when no wrapper is defined)
## Editor Attributes
When your section doesn't define a `wrapper` attribute, you must add {{ $section->editor\_attributes }} to the root element of your view. This injects the necessary data attributes for the Visual Editor to identify and interact with the section.
```blade
@if($section->childrenCount() > 1)
@endif
@children
@if($section->childrenCount() > 1)
@endif
editor_attributes }}
class="announcement-message"
x-show="current === {{ $block->index }}"
x-transition:enter="transition ease-out duration-300"
x-transition:enter-start="opacity-0"
x-transition:enter-end="opacity-100"
x-transition:leave="transition ease-in duration-300"
x-transition:leave-start="opacity-100"
x-transition:leave-end="opacity-0"
>
{{ $block->settings->text }}
```
### How it works
* The section auto-rotates announcements every 5 seconds when there are multiple messages
* Navigation arrows appear only when there's more than one announcement
* The section uses `@children` to render all announcement blocks
* Each announcement block uses `$block->index` to show/hide based on the section's `current` state
* Alpine.js transitions in the block view provide smooth fade effects
## Notes
* Use `$section->settings->key` to access section settings.
* Use `@children` to render all child blocks that merchants add through the Visual Editor.
* Always include {{ $section->editor\_attributes }} on the root element when not using a wrapper.
* For complex interactions like carousels or tabs, consider implementing the logic in JavaScript that wraps around the rendered children.
***
Next: [Using Sections in Templates](./using-section.md)
---
---
url: /building-theme/adding-sections/using-section.md
---
# Using Sections in Templates
Once a section is defined, it can be used in a page template a layout.
## Usage in JSON Templates
Sections can be used in JSON or YAML template files. See [JSON/YAML Templates](../../core-concepts/templates/json-yaml.md) for more details.
:::: tabs
::: tab JSON
```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": "@awesome-theme/announcement",
"settings": {
"text": "Extended returns until Jan 31"
}
},
"second": {
"type": "@awesome-theme/announcement",
"settings": {
"text": "Free delivery on orders over $50"
}
}
}
}
},
"order": ["announcement-bar"]
}
```
:::
::: tab YAML
```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: '@awesome-theme/announcement'
settings:
text: Extended returns until Jan 31
second:
type: '@awesome-theme/announcement'
settings:
text: Free delivery on orders over $50
order:
- announcement-bar
```
:::
::::
### Fields
| Field | Description |
| ---------- | ----------------------------------------------------------------- |
| `sections` | Map of section instances keyed by a unique name |
| `order` | List of section keys (from `sections`) to control rendering order |
| | |
| `type` | Section type (e.g., `@awesome-theme/announcement-bar`) |
| `settings` | Section-level settings |
| `blocks` | Named blocks, each with a `type` and `settings` |
## Usage in PHP Templates
You can also use sections programmatically using the `TemplateBuilder` API in PHP templates. See [PHP Templates](../../core-concepts/templates/php-templates.md) for more details.
```php
section('announcement-bar', '@awesome-theme/announcement-bar', fn($section) => $section
->settings([
'text' => 'Free shipping on all orders',
'background_color' => '#facc15',
'text_color' => '#000000',
])
->blocks([
$section->block('first', '@awesome-theme/announcement', fn($block) => $block
->settings(['text' => 'Extended returns until Jan 31'])
),
$section->block('second', '@awesome-theme/announcement', fn($block) => $block
->settings(['text' => 'Free delivery on orders over $50'])
),
])
)
->order(['announcement-bar']);
```
The `section()` method accepts:
* A unique section key
* The section type (`@vendor/section-name`)
* A closure that configures the section's settings and blocks
***
Next: [Section Attributes](./section-attributes.md)
---
---
url: /building-theme/adding-blocks/overview.md
---
# Adding Blocks - Overview
Blocks are the atomic building units of Bagisto Visual. This guide will walk you through creating custom blocks for your theme.
## What You'll Learn
This section covers everything you need to know about building blocks:
* **[Creating a Block](/building-theme/adding-blocks/creating-block)**: Step-by-step guide to creating your first block
* **[Block Attributes](/building-theme/adding-blocks/block-schema)**: Configuring settings, presets, and nested blocks
* **[Static Blocks](/building-theme/adding-blocks/static-blocks)**: Rendering blocks in Blade templates
* **[Container Blocks](/building-theme/adding-blocks/container-blocks)**: Creating blocks that accept child blocks
## When to Create Custom Blocks
Create custom blocks when you need:
* **Reusable components** that appear across multiple sections (buttons, testimonials, badges)
* **E-commerce elements** specific to your store (custom product cards, pricing displays)
* **Branded components** that reflect your design system (CTAs, social proof, icons)
* **Content types** that merchants will manage repeatedly (team members, features, FAQs)
## Block Types Overview
Bagisto Visual provides three base block types to extend:
### BladeBlock
The most common block type. Uses Blade templates for rendering.
**Best for:**
* Standard content blocks (text, images, buttons)
* Blocks with settings but no complex logic
* Most use cases
### LivewireBlock
Dynamic blocks powered by Livewire components.
**Best for:**
* Interactive blocks (forms, calculators, live search)
* Blocks that need real-time updates
* AJAX-based functionality
### SimpleBlock
Minimal blocks without settings or logic.
**Best for:**
* Structural elements (dividers, spacers)
* Static content
* Pure presentation blocks
## Quick Example
Here's a simple block to get you started:
**PHP Class** (`src/Blocks/Testimonial.php`):
```php
namespace Themes\YourTheme\Blocks;
use BagistoPlus\Visual\Block\BladeBlock;
use BagistoPlus\Visual\Settings\Text;
use BagistoPlus\Visual\Settings\Textarea;
use BagistoPlus\Visual\Settings\Image;
class Testimonial extends BladeBlock
{
protected static string $view = 'shop::blocks.testimonial';
public static function settings(): array
{
return [
Text::make('name', 'Customer name'),
Textarea::make('quote', 'Testimonial quote'),
Image::make('photo', 'Customer photo'),
];
}
}
```
**Blade View** (`resources/views/blocks/testimonial.blade.php`):
```blade
@if($block->settings->photo)
@endif
```
That's it! This Testimonial block can now be used in any section that accepts it.
## Directory Structure
```plaintext
/theme/
├── src/
│ └── Blocks/
│ ├── Button.php
│ ├── Testimonial.php
│ ├── ProductCard.php
│ └── Columns.php # Container block
├── resources/
│ └── views/
│ └── blocks/
│ ├── button.blade.php
│ ├── testimonial.blade.php
│ ├── product-card.blade.php
│ └── columns.blade.php
```
**Key points:**
* PHP classes go in `src/Blocks/`
* Blade views go in `resources/views/blocks/`
* One PHP class per block, one Blade view per block
* Class names should be PascalCase, view names should be kebab-case
## Development Workflow
1. **Plan your block**: Decide what settings it needs and where it will be used
2. **Create the PHP class**: Extend BladeBlock, LivewireBlock, or SimpleBlock
3. **Define settings**: Use the settings() method to configure merchant-editable options
4. **Create the Blade view**: Implement the block's HTML and styling
5. **Test in sections**: Add your block to sections and test in the theme editor
6. **Refine**: Iterate based on how merchants use it
## Best Practices
✅ **Keep blocks focused**: One purpose per block (button, testimonial, image)
✅ **Make them reusable**: Design for multiple contexts, not one specific section
✅ **Provide sensible defaults**: Settings should have good default values
✅ **Use clear naming**: Block names should clearly describe their purpose
✅ **Document settings**: Use descriptive labels for merchant-facing settings
✅ **Test responsiveness**: Blocks should work on all screen sizes
## Next Steps
Ready to create your first block? Start with **[Creating a Block](/building-theme/adding-blocks/creating-block)** to build a block step-by-step.
---
---
url: /building-theme/adding-blocks/creating-block.md
---
# Creating a Block
A block is a reusable UI component that can be added to sections in Bagisto Visual.
This guide walks you through creating a custom block step-by-step. We'll build a **Feature** block that displays an icon, heading, and description.
## Generate a Block
To generate a new block, use the `visual:make-block` Artisan command:
```bash
php artisan visual:make-block Feature --theme=awesome-theme
```
This will create a basic block class named `Feature` inside the awesome-theme package:
```text
packages/Themes/AwesomeTheme/src/Blocks/Feature.php
packages/Themes/AwesomeTheme/resources/views/blocks/feature.blade.php
```
### Interactive Mode
You can omit arguments to use interactive prompts:
```bash
php artisan visual:make-block
```
The command will prompt you for:
* **Block name** (e.g., `Feature`)
* **Target theme** (selects from installed Visual themes or `app/Visual`)
## Command Options
### Block Types
The command generates different block types based on flags:
| Option | Block Type | Description |
|--------|------------|-------------|
| *(none)* | `SimpleBlock` | **Default.** Lightweight block. Best for simple blocks that don't need component features. |
| `--component` | `BladeBlock` | Blade component-based block. Use when you prefer Blade component patterns. |
| `--livewire` | `LivewireBlock` | Livewire component-based block. Use when you need reactive behavior or real-time updates. |
::: info
The choice between `SimpleBlock`, `BladeBlock`, and `LivewireBlock` is based on your preferred development style and feature needs.
:::
::: warning
You cannot use both `--component` and `--livewire` flags together.
:::
### Other Options
| Option | Description |
|--------|-------------|
| `--theme=awesome-theme` | Target theme slug. Omit to use interactive selection. |
| `--force` | Overwrite existing block files if they already exist. |
## Generated Files
### Default Block (SimpleBlock)
**Command:**
```bash
php artisan visual:make-block Feature --theme=awesome-theme
```
**Generated class:**
```php
```
### Blade Component Block (BladeBlock)
**Command:**
```bash
php artisan visual:make-block Feature --component --theme=awesome-theme
```
**Generated class:**
```php
In default app
```
This generates files in your application directory:
```text
app/Visual/Blocks/Feature.php
resources/views/blocks/feature.blade.php
```
**Namespace:** `App\Visual\Blocks`
::: info
Blocks in `app/Visual` are useful for:
* Quick prototyping
* Application-specific blocks not tied to a theme
* Shared blocks used across multiple themes
:::
## Overwriting Existing Files
Use the `--force` flag to overwrite existing block files:
```bash
php artisan visual:make-block Feature --theme=awesome-theme --force
```
Without `--force`, the command will error if files already exist:
```
❌ Block class already exists: packages/.../Feature.php (use --force to overwrite)
```
## Registering Blocks
Bagisto Visual automatically discovers blocks from:
* `app/Visual/Blocks`
* `packages/{{ $block->settings->quote }}{{ $block->settings->name }}
editor_attributes }} class="feature-block">
```
### The $block Object
The `$block` variable is automatically injected into every block view:
* `$block->settings` - Access block settings
* `$block->id` - Unique block identifier
* `$block->type` - Block type name
* `$block->editor_attributes` - Required attributes for Visual Editor integration
* `$block->index` - Block's position index (useful for conditional rendering)
***
Next: [Block Schema](./block-schema.md)
---
---
url: /building-theme/adding-blocks/block-schema.md
---
# Block Attributes
Block classes in Bagisto Visual can define a number of attributes that control how they are identified, rendered, and displayed in the editor.
## type
The block type identifier used to reference this block in sections and the Visual Editor.
```php
protected static string $type = '@awesome-theme/product-card';
```
or
```php
public static function type(): string
{
return '@awesome-theme/product-card';
}
```
**Default:**
If omitted, the type is generated from the class name using kebab-case.
`ProductCard` becomes `product-card`
**Recommended format:** `@vendor/block-type`
It's recommended to include a vendor prefix (e.g., `@awesome-theme/product-card`) to avoid collisions, especially when blocks come from packages. This ensures uniqueness across different themes and packages.
## name
Display name in the block picker.
```php
protected static string $name = 'Product Card';
```
or
```php
use function BagistoPlus\Visual\t;
public static function name(): string
{
return t('awesome-theme::blocks.product_card.name');
}
```
**Default:**
Derived from the class name, title-cased.
Example: `ProductCard` becomes "Product Card".
## view
Blade view used to render the block.
```php
protected static string $view = 'shop::blocks.product-card';
```
**Default:**
* For theme blocks: `shop::blocks.{slug}`
* For non-theme blocks: `blocks.{slug}`
## wrapper
HTML wrapper using a simplified Emmet-style syntax. When a wrapper is defined, the necessary attributes for the Visual Editor are injected automatically.
```php
protected static string $wrapper = 'div.product-card>div.card-content';
```
Results in:
```html
{{ $block->settings->heading }}
{{ $block->settings->description }}
editor_attributes }} class="product-card">
```
The editor\_attributes helper injects the necessary data attributes required for the Visual Editor to identify and interact with the block.
## description
Short description shown in the block picker in the theme editor.
```php
protected static string $description = 'Displays a product with image, title, and price.';
```
or
```php
use function BagistoPlus\Visual\t;
public static function description(): string
{
return t('awesome-theme::blocks.product_card.description');
}
```
## category
Groups blocks together in the block picker of the Visual Editor.
```php
protected static string $category = 'Product';
```
or
```php
use function BagistoPlus\Visual\t;
public static function category(): string
{
return t('awesome-theme::blocks.categories.product');
}
```
Blocks with the same category will be grouped together in the block picker, making it easier for merchants to find related blocks.
Common categories: `Content`, `Product`, `Layout`, `Media`, `Forms`, `Marketing`
## icon
Icon displayed in the block picker in the Visual Editor. Must be a raw SVG string.
```php
protected static string $icon = '';
```
or
```php
public static function icon(): string
{
return '';
}
```
**Default:** A default block icon is used if not specified.
## previewImageUrl
Path to a preview image, relative to the `public/` directory or a full URL.
Displayed in the block picker in the theme editor.
```php
protected static string $previewImageUrl = 'images/blocks/product-card-preview.png';
```
or
```php
public static function previewImageUrl(): string
{
return url('images/blocks/product-card-preview.png');
}
```
**Default:**
* Theme: `vendor/themes/awesome-theme/assets/images/blocks/{slug}-preview.png`
* Non-theme: `images/blocks/{slug}-preview.png`
## previewDescription
Optional text shown below the preview image.
```php
protected static string $previewDescription = 'Shows product information in a card layout.';
```
or
```php
use function BagistoPlus\Visual\t;
public static function previewDescription(): string
{
return t('awesome-theme::blocks.product_card.preview_description');
}
```
## accepts
For container blocks that can accept child blocks, defines which block types can be nested inside.
```php
protected static array $accepts = [
'@awesome-theme/heading',
'@awesome-theme/button',
'@awesome-theme/image',
];
```
### Wildcards:
Accept all blocks:
```php
protected static array $accepts = ['*'];
```
Accept all blocks from a specific vendor/package:
```php
protected static array $accepts = ['@awesome-theme/*'];
```
### Using block classes:
You can also reference blocks using their PHP class names:
```php
use Themes\AwesomeTheme\Blocks\Heading;
use Themes\AwesomeTheme\Blocks\Button;
protected static array $accepts = [
Heading::class,
Button::class,
];
```
**Default:** `[]` (does not accept children)
### Rendering Children
Render child blocks in your block view using `@children`:
```blade
editor_attributes }} class="card">
```
## presets
Defines pre-configured variations of the block that merchants can choose from when adding the block. Presets allow you to provide quick-start templates with predefined settings.
```php
use BagistoPlus\Visual\Support\Preset;
use function BagistoPlus\Visual\t;
public static function presets(): array
{
return [
Preset::make(t('awesome-theme::presets.buttons.primary.name'))
->description(t('awesome-theme::presets.buttons.primary.description'))
->settings([
'text' => t('awesome-theme::presets.buttons.primary.text'),
'style' => 'primary',
'size' => 'large',
]),
Preset::make(t('awesome-theme::presets.buttons.secondary.name'))
->description(t('awesome-theme::presets.buttons.secondary.description'))
->settings([
'text' => t('awesome-theme::presets.buttons.secondary.text'),
'style' => 'secondary',
'size' => 'medium',
]),
Preset::make(t('awesome-theme::presets.buttons.outline.name'))
->description(t('awesome-theme::presets.buttons.outline.description'))
->settings([
'text' => t('awesome-theme::presets.buttons.outline.text'),
'style' => 'outline',
'size' => 'medium',
]),
];
}
```
Presets support:
* `name()` - Display name in the preset picker
* `description()` - Optional description text
* `settings()` - Default settings values
* `icon()` - Optional icon (SVG string)
* `category()` - Optional category for grouping
* `previewImageUrl()` - Optional preview image URL
For comprehensive documentation on creating presets, see the [Presets Guide](../../core-concepts/presets.md).
## settings
Defines the configurable fields for the block that appear in the Visual Editor's settings panel.
```php
use BagistoPlus\Visual\Settings\Text;
use BagistoPlus\Visual\Settings\Textarea;
use BagistoPlus\Visual\Settings\Color;
use BagistoPlus\Visual\Settings\Icon;
use function BagistoPlus\Visual\t;
public static function settings(): array
{
return [
Icon::make('icon', t('awesome-theme::blocks.feature.icon'))
->default('heroicon-o-star'),
Text::make('heading', t('awesome-theme::blocks.feature.heading'))
->default(t('awesome-theme::blocks.feature.default_heading')),
Textarea::make('description', t('awesome-theme::blocks.feature.description'))
->default(t('awesome-theme::blocks.feature.default_description')),
Color::make('icon_color', t('awesome-theme::blocks.feature.icon_color'))
->default('#4f46e5'),
];
}
```
For all available setting types and their options, see the [Settings documentation](../../core-concepts/settings/types.md).
## private
Controls whether the block appears in the general block picker. Private blocks are hidden from the main picker but can be made available to specific parent blocks or sections through explicit accepts listing.
```php
protected static bool $private = true;
```
**Default:** `false` (block is public and appears in pickers)
### Visibility Rules
Private blocks follow strict visibility rules:
1. **Hidden from General Picker**: Never appear in the main block picker
2. **Explicit Accepts Required**: Only visible when explicitly listed in a parent's `accepts` array
3. **Wildcards Don't Include Private**: Patterns like `'*'` or `'@vendor/*'` do NOT make private blocks visible
**Example:**
```php
// Private block - only usable within specific contexts
class TabItem extends SimpleBlock
{
protected static bool $private = true;
}
// Section that explicitly accepts the private block
class Tabs extends SimpleSection
{
protected static array $accepts = [
'@awesome-theme/tab-item', // Explicit - TabItem will appear
];
}
// Section with wildcard - private block still hidden
class Container extends SimpleSection
{
protected static array $accepts = ['*']; // TabItem NOT included
}
```
Use private blocks for:
* Component parts (like tab items, accordion panels)
* Blocks that only make sense in specific contexts
* Internal/structural blocks not meant for direct use
***
Next: [Static Blocks](./static-blocks.md)
---
---
url: /building-theme/adding-blocks/static-blocks.md
---
# Static Blocks
Static blocks are blocks that are rendered directly in Blade templates rather than being added through the Visual Editor. They provide a way for developers to maintain control over section structure while still allowing merchants to customize block settings.
Unlike dynamic blocks (which merchants can add, remove, and reorder through the editor), static blocks have a fixed position in the section layout defined by the developer.
::: info Why Use Static Blocks Instead of Direct Components?
Even though static blocks have a fixed position, they remain fully editable in the Visual Editor. Merchants can click on static blocks and customize their settings (text, colors, images, etc.). Static blocks can even accept their own children that merchants can add, remove, and reorder — making the content fully dynamic and merchant-controlled while the structure remains developer-controlled.
:::
## When to Use Static Blocks
Static blocks are ideal for:
* **Structural consistency**: Elements that are core to the section's design and shouldn't be removed
* **Conditional rendering**: Blocks that appear or disappear based on section settings
* **Fixed relationships**: Elements that must always appear together (like an icon paired with a heading)
* **Layout controls**: UI elements like slideshow navigation arrows or accordion icons
## Rendering Static Blocks
To render a static block in your section's Blade view, use the `@visualBlock` directive:
```blade
@visualBlock('type', 'unique-id')
```
### Parameters
* **`type`**: The block type (e.g., `'heading'`, `'@awesome-theme/button'`)
* **`id`**: A unique identifier for this block instance within the section
### Basic Example
```blade
{{ $block->settings->title }}
@children
{{-- Static heading block - merchants can edit the text --}}
@visualBlock('heading', 'hero-title')
{{-- Static paragraph block - merchants can edit the content --}}
@visualBlock('paragraph', 'hero-description')
{{-- Dynamic blocks area - merchants can add/remove/reorder blocks --}}
@children
```
::: warning Important
The `id` parameter must be unique within the section. Use descriptive IDs that indicate the block's purpose (e.g., `'hero-title'`, `'footer-logo'`, `'slide-1-caption'`).
:::
## Passing Data to Static Blocks
You can pass custom data to static blocks using an optional third parameter. These attributes are injected into the block's view context and accessible as variables.
### Syntax
```blade
@visualBlock('type', 'id', ['attribute' => 'value'])
```
### Basic Example
```blade
@visualBlock('@awesome-theme/heading', 'hero-title', [
'title' => 'Welcome to Our Store',
'subtitle' => 'Shop the latest trends'
])
```
In the block's view, these attributes are accessible as variables:
```blade
editor_attributes }}>
```
### With Dynamic Data
Pass data from the section or other sources:
```blade
@visualBlock('@awesome-theme/product-card', 'featured-product', [
'product' => $featuredProduct,
'showPrice' => true,
])
```
Block view:
```blade
{{ $title }}
{{ $subtitle }}
editor_attributes }} class="product-card">
```
## Conditional Rendering
One of the key advantages of static blocks is the ability to conditionally render them based on section settings:
```blade
{{ $product->name }}
@if($showPrice){{ $product->price }}
@endif
{{-- Always visible --}}
@visualBlock('heading', 'features-title')
{{-- Conditionally visible based on setting --}}
@if($section->settings->show_subtitle)
@visualBlock('paragraph', 'features-subtitle')
@endif
{{-- Dynamic feature blocks --}}
```
The Visual Editor provides visual cues to merchants when conditional static blocks are hidden, helping them understand why a block isn't currently visible.
### Rendering in Loops
Static blocks can also be rendered in loops. Each instance will share the same structure and settings configured by the merchant in the Visual Editor:
```blade
@children
@foreach ($testimonials as $testimonial)
@visualBlock('@awesome-theme/testimonial-card', 'testimonial-item', [
'testimonial' => $testimonial,
])
@endforeach
```
In this example:
* The merchant can customize the `testimonial-item` block's settings (colors, layout, etc.) **once** in the Visual Editor
* All instances in the loop share the same configuration
* Each instance receives different data via the attributes array (`$testimonial`)
This is useful for displaying dynamic lists (products, testimonials, blog posts) where you want:
* ✅ Consistent styling across all items (merchant controls design)
* ✅ Different data for each item (developer controls data)
* ✅ Fixed structure (developer controls which items appear)
## Configuring Static Blocks in Presets
One powerful feature of static blocks is the ability to pre-configure them in section presets. When you define a static block with an ID, you can reference that ID in the preset to provide default settings and child block structure.
**Section Blade:**
```blade
editor_attributes }} class="product-grid-section">
```
**Section Preset:**
```php
use BagistoPlus\Visual\Support\Preset;
use BagistoPlus\Visual\Support\PresetBlock;
public static function presets(): array
{
return [
Preset::make('Product Grid')
->settings([
'columns' => 4,
'gap' => 4,
])
->blocks([
PresetBlock::make('@awesome-theme/heading')
->settings(['text' => 'Featured Products']),
// Configure the static product card default structure
PresetBlock::make('@awesome-theme/product-card')
->id('static-product-card') // References static block by ID
->static() // Marks as static (required)
->settings([
'border_radius' => 'lg',
'shadow' => true,
])
->children([ // Define default child structure
PresetBlock::make('@awesome-theme/product-image')
->settings([
'aspect_ratio' => 'square',
'object_fit' => 'cover',
]),
PresetBlock::make('@awesome-theme/product-title')
->settings([
'tag' => 'h3',
'size' => 'lg',
]),
PresetBlock::make('@awesome-theme/product-price')
->settings(['show_compare_price' => true]),
PresetBlock::make('@awesome-theme/button')
->settings([
'text' => 'Add to Cart',
'style' => 'primary',
]),
])
])
];
}
```
When a merchant adds this section from the preset, the Visual Editor shows one instance of the static `static-product-card` block with:
* Pre-configured settings (border radius, shadow)
* All child blocks already in place (image, title, price, button)
* Each child block with its own default settings
The merchant customizes this one instance in the Visual Editor, and the configuration applies to all cards in the loop on the storefront.
Merchants can:
* ✅ Edit settings of the static block and its children (applies to all instances)
* ✅ Add, remove, or reorder the child blocks inside (applies to all instances)
* ❌ Cannot move or remove the block itself (it's static and controlled by the loop)
This provides a complete, ready-to-use structure with consistent styling across all loop instances.
***
Next: [Container Blocks](./container-blocks.md)
---
---
url: /building-theme/adding-blocks/container-blocks.md
---
# Container Blocks (Nesting)
Container blocks are blocks that accept child blocks, enabling deep nesting and sophisticated page layouts. This feature transforms the theme editor into a true page builder.
## What are Container Blocks?
Container blocks are regular blocks with one key difference: they can accept other blocks as children. This enables:
* **Multi-column layouts** with different content in each column
* **Tabbed content** with blocks inside each tab
* **Accordions** with rich content in each panel
* **Nested structures** up to 8 levels deep
## Creating a Container Block
To create a container block, define the `$accepts` property:
```php
options([
'2' => '2 Columns',
'3' => '3 Columns',
'4' => '4 Columns',
])
->default('3'),
];
}
}
```
## Rendering Child Blocks
In the container block's view, use the `@children` directive to render child blocks:
```blade
{{-- resources/views/blocks/columns.blade.php --}}
@foreach ($products as $product)
{{-- Static block repeated in loop --}}
@visualBlock('@awesome-theme/product-card', 'static-product-card', [
'product' => $product,
])
@endforeach
@children
```
## Sharing Data with Child Blocks
Container blocks can share data with their children using the `share()` method. Data returned from `share()` is automatically passed down the entire nested structure, making it available to all descendant blocks.
### How It Works
The `share()` method returns an array of data that becomes available in:
1. **Child block classes**: Access via `$this->context('key', 'default')`
2. **Child block views**: Available as variables (e.g., `$product`, `$category`)
3. **Child block presets**: Use dynamic sources with `@key` syntax (e.g., `'@product.name'`)
4. **Deeply nested blocks**: Automatically cascades to grandchildren and beyond
### Example 1: Product Card Sharing Product Data
The ProductCard container shares the product object so child blocks don't need their own product settings:
```php
class ProductCard extends SimpleBlock
{
protected static string $view = 'shop::blocks.product-card';
protected static array $accepts = [
'@awesome-theme/product-image',
'@awesome-theme/product-title',
'@awesome-theme/product-price',
];
public static function settings(): array
{
return [
Product::make('product', 'Product'),
];
}
public function share(): array
{
return [
'product' => $this->block->settings->product ?? $this->context('product')
];
}
}
```
Now child blocks can access the shared product data:
**In child block classes:**
```php
class ProductImage extends SimpleBlock
{
protected function getViewData(): array
{
$product = $this->context('product');
return [
'imageUrl' => $product?->base_image->url,
];
}
}
```
**In child block views:**
```blade
{{-- In product-image.blade.php view --}}
@if($product)
You are in design mode
@pushOnce('scripts')
@endPushOnce
@end_visual_design_mode
```
This prevents editor-specific code from running on the live storefront, keeping your production code clean and performant.
### Section Example
```blade
@visual_design_mode
@pushOnce('scripts')
@endPushOnce
@end_visual_design_mode
```
### Block Example
```blade
@visual_design_mode
@pushOnce('scripts')
@endPushOnce
@end_visual_design_mode
```
If you are using `Alpine.js` or `Livewire`, your state will automatically persist between updates—no additional setup is needed. However, if you rely on vanilla JS or third-party libraries, you should reinitialize them after every update.
## 2. Enabling Instant Setting Updates
For simple updates (text, image URLs, classes), you can avoid full re-renders and apply changes directly in the DOM to provide instant preview without delay.
Bagisto Visual supports this via:
***
### Option 1: `liveUpdate()` Blade Directives
Use `$section->liveUpdate()` or `$block->liveUpdate()` to bind settings to elements.
These helpers inject metadata to enable the editor to update the live preview without requiring a server-side re-render.
#### `->text(string $settingId)`
**Updates the element's `textContent`** whenever the specified setting changes.
```blade
liveUpdate()->text('heading') }}> {{ $section->settings->heading }}
``` #### `->html(string $settingId)` **Updates the element's `innerHTML`** with the new setting value. ```bladeliveUpdate()->html('html_content') }}>
{!! $section->settings->html_content !!}
```
#### `->outerHtml(string $settingId)`
**Replaces the entire element (`outerHTML`)** with the setting value.
```blade
liveUpdate()->outerHtml('html_block') }}>
{!! $section->settings->html_block !!}
```
#### `->attr(string $settingId, string $attributeName)`
**Updates the specified HTML attribute** (e.g. `src`, `href`, `alt`) with the setting value.
```blade
liveUpdate()->style('width', 'width') }}>
```
#### 🔹 Multiple Bindings on a Single Element
You can bind multiple settings fluently to different parts of the same element:
```blade
liveUpdate()
->text('link_text')
->attr('link_url', 'href') }}>
{{ $section->settings->link_text }}
```
#### 🔹 Using with Blocks
The `liveUpdate()` method works with both sections and blocks:
**In a section:**
```blade
liveUpdate()->text('heading') }}> {{ $section->settings->heading }}
``` **In a block:** ```bladeliveUpdate()->text('text') }}> {{ $block->settings->text }}
``` ### Option 2: JavaScript API (`Visual.handleLiveUpdate()`) For more complex cases (e.g. multiple targets, transform logic, or styling), use `Visual.handleLiveUpdate()`: ```blade @visual_design_mode @pushOnce('scripts') @endPushOnce @end_visual_design_mode ``` *** ### API Reference: `handleLiveUpdate` ```ts handleLiveUpdate( sectionType: string, mappings: { section?: RecordSection Title
Section body content goes here.
This will break compatibility with color schemes.
Please check your shipping details.
```
### Cards
```blade
Your Benefits
- Free shipping
- Easy returns
` | `` |
| `` | `` |
| `
` |
| `` | `` |
| `` | `` inside `` or `` |
### Common Roles
* Use ``, ``, `
- ` or `
- ` |
### Common Roles
* Use `