zanysoft/laravel-theme

Laravel 主题管理器，帮助您在 Laravel 项目中组织和维护主题。

维护者

详细信息

github.com/zanysoft/laravel-theme

主页

源代码

问题

安装: 387

依赖项: 0

建议者: 0

安全: 0

星标: 1

关注者: 2

分支: 0

开放问题: 0

2.0.4 2023-08-11 06:12 UTC

Requires

Suggests

MIT 25828f33a8b14c887b0683cc09bd303af9fc7d1f

assetsthemelaravelviewsbladelaravel-theme

This package is auto-updated.

Last update: 2024-09-11 08:37:01 UTC

README

Laravel License Downloads

这是一个 Laravel 扩展包，用于管理主题的基本支持。它允许您在单独的文件夹中构建视图和您的资源，并支持主题扩展！太棒了 :)

功能

  • 主题文件夹中的视图和资源分离
  • 主题继承：扩展任何主题并创建主题层次结构
  • 集成 Orchestra/Asset 以提供资源依赖管理
  • 您的应用程序和视图与主题无关。几乎无需修改即可包含新主题
  • 主题可分发！创建单个文件的主题包并在任何 Laravel 应用程序上安装它。
  • 附带用于管理主题的控制台命令

1 安装

此包设置非常简单。只有几个步骤。

使用 Composer 安装

composer require zanysoft/laravel-theme

如果您使用的是 Laravel 5.4 或更早版本，您需要将以下内容添加到您的 config/app.php 中（对于 Laravel 5.5 及更高版本，这些将被 Laravel 自动发现）

'providers' => [
    // ...
    ZanySoft\LaravelTheme\ThemeServiceProvider::class,
];

'aliases' => [
    // ...
    'Theme' => ZanySoft\LaravelTheme\Facades\Theme::class,
]

将包配置文件发布到您的应用程序。在终端中运行以下命令。

php artisan vendor:publish --provider="ZanySoft\LaravelTheme\ThemeServiceProvider" 那就这样。现在您可以开始为主题化应用程序了！

2 创建主题

有两种等价的方式来定义一个主题。您可以挑选更适合您的一种

####A) 使用 theme.json 文件配置主题

提示：您应该使用 php artisan theme:create 命令来创建主题。以下为手动步骤

在视图路径的根目录下创建一个新文件夹，然后在其中放置一个 theme.json 文件并添加一些配置

{
  "name"        : "THEME_NAME",
  "asset-path"  : "ASSET_PATH",
  "extends"     : "PARENT_THEME"
}

重要提示

  • THEME_NAME 是您主题的名称。可以是任何字符串。
  • ASSET_PATH 相对于 public 路径。您也应该创建这个文件夹！
  • PARENT_THEME 是父主题的名称。如果是独立主题，则设置为 null
  • 您可以在 json 文件中添加任何其他配置。您可以在运行时使用 Theme:getSetting('key') & Theme:setSetting('key','value') 访问您自己的设置。
  • 我们为什么没有设置视图路径？因为它就是当前路径！只需重命名当前文件夹，一切都会正常工作。

####B) 在 config/themes.php 文件中配置主题

您可能想将之前的设置（或定义新主题）覆盖到您的 config/themes.php 中。只需将您的主题添加到 themes 数组中。每个主题的格式都非常简单

// Select a name for your theme
'themes' => [
    'theme-name' => [

        /*
        |--------------------------------------------------------------------------
        | Theme to extend. Defaults to null (=none)
        |--------------------------------------------------------------------------
        */
        'extends'       => 'theme-to-extend',
  
        /*
        |--------------------------------------------------------------------------
        | The path where the view are stored. Defaults to 'theme-name' 
        | It is relative to 'themes_path' ('/resources/views' by default)
        |--------------------------------------------------------------------------
        */
        'views-path'    => 'path-to-views',
    
        /*
        |--------------------------------------------------------------------------
        | The path where the assets are stored. Defaults to 'theme-name' 
        | It is relative to laravels public folder (/public)
        |--------------------------------------------------------------------------
        */
        'asset-path'    => 'path-to-assets',
  
        /*
        |--------------------------------------------------------------------------
        | Custom configuration. You can add your own custom keys.
        | Use Theme::getSetting('key') & Theme::setSetting('key', 'value') to access them
        |--------------------------------------------------------------------------
        */
        'key'           => 'value', 
    ],
],

所有设置都是可选的，可以省略。

隐式主题声明

定义主题是完全可选的。

只要默认设置适合您，您可能不需要创建配置文件！如果尚未注册主题，则在激活时将使用默认值。

例如，如果您 Theme::set('my-theme') 并且您没有创建 theme.json 文件，也没有在 config\themes.php 文件中声明 'my-theme'，那么将假定默认位置

  • views = THEMES_ROOT_PATH/my-theme
  • assets = public/my-theme

自定义配置设置

您可以在主题中添加自己的配置（无论是 theme.json 文件还是 config/themes.php）。

这是一个添加了配置的示例 theme.json

{
  "name"        : "myTheme",
  "asset-path"  : "myTheme",
  "views-path"  : "myTheme",
  "extends"     : null,
  "thumbs-size"  : 150,
  "sidebar-position" : "right"
}

您可以在运行时使用以下方式访问这些设置

Theme::getSetting('key','default'); // read current theme's configuration value for 'key'
Theme::setSetting('key','value');    // assign a key-value pair to current theme's configuration

缓存设置

警告：主题设置已缓存以提高加载速度。如果您更改任何设置，请刷新缓存以使其生效。

使用 php artisan theme:refresh-cache 命令刷新缓存。您可以在 config\themes.php 中禁用缓存。

3 构建视图

每次您需要包含根目录的文件（图像/css/js等）路径时，可以使用以下方式获取其路径：

theme_path('path-to-file')

if(file_exists(theme_path('path-to-file')){
    //
}

每次您需要本地文件的URL（图像/css/js等）时，可以使用以下方式获取其路径：

theme_url('path-to-file',$absolute) //if absolute true then will return full url other wil return reletive to root.

path-to-file 应相对于主题文件夹（NOT到public!）。例如，如果您在 public/theme-name/img/logo.png 中放置了一个图像，那么您的Blade代码将是：

<img src="{{theme_url('img/logo.png')}}">

当您引用本地文件时，它将在当前主题层次结构中查找，并返回正确路径。如果当前主题或其父主题中找不到该文件，则可以在配置文件中定义要执行的操作：THROW_EXCEPTION | LOG_ERROR 作为警告（默认）| IGNORE 假定文件确实存在于public文件夹中，并返回路径。

您可以使用的一些有用的辅助工具

Theme::path('file-name'); // Equivalent to theme_path('filename')
    Theme::url('file-name'); // Equivalent to theme_url('filename')
    Theme::js('file-name');  // Use with {!! ... !!} syntax
    Theme::css('file-name'); // Use with {!! ... !!} syntax
    Theme::img('src', 'alt', 'class-name', ['attribute' => 'value']);

完全合格的URL

生成的URL将是完全合格的。如果需要相对于文档根的URL，则将第二个参数设置为false（默认为true）。

theme_url('path_to/file.jpg');  // "http://my-domain/theme/path_to/file.jpg"
    theme_url('path_to/file.jpg',false);  // "/theme/path_to/file.jpg"

您的域名从 app.php 配置文件中的 url 设置中检索（默认情况下将读取您的 .env 文件条目）。

URL查询

您可以在任何URL函数中包含查询。例如：

Theme::css('theme.css?ver=1.2') // theme-path/theme.css?ver=1.2

参数化文件名 您可以使用大括号将当前主题的任何配置密钥（见自定义主题设置）包含在任何路径字符串中。例如：

Theme::url('jquery-{version}.js')

如果主题配置中定义了“版本”键，则它将被评估，然后根据主题层次结构查找文件名。例如：许多商业主题提供多个版本的主.css，用于不同的配色方案，或者您可以使用语言相关的资源。

4. 扩展主题

您可以设置一个主题扩展另一个主题。检查如何创建主题部分以获取说明。子主题可以覆盖父主题的资产和视图。

当您请求的视图/资产不在您的活动主题中时，它将从其父主题中解析。您可以轻松地通过覆盖不同的视图/主题来创建您主题的变体。

资产

以下示例将帮助您了解主题层次结构的行为

\public
 +- image1.jpg
 | 
 +- \ThemeA
 |   +- image2.jpg
 |   +- image3.jpg
 | 
 +- \ThemeB   // (Also it Extends ThemeA)
     +- image3.jpg

考虑以下场景

Theme::Set('ThemeA'); // ThemeA is Active
theme_url('image1.jpg'); // = /image1.jpg
theme_url('image2.jpg'); // = /ThemeA/image2.jpg
theme_url('image3.jpg'); // = /ThemeA/image3.jpg

Theme::Set('ThemeB'); // ThemeB is Active, it extends ThemeA
theme_url('image1.jpg'); // = /image1.jpg
theme_url('image2.jpg'); // = /ThemeA/image2.jpg
theme_url('image3.jpg'); // = /ThemeB/image3.jpg

所有主题在主题文件夹中找不到资源时将回退到默认的Laravel文件夹。因此，例如，您可以将您的常用库（jQuery/bootstrap等）放在您的 public 文件夹中，并从所有主题中使用它们。不需要为每个主题重复常见资产！

视图

此行为也适用于您的视图。当Laravel渲染视图时，它将遍历活动主题的层次结构，直到找到正确的blade文件并渲染它。这甚至可以是部分视图（通过 @include 或 @extends 请求）或 @component。所有主题都将回退到Laravel默认文件夹（例如 resources\views）。

5 设置活动主题

与主题一起工作非常简单。使用：

Theme::set('theme-name');        // switch to 'theme-name'
Theme::get();                    // retrieve current theme's name
Theme::current();                // retrieve current theme (insance of ZanySoft\LaravelTheme\Theme)
Theme::exists('theme-name');     // Check if 'theme-name' is a registered theme

您应该在每次请求上设置您的活动主题。一个好的地方是在中间件中。您甚至可以在返回视图之前在控制器中定义主题。

您可以在 theme.php 配置文件中可选地设置一个默认主题，它将在应用程序引导期间激活。

使用中间件设置主题

如果想要为每个路由定义一个主题，那么包含了一个辅助中间件。要使用它：

首先在 app\Http\Kernel.php 中注册它

protected $routeMiddleware = [
    // ...
    'setTheme' => \ZanySoft\LaravelTheme\Middleware\setTheme::class,
];

现在您可以将中间件应用于路由或路由组。例如：

Route::group(['prefix' => 'admin', 'middleware'=>'setTheme:ADMIN_THEME'], function() {
    // ... Add your routes here 
    // The ADMIN_THEME will be applied.
});

示例：允许用户更改主题

场景：您有一个主题切换器，当用户点击一个主题时，然后他触发了路由，整个应用程序将应用该主题，对于所有后续请求。

注意：这只是一个模板，以帮助您开始。您可能需要根据您的需求进行修改...

路由

Route::get('/change-theme/{theme-name}', 'themeController@changeTheme');

控制器

public function changeTheme($themeName)
{
    if(Theme::exists($themeName)){
        Theme::set($themeName)
        session(['theme-name' => $themeName]);
        return redirect()->back();
    }
}

在自定义中间件中设置主题

首先创建您的中间件。例如：artisan make:middleware SetThemeFromSession

然后在您的中间件的 handle 方法中，读取存储在会话中的主题名称

public function handle($request, Closure $next)
{
    if(session()->has('theme-name')){
        \Theme::set(session('theme-name'));
    }
}

现在您需要在 app\Http\Kernel.php 文件中注册您的中间件。例如，如果您想将主题应用到所有路由上，则应将其添加到 web 数组中

'web' => [
        // ...
        \App\Http\Middleware\SetThemeFromSession::class,
    ],

6 个控制台命令

theme:list

将显示您已安装的主题列表。

php artisan theme:list

示例输出

+--------------------+--------------------+----------------------+----------------------+
|     Theme Name     |       Extends      |      Views Path      |      Asset Path      |
+--------------------+--------------------+----------------------+----------------------+
| theme1             |                    | theme1-views         | theme1-assets        |
| theme2             | theme1             | theme6               | theme6               |
+--------------------+--------------------+----------------------+----------------------+

theme:create [THEME-NAME]

将收集一些信息并创建一个新的主题。

php artisan theme:create

这是一个示例

php artisan theme:create

 Give theme name:
 > dummyTheme

 Where will views be located [Default='dummyTheme']?:
 > dummyTheme

 Where will assets be located [Default='dummyTheme']?:
 > dummyTheme

 Extends an other theme? (yes/no) [no]:
 > y

 Which one:
  [0 ] Main Theme
  [1 ] Some other Theme
 > 0

Summary:
- Theme name: dummyTheme
- Views Path: laravel-app/resources/themes/dummyTheme
- Asset Path: laravel-app/public/dummyTheme
- Extends Theme: Main Theme

 Create Theme? (yes/no) [yes]:

theme:remove [THEME-NAME]

将删除主题视图和资产文件夹。

php artisan theme:remove

theme:package [THEME-NAME]

将创建可分发主题包。

主题包是包含主题的视图和资产文件夹的存档。您可以以包的形式分发主题并将其安装到任何 Laravel 应用程序中。主题包将存储在 storage/themes 路径中。

theme:install

将从主题包中安装主题。将为主题创建视图和资产文件夹。主题信息将从存档内的 themes.json 文件中提取。

php artisan theme:install

 Select a theme to install::
  [0] theme-admin
  [1] theme-client
 > 0

Theme views installed to path [laravel-app/resources/themes/admin]
Theme assets installed to path [laravel-app/public/admin]

theme:refresh-cache

php artisan theme:refresh-cache

重建主题缓存。主题缓存将所有主题设置存储在单个文件中，以减少文件系统查询。可以在 config\themes.php 中禁用主题缓存。