README

附件包提供了处理模型之间关系支持的功能。

安装

composer require charcoal/attachment

概述

该包还提供了一组基本的附件：文档、嵌入、图片、画廊、链接视频等。

对象

附件包中的对象扩展了来自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附件。
• 附件
  • 最通用的附件，可以是任何东西。
• Container
  • 基本的“分组”附件。
• 嵌入
  • 嵌入内容，通常是视频嵌入代码。
  • 强制file属性为image，并将description强制为html。
• 文件
  • 可上传的文档。
• 链接
  • 一个URL（资源的链接）。
• 图片
  • 可上传的图片
  • 强制file属性为image。
• 画廊
  • 一个Container（分组）附件，用于多个图片的画廊。
  • 仅限于image附件。
• 文本
  • 文本（HTML）内容。
• 视频

小部件

该包提供自己的命名空间为Charcoal\Admin的admin小部件。

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

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

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

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

配置

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

"metadata": {
    "paths": [
        "...",
        "vendor/charcoal/attachment/metadata/"
    ]
},
"view": {
    "paths": [
        "...",
        "vendor/charcoal/attachment/templates/"
    ]
},
"translations": {
    "paths": [
        "...",
        "vendor/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" ]
        }
    }
}

用法

您需要使您的对象(们)“Attachment Aware”，以便它知道它可以有附件。为此，请使用/实现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/link
• charcoal/attachment/object/text
• charcoal/attachment/object/video

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

在删除对象时，为了删除不必要的关联，您需要将此添加到您的对象中

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

附件创建

关于附件，您需要知道的是，它全部在一个表中。如果它们不是 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"
    }
}

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

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

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

注意

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

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

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

资源

• 贡献
• 报告问题 和 发送拉取请求 在 Charcoal的主要存储库