README

概述

小部件是一些功能模块，例如显示最新评论或Flickr照片。它们通常显示在您网站的侧边栏中。

要求

SilverStripe 4.0

注意：此版本与SilverStripe 4兼容。对于SilverStripe 3，请参阅1.x发布分支。

安装

通过composer安装模块

$ composer require silverstripe/widgets

小部件本质上是与其他模型（主要是页面类型）的数据库关系。默认情况下，它们不会添加到您自己的任何模型中。最容易和最常见的方法是在您的Page类下创建一个名为“SideBar”的单个小部件集合。这由一个扩展处理，您可以通过您的config.yml启用它

Page:
  extensions:
    - SilverStripe\Widgets\Extensions\WidgetPageExtension

运行dev/build，并调整您的模板以包含生成的侧边栏视图。占位符为$SideBarView，它遍历分配给当前页面的所有小部件。

或者，您可以将一个或多个小部件集合添加到您自己的页面类型中。以下是一个将小部件添加到MyPage类型并命名为MyWidgetArea的示例。请确保为您的模块添加正确的命名空间。

安装小部件

遵循下面的“打包”规则，小部件可以轻松安装。此示例使用默认已启用小部件的博客模块。

安装博客模块。
下载小部件并将其解压到SilverStripe网站的主文件夹中，例如到/widget_<widget-name>/。文件夹将包含一些文件，通常不需要编辑或阅读。
运行http://my-website.com/dev/build
登录到CMS并转到“博客”页面。选择“小部件”选项卡并点击新小部件以激活它。
您的博客现在将显示小部件

文档

请参阅docs/en文件夹。

版本控制

此库遵循Semver。根据Semver，您将能够升级到此库的任何次要或补丁版本，而无需对公共API进行任何破坏性更改。Semver还要求我们明确定义此库的公共API。

报告问题

请创建一个问题，报告您发现的任何错误或缺少的功能。

安装小部件模块，见上文。
向您的页面添加一个WidgetArea字段。
在CMS中添加一个新标签页，其中包含用于管理小部件的WidgetAreaEditor字段。例如：

mysite/code/Page.php

<?php

use SilverStripe\CMS\Model\SiteTree;
use SilverStripe\Widgets\Forms\WidgetAreaEditor;
use SilverStripe\Widgets\Model\WidgetArea;

class Page extends SiteTree
{
    // ...
    private static $has_one = array(
        'MyWidgetArea' => WidgetArea::class
    );

    public function getCMSFields()
    {
        $fields = parent::getCMSFields();
        $fields->addFieldToTab('Root.Widgets', new WidgetAreaEditor('MyWidgetArea'));
        return $fields;
    }
}

在这种情况下，您需要修改您的模板以包含占位符$MyWidgetArea。

编写您自己的小部件

创建小部件至少需要三个文件 - 包含类的PHP文件、同名模板文件以及名为_config.php的配置文件（如果您不需要任何配置选项来使小部件工作，则可以将其留空）。每个小部件应放在自己的文件夹中，例如widgets_widgetName/

安装或创建新的小部件后，请确保在尝试使用之前，在URL末尾运行db/build?flush=1。

类应该扩展Widget类，并且必须指定三个配置变量

title：将在渲染的小部件中显示的标题（例如照片）。这可以通过CMS管理员进行自定义。
cmsTitle：一个更详细的标题，将在CMS编辑器中显示（例如Flickr照片）
description：将在CMS编辑器中显示的简短描述（例如此小部件显示Flickr中的照片）。类还可以指定在模板中使用的函数，就像页面类型一样。

如果小部件有可配置的选项，则可以指定一些数据库字段来存储这些选项，通过静态$db数组，并且还可以指定一个返回FieldList的getCMSFields函数，这与页面类型类似。

以下是一个示例小部件

FlickrWidget.php

<?php

namespace Yourname\MyWidget;

use FlickrService;
use SilverStripe\Widgets\Model\Widget;
use SilverStripe\Forms\FieldList;
use SilverStripe\Forms\TextField;
use SilverStripe\Forms\NumericField;
use SilverStripe\ORM\ArrayList;
use SilverStripe\View\ArrayData;
use SilverStripe\View\Requirements;

class FlickrWidget extends Widget
{
    private static $db = array(
        'User' => 'Varchar',
        'Photoset' => 'Varchar',
        'Tags' => 'Varchar',
        'NumberToShow' => 'Int'
    );

    private static $defaults = array(
        'NumberToShow' => 8
    );

    private static $title = 'Photos';
    private static $cmsTitle = 'Flickr Photos';
    private static $description = 'Shows flickr photos.';

    public function Photos()
    {
        // You'll need to install these yourself
        Requirements::javascript(THIRDPARTY_DIR . '/prototype/prototype.js');
        Requirements::javascript(THIRDPARTY_DIR . '/scriptaculous/effects.js');
        Requirements::javascript('mashups/javascript/lightbox.js');
        Requirements::css('mashups/css/lightbox.css');

        $flickr = new FlickrService();
        if ($this->Photoset == '') {
            $photos = $flickr->getPhotos($this->Tags, $this->User, $this->NumberToShow, 1);
        } else {
            $photos = $flickr->getPhotoSet($this->Photoset, $this->User, $this->NumberToShow, 1);
        }

        $output = new ArrayList();
        foreach ($photos->PhotoItems as $photo) {
            $output->push(
                new ArrayData(
                    array(
                        'Title' => $photo->title,
                        'Link'  => 'http://farm1.static.flickr.com/' . $photo->image_path .'.jpg',
                        'Image' => 'http://farm1.static.flickr.com/' .$photo->image_path. '_s.jpg'
                    )
                )
            );
        }
        return $output;
    }

    public function getCMSFields()
    {
        return new FieldList(
            new TextField('User', 'User'),
            new TextField('PhotoSet', 'Photo Set'),
            new TextField('Tags', 'Tags'),
            new NumericField('NumberToShow', 'Number to Show')
        );
    }
}

FlickrWidget.ss

<% control Photos %>
    <a href="$Link" rel="lightbox" title="$Title"><img src="$Image" alt="$Title" /></a>
<% end_control %>

发布小部件

遵循为发布SilverStripe模块定义的标准程序。

以下是一个您可以使用的composer模板。

您需要完成/更改以下内容

名称（例如：yourorganisation/silverstripe-widget-carousel）
描述
关键词
许可证
作者
安装程序名称（例如：widgets_carousel）

{
    "name": "",
    "description": "",
    "type": "silverstripe-module",
    "keywords" : ["widget"],
    "require": {
        "silverstripe/framework": "^4.0",
        "silverstripe/cms": "^4.0"
    },
    "license": "BSD-2-Clause",
    "authors": [
        {
            "name": "",
            "email": ""
        }
    ],
    "extra" : {
        "installer-name": "widgets_"
    },
    "autoload": {
        "psr-4": {
            "Yourname\\MyWidget\\": "src/"
        }
    }
}

扩展和自定义

单独渲染$Widget

要在页面中调用单个小部件 - 而不是在CMS中添加/删除小部件的Widget区域，您可以在Page控制器中定义合并变量并在Page模板中包含它。

此示例创建了一个使用SilverStripe博客源的网络源小部件。

public function SilverStripeFeed()
{
    $widget = new RSSWidget();
    $widget->RssUrl = 'http://feeds.feedburner.com/silverstripe-blog';
    return $widget->renderWith('WidgetHolder');
}

要渲染小部件，只需在模板中包含$SilverStripeFeed

$SilverStripeFeed

如SilverStripeFeed()的定义所示，小部件将通过WidgetHolder模板进行渲染。这是在widgets/templates/WidgetHolder.ss中预定义的，它只包含

<div class="WidgetHolder">
    <h3>$Title</h3>
    $Content
</div>

您也可以通过将WidgetHolder和Widget模板添加到themes/myThemeName/templates/Includes/来覆盖WidgetHolder.ss和Widget.ss模板。

更改小部件的标题

要更改小部件的标题，您需要重写getTitle()方法。默认情况下，这仅返回$title变量。例如，要将小部件的标题设置为'Hello World!'，您可以

widgets_yourWidget/src/YourWidgetWidget.php

public function getTitle()
{
    return 'Hello World!';
}

但是，您也可以通过设置$title变量来做到这一点。

重写getTitle()的更常见原因是允许在CMS中设置标题。假设您的小部件中有一个名为WidgetTitle的文本字段，您希望将其用作标题。如果没有设置，则将使用默认标题。这与博客模块中的RSS小部件类似。

public function getTitle()
{
    return $this->WidgetTitle ? $this->WidgetTitle : self::$title;
}

这返回在CMS中输入的值（如果设置了）或存在于$title变量中的值（如果没有设置）。

小部件内的表单

要在小部件内实现表单，您需要为您的表单实现一个自定义控制器。确保您的控制器遵循常规命名约定，它将被自动拾取以在您的Page.ss模板中的WidgetArea渲染中。

mysite/code/MyWidget.php

<?php

namespace Yourname\MyWidget;

use SilverStripe\Widgets\Model\Widget;

class MyWidget extends Widget
{
    private static $db = array(
        'TestValue' => 'Text'
    );
}

<?php

namespace Yourname\MyWidget;

use SilverStripe\Widgets\Controllers\WidgetController;
use SilverStripe\Forms\Form;
use SilverStripe\Forms\FormAction;
use SilverStripe\Forms\FieldList;
use SilverStripe\Forms\TextField;

class MyWidgetController extends WidgetController
{
    public function MyFormName()
    {
        return new Form(
            $this,
            'MyFormName',
            new FieldList(
                new TextField('TestValue')
            ),
            new FieldList(
                new FormAction('doAction')
            )
        );
    }

    public function doAction($data, $form)
    {
        // $this->widget points to the widget
    }
}

要输出此表单，请修改您的表单模板。

mysite/templates/Yourname/MyWidget/MyWidget.ss

$Content
$MyFormName

注意：必要的控制器操作仅在PageController的子类中存在。要在其他控制器子类中使用小部件表单，请查看ContentController->handleWidget()和ContentController::$url_handlers。

但是我目前在我的博客上有小部件怎么办呢？？

注意：这适用于博客模块的旧版本。本模块的最新版本不包含BlogHolder.php。

如果您当前已安装博客，小部件字段将出现在这些页面上（因为博客扩展了Page类）。一种解决方法是取消注释BlogHolder.php中的第30行，并通过运行http://www.mysite.com/db/build来删除数据库条目。

blog/code/BlogHolder.php

<?php
class BlogHolder extends Page
{
    // ........
    static $has_one = array(
        // "Sidebar" => "WidgetArea", COMMENT OUT
        'Newsletter' => 'NewsletterType'
    );
    // .......
    public function getCMSFields()
    {
        $fields = parent::getCMSFields();
        $fields->removeFieldFromTab("Root.Content","Content");
        // $fields->addFieldToTab("Root.Widgets", new WidgetAreaEditor("Sidebar")); COMMENT OUT
    }
    // ...
}

然后您可以使用在Page.php中定义的Widget区域

翻译

自然语言字符串的翻译通过第三方翻译界面transifex.com管理。新添加的字符串将定期上传到该网站进行翻译，任何新的翻译都将合并回项目源代码。

请使用https://www.transifex.com/projects/p/silverstripe-widgets/来贡献翻译，而不是发送包含YAML文件的拉取请求。

有关更多详细信息，请参阅doc.silverstripe.org上的“i18n”主题。

grandcreation / silverstripe-widgets

维护者

详细信息