Inside Kentico: Best Practice to manage files

In previous versions of Kentico there was only one single procedure for adding files, like images or PDFs to your web site. But since version 4, you have now three different possibilities to upload and manage your files within the CMS: You can store them within the site tree, as document attachment or within the media library.

In a review of Kentico 4.0 and 4.1 I previously described how the document attachments and media library work. The purpose of this post is to compare strategies for the use of these different methods. This review is for power users and content managers who wish to understand why the programmers make the choices they do.

1. The “File” document type

The easiest –and oldest way – to add an image or any other document to your website is to create a new document with the document type “File”.

As for any of the three methods there are advantages and disadvantages that I will simply list in point form:

Advantages:

• The file is accessible throughout the site;
• The image or file can be controlled by a workflow, so you can update a file without publishing it to the live site immediately;
• The file can be easily translated into each culture if necessary. This can come in handy for files that contain language specific data, such as PDFs or images with type on it; If this is not required, a server wide setting allows to use the file of the base culture in all other cultures;
• You can rollback to previous version.

Disadvantages:

• The fact that the file can be controlled by a workflow also means that the file needs to be published before being available on the live site, which can be a drag.
• When used with images, the display will not be as snappy as it will be with media libraries because every request will trigger a database request. File caching can help a bit, but don’t expect miracles.
• You need to upload files document by document and there is no easy way to batch update files.
• Versioning will blow up your database, which can become a real problem for huge attachments such as videos or audio files.

Possible uses:

• Quick and dirty solution, if you do not want to setup media libraries
• Use for files that are different in each culture and that you want to have the same alias path. For example, you create a list of links to PDFs in an editable text field and want to avoid redoing the links for each culture.
• If your documents or images need to be controlled by a workflow (i.e. PDF files)

2. Document attachments

Document attachments were introduced in version 4.1. I covered some of the advantages in an older blog post, but I will round it up here again.

Document attachments are files that are attached to a document in the document tree. This means a couple of things: These files can only be used within this document. They are automatically published when the document is published and they are also deleted once the document is deleted.

Using document attachments makes a lot of sense if you are sure, that you will use the attachment only for this document. The advantage is obvious, you will spend less time looking around for these files in your document tree or the media library, because they are stored in the property/attachment tab of the document.

Inline controls – a feature within your text editor – can help you to easily display these attachments (Check you text editor for the button “insert inline control” and use “Document attachments” or Attachment image gallery”).

There is currently one bug with these file types (and if it's not a bug, it is at least weak): if you are not using permanent URLs (“use permanent URLs” in the category “URL and SEO” is unchecked) - which is very likely because you care about SEO friendly URLs - you are not allowed to change the alias path of your document any more after inserting an image in a text field. Doing so will break all links and you will have to reinsert all images/files again.

Unfortunately, there currently is no setting that allows using permanent URLs for document attachments only. I actually would have expected that document attachments are using document aliases to make sure these links don’t break. Let’s wait for version 5.5….

Another disadvantage when using PDF files with document attachments (and the same applies to the file document type), is that the files are actually being renamed. Instead of having a nice name like “newsletter.pdf”, the file will be called “bf5fa0ac-b0a4-43dc-984a-a35526b4ef66.pdf”. Obviously, if a user wants to download this file to his desktop, he won’t have a clue what the document is about.

Advantages:

• The file is well organized, because attached to one specific document.
• The file is automatically published once the document is published.
• You can scale images stored as document attachments and they will be automatically resized on the server side — while keeping the original dimensions (very smart feature!).
• Different versions of your attachments will not be saved

Disadvantages:

• Once you have created links to your images with your text editor, you are not allowed to change the alias path any more. Serious disadvantage!
• You can’t reuse an attachment for other cultures.
• Same issue, as with the document file type, image display is not very fast.
• Different versions of your attachments will not be saved (well, depending what you want to achieve this can be an advantage or a disadvantage).

Possible uses:

• Blog posts, press releases, events
• All images (and files, if you don’t care about the file name) that are needed only for this document.

3. The Media library

File handling with the media library is what come closest to what we are used to within old-fashioned HTML pages. In my opinion it remains in most cases the best option.

Of course you will not be able to take advantage of the workflow features and you will need to be somewhat organized to remember which file is stored where, but in return you get a bunch of advantages.

While document attachments can be used by inline controls, files stored in the media library can be used with many web parts, be it a complete folder tree, a simple viewer or even the file uploader. The media file data source also presents a smart option to display media library content on your site.

Custom document types can take advantage of a media library file picker. Very convenient.

Advantages:

• Fast! If not used with permanent URLs, the files are directly accessed from the hard drive of your web server.
• Bulk upload: You can use an FTP program to upload entire folders of heavy files and simply overwrite them if necessary. Once uploaded the files need to be imported (bulk feature available) to be accessible by the text editor. Remember that by default the maximum size for uploading files within the CMS is limited to 10MB (check your config file to change this setting), so uploading files via FTP is sometimes your best option.
• You can upload a preview file for each file in the media library. This is especially useful for movies, audio or PDF files (It is actually a bit tricky to access these preview files, but it is possible).
• All files keep their original name!

Disadvantages:

• No workflow
• If you are expecting to use your web site for many years, you will need to be organized.
• You move or rename a file and you will break the link, as long you do not use permanent URLs (which again, would have performance issues).

Possible uses:

• Skins. I am using media libraries to store all images used in style sheets
• PDF Libraries, movie and audio libraries
• All other files that are used site-wide
• Pretty much everything, as long you do not depend on a workflow and the document attachments won’t work for you.

Summary

Depending on your needs, you have three options available to handle files with Kentico. Most probably you want to use Media Libraries, but there are situations, where document attachments or even the file document type might come in handy.