This plugin adds categories and tags to the WordPress media library - lightweight and developer-friendly.
The plugin adds two taxonomies to the WordPress media library which are then available to categorize and tag your attachments. By default, these taxonomies, although sharing the same names and behavior, are separate from the default post taxonomies, but this can easily be changed if desired.
The plugin follows WordPress Core principles and offers a lightweight alternative to similar approaches which often tend to be incredibly flexible, but at the same time complicated and bloated. And if you have a little knowledge of code, you should be able to adjust the plugin exactly to your needs if the default configuration doesn’t satisfy you.
[gallery]
shortcode so that images of a specific attachment taxonomy can be included automaticallyhas_default
argument that can be used when registering an attachment taxonomy in order to automatically add a setting for the default taxonomy termattachment-taxonomies
folder to the /wp-content/plugins/
directory or download it through the WordPress backend.If you don’t know what a must-use plugin is, you might wanna read its introduction in the WordPress Codex.
attachment-taxonomies
folder to the /wp-content/mu-plugins/
directory (create the directory if it doesn’t exist)./wp-content/mu-plugins/attachment-taxonomies/attachment-taxonomies.php
out of its directory to /wp-content/mu-plugins/attachment-taxonomies.php
.Note that, while must-use plugins have the advantage that they cannot be disabled from the admin area, they cannot be updated through WordPress, so you’re recommended to keep them up to date manually.
Once the plugin is activated, you will see two new submenu items under Media (Categories and Tags), where you can manage available attachment categories and tags.
If you like, you can set a default category to apply to new attachment uploads, via using the added dropdown on the Settings > Writing screen.
The plugin follows the WordPress Core philosophy “Decisions, not Options” – therefore there is no additional settings screen. However, the plugin is easily extendable and adjustable by developers (see FAQ). So if the base configuration does not suit your needs, it shouldn’t be too hard to change that.
Note that all code samples below should be run before the init
action hook and not earlier than the plugins_loaded
(or muplugins_loaded
if you use the plugin as a must-use plugin) hook.
You can simply use the WordPress Core function register_taxonomy()
and specify 'attachment'
as the second parameter. As an alternative, you can create your own class for the taxonomy, extending the abstract Attachment_Taxonomy
class provided by the plugin. Then you can add it using the method add_taxonomy( $taxonomy )
of the class Attachment_Taxonomies
.
Example Code (adds an attachment taxonomy called “Location”):
<?php final class Attachment_Location extends Attachment_Taxonomy { protected $slug = 'attachment_location'; protected $labels = array( 'name' => __( 'Locations', 'textdomain' ), 'singular_name' => __( 'Location', 'textdomain' ), /* more labels here... */ ); protected $args = array( 'hierarchical' => true, 'query_var' => 'location', /* more arguments here... */ ); } add_action( 'plugins_loaded', function() { Attachment_Taxonomies::instance()->add_taxonomy( new Attachment_Location() ); } );
To remove one of the default attachment taxonomies you should call the method remove_taxonomy( $taxonomy_slug )
of the class Attachment_Taxonomies
.
Example Code (removes the attachment taxonomy “Category”):
<?php add_action( 'plugins_loaded', function() { Attachment_Taxonomies::instance()->remove_taxonomy( 'attachment_category' ); } );
To accomplish that, first you need to remove the two taxonomies that the plugin adds (attachment_category
and attachment_tag
). See above for instructions on how to do that.
Then you can simply use the WordPress Core function register_taxonomy_for_object_type()
and specify 'attachment'
as the second parameter. As an alternative, you can create your own instance of the Attachment_Existing_Taxonomy
class provided by the plugin. Then you can add it using the method add_taxonomy( $taxonomy )
of the class Attachment_Taxonomies
, as seen in the example below.
Example Code (makes the regular category and tag taxonomies available for attachments):
<?php add_action( 'plugins_loaded', function() { Attachment_Taxonomies::instance()->add_taxonomy( new Attachment_Existing_Taxonomy( 'category' ) ); Attachment_Taxonomies::instance()->add_taxonomy( new Attachment_Existing_Taxonomy( 'post_tag' ) ); } );
The [gallery]
shortcode can now be passed taxonomy attributes. They have to have the attachment taxonomy slug as the attribute name and a comma-separated list of term slugs or term IDs as value. You may also specify a new “limit” attribute to limit the amount of images shown. This is especially recommended if the attachment taxonomy term you are querying for contains a lot of images. As of version 1.2.0, the plugin furthermore supports an optional “tax_relation” attribute, which you can set to “AND” in order to show only images that satisfy all of the taxonomy attributes provided on the shortcode.
Example Code (shows images with attachment categories 1 or 2 or attachment tag 5 with a limit of 20 images shown):
[gallery attachment_category="1,2" attachment_tag="5" limit="20"]
Example Code (shows images with attachment categories 1 or 2 and attachment tag 5):
[gallery attachment_category="1,2" attachment_tag="5" tax_relation="AND"]
Note that there is currently no UI in the backend for this, and the preview in the editor will not work properly. It will show up correctly in the frontend though.
The plugin provides some filters to adjust taxonomy arguments and labels.
attachment_taxonomy_args
where first argument is the array of taxonomy arguments and the second argument is the taxonomy slug that these arguments apply toattachment_taxonomy_{$taxonomy_slug}_args
where the only argument is the array of taxonomy arguments for the taxonomy defined by $taxonomy_slug
attachment_taxonomy_labels
where first argument is the array of taxonomy labels and the second argument is the taxonomy slug that these labels apply toattachment_taxonomy_{$taxonomy_slug}_labels
where the only argument is the array of taxonomy labels for the taxonomy defined by $taxonomy_slug
attachment_taxonomy_class_names
where the only argument is the array of class names of the taxonomies to register by defaultFor regular support requests, please use the wordpress.org support forums. If you have a technical issue with the plugin where you already have more insight on how to fix it, you can also open an issue on GitHub instead.
If you have ideas to improve the plugin or to solve a bug, feel free to raise an issue or submit a pull request in the GitHub repository for the plugin. Please stick to the contributing guidelines.
You can also contribute to the plugin by translating it. Simply visit translate.wordpress.org to get started.
build-cs
is no longer included in the plugin ZIP.wp/v2/media
endpoint.tax_relation
attribute on gallery
shortcode to control whether to include attachments with any or all of the given taxonomies.show_ui
.load_plugin_textdomain()
.has_default
argument of true
when registering the taxonomy.[gallery]
shortcode now supports passing taxonomy arguments: The slug of a taxonomy can be given alongside with a comma-separated list of term slugs or IDs.attachment_taxonomy_class_names
can be used to filter the class names for the taxonomies that should be registered by default.$existing
parameter across several functions.