silverstripe/widgets

小部件是显示最新评论或Flickr照片等功能的小片段。它们通常显示在您网站的侧边栏中。

维护者

详细信息

github.com/silverstripe/silverstripe-widgets

源代码

问题

安装数: 376,059

依赖项: 30

建议者: 8

安全性: 0

星标: 38

关注者: 19

分支: 56

开放问题: 13

类型:silverstripe-vendormodule

3.0.1 2023-08-29 22:23 UTC

Requires

Requires (Dev)

BSD-3-Clause 791e24722b4f2b11461a08aa4eba1e2e5268747b

  • Ingo Schommer <ingo.woop@silverstripe.com>

blogsilverstripewidgets

This package is auto-updated.

Last update: 2024-09-04 04:28:38 UTC

README

CI

概述

小部件是显示最新评论或Flickr照片等功能的小片段。它们通常显示在您网站的侧边栏中。

安装

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。

报告问题

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

  • 安装Widgets模块，见上文。
  • 将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模块定义的标准程序。

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

您需要完成/更改

  • 名称（例如：yourorganisation/silverstripe-widget-carousel）
  • 描述
  • 关键词
  • 许可证
  • 作者
{
    "name": "",
    "description": "",
    "type": "silverstripe-module",
    "keywords" : [
        "widget"
    ],
    "require": {
        "silverstripe/framework": "^5.0",
        "silverstripe/cms": "^5.0"
    },
    "license": "BSD-2-Clause",
    "authors": [
        {
            "name": "",
            "email": ""
        }
    ],
    "autoload": {
        "psr-4": {
            "Yourname\\MyWidget\\": "src/"
        }
    }
}

扩展和自定义

单独渲染$Widget

要在页面中调用单个小部件（无需在CMS中添加/删除小部件的区域），您可以在页面控制器中定义一个合并变量并将其包含在页面模板中。

此示例创建了一个使用Silverstripe博客源的小部件RSSWidget。

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>

您也可以通过向themes/myThemeName/templates/Includes/添加WidgetHolder和Widget模板来覆盖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。

如果您目前安装了博客，小部件字段将在这些页面上重复（因为博客扩展了页面类）。修复此问题的一种方法是取消注释 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 中定义的小部件区域。

翻译

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

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

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