How to track recently used files and folders (HTML)

Article
10/13/2015

[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]

Track files that your user accesses frequently by adding them to your app's most recently used list. The platform manages the mostRecentlyUsedList for you by sorting items based on when they were last accessed and by removing the oldest item when the list's 25-item limit is reached. All apps have their own mostRecentlyUsedList.

Typically, your app's most recently used list (MRU) will be most useful for tracking your user's most recently used files, but the MRU can also be used to track folders. You can store both files and folders in your app's most recently used list (MRU). Items are stored as IStorageItem objects which means that storageFile objects (which represent files) and storageFolder objects (which represent folders) can both be added to the MRU.

Prerequisites

File access and permissions

Explains which files and locations your app has access to by default, and the ways your app can gain access to additional files and locations.

Quickstart: Accessing files with file pickers

Explains how to let users pick the files for your app to operate on. Picked files are often the same files that users return to again and again.

File access sample

File picker sample

Add picked files to the MRU

The files that your user picks are often files that he or she returns to over and over again. Because of this, if your user picks a file, you should strongly consider adding that file to your app's most recently used list (MRU). You can easily add picked files to the MRU as soon as they are picked, by following these steps.

Find the code in your app that lets your user pick files and/or folders.

If you're not sure where this code is or if you don't understand how to use the file picker to access files, read Quickstart: Accessing files with file pickers before you continue.

For example, if you let the user pick a single file, your code should look similar to this:
```
var openPicker = new Windows.Storage.Pickers.FileOpenPicker();
openPicker.viewMode = Windows.Storage.Pickers.PickerViewMode.thumbnail;
openPicker.suggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.picturesLibrary;
openPicker.fileTypeFilter.replaceAll([".png", ".jpg", ".jpeg"]);

// Open the picker for the user to pick a file
openPicker.pickSingleFileAsync().done(function (pickedFile) {
    if (pickedFile) {
        // Process picked file       
    } else {
        // Canceled; no file was picked
    }
});
```
When the asynchronous call returns, pickSingleFileAsync in the example, the file that the user picked is returned as a storageFile. We use done to pass the picked file (pickedFile in the example) to a processing function (the anonymous function in the example) where we will add the file to the mostRecentlyUsedList.

If you are letting your user pick a folder, instead of a file, your code uses pickSingleFolderAsync, and the picked folder is returned as a storageFolder.
Add the picked file to the most recently used list (MRU) inside your processing function with a line of code like this:
```
        var mruToken = Windows.Storage.AccessCache.StorageApplicationPermissions.mostRecentlyUsedList.add(pickedFile, pickedFile.name);
```
mostRecentlyUsedList.add is overloaded. In the example, we use add(fileOrFolder, metadata) so that we can associate metadata with the file. Setting metadata lets you capture additional information like the item's purpose. In the example, we capture the purpose of the file by setting the metadata to "profile pic". You can also add the file to the MRU without metadata by calling add(fileOrFolder).

Whenever you add an item to the MRU, the method returns a uniquely identifying string, called a token, that is used to retrieve the item. In the example, we capture this token in the mruToken local variable, but we don't do anything else with it.

Tip Because you need to use a token to retrieve an item from the MRU, you should consider saving the token to app data for subsequent use. For example, if your app adds a profile pic to the MRU (like we do in the example), you might want to save the token to a list in app data where you track the user's profiles pictures. You can learn more about app data in Managing application data.

Your processing function should now look similar to this:
```
openPicker.pickSingleFileAsync().done(function (pickedFile) {
    if (pickedFile) {
        // Add picked file to MRU
        var mruToken = Windows.Storage.AccessCache.StorageApplicationPermissions.mostRecentlyUsedList.add(pickedFile, pickedFile.name);

        // Continue processing picked file      
    } else {
        // Canceled; no file was picked
    }
});
```

Use tokens to retrieve items from the MRU

To retrieve an item from the mostRecentlyUsedList you need the token for that item. You should use the retrieval method most appropriate for the item you want to retrieve:

Retrieve a file as a storageFile by using getFileAsync.
Retrieve a folder as a storageFolder by using getFolderAsync.
Retrieve a generic IStorageItem that can represent either a file or folder by using getItemAsync.

For example, we get the token for the first item, a file, in our MRU and then use the token to retrieve a storageFile that represents that file, with this code:

var mruFirstToken = Windows.Storage.AccessCache.StorageApplicationPermissions.mostRecentlyUsedList.entries.first.token;
Windows.Storage.AccessCache.StorageApplicationPermissions.mostRecentlyUsedList.getFileAsync(mruFirstToken).done(
    function (retrievedFile) {
        // Process retrieved file
    },
    function (error) {
        // Handle errors 
    }
);

In the example, we know that the first item is a file because we have only added one file to the mostRecentlyUsedList.

Retrieve tokens for all items in the MRU

You can retrieve the token for every item in the list by iterating the entries like this:

var mruEntries = Windows.Storage.AccessCache.StorageApplicationPermissions.mostRecentlyUsedList.entries;
if (mruEntries.size > 0) {
    mruEntries.forEach(function (entry) {
        var mruToken = entry.token;
        // Continue processing the MRU entry
    });
} else {
    // Handle empty MRU
}

These entries are accessListEntry structures that contain the token and metadata for an item. Entries do not contain the item itself and can't be used to retrieve the associated item directly.

Instead, you can use the accessListEntry to retrieve the token for an associated item, and then retrieve an item by using one of the methods listed in the preceding section, Use tokens to retrieve items from the MRU. In the example, we capture the token for each entry in the mruToken local variable, but we don't do anything else with it.

The metadata stored in an accessListEntry is a string with additional information about the item. You can specify the information when you add an item to the mostRecentlyUsedList.

Remarks

Removing items from the MRU when the 25-item limit is reached

When the MRU's 25-item limit is reached and you try to add a new item, Windows automatically removes the oldest item (the item that was last accessed the longest time ago). You therefore don't need to remove an item before you add a new one, even if the MRU contains the maximum number of items (25).

Preserving access to files and folders beyond the 25-item limit

In addition to the most recently used list, your app also has a future access list (futureAccessList) that you can use to maintain your app's access to files and folders that might not be accessible otherwise.

When the user picks a file or folder you should consider adding that item to both your app's mostRecentlyUsedList and futureAccessList. Adding the file or folder to the futureAccessList helps ensure that your app maintains access to the item even if the user does not return to it frequently.

How you work with the futureAccessList is different from how you work with the MRU in a couple of key ways:

The futureAccessList can hold up to 1000 items.
Unlike the MRU, the platform does not manage the futureAccessList for you. When you reach the 1000 item limit, you must remove an item from the list before adding another one. You can do this by using the remove method.

All apps have their own mostRecentlyUsedList and futureAccessList by default.