Charcoal Attachments Module


Attachments add support for working with relationships between models. Also provided are a usable set of basic attachments: Document, Embed, Image, Gallery, Link Video, amongst others.

How to install

The preferred (and only supported) way of installing _charcoal-attachment is with composer:

★ composer require locomotivemtl/charcoal-attachment



Objects in the charcoal-attachments module extends Content, from charcoal-object, which is an AbstractModel, from charcoal-core.

In addition from the default metadata provided by Content, the following properties are default for all Attachment objects:

Standard properties (used by all attachments objects):

Property Type Description
id id A uniqid, for referencing.
title string (l10n)
show_title boolean
categorie `object (multiple) By default, categories are charcoal/attachment/object/category/generic objects.
subtitle string (l10n)
description text (l10n)
keywords string (l10n, multiple) Typically used for searching purpose.
type string

Specialized properties which can be used differently, depending on context:

Property Type Description
link string (l10n) URL.
file file (l10n) Uploadable file, or "document".
file_size string The uploaded file size, in bytes (auto-generated).
file_type string The uploaded file mimetype (auto-generated).
thumbnail image (l10n)
embed text (l10n) Typically a video.

All attachments are assumed to have a title, subtitle, description and keywords. Some attachments also

Read the charcoal-object documentation for the other default properties provided by the Content object (and RevisionableInterface).

Read the charcoal-core documention for the other default properties provided by AbstractModel (and DescribableInterface and StorableInterface).

Type of Attachment objects

  • Accordion
    • A Container (grouping) attachment, used for accordion type of display.
    • By default, support text, image, gallery and embed attachments.
  • Attachment
    • The most generic attachment, can be anything.
  • Container
    • Base "grouping" attachment.
  • Embed
    • Embedded content, typically video embed code.
    • Force the file property to be an image, and description to be html.
  • File
    • An uploadable Document.
  • Link
    • A URL (link to a resource).
  • Image
    • An uploadable image
    • Force the file property to be an image.
  • Gallery
    • A Container (grouping) attachment, used for a gallery of multiple images.
    • Is limited to image attachments.
  • Text
    • Text (HTML) content.
  • Video


The module provides his own admin widgets namespaced as Charcoal\Admin.


The setup is fairly easy, but you need to remember a few things in order for it to work.


Add the views path and metadata path to the config file.

"metadata": {
    "paths": [
"view": {
    "paths": [
"translations": {
    "paths": [

Then, we need to add the necessary routes for the widgets in admin.json config file.

"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" ]


You need to make your object(s) "Attachment Aware", so that it knows it can have attachments. To do that, use/implement attachmentAware:

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

Then, just add in the widget in the edit dashboard or the form like this:

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

Available attachable objects as provided by the current modile are:

  • charcoal/attachment/object/image
  • charcoal/attachment/object/gallery
  • charcoal/attachment/object/file
  • charcoal/attachment/object/link
  • charcoal/attachment/object/text
  • charcoal/attachment/object/video

To create a new attachment, you need to extend the base Attachment object charcoal/attachment/object/attachment and provide a "quick" form.

To remove unnecessary join when deleting an object, you need to add this to your object:

public function preDelete()
    // AttachmentAwareTrait
    return parent::preDelete();


Attachment widget can be use more than once in a form. In order for it to work properly, you need to define a group ident group different for each instanciated widgets.

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

In this case, we set the group to "main". If none defined, the default group will be "generic". Without those ident, widgets won't be able to know which attachments are his.

You can than access a perticular "group" attachments calling the object's method "attachments(group_ident)". In this case, $object->attachments('main') will return attachments associated with the widgets that has the group set to "main".

Attachment creation

The one thing you need to know about the attachment is that it is all in a single table. You can't associate custom objects with other objects if they are not attachments.

Then, how could you create new attachments? It all depends on what you want.

Adding or modifying properties

IF you need to add properties to an existing attachment, you can always extend it. Let's say you want to change the editor options for the description field given with the attachments. The first step is to create a new object that will extend the existing one.

 * Extended text class.
namespace My\Namespace;

use Charcoal\Attachment\Object\Text as AttachmentText;

class Text extends AttachmentText

Now that we have the extend, let's add to the JSON by creating a my/namespace/text.json file.

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

In that case, the editor options are changed to remove the base style formats, change the body class and add the appropriate css. The important part is to set the data type to the current object. This is used in live edit and delete features.

If you added some extra properties, you can use the alter script to add them into the table.

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


Don't use "attachments" method directly in mustache template. This will return ALL attachments without considering the group.

Custom templates for the attachment preview in the backend widget is on the to-do list.

Other actions such quick view are on the to-do list as well.

For a complete project example using charcoal-attachment, see the charcoal-project-boilerplate.


To install the development environment:

★ composer install --prefer-source

Run the code checkers and unit tests with:

★ composer test

API documentation

Development dependencies

  • phpunit/phpunit
  • squizlabs/php_codesniffer
  • satooshi/php-coveralls

Continuous Integration

Service Badge Description
Travis Build Status Runs code sniff check and unit tests. Auto-generates API documentaation.
Scrutinizer Scrutinizer Code Quality Code quality checker. Also validates API documentation quality.
Coveralls Coverage Status Unit Tests code coverage.
Sensiolabs SensioLabsInsight Another code quality checker, focused on PHP.

Coding Style

The Charcoal-Attachment module follows the Charcoal coding-style:

Coding style validation / enforcement can be performed with composer phpcs. An auto-fixer is also available with composer phpcbf.



Charcoal is licensed under the MIT license. See LICENSE for details.