When we are trying to insert a file using the WordPress Media Uploader, we will embed them. For images those are attachment display options, for videos those are embed options etc. The embed options can be used to insert something more such as a new format or similar. In this tutorial, we will now see how we can add a new field as an embed option to that part of the WordPress Media Uploader screen.
I have worked on a project which required such functionality. I had to add different format for a video which would have on embed option. When it comes to images, there would be much more embed options. We are going to see how we can add new embed option and also use it for images.
Changing the WordPress Media Uploader Template
First, we need to add our script to the admin footer. But we will only add it when the WordPress Media script is enqueued.
Creating a new Template
The template we need to change can be found at
wp-includes/media-template.php and the name of our template is
We will need to copy the whole template, name it a little different and use it. Let’s now add that template and also add a new field at the end:
At the end, we are checking if the attachment is an image and then add a checkbox that we will check if we want this image to be only displayed for logged in users.
input field we got two attributes:
data-user-setting. Both have the same value. This value
loggedIn will be used when sending the attachment to our editor. Since, such setting is not there by default, we will need to extend the function where we are sending the attachment to editor (later in this tutorial).
By placing this template at the admin footer, we got nothing.
Replacing the Template
The new template has to be used in the place of the old (original) template. This will be done in another
With this code, we are first saving the original Backbone.js view into the variable
attDisplayOld. After that we are extending that display but adding a new template to it, which is our new one. The extended display is then being assigned to the
wp.media.view.Settings.AttachmentDisplay. That view is used to rendered the edit screen inside the WordPress Media Uploader.
If you try to add an attachment to the editor, you can see our new field as an embed option.
Sending new Setting to the Editor
When we hit the button Insert into Post, WordPress will perform an AJAX request and add the HTML to the editor. We need to send our new settings also in that AJAX request. The HTML we will get will be done in the next tutorial.
The function that is doing this is defined as
wp.media.editor.send.attachment. This can be found at
wp-includes/js/media-editor.js. Let’s add that function in our second script and add our settings to the images:
We are adding our embed option to the variable
options. This variable will then be set as the parameter
attachment when sending a request.
Let’s look at the AJAX request when our setting is not added (before adding this code):
If we now enable our new setting as we did in our code, we will have a slightly different request. Do note that the setting gets inserted only when there is a change on the setting. This means that the setting will be send only when the checkbox has been checked. Let’s check our new setting and try to insert the attachment into a post:
Controlling the Template fields by sending data
Here is a rather simple scenario. We will the data to check if the attachment has that field or not. This can be anything, but for the purpose of this tutorial I have chosen the most simpler scenario.
If the attachments need to add this field, we will have it set to true, otherwise will be false. The returned variable
$post will then add that data to the variable
data in out template.
Each new data that we set through
$post is available at
data.attachment.attributes. Our own option will be then available at
data.attachment.attributes.loggedin. Let’s now edit our template to reflect this change:
Now, we are checking if our attachment is an image and if it should show this field or not.
Tutorials from this series: