README

这是一个用于 Laravel 5 框架的包，它增加了对主题管理的基本支持。它允许您将视图和资产文件分别放在不同的文件夹中，并支持主题扩展！很棒 :)

功能

主题文件夹中视图和资产的分离
主题继承：扩展任何主题并创建主题层次结构（WordPress风格！）
集成了 Orchestra/Asset 以提供资产依赖管理
您的应用程序和视图保持与主题无关。通过（几乎）无需修改即可包含新主题

对于 Laravel 5.0 和 5.1，请使用 v1.0.x 分支

工作原理

非常简单，您在 'resources/views' 中为每个主题创建一个文件夹，并将所有视图分开。对于资产也是如此：在您的 'public' 目录中为每个主题创建一个文件夹。设置您的活动主题，然后您就完成了。您的应用程序的其他部分保持与主题无关，这意味着当您 View::make('index') 时，您将访问所选主题文件夹中的 index.blade.php。同样适用于您的资产。

安装

使用以下命令安装

composer require "mauro-moreno/laravel-theme"

在 app/config/app.php 中的 Providers 数组中添加服务提供者

MauroMoreno\LaravelTheme\ThemeServiceProvider::class,

还编辑 Facades 数组并添加

'Theme' => MauroMoreno\LaravelTheme\Facades\Theme::class,

几乎完成。您可以选择使用以下命令将配置文件发布到应用程序中

php artisan vendor:publish --provider="MauroMoreno\LaravelTheme\ThemeServiceProvider"

就这样。现在您可以开始为应用程序添加主题了！

定义主题

注意：定义主题完全是可选的。如果您对默认设置满意，则无需修改配置文件！如果您想有更多的控制权，则可以在 config/themes.php 中的 themes 数组中定义您的主题。每个主题的格式都非常简单

// Select a name for your theme
'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.
    | Retrieve these values with Theme::config('key'). e.g.:
    |--------------------------------------------------------------------------
    */
    'key'           => 'value', 
],

所有设置都是可选的，可以省略。请检查配置文件中的示例...如果您对默认设置满意，则甚至无需触摸配置文件。如果没有注册主题，则将使用默认值！

扩展主题

您可以将一个主题设置为扩展另一个主题。当您请求一个在您的活动主题中不存在的视图/资产时，它将从这个父主题中解析出来。您可以通过简单地覆盖不同的视图/主题来轻松创建主题的变体。

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

与主题一起工作

默认主题可以在 theme.php 配置文件中进行配置。与主题一起工作非常简单。使用

Theme::set('theme-name');        // switch to 'theme-name'
Theme::get();                    // retrieve current theme's name
Theme::current();                // retrieve current theme's object
Theme::config('key');            // read current theme's configuration value for 'key'
Theme::configSet('key','value'); // assign a key-value pair to current theme's configuration

您可以根据需要创建自己的实现来通过 ServiceProvider、Middleware 或在控制器中定义主题来设置主题。

构建视图

无论何时你需要本地文件（图像、CSS、JS等）的URL，你都可以使用以下方式检索其路径：

Theme::url('path-to-file')

路径相对于主题文件夹（NOT相对于公共文件夹！）。例如，如果你将一个图像放在public/theme-name/img/logo.png，你的Blade代码将是：

<img src="{{Theme::url('img/logo.png')}}">

当你引用本地文件时，它将在当前主题层次结构中进行查找，并返回正确的路径。如果文件在当前主题或其父主题中找不到，你可以在配置文件中定义将要执行的操作：THROW_EXCEPTION | LOG_ERROR（默认警告）| ASSUME_EXISTS假设文件存在并返回路径 | IGNORE完全忽略。

一些有用的辅助工具

Theme::js('file-name')
Theme::css('file-name')
Theme::img('src', 'alt', 'class-name', ['attribute' => 'value'])

'SetTheme'中间件（Laravel 5.2+）

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

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

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

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

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

要查看更高级的示例，请检查演示应用程序：在会话中设置主题

参数化文件名

你可以在任何路径字符串中包含当前主题的任何配置键，使用大括号。例如：

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

如果主题配置中定义了"version"键，它将被评估，然后将在主题层次结构中查找文件名。（例如：许多商业主题为不同的颜色方案提供了多个版本的main.css，或者你可以使用语言相关的资源）

处理供应商路径（例如，用于包开发）

当你对视图进行命名空间时，Laravel将查找视图文件到活动主题的vendor文件夹中

view('VENDOR_NAME::viewName'); //  \theme_Path\vendor\VENDOR_NAME\viewName.blade.php

你可以为每个主题重新定义每个命名空间的路径。在主题配置中，你可以定义namespace-overrides关联数组

'theme-name' => [

    'namespace-overrides' => [
        'ns-a' => ''           // view('ns-a::viewName') = /themePath/viewName.blade.php
        'ns-b' => 'modules'    // view('ns-b::viewName') = /themePath/modules/viewName.blade.php
        //ns-c not in array so // view('ns-c::viewName') = /themePath/vendor/ns-c/viewName.blade.php
    ]

    // .... theme configuration
]

资产管理（可选）

此包提供了与Orchestra/Asset组件的集成。所有功能都在官方文档中有解释。如果你不需要额外的功能，可以跳过本节。Orchestra/Asset不会与该包一起安装 - 你必须手动安装它。

要安装Orchestra\Asset，你必须将其添加到你的composer.json中（请参阅官方文档）

"orchestra/asset": "~3.0",
"orchestra/support": "~3.0",

然后运行composer update。然后在你的Provider数组中添加服务提供者（在app/config/app.php）

Orchestra\Asset\AssetServiceProvider::class,
Collective\Html\HtmlServiceProvider::class,

在aliases数组中添加Asset外观

'Asset' => Orchestra\Support\Facades\Asset::class,

现在你可以利用Orchestra\Asset包的所有功能。然而，当使用Themes + Orchestra/Asset时，语法可能相当繁琐，因此添加了一些Blade特定的糖来简化你的工作。以下是如何构建你的视图：

在任何blade文件中，你可以引入脚本或CSS

@css('filename')
@js('filename')
@jsIn('container-name', 'filename')

请注意，你只是在定义你的css/js文件，而不是实际上将它们输出到HTML中。通常你只需要在你的页面头部/页脚中写一次你的css/js声明。所以打开你的主布局文件，并将

{!! Asset::styles() !!}
{!! Asset::scripts() !!}
{!! Asset::container('container-name')->scripts() !!}

放置在你想写入声明的地方。

资产依赖关系

这是Orchestra/Asset的一个特性，在官方文档中有很好的解释。长话短说

@css ('filename', 'alias', 'depends-on')
@js  ('filename', 'alias', 'depends-on')

你的资产依赖关系将被自动解决。你的资产将以正确的顺序导出。这种方法的最大好处是，你不必将所有的声明都移动到主布局文件中。每个子视图可以定义它的需求，它们将按正确的顺序自动解决，无需重复。太棒了！一个简短的例子

@js  ('jquery.js',    'jquery')
@js  ('bootstrap.js', 'bootsrap', jquery)

常见问题解答

这个包与AWS兼容吗？

是的，但有一个例外：如果您正在构建主题层次结构，则不会在父主题中查找资源。在远程仓库中执行文件搜索不是最佳实践。应该在未来的版本中解决这个问题... 然而，Blade模板的自动发现功能正常，因为它们是本地文件。

关于外部资源（例如CDN）怎么办？

直接链接到您的外部资源。以http(s)开头的每个URL默认情况下都不会被处理。

我能否将我的主题放在Laravel视图文件夹之外的其他路径？

是的。在themes.php配置文件中将themes_path选项设置为任何路径。然而，当请求视图且无法在任何其他文件夹中找到时，将使用默认的Laravel视图路径作为后备。

如何更改公共路径？

重新绑定Laravel的'path.public'。 (更多信息)

我正在编辑一个视图，但看不到变化

Laravel会编译您的视图，每次您进行编辑时。只有当您对视图进行任何编辑时，已编译的视图才会重新编译。您可以使用artisan view:clear手动清除已编译的视图。在开发主题时请记住这一点...

mauro-moreno / laravel-theme

维护者

详细信息