From cd738732eb6bb1f999dd4dfdc14c521fae05a193 Mon Sep 17 00:00:00 2001 From: Diogo Pinto Date: Tue, 29 Oct 2024 12:40:09 +0000 Subject: [PATCH 01/11] Add diogogpinto-filament-themes-full-guide.md content and respective art --- .../diogogpinto-filament-themes-full-guide.md | 333 ++++++++++++++++++ .../after-create-theme.webp | Bin 0 -> 89958 bytes .../blade-backdrop-blur.webp | Bin 0 -> 143916 bytes .../breadcrumb-example.webp | Bin 0 -> 138906 bytes .../breadcrumbs-final.webp | Bin 0 -> 111316 bytes .../create-theme.webp | Bin 0 -> 57528 bytes .../npm-run-build.webp | Bin 0 -> 76080 bytes .../vendor-publish.webp | Bin 0 -> 74432 bytes 8 files changed, 333 insertions(+) create mode 100644 content/articles/diogogpinto-filament-themes-full-guide.md create mode 100644 public/images/content/articles/diogogpinto-filament-themes-full-guide/after-create-theme.webp create mode 100644 public/images/content/articles/diogogpinto-filament-themes-full-guide/blade-backdrop-blur.webp create mode 100644 public/images/content/articles/diogogpinto-filament-themes-full-guide/breadcrumb-example.webp create mode 100644 public/images/content/articles/diogogpinto-filament-themes-full-guide/breadcrumbs-final.webp create mode 100644 public/images/content/articles/diogogpinto-filament-themes-full-guide/create-theme.webp create mode 100644 public/images/content/articles/diogogpinto-filament-themes-full-guide/npm-run-build.webp create mode 100644 public/images/content/articles/diogogpinto-filament-themes-full-guide/vendor-publish.webp diff --git a/content/articles/diogogpinto-filament-themes-full-guide.md b/content/articles/diogogpinto-filament-themes-full-guide.md new file mode 100644 index 000000000..2a83acb6d --- /dev/null +++ b/content/articles/diogogpinto-filament-themes-full-guide.md @@ -0,0 +1,333 @@ +--- +title: "Filament Custom Themes - The Full Guide" +slug: diogogpinto-filament-themes-full-guide +author_slug: diogogpinto +publish_date: 2024-29-10 +categories: [panel-builder] +type_slug: article +--- + +Welcome to this "full guide" on how to create a custom theme in Filament v3. + +Are you looking to elevate your Filament v3 Panels with a unique appearance? This in-depth guide will take you beyond the basics covered in the official documentation. + +## Resources + +I would recommend checking the following resources if you haven't already. + +- [Filament Official Documentation](https://filamentphp.com/docs/) + - [Filament Official Documentation on Themes](https://filamentphp.com/docs/3.x/panels/themes#creating-a-custom-theme) + - [Filament Official Documentation on Style Customization](https://filamentphp.com/docs/3.x/support/style-customization) +- [Tailwind Official Documentation](https://tailwindcss.com/docs/installation) + +## Before You Start + +I am assuming you already have a Filament Panel setup. If you don't have one, please set up a panel using the [official documentation guide](https://filamentphp.com/docs/3.x/panels/getting-started). + +## Creating a theme + +In this example, we will be creating a custom theme for Filament's default panel, the `admin`panel. + +> [!note] +> The same steps apply for any other panel you may have in your Filament project + +### Creating the theme using the terminal + +In your project's root directory, run: + +```bash +php artisan make:filament-theme +``` + +It will scan your app for all the panels you have installed and let you select which panel this themes applies to. Select the panel which you wish to customize. In this particular case, we will select the panel `admin`. + +![Create Theme Terminal Command](/images/content/articles/diogogpinto-filament-themes-full-guide/create-theme.webp) + +After you've selected the panel, the terminal will give you all further instructions, but we'll go by each one step by step. + +![After Creating the Theme](/images/content/articles/diogogpinto-filament-themes-full-guide/after-create-theme.webp) + +#### Editing vite.config.js + +Go to the `vite.config.js` file in your project's root directory and set the input array like below: + +```javascript +import { defineConfig } from 'vite' +import laravel, { refreshPaths } from 'laravel-vite-plugin' + +export default defineConfig({ + plugins: [ + laravel.default({ + input: [ + 'resources/css/app.css', + 'resources/js/app.js', + // Add the following line of code + 'resources/css/filament/admin/theme.css' + ], + refresh: [ + ...refreshPaths, + 'app/Filament/**', + 'app/Forms/Components/**', + 'app/Livewire/**', + 'app/Infolists/Components/**', + 'app/Providers/Filament/**', + 'app/Tables/Columns/**', + ], + }), + ], +}) +``` + +See how we've added `resources/css/filament/admin/theme.css` to that array? This will tell vite where our custom theme is located when running the build process. + +>[!note] +> If you have other themes for other panels, you can add them in the same array. This vite config file can contain as many themes for as many panels as you like! + +#### Registering the viteTheme() on our panel + +Now we shall edit the `AdminPanelProvider.php` file and add the viteTheme method to our `$panel`, like the example below: + +```php +return $panel + ->id('admin') + ->viteTheme('resources/css/filament/admin/theme.css') // Added this line of code +``` + +Our panel now knows we are using a custom theme and what our theme path is. + +#### Running the build process + +![Build Process](/images/content/articles/diogogpinto-filament-themes-full-guide/npm-run-build.webp) + +At last, we shall run the build process with the terminal in our project's root directory: + +```bash +npm run build +``` + +### Registering vendor files from Filament Plugins + +Sometimes, when installing plugins like [Auth UI Enhancer](https://www.github.com/diogogpinto/filament-auth-ui-enhancer) or [Filament Curator](https://github.com/awcodes/filament-curator), for example, the docs may say something to the effect of: + +> 1. Add the plugin's views to your tailwind.config.js file. +> ```javascript +> content: [ +> './vendor/diogogpinto/filament-auth-ui-enhancer/resources/**/*.blade.php', +> ] +> ``` + +#### What does this mean? + +We need to make sure that - when we start the building process - `vite` will check the files in the paths specified in the `content`array and collect all used CSS classes in the plugin views. It will then compile all used CSS classes into the one single CSS file in your Filament panel. + +So, in our case, installing `Auth UI Enhancer` and `Curator`plugin in our panel, we will go to `resources/css/filament/admin/tailwind.config.js`and edit it like the code below: + +```js +import preset from '../../../../vendor/filament/filament/tailwind.config.preset' + +export default { + presets: [preset], + content: [ + './app/Filament/Clusters/Products/**/*.php', + './resources/views/filament/clusters/products/**/*.blade.php', + './vendor/filament/**/*.blade.php', + // Added the following lines of code + './vendor/diogogpinto/filament-auth-ui-enhancer/resources/**/*.blade.php', + './vendor/awcodes/filament-curator/resources/**/*.blade.php', + ], +} +``` + +Additionally, in the case of the `Curator` plugin, the author requires you to import some CSS files in your `theme.css`. This can be done, by editing the file `resources/css/filament/admin/theme.css` and making it look like below: + +```css +@import '/vendor/filament/filament/resources/css/theme.css'; +@import '/node_modules/cropperjs/dist/cropper.css'; +@import '/vendor/awcodes/filament-curator/resources/css/plugin.css'; + +@config 'tailwind.config.js'; +``` + +This last step imports all custom classes needed by the plugin to render correctly. It imports the class, puts into our panel's unique CSS file and minimizes it all for greater performance. + +#### Running the build process + +When installing plugins and editing any theme related files, always remember to run `npm run build` when you're finished to compile all the assets. + +## Customizing the theme + +Laravel, and Filament being Laravel based, offer multiple solutions to the same problem. So, we will address two ways of building your own Filament look and feel, the recommended way and the not-so-recommended way. Let's start with the latter. + +### Before starting the customization process + +You should start the `npm run dev` process in the root of your project. This process watches for changes in the files registered in the `vite.config.js` (and `tailwind.config.js` by extension) and automatically builds a temporary CSS file to render the changes on file save. + +> [!note] +> You still need to run `npm run build` when you're done customizing your theme + +### The recommended way to customize your theme + +The Filament panels core offers you a list of classes. Every component of the panel layout, including forms, infolists and tables, were wrapped in custom classes to make it possible, for any developer, to customize the panel look and feel. Let's look at the following example: + +![Breadcrumb Example](/images/content/articles/diogogpinto-filament-themes-full-guide/breadcrumb-example.webp) + +Looking at the breadcrumb component with Chrome's builtin Developer Tools > Inspect Element, you can see that the `