• Features
• Prerequisites
  • Composer Installation Instructions
    • 3.x version:
  • Settings and translations
    • Configuration file
    • Translations
    • Configure the plugin per panel
• Usage
• Integrations
  • TinyMCE editor integration
  • TipTap editor integration
  • GalleryPicker Form Field
  • Lightbox (frontend)
    • Blade directives
    • Helper functions
• Other configuration options
  • Disable image optimizations
• Changelog
• Support

Unlock the full potential of galleries management with the Laravel Filament Gallery, a feature-rich solution designed to streamline and enhance your gallery-related tasks. This package offers an array of advanced functionalities, empowering you to effortlessly organize, showcase, and administer your media assets with precision and ease.

This plugin provides a toolset for managing and displaying galleries on your website with ease and efficiency. It is designed to work seamlessly with the Filament Admin package, allowing you to take full advantage of its powerful features:

#Features

• Gallery Resource Page - Manage your galleries using the Filament Admin Panel. The plugin provides a dedicated resource page that allows you to create, edit, and delete galleries. You can also use the resource page to upload, edit, and delete images, as well as to reorder them using drag-and-drop functionality.
• Gallery Picker Form Field - provides a custom form field that allows you to select a gallery using a modal window. You can use this field in your resources to associate a gallery with a model. Customize the appearance of your galleries by creating your own views.
• Lightbox - The plugin provides a lightbox that allows you to display galleries on the frontend. You can use the lightbox to display galleries in your views, or you can use the provided Blade directives and helper functions to display galleries in your content.
• TinyMCE Editor Integration - The plugin provides a button that allows you to insert a gallery shortcode into the TinyMCE editor.
• TipTap Editor Integration - The plugin provides a button that allows you to insert a gallery shortcode into the TipTap editor.
• Blade directives and custom helpers - The plugin provides Blade directives and custom helpers that allow you to display galleries in your views.
• Media conversions - customize the size and format of your images to suit your needs.
• Dark mode support - The plugin supports dark mode out of the box.
• Translations - The plugin is fully translatable. You can easily translate it into your language using the provided translations file. The plugin currently supports English, Polish and German.
• Highly customizable - You can easily customize the appearance of your galleries by creating your own views for frontend. You can also customize the plugin's configuration file to suit your needs.

Light mode	Dark mode

To ensure these installation guidelines are effective, you must have the Filament Admin package properly installed and configured.

Additionally, please note that this package relies on the Spatie MediaLibrary package. For additional image optimizations and conversions, you should have the ImageMagick or GD PHP extensions installed on your server. If your web server does not have these extensions installed, you can still use the package, but have to disable the image optimization for each conversion in the config file.

#Prerequisites

You should have the Filament Admin v3.x or Filament Admin v2.x package properly installed and configured. Plugin uses Spatie MediaLibrary package. If you already have it installed, you can skip this step.

To install run this command:

composer require "spatie/laravel-medialibrary"

You need to publish the migration to create the media table:

php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="medialibrary-migrations"

#Composer Installation Instructions

To add the package to your project using Composer, follow these steps:

1. Start by including the package in your project's composer.json file within the repositories section:

{
  "repositories": [
    {
      "type": "composer",
      "url": "https://filament-gallery.composer.sh"
    }
  ],
}

2. Then, request the package via the command line. During this process, you'll need to provide your email address as the username and your license key along with a colon (':') followed by the domain where you activated it as your password. This information will be provided from your Anystack account where you purchased the package.

If you intend to use the plugin in Filament version 2.x, make sure to require version '^2.0'. For Filament version 3.x, you can simply require version '^3.0', or omit the version altogether as it is the default.

#3.x version:

composer require naturalgroove/laravel-filament-gallery

####2.x version:

composer require naturalgroove/laravel-filament-gallery:^2.0

Loading composer repositories with package information
Authentication required (laravel-filament-gallery.composer.sh):
Username: [licensee-email]
Password: [license-key]

You will be prompted to provide your username and password. Your username will be your email address, and your password will be equal to your license key. If your license policy requires a fingerprint, you will need to append your fingerprint to your license key. For example, let's say you have the following licensee and license activation:

Contact email: your-email@example.com License key: 8c21df8f-6273-4932-b4ba-8bcc723ef500 Activation fingerprint: your-website-domain-address.com

After Composer installation, you will need to install the plugin. Best way to do it is to run the following command:

php artisan filament-gallery:install

This command will publish the migration and migrate the database and asks You for optional assets and config publishing.

#Settings and translations

Settings can be managed through the plugin's config file. You can publish the config file using the following:

#Configuration file

php artisan vendor:publish --tag="filament-gallery-config"

#Translations

If you want to translate the plugin into your language, you need to publish the translations file using the following command:

php artisan vendor:publish --tag="filament-gallery-translations"

#Configure the plugin per panel

You need to register the plugin for each panel you want to use it in. To do so, you need to add the following code to the panel's provider class:

use NaturalGroove\Filament\Gallery\FilamentGalleryPlugin;
 
$panel
    ->plugins([
        [...]
        FilamentGalleryPlugin::make()
    ])

#Usage

After installing the plugin, you can access the gallery resource page by clicking on the Galleries link in the sidebar menu. The gallery resource page allows you to create, edit, and delete galleries. You can also use the resource page to upload, edit, and delete images, as well as to reorder them using drag-and-drop functionality.

Each image in the gallery can be edited individually. You can change the caption and alternative name as well as its position in the gallery. You can also delete the image from the gallery.

#Integrations

This plugin offers a variety of integration options, allowing you to seamlessly incorporate it into your Filament Admin Panel and your app frontend.

#TinyMCE editor integration

Note This integration utilizes the TinyEditor plugin for the Filament Admin Panel. If you haven't already installed it, you need to do so before proceeding.

Integration adds a button to the TinyMCE editor toolbar that opens a modal window with a list of galleries. You can select a gallery and insert a gallery shortcode into the editor. To enable this feature, you need to publish the plugin's assets using the following command:

php artisan vendor:publish --tag="filament-gallery-tinymce-plugin"

Make sure the config from the TinyEditor plugin plugin is published - if not run the following command:

php artisan vendor:publish --tag="filament-forms-tinyeditor-config"

and then add the following code to your TinyMCE configuration file config/filament-tiptap-editor.php:

[...]
'profiles' => [
 
    'default' => [
        [...]
        'plugins' => '... linkgallery',
        'toolbar' => '... hr linkgallery | ...',

Of course the position for the button or profile name can be different. It is up to you where you want to place the button.

#TipTap editor integration

Note This integration utilizes the Tiptap editor for the Filament Admin Panel. If you haven't already installed it, you need to do so before proceeding.

Integration adds a button to the TipTap editor toolbar that opens a modal window with a list of galleries. You can select a gallery and insert a gallery shortcode into the editor.

Make sure the config from the TipTap editor plugin is published - if not run the following command:

php artisan vendor:publish --tag="filament-tiptap-editor-config"

and then add the following code to your Tiptap configuration file config/filament-tiptap-editor.php:

[...]
'extensions' => [
    [
        'id' => 'filament-gallery',
        'name' => 'Filament Gallery',
        'button' => 'filament-gallery::tiptap-button-toolbar',
        'parser' => NaturalGroove\Filament\Gallery\TipTap\Extensions\FilamentGalleryExtension::class,
    ]
],

#GalleryPicker Form Field

Filament Gallery plugin provides custom Form Field that allows you to select a gallery using a modal window. For example to use this field in Your resources you need to add the following code to the resource's class:

[...]
public static function form(Form $form): Form
{
return $form
    ->schema([
        [...]
        \NaturalGroove\Filament\Gallery\Forms\Components\GalleryPicker::make('gallery_id')
            ->name('Associated gallery')
            ->buttonLabel('Select Gallery')
            ->columnSpanFull(),
    ]);
}

gallery_id is the name of the attribute that will be used to store the gallery ID in your model. There is also a command that helps you add attribute to your model. You colud simply run the following command:

php artisan filament-gallery:relation-migration YourModelName

This command will add gallery_id attribute to your model and create a migration for it. The You simply run the migration and you are ready to go.

Additionally you can add the following code to your model:

[...]
use NaturalGroove\Filament\Gallery\Traits\HasGallery;
[...]
 
class YourModelName extends Model
{
    use HasGallery;

This will add a relation to your model and you can easilly access the gallery using $model->gallery attribute.

#Lightbox (frontend)

Note This integration with default settings uses Simplelightbox plugin.

This plugin provides a lightbox that allows you to display galleries on the frontend. To use it, you need to publish the plugin's assets using the following command:

php artisan vendor:publish --tag="filament-gallery-lightbox"

The simplest and easiest way to use the lightbox is to add the following code to your layout file right before the closing </body> tag:

[...]
    @stack('filament-gallery-scripts')
    @stack('filament-gallery-styles')
</body>
</html>

Second method is to add the following code on the top to your main CSS and JS files:

@import "../../vendor/naturalgroove/laravel-filament-gallery/resources/dist/filament-gallery-lightbox.css";

import '../../vendor/naturalgroove/laravel-filament-gallery/resources/dist/filament-gallery-lightbox.js';

Note Lightbox integration uses Alpine.js. Make sure you have it installed and configured properly.

To display a gallery on the frontend, you need to use one of the following methods:

#Blade directives

@filamentGallery($gallery_id, $view)

where $gallery_id is the ID of the gallery you want to display. $view parameter is optional and allows you to specify the view that will be used to render the gallery. If you don't specify the view, the default view configured in the config file will be used.

@renderWithGallery($content, $view)

where $content is the content that contains gallery shortcodes. $view parameter is optional and can be used as described above.

#Helper functions

{{ filament_gallery($gallery_id, $view) }}

where $gallery_id is the ID of the gallery you want to display. $view parameter is optional and can be used as described above.

{{ render_with_gallery($content, $view) }}

where $content is the content that contains gallery shortcodes. $view parameter is optional and can be used as described above.

You can register your own views by adding the following code to the filament-gallery.php config file:

[...]
'lightbox' => [
    [...]
    'views' => [
        'simple' => 'filament-gallery::gallery.frontend.simple',
+       'fancy' => 'lightbox.my-fancy-view',
    ],
-   'default-view' => 'simple',
+   'default-view' => 'fancy',

As You can see the fancy view is the now set to default view.

#Other configuration options

#Disable image optimizations

If you don't have ImageMagick or GD PHP extensions installed on your server (shared hosting), you can still use the package, but You have to disable the image optimization for each conversion in the config file.

[...]
'conversions' => [
    'thumb' => [
        'width' => 100,
        'height' => 100,
-       'optimize' => true,
+       'optimize' => false,
    ],
    'medium' => [
        'width' => 300,
        'height' => 300,
-       'optimize' => true,
+       'optimize' => false,
    ],
    'large' => [
        'width' => 800,
        'height' => 800,
-       'optimize' => true,
+       'optimize' => false,
    ],
],
[...]

Make sure you have the optimize option set to false for each conversion.

#Changelog

Please see CHANGELOG for more information on what has changed recently.

#Support

If you have a question or feature request, please e-mail me at filament-gallery@netseven.dev.

Also you can use the Discord Channel to ask questions and get support.

All ideas and suggestions are welcome.