Theming

The base theming is located within rapidez/core which you can publish to your project and change it. Alternatively, you can create your own package with views, CSS, and Javascript like a theme.

TIP

Read the Laravel Blade Templates docs before you begin.

Views

To change the views, you can publish them with:

bash

php artisan vendor:publish --provider="Rapidez\Core\RapidezServiceProvider" --tag=views

After that, you'll find all the Rapidez Core views in resources/views/vendor/rapidez. For more information, see Overriding Package Views in the Laravel docs.

TIP

It's recommended to only add the views you've changed into your source control for upgradability. To keep track of what you've changed in a view, it's a good idea to add the unchanged version to version control before you make any changes.

CSS

We're using Tailwind CSS with Vite, so probably you don't need to touch the CSS, but if you need to add a simple class, the "starting point" is resources/css/app.css. From there, we include the core styling and that's where the color variables can be defined. For any Tailwind changes, you'll need to be within the tailwind.config.js.

But... I don't like Tailwind CSS

If you don't like Tailwind CSS you can use anything else. But it's widely used in Rapidez packages, so we don't recommend it. Just clear out the resources/css/app.css and write your own.

Colors

Colors can be configured from resources/css/app.css and all colors used by Rapidez can be found within the tailwind.config.js. This is just a starting point to easily change the whole look and feel with some variables. We advice you to use those variables / classes as much as possible but you're free to use anything else.

The colors variables are inspired by GitHub Primer where Tailwind CSS provides the "base color tokens", see: design token categories and within the tailwind.config.js we're just "aliasing" those to "functional color tokens". More information with examples on color naming can be found in the color names refactor pull request.

Semantic colors

These colors can be used to apply your branding. There is one "modifier" by default provided: text. That color modifier is used for the text on top of the color, for example with buttons. The conversion color is used for anything "conversion" related.

Color name	CSS variable	Default color
`primary`	`--primary`	`#2FBC85`
`primary-text`	`--primary-text`	`white`
`secondary`	`--secondary`	`#202F60`
`secondary-text`	`--secondary-text`	`white`
`conversion`	`--conversion`	`green-500`
`conversion-text`	`--conversion-text`	`white`

These color names work the same as Tailwind colors. You can use them for anything, for exmaple: bg-primary, border-primary, text-primary, etc.

Neutral colors

Used for the text color, borders and backgrounds to give some design system to work with. Visual examples can be found with in the Primer neutral colors docs. These colors should not be used directly: ~~text-foreground~~ as those colors are "linked and scoped" to the text, border and background colors. Just use the provided classes to keep a consistent style.

Text / Foreground

Class	CSS variable	Default color
`text-emphasis`	`--foreground-emphasis`	`slate-900`
`text` / `text-default`	`--foreground`	`slate-800`
`text-muted`	`--foreground-muted`	`slate-600`

Border

Class	CSS variable	Default color
`border-emphasis`	`--border-emphasis`	`slate-500`
`border` / `border-default`	`--border`	`slate-200`
`border-muted`	`--border-muted`	`slate-100`

Background

Class	CSS variable	Default color
`bg-emphasis`	`--background-emphasis`	`slate-200`
`bg` / `bg-default`	`--background`	`slate-100`
`bg-muted`	`--background-muted`	`slate-50`

Javascript

We automatically import everything in resources/js/app.js, and you can extend from there. If you need additional Vue components, read the readme within the components folder.

Blade Directives

Rapidez provides some Blade Directives to easily get information from Magento.

Caching

Keep in mind the output of these directives is cached! So after changing a configuration, block, or widget, the cache needs to be cleared. See the caching docs.

`@config`

Get a config value for the current store scope with optionally a fallback, example:

blade

@config('general/locale/timezone', 'Europe/Amsterdam')

A third parameter can be set to true when it's a sensitive/encrypted config.

`@block`

Get the block contents for the current store scope:

blade

@block('your_block_identifier')

Optionally, you can specify a second argument with an array, which will be passed through to the strtr function to replace data within the block, for example:

blade

@block('footer_links_block', [
    '<a' => '<a class="text-red-600"'
])

`@content`

Processes content containing variables from Magento so that variables, blocks, and widgets are working.

blade

@content($page->content)

Created your own variables? Have a look at the content-variables configuration.

`@widget`

Used to specify a widget location where widgets can be rendered.

blade

@widget('location', 'type', 'handle', $entityId)

Have a look at the current widget locations we've added by default and the widget tables in the database to see how the parameters work. Custom widgets can be defined with the widgets configuration.

Blade Components

Rapidez uses a separated package with Blade Components for inputs, checkboxes, buttons, etc. See: rapidez/blade-components. An example of the input component:

blade

<label>
    <x-rapidez::label>Something</x-rapidez::label>
    <x-rapidez::input name="something" class="extra-styling" />
</label>

Additionally, there are some Rapidez specific components within the core. See the resources/views/components/ directory.

TIP

Try to use these elements as much as possible, so that if you'd like to change the appearance you can do so in only one place.

Another example is the "productlist" component, which outputs a nice product list:

blade

<x-rapidez::productlist :value="['MS04', 'MS05', 'MS09']"/>

Rapidez is using this component to render the related products, up-sells, and cross-sells, but it can be used anywhere.

Blade Icons

Rapidez comes preinstalled with Blade Icons, providing a massive library of icons you can use in your project! With many icon packages available to get even more icons.

Icon Deferring

We've added Icon deferring support to Blade Icons in order to reduce HTML element count when icons are used often. In Rapidez, this is enabled by default. If you would rather turn it off, you can change it globally in the options by publishing the config with:

bash

php artisan vendor:publish --tag=blade-icons

And adding 'defer' => false to the 'attributes' section within the config file:

php

...
'attributes' => [
    // 'width' => 50,
    // 'height' => 50,
    'defer' => false
],
...

Or per icon:

blade

<x-heroicon-s-heart class="h-6 w-6 text-red-600" :defer="false" />

Vue Directives

On top of Vue, we've added some extra directives.

`v-blur`

Just like v-cloak, but instead of hiding, the element will be blurred. Useful if you don't like to have any layout shifts.

`v-on-click-away`

Rapidez uses vue-clickaway, enabling you to close something if you click away from the element. An example can be found within the core.

Multistore

Rapidez also has support for multiple themes! This is based on the MAGE_RUN_CODE.

Blade

In config/rapidez.php, you can define the themes you'd like to be used per store code:

php

'themes' => [
    'default' => resource_path('themes/default'),
    'extra_store' => resource_path('themes/extra_store'),
    'extra_store_nl' => resource_path('themes/extra_store'),
],

In this example, we have the default store using a "default" theme. The extra store in both languages is using the same "extra_store" theme since its changes are only translations.

The structure of your theme folder will be the same as your views folder, so overriding the views folder is as simple as copying and pasting the file with the correct folder structure.

Tailwind & CSS

If you only want to change some Tailwind colors and styling in your multistore and do not need to overwrite any templates, it may be a good idea to only use a different Tailwind config. This can be done by editing your Vite config to generate different CSS files with different Tailwind configs.

vite.config.js

export default defineConfig({
    plugins: [
        laravel({
            input: [
                'resources/css/app.css',
                'resources/css/app.<store_code>.css',
                'resources/css/app.<another_store_code>.css',
                'resources/js/app.js',
            ],

resources/css/app.<store_code>.css

css

@import "./<store_code>/config.css";
@import "./app.css";

resources/css/<store_code>/config.css

css

@config "../../../tailwind.<store_code>.js";

tailwind.<store_code>.js

module.exports = {
    presets: [
        require('./tailwind.config.js')
    ],
    theme: {
        colors: {
            blue: {
                100: '#EAF1F4',
                110: '#CCDFE8',
                200: '#D0D9DC',
                300: '#A0B1B9',
                400: '#6A8693',
                900: '#143F51',
            }
        },
    }
}

resources/views/layouts/app.blade.php

blade

@vite([
    'resources/css/app.css',
    'resources/css/app.' . config('rapidez.store_code') . '.css',
    'resources/js/app.js'
])

Of course, you can do this any way you want if you want to load the same CSS for specific stores. Map the store code to a theme name and use that as your CSS file.

Translations

You can create a JSON file for your language within the lang directory, for example: /lang/de.json. As an example, have a look at the existing translations in the core. For more information, read the Laravel Localization docs.

In the core, we also have a frontend.php translation file per language. These translations will be available from Javascript with: config.translations.key. To publish them to your project, use:

bash

php artisan vendor:publish --provider="Rapidez\Core\RapidezServiceProvider" --tag=rapidez-translations

Theming ​

Views ​

CSS ​

Colors ​

Semantic colors ​

Neutral colors ​

Text / Foreground ​

Border ​

Background ​

Javascript ​

Blade Directives ​

@config ​

@block ​

@content ​

@widget ​

Blade Components ​

Blade Icons ​

Icon Deferring ​

Vue Directives ​

v-blur ​

v-on-click-away ​

Multistore ​

Blade ​

Tailwind & CSS ​

Translations ​

Theming

Views

CSS

Colors

Semantic colors

Neutral colors

Text / Foreground

Border

Background

Javascript

Blade Directives

`@config`

`@block`

`@content`

`@widget`

Blade Components

Blade Icons

Icon Deferring

Vue Directives

`v-blur`

`v-on-click-away`

Multistore

Blade

Tailwind & CSS

Translations