README

一个轻量级、低调、可重用的组件库和框架，用于简化 Magento2 安装中各个部分之间的互操作性。

组件

在本扩展中，组件是指任何将被渲染到页面上的 HTML 标记部分，它将使用各种 PHP 变量进行渲染，并且在将来可能被重用。如果您认为您的标记有可能被重用，请将其作为组件。

结构

所有组件都继承自 Base 组件，并按各种类别分组

Model/Basic         Basic components, such as buttons or links
Model/Groups        Components that use other components in their rendering, such as FormGroups
Model/Input         Components related to user input

组件模板位于扩展的 view/frontend/Components 目录中。当您创建新组件时，请将您的组件放在对应的目录中。

创建新组件

首先：我们希望这个组件经过测试。如果没有测试，它就不工作。所以确定组件属于目录中的哪个位置（Components/Model），如果您想的话，可以创建一个新的组件），并创建 MyComponent.test.php 文件。

测试

我们放弃了庞大的测试框架来测试这些组件，因为目标是轻量级并确保基本的 PHP 级功能测试。为了确保更稳健的 UI 测试和查找回归，组件库旨在显示在风格指南或模式库中。

当您创建自己的测试时，测试您相当确信将始终由该组件负责的最基本的单元。

例如，如果您制作了一个链接组件，您可能不确定链接会有 class、title 或 id 属性。但因为它是一个链接，您可以相当肯定它会有一个 href 属性，并包含一些内容文本。所以让我们测试这些。

<?php
// Basic/Link.test.php

require_once(dirname(__FILE__) . '/../Base.php');
require_once('Link.php');

$a = new Rsc\Components\Model\Basic\Link();
$a->setVariables(['href' => 'http://www.google.com', 'text' => 'test']);

$rendered = $a->render();

// Basic assertions are good enough for this use case
assert( (bool) stristr($rendered, '<a') );
assert( (bool) stristr($rendered, 'href="') );
assert( (bool) stristr($rendered, 'http://www.google.com') );
assert( (bool) stristr($rendered, 'test') );

这个基本测试将确保我们输出的确实是一个链接，它包含一个 href 属性，链接本身出现在渲染输出中，链接文本也是如此。

现在您可以通过进入目录并运行 php Link.test.php 或在组件基本目录中运行 php Tests.php 来测试您的组件，这将测试所有组件。

组件类

创建组件就像创建类和类渲染的模板一样简单。以我们的链接示例继续

<?php
// Components/Model/Basic/Link.php

namespace Rsc\Components\Model\Basic;
use Rsc\Components\Base;

class Link extends Base
{
    // Template file, relative to Components/view/frontend/Components
    protected $file = 'Basic/Link.phtml';

    // Variables required to render this component without an exception
    protected $requiredVariables = ['url', 'text'];
}

这是一个简单的组件，在渲染之前不需要处理变量。如果您想了解如何添加预渲染自定义，请参阅 Components/Model/Base.php 和一些内置组件。

模板

模板是标准的 .phtml 文件，根据通过 setVariable($key, $value) 或 setVariables($variables = []) 类传递给组件的一组变量来渲染标记。脚本提取变量，例如，['url' => 'http://www.google.com'] 变为 $url = 'http://www.google.com';。

<!-- Components/view/frontend/Components/Basic/Link.phtml -->
<a href="<?php echo $url; ?>"><?php echo $text; ?></a>

模板辅助方法

基本类为您提供大量辅助工具来缩短组件并尽可能将显示逻辑从组件中提取出来。

/**
 * Prints a variable with the value as <attributeName>="<attributeValue">
 * @param string $variable
 */
protected function attr($variable)

/**
 * Prints a variable with the value as <attributeName>="<attributeValue">
 * if the attribute exists in the Component's variables. If the variable
 * does not exist, it does not render anything.
 * @param string $variable
 */
protected function attrIf($variable)

/**
 * Prints a template variable as an attribute in the same as $this->attributeId(),
 * but instead of hiding the attribute if the variable is not set, this will
 * print a default value.
 * @param  string $variable
 * @param  mixed $default
 */
protected function attrDefault($variable, $default)

/**
 * Prints a template variable as an attribute with a portion of content pre-
 * pended to the value. For example, if you want all of your input boxes to
 * have a base class name of "textInput", you would use this function to
 * let devs set other custom classes to it, without having to constantly
 * add it.
 *
 * <?php $this->attrPlus('class', 'textInput'); ?>
 *
 * @param  string $variable Variable to turn into an attribute
 * @param  string $base     The base attribute value. Spaces are automatically prepended
 */
protected function attrPlus($variable, $base)

/**
 * Prints $html if $condition is true. Useful shorthand for simple markup
 * with conditions to prevent tons of indentations.
 */
protected function echoIf($condition, $html)

有关这些用途的示例，请参阅默认组件中提供的模板。

使用组件

组件旨在在 Magento2 范围之外 使用，并且不应自身需要任何除了将它们转换为渲染的 HTML 的原始数据之外的东西。

因此，有三种调用组件的方法

间接地，从模板和块内部

此插件将 ComponentManager 的主实例引用附加到每个 Magento2 块，因此如果您处于块上下文（即 Magento2 中您可能使用组件的大部分地方），您可以通过 $this->ComponentManager->... 简单地调用此类。

间接地，通过 Magento2 依赖注入

如果您希望在与 Magento2 核心模板 .phtml 文件之前配置和渲染您的组件，并将其推迟到块或模板上下文之外的地方，您可以通过 Magento2 依赖注入 注入组件管理器来始终访问组件管理器。

您需要为您的模块创建以下 di.xml

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <type name="Namespace\MyModule\MyClass">
        <arguments>
            <!-- Other arguments for your class -->
            <argument name="config" xsi:type="object">Rsc\Components\Model\ComponentManager</argument>
        </arguments>
    </type>
</config>

直接（不推荐）

如果您出于某种原因需要在 Magento2 上下文之外使用组件，您可以通过仅创建 Components/Model/ComponentManager() 类的新实例来轻松调用这些组件。此类是创建和处理整个组件库的工厂。

然而，由于我们可以缓存某些组件，因此这种方法在 Magento2 上下文中并不推荐。

建议使用场景：在一个展示如何使用和修改您的 Magento2 组件的样式指南中。