Rename a file in chrome before download

Project Gutenberg is an online library where you can download e-books for free. But every time I download one, the file has a stupid filename, like so I have to manually rename it to the book's title.

I decided to do something about it and create a plugin so that the file is automatically renamed with the book title followed by the book's authors' names. The goal is to have a file with a name useful for Windows' search function.

In this article, I'll walk you through the development stages and the plugin's code. This is my first Google Chrome plugin and I'm not a javascript developer so suggestions for improvement are welcome.

On a side note, the extension is a lot shorter and simpler than I expected.

Demo

Here is a video of what the plugin achieves. On the video, we can see that I download a book from Project Gutenberg. The book appears in my folder with a gibberish filename. Then, I activate the plugin before re-downloading the same book. The book is automatically downloaded inside the subfolder and the file is named according to the book's title :-)

Turn on the subtitles for a real time text description of what is happening.

Our task

When downloading a book from Project Gutenberg, the usual flow is as follows:

1. user lands on www.cronistalascolonias.com.ar and search for a book
2. user clicks on a book and lands on the book's page, for instance www.cronistalascolonias.com.ar
3. user clicks the download link and a file with a non-semantic filename is downloaded
4. user leaves the book's page

Our task is to:

• inspect the book's page at step 2 to find the book's title and store it
• rename the downloaded file automatically at step 3
• free up the storage space at step 4.

To do so, we will create a chrome extension.

Creating an extension

To create an extension, we must create a new folder with a json file called . This manifest file is the entry point for chrome to recognize and load the extension.

The minimal content of for chrome to recognize the folder as an extension is the following:

To load the extension into Chrome, proceed as follows:

1. Open the Extension Management page by navigating to ;
2. Enable Developer Mode by clicking the toggle switch next to Developer mode ;
3. Click the LOAD UNPACKED button and select the directory to load the extension into Chrome.

Scraping the book's title

First, we need a way to get the book's title. To do so, we will parse the download page with a content script. A content script is a javascript code that executes when a given page is loaded. It can read details (i.e. html) of the page, make changes to it and pass information to the parent extension.

We need to update the manifest to ask for permission to run the extension on the Gutenberg URL and to let chrome know about our content script. To be able to store the book's title, we also need access to the API:

Now, let's create our content script in the file .

If we inspect the source code of a page to download a book, for instance this one, we can see that the title is in a heading with :

We can fetch it easily in javascript using . Then, we need to store it so that our extension can later access it. For that, we will use the storage API and store the book's title along with the page URL:

We need to ensure that the filename is removed from the storage at some point. The best option I could think of is to remove the entry when we leave the page, since we usually leave the page after we have clicked the download link and the entry is thus no longer required. The code is usual javascript along with another call to the storage API:

And that's it! Let's see how to intercept the download and rename the file with this newly constructed filename.

Intercepting downloads

To intercept downloads, we will use a background script. A background script is used to monitor events and let our extension react to them. Here, we will use it to react to the downloading of a file.

First, we need to update our manifest to ask permission to access the API and to register our background script:

Background scripts should almost always be set to . As the documentation indicates:

The only occasion to keep a background script persistently active is if the extension uses www.cronistalascolonias.com.aruest.

There are many events that we can listen to in the download API. The one of interest here is the onDeterminingFilename event.

According to the doc, each listener must call exactly once to change the filename. If the listener calls asynchronously, then it must return . The template is as follows:

We can use the argument to find context about the downloaded file. We will use it to ensure the file comes from Project Gutenberg, and use the referrer URL to fetch the book's title in storage. Here's the full code:

An icon for our extension

In the page, click the reload icon in the extension's pane. Try downloading an e-book, it should be automatically renamed and put in the subfolder . Yeay!

The last step is to provide a nice icon for the extension. Download one somewhere on the internet, put it in the extension folder and specify its name in the manifest as follows:

You can use different icon sizes. For more information see the doc here.