Single media/file attachment: attachOne

With the attachOne function files like images, movies or documents can be attached to a record of a database table. Media attachments are using built-in relations of OctoberCMS. So it is very easy to implement them.

This is what a record with an attached file - an image in this case - will look like.

Prerequisites are

• an installed builder plugin
• any source code editor or e.g. the Developer Tools plugin with built-in Code editor like in the screenshoots
• a database table for records to attach the media to
• a form (at least in backend) to display the media
• some media already uploaded to the media manager or ready to do so

Required skills

• how to work with builder
• how to create a plugin with builder
• how to create tables and forms with builder

As for any relation OctobrCMS requires a relation behaviour. This simply means to tell October how to deal with relations.
The main controller file is located in the respective plugin directory, subdirectory /controllers/
For our library example with the book table this is

  /pds/library/controllers/books.php

Here there are two changes required:

Here is the source code, required changes are highlighted:

<?php namespace Pds\Library\Controllers;

use Backend\Classes\Controller;
use BackendMenu;

class Books extends Controller
{
    public $implement = ['Backend\Behaviors\ListController',
                         'Backend\Behaviors\FormController',
                         'Backend\Behaviour\RelationController']; // this line adds the relation behaviour
    
    public $listConfig = 'config_list.yaml';
    public $formConfig = 'config_form.yaml';
    
    //add configuration of relation for Books
    // this file has to be created then manually inside the
    // [namespace]\controllers\[controllername] folder
    public $relationConfig = 'config_relation.yaml'; 

    public function __construct()
    {
        parent::__construct();
        BackendMenu::setContext('Pds.Library', 'library-main-menu-item');
    }
}

The base model requires to know the type of desired relation as well as the name of the relation. This name can be seen like a field name of a database-table.

The base model is located in the plugin directory, subdirectory models using the singular of the related db-table name. In our library example this is:

  /pds/library/models/book.php

Here, the attachOne relation has to be inserted:

These are the lines of code to add (comments are not necessary, of course, but they will help to maintain the code):

    // add a relation for a SINGLE image, field name is 'cover'
    // this table must not have a field named 'cover' !
    public $attachOne = [
        'cover' => ['System\Models\File', 'public' => false]
    ];

Next step is to complete the form with an additional field to upload and display media and/or files:

Finally, in the backend form view of the plugin, a file can be uploaded by clicking on the file upload symbol - the area below the 'Cover Image' title in the example: