Senior Frontend Engineer
Callin’s primary goal as a frontend engineer is translating designs into working, interactive pieces of the internet. He’s also responsible for building systems that allow existing designs to extend to new features without feeling out of place.
September 30, 2020
When upgrading an old site or migrating to a new platform, file management is one of those tasks that either gets ignored or unearths old habits. Throughout the years, site managers have accommodated typical requests like “Can you make this PDF available for download on the website?” This is a simple task, but it can cause problems years from now when file versioning and links in a WYSIWYG editor are thrown into the mix
How can site managers enforce strict organizational guidelines across dozens, hundreds, or thousands of users? The default solution is to push this file mess to the sites/default/files directory and not get too concerned over how this directory grows over time
By organizing your folder structure and defining a file naming convention, you can maintain the site for years to come. So let’s embrace our organizational side and put some effort into a better future of managing user-uploaded files.
Modules and organizational structure
When Media was added to the Drupal 8.5.x release, it was a game changer for storing and managing user-facing files. It’s highly recommended that you follow the “Creating and configuring Media Types” guide published on Drupal.org unless you have specific use cases
File (Field) Paths is my module of choice. It handles folder structure and file renaming via tokens. As of September 2020, it is still in beta, but it is actively being maintained with a strong effort to get a stable release out the door.
How to define the organization
When creating media, we’ll have “Title” and “File Upload” fields, but we’ll need to add two more fields to achieve the ideal organizational structure. I suggest adding two term reference fields to help categorize media and another to tag items in a non-hierarchical way
“Category” vocabulary should be hierarchical and is the base for the new folder structure. By using taxonomy, we have an easy-to-use UI for defining a dynamic folder structure without the need for an FTP client. Category terms may be user facing or have some additional meaning to the organization. Examples include departments for higher education sites, sections for publishing sites, or product categories for e-commerce
The “Tags” field is for internal use only and should only be used to find media easier. More on this to come in Part 2 of this article.
File naming conventions
Next, we need to address the file name itself. Consistency should be the goal when working with lots of users uploading files. At a minimum, rename any uploaded file as an all-lowercase, no-spaces version of the value of the “Title” field that is transliterated into the US-ASCII alphabet. Transliteration is the process of taking letters or characters that exist in other languages and replacing them with their English equivalent. This process ensures that we do not have to account for special characters, browser compatibility in those languages, and the complexity of sorting characters from different languages. Depending on the site’s needs, it might make sense to add a date or the username of the person who uploaded the file.
Setting up the organization
- Download and install the File (Field) Paths module. It does not have any dependencies so this process is pretty straightforward. For reference, here is Drupal’s guide to installing modules.
- Create the two taxonomy vocabularies outlined above.
- Modify an existing media entity or create a new one so it has two term reference fields pointed at the new vocabularies. The user should only be able to reference one term from the category vocabulary and unlimited terms from the tag vocabulary.
File path configuration
Once you have File (Field) Paths enabled, there will be a new configuration option for every instance of a File or Image field. This configuration should be consistent across all media types
First, we’ll define the File path by using tokens:
[media:field_media_category:entity:parent:parent:parent:parent]/rn[media:field_media_category:entity:parent:parent:parent]/rn[media:field_media_category:entity:parent:parent]/rn[media:field_media_category:entity:parent]/rn[media:field_media_category]
Let me break down what we’re doing here, starting from the last token. [media:field_media_category] tells Drupal to create a new folder within sites/default/files and use the term referenced
The second part of this configuration is the parent structure. If the term referenced is at a second level, we want Drupal to create two folders: First will be the term’s parent and then the actual referenced term. This is where the [media:field_media_category:entity:parent]/ values come into play. Chaining this token with an added :parent argument allows the folder structure to include multiple parent levels. In my example above, I wasn’t sure how deep my category tree would go, but I didn’t anticipate it being deeper than four levels. Your situation may be different, so be mindful of how this structure could expand over time
Below the path tokens, there are three additional options that help clean up the tokenized output. Select all of these options and the folder structure will output a browser-friendly path that matches the vocabulary structure. The folder names will be transliterated with the extra slashes between non-existent parents removed. The result: Files stored at any level of the hierarchy.
Renaming the file
For the file name, we’ll use the title of the media and its original extension: [media:name:value].[file:ffp-extension-original]. This cleans up file names in case users upload files to the “Biology 101 Syllabus” media entity with names like “Biology-101 Syllabus-Semester-1 2020.pdf.” This example transforms to “biology-101-syllabus.pdf.”
Additional configuration
Lastly, as media files are revised and potentially recategorized, I want Drupal to reflect these changes here. By enabling “Replace Existing Files,” I can be assured that the latest file is always being used. If I have a media entity with the name “Biology Class Syllabus” and upload a new file with the same name, or even an entirely different name, it will automatically replace the correct file. If a content admin changes the referenced category, it will move the file to a different folder. I also recommend adding the “Create Redirect” option so existing links that were manually created still point to the correct file
Quick tip: There are a lot of taxonomy term field widgets available on Drupal.org. Here are two I recommend:
- The Client-side Hierarchical Select module works well with the category field. It allows the content editor to choose parents or easily find child terms without the ambiguous nature of an autocomplete widget.
- The Autocomplete Deluxe module is hard to beat when it comes to tagging content. The content editor can reference existing tags or create new ones on the fly.
What we’ve accomplished
As your site grows, your files folder will remain organized intuitively and consistently across users. By integrating a taxonomy vocabulary as the folder structure, you can grow and modify this organization as time goes on
If your site’s files directory is disorganized and you need some help, contact us about our support offerings and how we can help.
Making the web a better place to teach, learn, and advocate starts here...
When you subscribe to our newsletter!