README

附件支持处理模型之间的关系。此外，还提供了一套可用的基本附件：文档、嵌入、图片、画廊、链接视频等。

如何安装

安装_charcoal-attachment 的首选（也是唯一支持的）方式是使用 composer

★ composer require locomotivemtl/charcoal-attachment

依赖项

对象

charcoal-attachments 模块中的对象扩展了来自 charcoal-object 的 Content，它是来自 charcoal-core 的 AbstractModel。

除了 Content 提供的默认元数据外，以下属性对所有 Attachment 对象默认有效

标准属性（用于所有附件对象）

特定属性，可以根据上下文以不同的方式使用

所有附件都假定有 title、subtitle、description 和 keywords。一些附件还有

阅读 charcoal-object 文档以了解 Content 对象（和 RevisionableInterface）提供的其他默认属性。

阅读 charcoal-core 文档以了解 AbstractModel（和 DescribableInterface 及 StorableInterface）提供的其他默认属性。

附件对象的类型

手风琴
- 一种 Container（分组）附件，用于手风琴类型的显示。
- 默认支持 text、image、gallery 和 embed 附件。
附件
- 最通用的附件，可以是任何东西。
容器
- 基本 "分组" 附件。
嵌入
- 嵌入内容，通常是视频嵌入代码。
- 强制将 file 属性设置为 image，将 description 设置为 html。
文件
- 可上传的文档。
链接
- 一个 URL（资源的链接）。
图片
- 可上传的图片
- 强制将 file 属性设置为 image。
画廊
- 一种 Container（分组）附件，用于多个图片的画廊。
- 仅限于 image 附件。
文本
- 文本（HTML）内容。
视频

小部件

该模块提供自己的命名空间为 Charcoal\Admin 的管理小部件。

但是如何

设置相当简单，但你需要记住一些事情才能使其工作。

配置

将视图路径和元数据路径添加到配置文件中。

"metadata": {
    "paths": [
        "...",
        "vendor/locomotivemtl/charcoal-attachment/metadata/"
    ]
},
"view": {
    "paths": [
        "...",
        "vendor/locomotivemtl/charcoal-attachment/templates/"
    ]
},
"translations": {
    "paths": [
        "...",
        "vendor/locomotivemtl/charcoal-attachment/translations/"
    ]
}

然后，我们需要在 admin.json 配置文件中添加小部件的必要路由。

"routes": {
    "actions": {
        "join": {
            "ident": "charcoal/admin/action/join",
            "methods": [ "POST" ]
        },
        "add-join": {
            "ident": "charcoal/admin/action/add-join",
            "methods": [ "POST" ]
        },
        "remove-join": {
            "ident": "charcoal/admin/action/remove-join",
            "methods": [ "POST" ]
        }
    }
}

用法

您需要使您的对象（s）"附件感知"，以便它知道它可以有附件。为此，请使用/实现 attachmentAware

use Charcoal\Attachment\Traits\AttachmentAwareTrait;
use Charcoal\Attachment\Interfaces\AttachmentAwareInterface;

然后，只需在编辑仪表板或表单中添加小部件即可，如下所示

"attachment": {
    "title": "Documents",
    "type": "charcoal/admin/widget/attachment",
    "group": "main",
    "attachable_objects": {
        "charcoal/attachment/object/file": {
            "label": "Document / File"
        }
    }
}

当前模块提供的可用可附件对象

charcoal/attachment/object/image
charcoal/attachment/object/gallery
charcoal/attachment/object/file
炭黑/附件/对象/链接
炭黑/附件/对象/文本
炭黑/附件/对象/视频

要创建一个新的附件，您需要扩展基本附件对象 charcoal/attachment/object/attachment 并提供一个“快速”表单。

在删除对象时，要删除不必要的连接，您需要将此添加到您的对象中

public function preDelete()
{
    // AttachmentAwareTrait
    $this->removeJoins();
    return parent::preDelete();
}

文档

附件小部件可以在表单中使用多次。为了使其正常工作，您需要为每个实例化的小部件定义一个不同的组标识 group。

"attachment": {
    "type": "charcoal/admin/widget/attachment",
    "group": "main"
}

在这种情况下，我们将组设置为“main”。如果没有定义，则默认组将是“通用”。没有这些标识，小部件将无法知道哪些附件属于它。

然后，您可以通过调用对象的“attachments(group_ident)”方法来访问特定的“组”附件。在这种情况下，$object->attachments('main') 将返回与设置了“main”组的 widgets 关联的附件。

附件创建

关于附件，您需要知道的是，它都在一个单独的表中。如果它们不是 attachments，则无法将自定义对象与其它对象关联。

那么，您如何创建新的附件呢？这完全取决于您的需求。

添加或修改属性

如果您需要向现有的附件添加属性，您始终可以扩展它。假设您想更改附件提供的描述字段的编辑器选项。第一步是创建一个新的对象，该对象将扩展现有的对象。

/**
 * Extended text class.
 */
namespace My\Namespace;

use Charcoal\Attachment\Object\Text as AttachmentText;

class Text extends AttachmentText
{
}

现在我们已经扩展了，让我们通过创建一个 my/namespace/text.json 文件来添加到 JSON 中。

{
    "properties": {
        "description": {
            "editor_options": {
                "style_formats": [],
                "body_class": "s-wysiwyg",
                "content_css": "../../../../../styles/main.css"
            }
        }
    },
    "data": {
        "type": "my/namespace/text"
    }
}

在这种情况下，编辑器选项已更改，以删除基本样式格式，更改 body 类并添加适当的 CSS。重要的是要将数据类型设置为当前对象。这在实时编辑和删除功能中使用。

如果您添加了一些额外的属性，您可以使用修改脚本来将它们添加到表中。

vendor/bin/charcoal admin/object/table/alter --obj-type=my/namespace/text

注意事项

不要在 mustache 模板中直接使用“attachments”方法。这将返回所有附件，而不考虑组。

在后台小部件中为附件预览自定义模板在待办事项列表中。

其他操作，如快速查看，也位于待办事项列表中。

有关使用 charcoal-attachment 的完整项目示例，请参阅 charcoal-project-boilerplate。

开发

要安装开发环境

★ composer install --prefer-source

使用以下命令运行代码检查器和单元测试

★ composer test

API 文档

自动生成的 phpDocumentor API 文档可在 https://locomotivemtl.github.io/charcoal-attachment/docs/master/ 获得
自动生成的 apigen API 文档可在 https://locomotivemtl.github.io/charcoal-attachment/apigen/master/ 获得

开发依赖

phpunit/phpunit
squizlabs/php_codesniffer
satooshi/php-coveralls

持续集成

编码风格

Charcoal-Attachment 模块遵循 Charcoal 编码风格

PSR-1
PSR-2
PSR-4，因此自动加载由 Composer 提供。
phpDocumentor 注释。
有关代码样式的详细信息，请参阅 phpcs.xml 文件。

可以使用 composer phpcs 执行代码样式验证/强制执行。还有一个可用的自动修复程序，使用 composer phpcbf。

作者

Mathieu Ducharme mat@locomotive.ca
Chauncey McAskill chauncey@locomotive.ca
本杰明·罗奇 benjamin@locomotive.ca

许可证

炭黑遵循MIT许可证。有关详细信息，请参阅LICENSE。

locomotivemtl / charcoal-attachment

维护者

详细信息