Related Documents New Functionality

Related Documents have received new functionality in the latest update. Now, you can also use functions to define default values for documents dropped onto the specified Related items control. You can define any values, including the name of the file, pass certain conditions to this function, as well as use form fields to define values dynamically. It also gives you much more versatility with what you do, allowing implementation of asynchronous functions as well. In general, it gives you more control and utility when it comes to uploading documents.

In order to use this new functionality, simply pass function(listItem) {}, instead of an object {}, as an overload into fd.updateDroppedDocuments. Function takes List Item that is being added as a parameter. It should look like this:

fd.updateDroppedDocuments($('.related-docs'), function(listItem) {

});

How to rename the uploaded document?

Renaming the file is very easy. It’s similar to changing the directory of the file, but you can also change the name and even extension is changed. So, be very careful with extensions if you want your files to remain accessible. Here is a code sample:

fd.updateDroppedDocuments($('.related-docs'), function(listItem) {
    //new name for the file:
    var newName = "newName.txt";

    //file name with the current directory:
    var newFileName = listItem.get_item('FileDirRef') + '/' + newName;

    //finally, renaming the file after all the code:
    listItem.get_file().moveTo(newFileName);
});

Important: Change of the name should be the last thing that you do with the item as it moves it to a different place. All other changes should come first.

Also, remember that there cannot be two files with the same name in the Library, so you need to change the value dynamically somehow. In the next section, you can see how you can use fields to your advantage.

How to define values using fields on the form?

Accessing the fields is as easy as it always was. But to define a certain value of the uploaded file, you need to use code like this:

fd.updateDroppedDocuments($('.related-docs'), function(listItem) {
    //get the values from the Form fields:
    var price = fd.field("Info").value();
    var info = fd.field("Info").value();

    //set the values on uploaded document:
    listItem.set_item('Price', price);
    listItem.set_item('Information', info);

    listItem.update();
});

How to manually check in the file and why?

So, what is Check In and why do we have to add it? As many of you are aware, for the files to be available to all people with access, it needs to be checked in first. It happens automatically when you create a new item and all mandatory fields are filled in correctly.

But what if we want to fill the required fields with our function? In this case, the file won’t check in properly, unless we explicitly add the command to do so. So, if you created an item and all mandatory fields are filled, but other people can’t see it somehow, most likely it didn’t check in properly. Simply include listItem.get_file().checkIn(); in your code after filling all the required fields:

fd.updateDroppedDocuments($('.related-docs'), function(listItem) {
    //filling in the required field "Cheese"
    listItem.set_item('Cheese', 'Mozzarella');
    listItem.update();

    //need to check in manually in the end
    listItem.get_file().checkIn();
});

Asynchronous functions?

So, I mentioned async functions, but so far my examples were very simple and straightforward. But yes, if you need to, you can create complex functions when populating values for your documents, and you can even use async.

Here is an example:

fd.updateDroppedDocuments($('.related-docs'), function(listItem) {
    var result = $.Deferred();

    var ctx = listItem.get_context();
    var file = listItem.get_file();
    ctx.load(file);
    ctx.executeQueryAsync(function() {
        file.moveTo(listItem.get_item('FileDirRef') + '/newfilename.txt');
        file.checkIn();
        ctx.executeQueryAsync(function() {
            result.resolve();
        });
    });

    return result;
});

This code simply renames the file and checks it in, but it returns a Deferred object (or a promise). Only after resolving the returned promise, next handlers will be executed. This functionality might be very useful in some of the more advanced and complicated scenarios.