README

https://img.shields.io/github/issues/artisancms/widgets.svg #Laravel的小部件

视图编辑器的强大替代品。异步小部件，可重载小部件，控制台生成器，缓存——一切你想得到的。

安装

1. 运行 composer require artisancms/widgets

2. 在 app.php 配置文件中注册一个服务提供者

<?php

'providers' => [
    ...
    ArtisanCMS\Widgets\ServiceProvider::class,
],
?>

1. 在这里也可以添加一些门面。如果您更喜欢自定义blade指令而不是门面，可以跳过此步骤。

<?php

'aliases' => [
    ...
    'Widget'       => ArtisanCMS\Widgets\Facade::class,
    'AsyncWidget'  => ArtisanCMS\Widgets\AsyncFacade::class,
],
?>

用法

让我们考虑我们想要创建一个最近新闻的列表，并在几个视图中重用它。

首先，我们可以使用包提供的artisan命令创建一个Widget类。

php artisan make:widget RecentNews

此命令生成两个文件

1. resources/views/widgets/recent_news.blade.php 是一个空视图。

如果您不需要视图，请添加"--plain"选项。

1. app/Widgets/RecentNews 是一个小部件类。

<?php

namespace App\Widgets;

use ArtisanCMS\Widgets\AbstractWidget;

class RecentNews extends AbstractWidget
{
    /**
     * The configuration array.
     *
     * @var array
     */
    protected $config = [];

    /**
     * Treat this method as a controller action.
     * Return view() or other content to display.
     */
    public function run()
    {
        //

        return view("widgets.recent_news", [
            'config' => $this->config,
        ]);
    }
}

注意：如果您需要，可以使用自己的占位符。发布配置文件以更改路径。

最后一步是调用小部件。您实际上有几种方法可以做到这一点。

@widget('recentNews')

或

{{ Widget::run('recentNews') }}

甚至

{{ Widget::recentNews() }}

它们之间没有真正的区别。选择权在您。

注意：对于Laravel 5.0.0 - 5.1.3，您必须使用{!! !!}标签而不是{{ }}

将变量传递给小部件

通过配置数组

让我们继续使用“最近新闻”的例子。

假设我们通常需要显示五条新闻，但在某些视图中我们需要显示十条。这可以很容易地实现如下

class RecentNews extends AbstractWidget {
    ...
    protected $config = [
        'count' => 5
    ];
    ...
}

...
@widget('recentNews') // shows 5
@widget('recentNews', ['count' => 10]) // shows 10

['count' => 10] 是一个配置数组，可以通过 $this->config 访问。

配置数组在所有小部件方法中都可用，因此您可以使用它来配置占位符和容器（见下文）

注意：在调用小部件时未指定的配置字段不会被覆盖

class RecentNews extends AbstractWidget {
    ...
    protected $config = [
        'count' => 5,
        'foo'   => 'bar'
    ];
    
    ...
}

@widget('recentNews', ['count' => 10]) // $this->config['foo'] is still 'bar'

注意 2：您可能想要（但可能不需要）创建自己的BaseWidget并从中继承。这是可以的。唯一的边缘情况是从父类和子类合并配置默认值。在这种情况下，请执行以下操作

1. 不要在子类中添加protected $config = [...]行。

2. 相反，添加默认值如下

    public function __construct(array $config = [])
    {
        $this->addConfigDefaults([
            'child_key' => 'bar'
        ]);

        parent::__construct($config);
    }

直接

您还可以选择直接向 run() 方法传递额外的参数。

@widget('recentNews', ['count' => 10], 'date', 'asc')
...
public function run($sortBy, $sortOrder) { }
...

run() 方法通过服务容器解析，因此也可以在这里使用方法注入。

命名空间

默认情况下，该包尝试在 App\Widgets 命名空间中查找您的组件。

您可以通过发布包配置（php artisan vendor:publish --provider="ArtisanCMS\Widgets\ServiceProvider"）并设置 default_namespace 属性来覆盖此设置。

尽管使用默认命名空间非常方便，但在某些情况下，您可能希望有更多的灵活性。例如，如果您有成百上千的组件，那么将这些组件分组在命名空间文件夹中是有意义的。

没问题，您有几种方法可以调用这些组件

1. 将 default_namespace（基本上是 App\Widgets）中的完整组件名称传递给 run 方法。

@widget('News\RecentNews', $config)

1. 使用点表示法。

@widget('news.recentNews', $config)

1. FQCN 也是一个选项。

@widget('\App\Http\Some\Namespace\Widget', $config)

异步组件

在某些情况下，使用AJAX加载组件内容可以非常有益。

幸运的是，这可以很容易地实现！您需要做的所有事情就是更改门面或blade指令 - Widget:: > AsyncWidget::，@widget > @asyncWidget

注意：组件参数将被加密并通过ajax调用发送。预期它们在之后被json_encoded和json_decoded。

注意：自版本 3.1 起，您不再需要 jquery 来进行 AJAX 调用。但是，如果您想这样做，可以在配置文件中将 use_jquery_for_ajax_calls 设置为 true。

默认情况下，直到 AJAX 调用完成，不会显示任何内容。

可以通过向小部件类中添加一个 placeholder() 方法来自定义此行为。

public function placeholder()
{
    return "Loading...";
}

旁注：如果您需要使用路由包加载异步小部件（例如，您在子目录中运行应用 http://site.com/app/），则需要将 ArtisanCMS\Widgets\ServiceProvider 复制到您的应用中，根据您的需求进行修改，并在 Laravel 中注册它，而不是原来的一个。

可重新加载的小部件

您甚至可以更进一步，每 N 秒自动重新加载小部件。

只需设置小部件类的 $reloadTimeout 属性即可。

class RecentNews extends AbstractWidget
{
    /**
     * The number of seconds before each reload.
     *
     * @var int|float
     */
    public $reloadTimeout = 10;
}

同步和异步小部件都可以成为可重新加载的。

您应该谨慎使用此功能，因为如果超时时间太短，它很容易用 AJAX 调用垃圾邮件您的应用。考虑使用 WebSockets，但它们设置起来要困难得多。

容器

异步和可重新加载的小部件都需要一些 DOM 交互，因此它们将所有小部件输出包裹在一个 HTML 容器中。该容器由 AbstractWidget::container() 方法定义，也可以进行自定义。

    /**
     * Async and reloadable widgets are wrapped in container.
     * You can customize it by overriding this method.
     *
     * @return array
     */
    public function container()
    {
        return [
            'element'       => 'div',
            'attributes'    => 'style="display:inline" class="artisancms-widget-container"',
        ];
    }

注意：不支持嵌套的异步或可重新加载的小部件。

缓存

还有一个简单内置的方法可以缓存整个小部件输出。只需在您的 小部件类中设置 $cacheTime 属性即可。

class RecentNews extends AbstractWidget
{
    /**
     * The number of minutes before cache expires.
     * False means no caching at all.
     *
     * @var int|float|bool
     */
    public $cacheTime = 60;
}

默认情况下未启用缓存。缓存键取决于小部件名称和每个小部件参数。如果需要调整，请重写 cacheKey 方法。

小部件组（额外）

在大多数情况下，Blade 是设置小部件位置和顺序的完美工具。然而，有时您可能会发现以下方法很有用

// add several widgets to the 'sidebar' group anywhere you want (even in controller)
Widget::group('sidebar')->position(5)->addWidget('widgetName1', $config1);
Widget::group('sidebar')->position(4)->addAsyncWidget('widgetName2', $config2);

// display them in a view in the correct order
@widgetGroup('sidebar')
//or 
{{ Widget::group('sidebar')->display() }}

position() 可以从链中省略。

Widget::group('sidebar')->addWidget('files');

等于

Widget::group('sidebar')->position(100)->addWidget('files');

您还可以为组中的小部件设置一个分隔符以显示它们之间。 Widget::group('sidebar')->setSeparator('<hr>');

检查小部件组的状态

Widget::group('sidebar')->isEmpty(); // bool

Widget::group('sidebar')->any(); // bool

Widget::group('sidebar')->count(); // int