In traditional web development, one of the trickier features to implement is file uploads. This is where you can use your web browser to select a file on your local computer, and upload it to your web server to share with others.
Adding Files
Drupal actually gives us several different ways to deal with this. In this tutorial, we're going to take a look at one of the most common ways of doing filing uploads, the file field. In our demo sight, let's say that Acme wants to attach some support documents to the product content type. We want to be able to add files, such as guides and manuals, to our product notes. This is where the file field comes into play.
To add a file field, we just need to go to where we can manage our fields, and that's underneath Structure, which I'm going to open in a new tab. Flip over to the new tab, go to content types, and then underneath Product, I'm going to go to Manage Fields. And down here is where I can add my new field field. I'm going to call this one Documents. I'm going to give it a machine name of Document, and I'm going to leave it singular--a lot of times it's the best practice when you're giving a field a machine name, to leave it singular, even though for this one we're going to allow multiple values. Under my field type, I'm going to go ahead and select File, and we only have one input widget, the file input widget, so I'm going to go ahead and leave that set and click Save.
And now we're presented with our Field Settings form. Up here we've got a couple of options dealing with whether we want to display this field on a node view. Most of the time this is what you're going to want to do with files, although there are some special scenarios, such as say for example if you're doing a podcast and you're uploading an audio file, you might do something other than just display the field. But we want to display these for people to see and download, so we're going to go ahead and check it, and then we want to be displayed by default. These can also be changed by the node author, but the default works well. Down here we have where we want to save the file, and what's kind of important to realize is that most fields store all their information into the database so you don't have to worry about storing files, but a file upload we've got to store it somewhere.
By default Drupal gives you one option: public files. If you set a private file directory, you can get that option here. You can have additional options though, depending on how your site is configured. Public files are ones that can be downloaded and viewed by the general public. Private files you've got to have certain permissions to view--I'm fine with these documents being viewed by the public, so we're going to go ahead and leave it set to public files. And now we get to our widget configuration page. I'm going to go ahead and leave this Label Documents. It's just the original one I put in and that's fine. I don't want to have this field be required because maybe some of our widgets don't have support documents, and that's fine so I'm not going to require it.
Additional Options
I do want to put in some instructional information to my node authors, so I'm going to put in: "Attach support documents." And then I scroll down and in our next field we see that we have what file extensions are allowed to be uploaded. And what happens here is that the user tries to upload anything that's not in this list, they'll get an error and it won't allow them to upload or submit the node. Txt is a little bit limiting, so we might want to add some different new types of file types, so I'm going to go ahead and put in "doc," "docx(the new file of Word documents)", maybe "odt (open doc)", and maybe "pdf." That gives us a pretty good sampling. Now we scroll down to our file directory field. What this is about is that we've already cited where we want to store our files in our public directory and our server, but this file field, other file fields we create and so forth, by default will put all these files into the root of this directory. And as you can imagine things get kind of messy quickly. We can have many different files that are not well organized. And so what this allows us to do is it allows us to create a subdirectory structure in order to store our files and organize them a little bit better.
One way that I like to store my files for a node file field is to use the node machine name/the file field name. So I'm going to go ahead and put it "product/document." Now one other thing that you might notice is down here, we've got a bunch of different variables that I could use in this path. Now this doesn't come as a part of Drupal core built in, this is actually a contributed module called Token, which you can download from drupal.org. But one thing it gives me is it gives me variables I can use to better organize my subdirectories, so I'm going to go underneath this one current page, and I'm going to copy out this variable, and I'm going to add it here. And then I'm going to change this and I want to change it to 1. Why I'm doing this is because if you notice that in our past structure, nodes are always nodes slash the node number, the node ID, and so this is going to say that for our blue widget is which node 3, any files I upload for that widget are going to go underneath product/3/document. So in scrolling down the page we get to our maximum upload size. If we don't put a value here, it's going to use whatever is our maximum size it said in PHP. On my installation this is set to 50 megabytes which is right here, but on your installation it might very well be something different. I do want to go ahead and limit our maximum file size upload to something a bit smaller, maybe 5 megabytes.
The next field says do I want to add a description for our documents that we're uploading, I don't want to do this for this particular field, but it's something you might want to in other types of fields. The next thing we'd say is what do we want to use as an indicator for when people are uploading--this is just kind of saying it's nice, it's not critical to the system. Basically if you're using smaller files are going to be uploaded, the throbber works well. If you have larger files that might take a while to upload, you might want to switch to the bar, because it's going to give you a progress meter, and that way people know that this much of the file is being uploaded and they can see that progress is being made so they don't just think that their browsers hung. We're not going be using big files so I'm going to go ahead and leave the throbber set. The last thing I want to do is I want to go ahead and allow us to accept multiple different values. I'm going to go ahead and set this to unlimited, so now people can upload multiple documents to a single node, not just a single one or a fixed number. So now I'm going to go ahead and save my settings.
The last thing we might want to do is figure out where we want to sort our new documents field inside of our node edit form. Because documents are optional and they're going to show up displayed below the body, I'm going to go ahead and leave the field down at the bottom, so I'm just going to leave it where it is. So now let's go add some files to our product node. To do that I'm going to click on our node edit form and scroll down below the body, where we see our new file upload field. To upload files I click Browse, and now I'm looking at a directory structure on my local computer and I can select a file that's on my local machine. So you're going to select this License text file and click Upload. Automatically upload to the browser, saved it on the server, and now I get a listing of this file and a checkbox on whether or not I want to display it on the node view. I'm going to go ahead and upload a couple more files. Have a Getting Started manual, and our support manual. Now I'm going to scroll down and click Save. Now we scroll down the page, and here we can see the documents that we've attached. I go ahead and click on one of them, and we can view the documents such as this PDF. What's also pretty nice is that the theme has detected what kind of filing extension we have and associated the appropriate icon.
That's the way file upload fields works. In this tutorial, we've reviewed how the file fields streamlines is a tricky website feature. File uploads to a server via a web browser. The file field gives us a robust set of options to control what files can be uploaded, how they're stored, and how they're displayed. The file field is ideal for working a wide range of general files, but there are more specialized upload fields for specific media types, such as images. videos, and audio. These provide advanced features specific to those file types. We'll take a look at some of these in future videos.