yaap/theme

Theme support for Laravel 4/5 with assets, theme extends etc.

Saturday, July 22, 2017
by yaapis
Repository
4 Watchers
81 Stars
12,425 Installations

PHP
3 Dependents
0 Suggesters
15 Forks
1 Open issues
19 Versions
5 % Grown

The README.md

Theme support for Laravel

Inspired by bigecko/laravel-theme. Themes are stored inside default laravel's resources folder, _(*1)

Introduction

This package provides a simple way to manage themes in Laravel applications., _(*2)

For example, you can develop multiple themes for your application and easily switch between themes for different purposes., _(*3)

Requirements

This version requires PHP 8.1 and supports Laravel 10-11., _(*4)

This package also provides support for Laravel Mix and Vite configurations., _(*5)

Themes	L5.5	L5.6	L5.7	L5.8	L6	L7	L8	L9	L10	L11
2.4	:white_check_mark:	:white_check_mark:	:white_check_mark:	:white_check_mark:	:x:	:x:	:x:	:x:	:x:	:x:
3.0	:x:	:x:	:x:	:x:	:white_check_mark:	:x:	:x:	:x:	:x:	:x:
4.1	:x:	:x:	:x:	:x:	:x:	:x:	:white_check_mark:	:white_check_mark:	:white_check_mark:	:x:
5.0	:x:	:x:	:x:	:x:	:x:	:x:	:x:	:x:	:white_check_mark:	:x:
5.1	:x:	:x:	:x:	:x:	:x:	:x:	:x:	:x:	:white_check_mark:	:white_check_mark:

Installation

To get the latest version, simply require the project using Composer:, _(*6)

composer require "yaap/theme:^5.0"

or manually add line to composer.json, _(*7)

{
    "require": {
        "yaap/theme": "^5.0"
    }
}

Optionally, publish config using artisan CLI (if you want to overwrite default config)., _(*8)

php artisan vendor:publish --provider="YAAP\Theme\ThemeServiceProvider"

Configuration

Package config

Config in config/theme.php file., _(*9)

return [

    /*
    |--------------------------------------------------------------------------
    | Path to directory with themes
    |--------------------------------------------------------------------------
    |
    | The directory with your themes.
    |
    */

    'path' => base_path('themes'),

    /*
    |--------------------------------------------------------------------------
    | Path to directory with assets build
    |--------------------------------------------------------------------------
    |
    | The directory with assets build in public directory.
    |
    */

    'assets_path' => 'themes',

    /*
    |--------------------------------------------------------------------------
    | A pieces of theme collections
    |--------------------------------------------------------------------------
    |
    | Inside a theme path we need to set up directories to
    | keep "layouts", "assets" and "partials".
    |
    */

    'containerDir' => [
        'assets' => 'assets',
        'lang' => 'lang',
        'layout' => 'views/layouts',
        'partial' => 'views/partials',
        'view' => 'views',
    ],
];

Theme config

Config in theme folder. Placeholder %theme_name% will be replaced with theme name on creation., _(*10)

return [

    /*
    |--------------------------------------------------------------------------
    | Theme name
    |--------------------------------------------------------------------------
    |
    | Use in assets publishing etc.
    |
    */

    'name' => '%theme_name%',

    /*
    |--------------------------------------------------------------------------
    | Inherit from another theme
    |--------------------------------------------------------------------------
    |
    | Set up inherit from another if the file is not exists.
    |
    */

    'inherit' => null,

];

Usage

Create theme with artisan CLI

Create command

The first time you have to create theme default structure, using the artisan command:, _(*11)

php artisan theme:create default

By default, it will use vite as assets builder. If you want to use laravel mix instead, use the command:, _(*12)

or with laravel mix:, _(*13)

php artisan theme:create default mix

Destroy command

To delete an existing theme, use the command:, _(*14)

php artisan theme:destroy default

Structure

Here is an example of the folder structure of project with theme, _(*15)

project-root
├── app/
<...>
├── public/
|   ├── index.php
|   └── themes/
|       └── default/
|           ├── js/
|           |   └── app.js
|           ├── css/
|           |   └── styles.css
|           └── images/
|               └── icon.png
├── resources/
<...>
├── themes/
|   ├── default/
|   |   ├── assets/        
|   |   ├── lang/        
|   |   ├── views/
|   |   |   ├── layouts/
|   |   |   ├── partials/
|   |   |   └── hello.blade.php
|   |   └── config.php
|   ├── admin/
|   ├── views/
|       ├── emails/
|       |   └── notify.blade.php
|       └── hello.blade.php

Init theme

To init and use theme in your application, add the following code to any boot method in application service provider (e.g. AppServiceProvider):, _(*16)

use YAAP\Theme\Facades\ThemeLoader;

class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        ThemeLoader::init('default');
    }
}

This will add to views find path:, _(*17)

themes/{$name}/views

Lang files will be added as well:, _(*18)

themes/{$name}/lang

Making view

Laravel: Creating & Rendering Views, _(*19)

View::make('hello');
View::make('emails.notify');

// or

view('hello');
view('emails.notify');

Assets

Vite

If you use Vite, ensure vite.config.js have specified the input path for theme, _(*20)

import {defineConfig} from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            input: [
                'themes/default/assets/js/app.js', // for default theme
                // ...
            ],
            refresh: true,
        }),
    ],
});

Because app.js includes app.scss you can use the following code to include assets in your views:, _(*21)

<head>
    <!--...-->
    @vite([
        'themes/default/assets/js/app.js',
    ])
</head>

Laravel Mix

If you use Laravel Mix, ensure webpack.mix.js have specified mix configuration for theme, _(*22)

const mix = require('laravel-mix');

mix.disableNotifications();
mix.browserSync({
    open: true,
    proxy: 'localhost:8000',
    files: [
        'app/**/*',
        'routes/**/*', 
        'themes/**/*', // manually add this line
    ]
});

// other configutraions...

// mix for default theme
mix.copyDirectory('themes/default/assets/img', 'public/themes/default/img');
mix.copyDirectory('themes/default/assets/fonts', 'public/themes/default/fonts');
// js
mix.js(['themes/default/assets/js/app.js'], 'public/themes/default/js/app.min.js')
// sass
mix.sass('themes/default/assets/sass/app.scss', 'public/themes/default/css/app.min.css')

Then you can use the following code to include assets in your views:, _(*23)

in the <head> tag, _(*24)

<head>
    <!--...-->
    <link rel="stylesheet" href="{{ mix('/themes/default/css/app.min.css') }}"/>
</head>

and before </body> tag, _(*25)

<body>
    <!--...-->
    <script type="text/javascript" src="{{ mix('/themes/default/js/app.min.js') }}"></script>
</body>

To use images, you can use the following code:, _(*26)

<img src="{{ mix('themes/default/img/icon.png') }}" alt="icon">

Building layouts

Layouts using Components

Laravel: Blade Components, _(*27)

Layouts using template inheritance

To build layouts we use template inheritance. You can use @extends directive to specify a parent layout., _(*28)

@extends('layouts.master')

@include('partials.header')

@section('content')
    <section id="main">
        <h1>HOME</h1>
    </section>
@stop

@include('partials.footer')