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 "igaster/laravel-theme"

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

igaster\laravelTheme\themeServiceProvider::class,

还编辑 Facades 数组并添加

'Theme' => igaster\laravelTheme\Facades\Theme::class,

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

php artisan vendor:publish --provider="igaster\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或直接在控制器中定义主题。

构建您的视图

每当您需要本地文件的URL（如图片、CSS、JS等）时，您可以使用以下方法获取其路径

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' => \igaster\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

您可以在每个主题配置中设置供应商列表，这些供应商将从主题根目录而不是从'供应商'目录加载

'theme-name' => [

    /*
    |--------------------------------------------------------------------------
    | An array of vendors to load from the root of the theme rather than vendor/ 
    | e.g. view('backend::menu.main') would normally look for following path
    | \path\to\theme\views\vendor\backend\menu\main.blade.php
    | if the below array contained the vendor 'backend' view('backend::menu.main')
    | will instead look in \path\to\theme\views\backend\menu\main.blade.php
    | non-listed vendors will still look in \vendor\...
    |--------------------------------------------------------------------------
    */
    'vendor-as-root'    => ['name', 'of', 'vendors'],    

    // ....
]
```php

Now you can:

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

自定义错误页面

当然！在您的主题文件夹中创建一个名为 'errors' 的文件夹，并将 404.blade.php 等。原始错误页面将被每个主题覆盖！

资产管理（可选）

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

要安装 Orchestra\Asset，必须在您的composer.json中添加它（参见官方文档）

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

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

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

在aliases数组中添加资产外观

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

现在您可以利用 Orchestra\Asset 包的所有功能。然而，当您使用主题 + 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手动清除编译后的视图。在开发主题时请记住这一点...

ibrand / laravel-theme

维护者

详细信息