Awesome Theme

`, `

` (or equivalent) block. ## Special Layout for Customer Accounts Bagisto Visual optionally supports a special layout for customer account pages, named: ``` account.blade.php ``` This layout can be used to create a **cleaner, simplified structure** for customer-specific areas such as login, registration, dashboard, and order management. > **Note:** > Using `account.blade.php` is **optional**. If not provided, customer account pages will automatically fallback to the `default.blade.php` layout. ## Developer Flexibility Developers are **free to create and use additional layouts** based on the needs of their project. You can define layouts for specific purposes like checkout, landing pages, or other specialized flows — there are no restrictions. Simply create the desired layout inside `/resources/views/layouts/` and extend it in your templates: ```blade @extends('layouts.custom-layout') ``` --- --- url: /introduction/llms.md --- # LLMs.txt Helping AI tools like GitHub Copilot, Cursor, ChatGPT, and Claude understand **Bagisto Visual**. ## What is `llms.txt`? Bagisto Visual provides `llms.txt` files to support language models and AI-powered tools that interact with our documentation and developer experience. These files help large language models: * Understand how Bagisto Visual works * Suggest accurate code completions and section structures * Reference correct naming conventions and architecture * Improve search, retrieval, and autocomplete when used in IDEs or chat-based assistants ## Available Files We provide the following routes: * [`llms.txt`](/llms.txt): A compact overview of Bagisto Visual, including keywords and top-level concepts * [`llms-full.txt`](/llms-full.txt): A detailed description of the framework, its architecture, usage patterns, and terminology These files are designed for easy ingestion by AI tools and indexing systems. ## Usage with AI Tools ### GitHub Copilot / ChatGPT / Claude These tools can use `llms.txt` files to: * Recommend valid section structure using Blade or Livewire * Autocomplete field definitions and settings * Suggest markup that respects Bagisto Visual’s layout and theming conventions *** ### Cursor If you're using Cursor, you can include `llms.txt` files in your workspace via the `@Docs` directive. This helps Cursor learn from the Bagisto Visual documentation directly for faster, more accurate suggestions. Learn more at [cursor.sh](https://docs.cursor.com/context/@-symbols/@-docs) *** ### Other Tools Any AI tool that supports `llms.txt` indexing or document injection can use these files to build: * Better code generators * Custom autocomplete providers * Enhanced prompts for RAG pipelines Simply include these files alongside your theme or development project. --- --- url: /theme-editor/overview.md --- # Overview The Visual Editor is where you build and customize your storefront in real time — without writing code. It lets you add sections, update content, and see changes live as you make them. ## What Can You Do? * Add sections like banners, featured products, or newsletters * Change images, text, buttons, colors, and layout options * Reorder content by dragging and dropping sections * Preview how your store looks on desktop, tablet, and mobile * Customize each page individually (like homepage, contact, etc.) ![The Visual Editor screenshot](/editor-screenshot-callout.png) ## Sections, Pages & Themes * Your storefront is built using **sections** * Each page (homepage, contact, etc.) can have different sections * Some sections (like header or footer) appear on every page * You can preview and switch between different pages right from the editor ![The Visual Editor page swicther screenshot](/editor-page-switcher.png) ## Why Use the Visual Editor? * **No code required** — edit everything visually * **Live preview** — see changes as you make them * **Flexible layout** — reorder or remove sections anytime * **Built for merchants** — fast, simple, and clear --- --- url: /building-theme/best-practices/performance.md --- # Performance A fast storefront isn't just a nice-to-have — it drives conversions, improves SEO, reduces bounce, and creates a smoother experience for merchants and customers alike. This guide provides practical tips for building performant Bagisto Visual themes and sections, with a focus on the **live storefront**. > 🧩 Editor preview performance is covered separately: [Integrating with the Editor](../adding-sections/integrating-editor.md) ## 1. Keep Your Markup Lean * Don’t over-nest elements. Avoid structures like `

...

` * Use semantic elements (`

`, `

`, `
`) to reduce overhead and improve clarity * Only render content when needed: ```blade @if ($section->settings->heading)
{{ $section->settings->heading }}
@endif ``` * Use `@empty`, `@unless`, or `??` to prevent rendering empty elements ## 2. Load Images Responsibly * Add `loading="lazy"` to all images that aren’t visible on first render * Always define `width` and `height` to prevent layout shifts * Use compressed and appropriately sized images * For responsive assets, use `srcset` and `sizes` ```blade ``` ## 3. Defer Section-Specific JavaScript * Use `@push('scripts')` or similar to load JS only when the section is used * Avoid global scripts for features like carousels or modals that are section-scoped * Add `type="module"` and `defer` to reduce blocking ```blade @push('scripts') @endpush ``` ## 4. Avoid Expensive Blade Logic * Avoid database queries, `json_decode`, or filtering inside Blade * Do data prep in the section class (controller layer) * Use Laravel collections sparingly inside views — prefer `collect($data)->filter()` in PHP ✅ Good: ```php return [ 'products' => Product::limit(4)->get(), ]; ``` 🚫 Avoid: ```blade @foreach (Product::all() as $product) ``` ## 5. Prioritize Mobile Responsiveness * Mobile users are the majority — test every section at 320px, 375px, and 768px * Avoid fixed-width images and layouts * Use readable text sizes and adequate spacing * Ensure buttons are at least 44×44px tappable ## 6. Test Like a Real User Use these tools to simulate real-world performance: * [PageSpeed Insights](https://pagespeed.web.dev/) * [WebPageTest](https://www.webpagetest.org/) * Lighthouse (Chrome DevTools → Audits tab) Simulate: * Slow 3G * Low CPU * Cold cache And fix: * Layout shifts * Image pop-ins * Unused code ## Summary * Write efficient markup and only render what's necessary * Lazy-load images with proper dimensions * Keep JS scoped and defer it when possible * Avoid expensive logic in Blade — prep data in PHP * Prioritize mobile users and test your work with real tools Fast themes feel better, rank better, and convert better. --- --- 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->blocks` — for repeatable items defined in `blocks()` ## Example: Rotating Announcement Bar This example uses Alpine.js to rotate through multiple announcements: ### Section Class Let's consider the following section: ```php use BagistoPlus\Visual\Sections\BladeSection; use BagistoPlus\Visual\Sections\Block; use BagistoPlus\Visual\Settings\Color; use BagistoPlus\Visual\Settings\Text; class AnnouncementBar extends BladeSection { protected static string $view = 'shop::sections.announcement-bar'; public static function settings(): array { return [ Color::make('background_color', 'Background')->default('#facc15'), Color::make('text_color', 'Text Color')->default('#000000'), ]; } public static function blocks(): array { return [ Block::make('announcement') ->settings([ Text::make('text', 'Text')->default('Message content here'), ]), ]; } public static function default(): array { return [ 'settings' => [ 'background_color' => '#facc15', 'text_color' => '#000000', ], 'blocks' => [ ['type' => 'announcement', 'text' => 'Free shipping on all orders'], ['type' => 'announcement', 'text' => 'Extended returns until Jan 31'], ], ]; } } ``` ### Blade view This will be the corresponding view ```blade

@foreach($section->blocks as $index => $block)
{{ $block->settings->text }}
@endforeach

``` ## Notes * Use `$section->settings->key` for values. * Use `$section->blocks` for rendering repeatable content. * You can mix Alpine.js and Blade to match the UX requirements of your section. * Next: [Using Sections in Templates](./using-section.md) --- --- url: /building-theme/adding-sections/section-attributes.md --- # Section Attributes Section classes in Bagisto Visual can define a number of attributes that control how they are identified, rendered, and displayed in the editor. ## slug The unique identifier of the section. ```php protected static string $slug = 'announcement-bar'; ``` or ```php public static function slug(): string { return 'announcement-bar'; } ``` Default: If omitted, the slug is generated from the class name using kebab-case. `AnnouncementBar` → `announcement-bar` ## name Display name in the section editor. ```php protected static string $name = 'Announcement Bar'; ``` or ```php public static function name(): string { return __('Announcement Bar'); } ``` Default: Derived from the slug, title-cased. `announcement-bar` → `Announcement Bar` ## view Blade view used to render the section. ```php protected static string $view = 'shop::sections.announcement-bar'; ``` Default:** * For theme sections: `shop::sections.{slug}` * For non-theme sections: `sections.{slug}` ## wrapper HTML wrapper using a simplified Emmet-style syntax. ```php protected static string $wrapper = 'section#announcement-bar>div.container'; ``` Results in: ```html

``` Default: `section` ## description Short description shown in the section picker in the theme editor. ```php protected static string $description = 'Used for banners or alerts.'; ``` or ```php public static function description(): string { return ('Used for banners or alerts.'); } ``` ## previewImageUrl Path to a preview image, relative to the `public/` directory or a full URL. Displayed in the section picker in the theme editor ```php protected static string $previewImageUrl = 'images/sections/announcement-bar-preview.png'; ``` or ```php public static function previewImageUrl(): string { return url('images/sections/announcement-bar-preview.png'); } ``` Default: * Theme: `vendor/themes/awesome-theme/assets/images/sections/{slug}-preview.png` * Non-theme: `images/sections/{slug}-preview.png` ## previewDescription Optional text shown below the preview image. ```php protected static string $previewDescription = 'Displays a rotating announcement banner.'; ``` or ```php public static function previewDescription(): string { return ('Displays a rotating announcement banner.') } ``` ## maxBlocks Limits how many blocks this section can have. ```php protected static int $maxBlocks = 4; ``` Default: 16 ## default Initial settings and blocks shown when the section is added. ```php protected static array $default = [ 'settings' => [...], 'blocks' => [...], ]; ``` or ```php public static function default(): array { return [ 'settings' => [...], 'blocks' => [...] ] } ``` ## enabledOn Specifies which template types this section can be added to. By default, a section can be added to any template. If needed, you can restrict a section to only be available on specific templates. ```php protected static array $enabledOn = ['index', 'product', 'account/']; ``` This determines where the section appears in the “Add Section” menu of the Visual Editor. You may use `` as a wildcard to match a group of templates: * `'auth/'` matches auth/login, auth/register, etc. `'account/'` matches account/profile, account/addresses, etc. Default: \['\'] → [See available template types](../../core-concepts/templates/available.md) ## disabledOn Specifies which template types this section should be hidden from. This is the inverse of `enabledOn`. If a template is listed in `disabledOn`, the section will be excluded from that template, even if it would normally be available (for example, via `enabledOn`). ```php protected static array $disabledOn = ['checkout', 'auth/', 'account/']; ``` Default: \[] Use this to prevent a section from being added where it doesn’t make sense (like checkout or account pages) You can use both `enabledOn` and `disabledOn` — `disabledOn` always takes priority * Next: [Defining Settings and Blocks](./defining-section-schema.md) --- --- url: /core-concepts/sections.md --- # Sections Sections are modular, reusable building blocks that define the content and layout of storefront pages in Bagisto Visual. Each section is built as a PHP class and paired with a Blade view** for rendering. Sections expose configurable settings and optional blocks, making it easy for both developers and merchants to customize storefront pages dynamically. ## Why Sections Matter * For Developers: Create flexible, reusable UI components that can be configured without modifying the code. * For Merchants: Easily customize and rearrange sections using the Bagisto Visual Theme Editor, without needing a developer. Sections empower a truly dynamic storefront experience where layout and content can evolve over time. ## Anatomy of a Section A section is made up of three main parts: * A view, responsible for displaying the content. Typically built using Blade templates, the view controls the HTML and structure seen by customers. * A set of configurable settings, which define how merchants can customize the section’s behavior and appearance without touching the code. * Blocks, a set of customizable items that merchants can arrange in the Theme Editor to personalize the section, such as creating multiple categories in a list or slides in a carousel. Settings allow merchants to change things like text, colors, images, or layout options directly from the Theme Editor. Blocks make sections dynamic and flexible, allowing merchants to customize the internal structure of the section itself. Sections are designed to be simple for developers to create and highly flexible for merchants to personalize. ## Section Directory Structure ```plaintext /theme/ ├── src/Sections/ │ ├── AnnouncementBar.php │ ├── CategoryList.php ├── resources/views/sections/ │ ├── announcement-bar.blade.php │ └── category-list.blade.php ``` * `src/Sections/` contains the PHP section classes. * `resources/views/sections/` contains the corresponding Blade templates. ## Basic Section Example ### PHP Section Class ```php namespace Themes\YourTheme\Sections; use Bagisto\Visual\Section\BladeSection; use Bagisto\Visual\Settings\Text; use Bagisto\Visual\Settings\Link; use Bagisto\Visual\Settings\Color; class AnnouncementBar extends BladeSection { protected static string $view = 'shop::sections.announcement-bar'; public static function settings(): array { return [ Text::make('text', 'Banner text') ->default('Welcome to our store!'), Link::make('link', 'Banner link'), Color::make('background_color', 'Background color') ->default('#4f46e5'), Color::make('text_color', 'Text color') ->default('#ffffff'), ]; } } ``` * ### Blade View Example ```blade
{{ $section->settings->text }}
``` ✅ A `$section` object representing the section is automatically injected into each Blade view. Settings can be accessed via `$section->settings`. --- --- url: /core-concepts/settings/types.md --- # Setting Types Bagisto Visual includes a range of setting types like text inputs, color pickers, toggle switches, dropdowns, and more. These ready-made types make it easy for developers to offer flexible customization options in sections, blocks, and themes — all through the visual editor. ## Standard Setting Attributes Every setting type supports a few standard attributes: | Attribute | Description | Required | | :-------- | :------------------------------------------ | :------- | | `id` | The unique identifier for the setting. | Yes | | `label` | The text label shown to merchants. | Yes | | `default` | The default value assigned to the field. | No | | `info` | Optional helper text shown below the field. | No | ## Available Setting Types ### Text Single-line text input. Useful for headings, labels, and short descriptions. In addition to the standard attributes, Text type settings have the following attribute: | Attribute | Description | Required | | :------------ | :--------------------------------- | :------- | | `placeholder` | A placeholder value for the input. | No | ```php use BagistoPlus\Visual\Settings\Text; public static function settings(): array { return [ Text::make('title', 'Heading') ->default('Welcome to our store') ->placeholder('Enter heading here...'), ]; } ``` In Blade: ```blade @if ($section->settings->text)
{{ $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. ```php use BagistoPlus\Visual\Settings\Checkbox; public static function settings(): array { return [ Checkbox::make('show_banner', 'Show Banner') ->default(true), ]; } ``` 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

``` ::: info If default is unspecified, then the first option is selected by default. ::: * ### Select Dropdown selection. Useful for choosing from a list of predefined options. In addition to the standard attributes, Select 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\Select; public static function settings(): array { return [ Select::make('layout', 'Layout Style') ->options([ 'grid' => 'Grid', 'list' => 'List', ]) ->default('grid'), ]; } ``` Alternative format: ```php Select::make('layout', 'Layout Style') ->options([ ['value' => 'grid', 'label' => 'Grid'], ['value' => 'list', 'label' => 'List'], ]) ->default('grid'); ``` In Blade: ```blade

``` ::: info If `default` is unspecified, then the first option is selected by default. ::: * ### Range Numeric slider input. Useful for values like spacing, number of columns, or padding. In addition to the standard attributes, Range type settings have the following attributes: | Attribute | Description | Required | | :-------- | :------------------------------ | :------- | | `min` | Minimum value allowed | Yes | | `max` | Maximum value allowed | Yes | | `step` | Increment steps (default `1`) | No | | `unit` | Optional label for unit display | No | ```php use BagistoPlus\Visual\Settings\Range; public static function settings(): array { return [ Range::make('columns', 'Number of Columns') ->min(1) ->max(6) ->step(1) ->unit('cols') ->default(3), ]; } ``` In Blade: ```blade

``` ::: info If default is unspecified, it defaults to the minimum value. ::: * ### Number Single-line numeric input. Useful for entering quantities, prices, padding, margins, and other number-based configurations. In addition to the standard attributes, Number type settings have the following attribute: | Attribute | Description | Required | | :------------ | :--------------------------------- | :------- | | `placeholder` | A placeholder value for the input. | No | ```php use BagistoPlus\Visual\Settings\Number; public static function settings(): array { return [ Number::make('max_width', 'Max Width') ->default(1200) ->placeholder('Enter a maximum width...'), ]; } ``` In Blade: ```blade

``` * ### Color Color picker input. Useful for background colors, text colors, or brand-related customization. When accessing a color setting inside Blade, the value is either: * `null` (if no color selected) * an instance of [`matthieumastadenis\couleur\Color`](https://github.com/matthieumastadenis/couleur) ```php use BagistoPlus\Visual\Settings\Color; public static function settings(): array { return [ Color::make('background_color', 'Background Color') ->default('#92400e'), ]; } ``` In Blade: ```blade @if ($section->settings->background_color)

@endif ``` *** ### Link URL input field. Useful for buttons, banners, images, and any elements that need a hyperlink. The Link setting allows the merchant to either: * Enter a custom URL manually * Select a resource (like a Product, Category, or CMS Page) directly from the store ```php use BagistoPlus\Visual\Settings\Link; public static function settings(): array { return [ Link::make('cta_link', 'Call to Action Link') ->default('/'), ]; } ``` In Blade: ```blade @if ($section->settings->cta_link) Browse Collection @endif ``` *** ### Image Image picker input. Useful for banners, logos, thumbnails, or any visual element. The merchant can: * Upload a new image * Pick an existing image from the media library ```php use BagistoPlus\Visual\Settings\Image; public static function settings(): array { return [ Image::make('banner_image', 'Banner Image'), ]; } ``` In Blade: ```blade @if ($section->settings->banner_image) @endif ``` *** ### Category Dropdown selector input. Useful for allowing the merchant to select a category from the store catalog. When accessing a category setting inside Blade, the value is either: * `null` (if no category selected) * an instance of the `Webkul\Category\Models\Category` model ```php use BagistoPlus\Visual\Settings\Category; public static function settings(): array { return [ Category::make('featured_category', 'Featured Category'), ]; } ``` In Blade: ```blade @if ($section->settings->featured_category) @endif ``` *** ### Product Dropdown selector input. Useful for allowing the merchant to select a product from the store catalog. When accessing a product setting inside Blade, the value is either: * `null` (if no product selected) * an instance of the `Webkul\Product\Models\Product` model ```php use BagistoPlus\Visual\Settings\Product; public static function settings(): array { return [ Product::make('featured_product', 'Featured Product'), ]; } ``` In Blade: ```blade @if ($section->settings->featured_product) @endif ``` *** ### CmsPage Dropdown selector input. Useful for allowing the merchant to select a CMS page from the store. When accessing a CMS page setting inside Blade, the value is either: * `null` (if no page selected) * an instance of the `Webkul\CMS\Models\CmsPage` model ```php use BagistoPlus\Visual\Settings\CmsPage; public static function settings(): array { return [ CmsPage::make('policy_page', 'Policy Page'), ]; } ``` In Blade: ```blade @if ($section->settings->policy_page) {{ $section->settings->policy_page->page_title }} @endif ``` *** ### RichText WYSIWYG rich-text editor input. Useful for inserting formatted content like paragraphs, lists, links, and formatted text. RichText fields support the following basic formatting options: * Bold * Italic * Underline * Paragraph * Headings * Bullet list * Ordered list In addition to the standard attributes, RichText type settings have the following attribute: | Attribute | Description | Required | | :-------- | :-------------------------------------------- | :------- | | `inline` | Whether the editor should be rendered inline. | No | ```php use BagistoPlus\Visual\Settings\RichText; public static function settings(): array { return [ RichText::make('content', 'Content Block'), RichText::make('highlight', 'Highlight Text') ->inline(), ]; } ``` In Blade: ```blade @if ($section->settings->content)
{!! $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

``` This is used to scope the color schemes tokens to this block. * ### ColorSchemeGroup The `ColorSchemeGroup` setting type allows theme developers to define a set of named color schemes that merchants can reuse across multiple sections. Each color scheme is a collection of color roles (like `background`, `text`, `primary`, etc.) and can be selected using a [ColorScheme](#colorscheme) setting within any section. 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 color schemes * Enables consistency in color use across sections * Can be extended or modified by the merchant in the theme editor #### Usage in `config/settings.php` ```php use BagistoPlus\Visual\Settings\ColorSchemeGroup; return [ ColorSchemeGroup::make('color_schemes', 'Color Schemes') ->schemes([ 'light' => [ 'label' => 'Light', 'tokens' => [ 'background' => '#ffffff', 'on-background' => '#111827', 'primary' => '#4f46e5', '...' ], ], 'dark' => [ 'label' => 'Dark', 'tokens' => [ 'background' => '#111827', 'on-background' => '#f9fafb', 'primary' => '#6366f1', '...' ], ], ]), ]; ``` #### Scheme Format Each scheme is an array with: * A unique key (e.g., `light`, `dark`, `brand`) * A label (used in the dropdown) * A `tokens` array with color roles (e.g., `background`, `on-background`, `primary`, etc.) ```php [ 'light' => [ 'label' => 'Light', 'tokens' => [ 'background' => '#ffffff', 'on-background' => '#111827', 'primary' => '#4f46e5', ] ] ] ``` #### Behavior in the Theme Editor * Merchants can add, edit, or remove color schemes directly from the theme editor * They can: * Rename schemes * Change color values * Any section using a `ColorScheme` setting will automatically reflect the updated list #### Blade Usage The `ColorSchemeGroup` setting is not accessed directly in sections. However, theme developers must output CSS variables for every scheme so that sections using `ColorScheme` can style themselves accordingly. Each scheme should be scoped using a `data-color-scheme` attribute: ```html ``` #### 💡 Suggestion: Include Brand Color Shades For primary or accent colors, it’s recommended to output shades (like Tailwind’s colors). ```blade ``` These can be used in components via var(--color-primary-500) for consistent, scalable design. If you are using tailwindcss, you could just use utility classes: ```blade

``` *** Bagisto Visual provides a helper method to generate the full CSS output automatically from the theme's color schemes: ```blade {{-- layouts/default.blade.php --}} ``` * This will loop over every scheme * Output all defined colors as `--color-` tokens Automatically generate shades for brand color roles #### Notes * Only one `ColorSchemeGroup` should be defined per theme * Sections do not define color schemes — they reference them via the `ColorScheme` setting * If no `ColorSchemeGroup` is defined, `ColorScheme` fields will not be functional -> [Read more about color schemes](../../building-theme/best-practices/styling.md) *** ### 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/overview.md --- # Settings ## What Are Settings? Settings are the backbone of how customization works in Bagisto Visual. They allow merchants to configure sections, blocks, and even the entire storefront layout visually through the Theme Editor — without touching code. Settings make it easy to personalize storefronts, ensuring flexibility for developers and simplicity for merchants. Bagisto Visual settings can be used in two main places: | Setting Type | Scope | Example | | ---------------------- | -------------------------------------- | ----------------------------------------------- | | Section/Block Settings | Control individual sections and blocks | Banner text, Button color, Product grid columns | | Theme Settings | Global store-wide options | Typography, Color palette, default styles | ## How Settings Work * Section and Block Settings are defined inside each section class using a structured PHP API. * Theme Settings are defined globally and control the broader layout and style of the storefront. Settings provide an abstraction that allows customization without changing the underlying code. Developers expose options, and merchants adjust them through an intuitive visual interface. ## Setting Input Types Bagisto Visual supports a wide variety of input types for settings, including: | Type | Purpose | Example | | :------- | :------------------- | :---------------------------------- | | Text | Simple text input | Section headings, Button labels | | Textarea | Multiline text input | Detailed descriptions | | Link | URL input | Link buttons, Banners | | Color | Color picker | Background colors, Text colors | | Select | Dropdown option list | Layout styles, Alignment choices | | Range | Numeric sliders | Number of columns, Spacing settings | | Switch | On/Off toggle | Show/Hide features | | Category | Category selector | Featured categories, Menus | Each input type improves merchant experience by offering the most natural way to configure the setting. ## Editing Settings in the Theme Editor * Merchants can interact with settings directly through the Theme Editor. * They can instantly preview changes without needing to publish. * Section and Block Settings affect only their associated components. * Theme Settings affect the layout and design globally across the storefront. Settings changes are safe, reversible, and visual, making customization intuitive even for non-technical users. * Settings are a key reason why Bagisto Visual empowers both developers and merchants to create rich, personalized storefronts without friction. --- --- url: /building-theme/best-practices/styling.md --- # Styling and the Color System To ensure consistent design and easy customization across themes and third-party sections, Bagisto Visual promotes a shared, semantic color system. This system is implemented in the default `visual-debut` theme and is strongly recommended for all themes and section packages. Inspired by the [DaisyUI color system](https://daisyui.com/docs/colors/), this approach uses role-based tokens to ensure legibility, adaptability, and design consistency. ## 1. Color Roles Each color has a semantic role** that defines its purpose in the interface. These roles provide a stable design language that works across themes and sections. | Role | Description | Common Use | | ---------------- | ----------------------------------------- | ------------------------------------ | | `primary` | Main brand color | Buttons, links, CTAs | | `on-primary` | Foreground on `primary` | Text/icons on primary backgrounds | | `secondary` | Supporting tone | Headings, badges, accents | | `on-secondary` | Foreground on `secondary` | Text/icons on secondary backgrounds | | `accent` | Decorative or promotional highlights | Banners, badges | | `on-accent` | Foreground on `accent` | Text/icons on accent elements | | `neutral` | General-purpose text and passive surfaces | Body text, input borders | | `on-neutral` | Foreground on `neutral` | Text/icons on neutral surfaces | | `background` | Page background | Layout wrappers, full-width sections | | `on-background` | Foreground on `background` | Body text, links | | `surface` | Component or section background | Cards, forms, sidebars | | `on-surface` | Foreground on `surface` | Section text, icons | | `surface-alt` | Alternate surface (hover, nesting layer) | Hover states, dropdowns | | `on-surface-alt` | Foreground on `surface-alt` | Icons or overlays | | `success` | Positive feedback | Alerts, tags, confirmations | | `on-success` | Foreground on `success` | Text/icons on success backgrounds | | `warning` | Attention or caution | Notices, validation warnings | | `on-warning` | Foreground on `warning` | Text/icons on warning backgrounds | | `danger` | Critical or destructive state | Errors, danger zones | | `on-danger` | Foreground on `error` | Text/icons on error messages | | `info` | Informational messages | Tooltips, banners, guidance | | `on-info` | Foreground on `info` | Text/icons on info sections | Each background is paired with a `on-` foreground token for text and icon contrast. ## 2. Color Schemes A color scheme is a named set of color tokens that defines the look and feel of a section or page. Color schemes let themes support multiple visual styles (light, dark, promotional), and allow merchants to assign schemes without writing code. ### How They Work Color schemes are defined by the theme using the [ColorSchemeGroup](../../core-concepts/settings/types.md#colorschemegroup) setting type * Each scheme includes: * A unique key (e.g. `default`, `dark`, `highlight`) * A label for display in the Visual Editor * A complete set of semantic tokens (see list above) * The `default` (or first) scheme is applied to the entire page * Sections can override the global scheme using the [ColorScheme](../../core-concepts/settings/types.md#colorscheme) setting * Selected schemes are applied using a `data-color-scheme` attribute, which scopes CSS variables ### Important > 💡 Every scheme must define a value for all color roles documented above. > This ensures that any section relying on semantic tokens can render correctly and remain compatible. *** ### Why They Matter * Consistent branding across all pages and sections * Flexible design with support for dark mode, promotional themes, etc. * Third-party compatibility without visual clashes * Merchant control over appearance via the Visual Editor *** ### Best Practices * Define every required token (`primary`, `on-primary`, `background`, etc.) * Ensure strong contrast between background and `on-` foregrounds Offer 2–5 thoughtful schemes with clear visual identity * Render all scheme tokens in your layout using: ```blade @foreach ($theme->settings->color_schemes as $scheme) [data-color-scheme="{{ $scheme->id }}"] { {!! $scheme->outputCssVars() !!} } @endforeach ``` ## 3. Usage Guidelines Use role-based classes and tokens instead of hardcoded colors. ### ✅ Recommended ```blade

Section Title

Section body content goes here.

``` ### 🚫 Avoid ```blade

This will break compatibility with color schemes.

``` ## 4. Theme Developer Responsibilities Theme developers must: * Define all required tokens per scheme using CSS variables: ```css --color-primary, --color-on-primary, --color-surface, --color-on-surface, etc. ``` * Use kebab-case naming for consistency * Ensure visual contrast between paired tokens (e.g., `on-background` and `background`) * Store the token definitions inside a single `ColorSchemeGroup` setting ## 5. Section Developer Responsibilities Section developers should: * Use only semantic tokens (`bg-surface`, `text-on-primary`, etc.) * Never use hardcoded hex values or shortcuts like `text-white` * Always pair foreground text with its appropriate background token * Avoid relying on color alone to communicate meaning — use icons, labels, or layout cues * Make sections compatible with any theme or scheme ## 6. Common Patterns ### Buttons ```blade ``` ### Alerts ```blade
Please check your shipping details.
``` ### Cards ```blade

Your Benefits

Free shipping

Easy returns

``` ## Summary * Use role-based tokens like `primary`, `surface`, `error`, etc. * Always include `on-` counterparts for text and icon contrast Define color schemes centrally using `ColorSchemeGroup` * Let sections reference schemes using `ColorScheme` * Avoid fixed colors — rely on design tokens and scoping for flexibility This color system makes your sections consistent, theme-compatible, and easy to adapt for any brand or layout. --- --- url: /core-concepts/templates/overview.md --- # Templates Templates control the structure and layout of individual pages in a Bagisto Visual theme. Each storefront page — such as the homepage, a product page, a cart page, or a category listing — is linked to a template that defines what content to render and how to organize it. Templates act as blueprints for pages by specifying: * Which sections appear. * The order they appear in. * How the page content is assembled. ## Key Characteristics * Each page type has an associated template. Templates define how the content of that page is structured. * Templates use Blade, JSON (or YAML) formats. Developers can choose between: * Blade templates (`.blade.php`) for dynamic, code-driven pages. * JSON or YAML templates (`.json`, `.yaml`) for lightweight, section-driven pages. * Only one template is rendered per page. When a user navigates to a page, Bagisto Visual selects and renders the corresponding template. * Templates organize sections, not content directly. Sections provide the actual content and functionality. ## Location of Templates Templates are stored inside the following directory: ```plaintext /theme/ └── resources/ └── views/ └── templates/ ``` Example: ```plaintext /templates/ ├── index.blade.php # Homepage template ├── product.json # Product page ├── category.json # Category page ├── cart.yaml # Cart page ├── checkout.yaml # Checkout page ├── page.yaml # CMS pages ├── search.json # Search results page ``` ## Blade Templates vs JSON/YAML Templates | Format | Description | When to Use | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | Blade | Full Laravel Blade templates. Allow dynamic PHP, Livewire components, and advanced logic. Blade templates cannot be customized or rearranged through the Theme Editor. | Use Blade when you need maximum flexibility, dynamic behavior, or complex layouts. | | JSON/YAML | Static templates that define a list of sections in order. Sections can be added, removed, and reordered visually by merchants through the Theme Editor. | Use JSON/YAML for customizable, section-driven pages managed easily by merchants. | > Tip: > JSON and YAML templates are ideal for pages where merchant customization and flexibility are important (like the homepage, landing pages, etc.). > Blade templates are better suited for pages with strict structure or advanced dynamic functionality. --- --- 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 'Light Scheme Colors (default)', 'settings' => [ Settings\Color::make('light_background_color', 'Background') ->default('#ffffff') ->info('Default page color. Used for main page background and large content areas'), Settings\Color::make('light_primary_color', 'Primary') ->default('#92400e') ->info('Main brand color. Used for buttons and key elements'), // More color settings... ], ], [ 'name' => 'Typography', 'settings' => [ Settings\Font::make('heading_font', 'Heading Font') ->default('Inter'), Settings\Font::make('body_font', 'Body Font') ->default('Roboto'), ], ], [ 'name' => 'Social Media Links', 'settings' => [ Settings\Text::make('facebook_url', 'Facebook URL') ->default('https://www.facebook.com'), Settings\Text::make('instagram_url', 'Instagram URL') ->default('https://www.instagram.com'), Settings\Text::make('youtube_url', 'YouTube URL') ->default('https://www.youtube.com'), Settings\Text::make('tiktok_url', 'TikTok URL') ->default('https://www.tiktok.com'), Settings\Text::make('twitter_url', 'X/Twitter URL') ->default('https://www.x.com'), Settings\Text::make('snapchat_url', 'Snapchat') ->default('https://www.snapchat.com'), ], ], ]; ``` ## 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: /advanced-guides/extending.md --- --- --- url: /advanced-guides/debugging.md --- --- --- url: /index.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 :::: 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": "announcement", "settings": { "text": "Extended returns until Jan 31" } }, "second": { "type": "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: announcement settings: text: Extended returns until Jan 31 second: type: 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 slug (use a vendor prefix for package-defined ones) | | `settings` | Section-level settings | | `blocks` | Named blocks, each with a `type` and `settings` | * ### Referencing a Section Each section in the template is referenced using its `slug`: ```php protected static string $slug = 'announcement-bar'; ``` If the section belongs to a theme package, you should use a namespace prefix: ```yaml type: awesome-theme::announcement-bar ``` This ensures the editor resolves the correct section, even when multiple packages define similar slugs. ## Usage in Blade views In addition to JSON templates, sections can also be embedded statically** in Blade views using the `` component. This renders the section in a fixed location on the page. These statically-included sections: * Cannot be reordered or removed via the Visual Editor * Can still have their settings and blocks edited * Are rendered at a fixed location in the layout ### Syntax ```blade ``` For theme-based sections, use a vendor-prefixed slug: ```blade ``` * ### Example: Static Header and Footer in Layout In your `default.blade.php` layout ```blade Awesome Theme @bagisto_vite(['resources/assets/css/app.css', 'resources/assets/js/app.js'], 'awesome-theme')
@visual_layout_content
``` * ### Notes * A section can only be used statically once per page (layout + template combined) * This is ideal for layout-bound sections like headers, footers, sidebars, banners --- --- url: /introduction/what-is-bagisto-visual.md --- # What is Bagisto Visual? Bagisto Visual is the missing piece in the Bagisto ecosystem: a modern theme framework and visual editor that makes building and customizing storefronts simple, flexible, and powerful. Inspired by the best systems in the e-commerce world, Bagisto Visual transforms theme development from a tedious, technical task into an intuitive experience — empowering both developers and merchants to create beautiful, high-performing stores without complexity. ## Why Bagisto Visual? Building and maintaining Bagisto themes traditionally comes with real pain points: * Developers must dive deep into Bagisto's internals with little documentation. * There is no standardized, structured way to create custom themes. * Every small change or update requires developer intervention. * Merchants are often stuck, unable to tweak their store without costly and time-consuming help. Whenever a merchant needed even a small visual update — a color change, a new section, a layout adjustment — they had to call a developer, causing unnecessary delays, frustration, and added costs. Bagisto Visual solves this problem. It introduces a modern theme architecture and a visual editor that empower merchants to take control of their storefronts, while giving developers a faster, cleaner way to build flexible, maintainable themes. ## Who Is Bagisto Visual For? Bagisto Visual is designed to serve multiple audiences: * Merchants: Easily customize the look and feel of your store without writing a single line of code. Control sections, templates, content, and layout visually. * Developers: Build themes faster with a standardized, modular structure. Create powerful, flexible sections and templates without reinventing the wheel each time. * Agencies and Freelancers: Deliver projects faster, empower clients to manage their storefronts independently, and reduce post-launch maintenance workload. Bagisto Visual democratizes storefront customization — no matter if you're a store owner, a developer, or a full agency team. --- --- url: /building-theme/adding-sections/overview.md --- # Working with Sections In Bagisto Visual, sections are the building blocks of page templates. They are reusable, configurable components that render dynamic content, and can be defined using Blade or Livewire. This guide walks you through everything you need to know about creating, configuring, and using sections in themes and templates. ## Topics Covered * [Creating a Section](./creating-section.md) Generate a new section using Artisan and understand where the files are placed. * [Section Attributes](./section-attributes.md) Learn about common properties like `slug`, `name`, `view`, `wrapper`, and how their defaults are derived. * [Defining Settings and Blocks](./defining-section-schema.md) Declare editable fields and repeatable block structures using `settings()` and `blocks()`. * [Writing section view](./writing-section-view.md) Use settings and blocks in the Blade view to produce structured and styled HTML output. * [Using Sections in Templates](./using-section.md) Reference sections in JSON/YAML templates with examples and field details.

Welcome to Awesome Theme

Cart subtotal: {{ core()->currency($cart->base_sub_total) }}

{{ $category->name }}

Thank you for your order #{{ $order->id }}!

Cart subtotal: {{ core()->currency($cart->base_sub_total) }}

Compare Products By:

Error {{ $errorCode }}

Welcome to our Store!

{{ $page->title }}

{{ $product->name }}

Results for "{{ $query }}"

Forgot your password?

liveUpdate('title') }}> {{ $section->settings->title }}

{{ $section->settings->heading }}

{{ $section->settings->text }}

Section Title

Your Benefits