View source for User:P.A./Panel-based Download Manager

{{FeatureStatus
|Feature name=Panel-based Download Manager
|Feature stage=Landed
|Feature status=Complete
|Feature version=Firefox 20
|Feature health=OK
|Feature status note=In beta, go to release.
}}
{{FeatureTeam
|Feature product manager=Asa Dotzler
|Feature feature manager=Marco Bonardo
|Feature lead engineer=Paolo Amadini, Mike Conley
|Feature qa lead=Simona Badau
|Feature ux lead=Alexander Limi
|Feature additional members=Sinchan Banerjee, Stephen Horlander, Shawn Wilsher, Mehdi Mulani, Jared Wein
}}
{{FeaturePageBody
|Feature overview=<div style="margin: 1em 0px; border: 2px solid orange; padding: 1em; background-color: #FFC; text-align: center; font-size: large;">
THE DOWNLOADS PANEL HAS BEEN RELEASED IN FIREFOX 20.

YOU CAN READ MORE ABOUT THE FEATURE IN THE '''[http://mikeconley.ca/blog/2013/04/02/downloading-stuff-in-firefox-its-better-now/ INTRODUCTORY BLOG POST]'''.</div>

This is the detailed technical [[Features/Planning_and_Tracking|feature page]] for the [[User:P.A./Download_user_experience_improvements#Panel-based_Download_Manager|Downloads Panel]]. This feature is part of the [[User:P.A./Download_user_experience_improvements|download user experience improvements]].

The current Download Manager user interface is not optimized for several common use cases, and is not yet integrated with the latest Firefox user experience design. Integrating this interface with the latest design is the first step to improve the downloads user experience.

In the new design, an easily accessible panel shows you current state of downloads, your recent downloads, and gives you a good indicator of how far along your download is. Advanced operations like searching, clearing entries, sorting, and everything else related to download history is integrated with the interface for browsing history.

==== Goals ====
* Fit in with the [[User:P.A./Download_user_experience_improvements#Overall_goals|overall goals of download user experience improvements]].
* Remove the need for a separate Download Manager window.
* Unify download history with browsing history.
* Support common use cases, but not necessarily all of those supported previously.
* Improve the user interface code, and use asynchronous database queries.
|Feature users and use cases=* Downloading and running a setup program ([https://bugzilla.mozilla.org/show_bug.cgi?id=564934#c68 Bug 564934, comment 68] and [https://bug564934.bugzilla.mozilla.org/attachment.cgi?id=467459 attachment 467459]).

We also probably want to consider some, but not all, of the [[Download_Manager#Use_Cases_to_Consider|use cases previously suggested for the Download Manager]]. Note that the current Download Manager does not support all of suggested use cases, while some of them are in the scope of different [[User:P.A./Download_user_experience_improvements|download user experience improvements]].
|Feature non-goals=* Power user fuctionality, like handling many concurrent downloads.
* File management, except for showing where the target file is located.
* Improve download performance or general front-end responsiveness.
** ''Note that we still don't want to introduce significant regressions.''
* Improve the Download Manager or Places back-end C++ code, or make it asynchronous.
* '''Any other improvement already defined as [[User:P.A./Download_user_experience_improvements|download user experience improvements]].'''
** ''For example, streamlining the entire download process.''
|Feature ux design=We'll reach the stated goals by adding a panel for handling the most recent downloads, anchored to a status indicator in the main browser window, and moving the interface for handling all downloads to a new '''Downloads''' predefined folder in the Library window.

In the following sections, entries are marked with these indicators:
* {{ok|Not yet implemented.}}
* <span style="color: orange; font-size: 80%; font-weight: bold">[INPUT]</span> Needs design feedback, or a prototype implementation to understand what to do.
* {{done|Has an initial implementation that can be tested.}}

=== Downloads indicator ===

Provides a status overview, visible during normal browsing when there are download notifications.

* {{done|Always visible by default, located on the navigation bar, between the search bar and the home button.}}
* {{done|When there are no active downloads, shows the classic button icon (downwards arrow).}}
* {{done|When there are active downloads, shows a progress bar and a compact indication of the remaining time, if known.}}

Provides visual indication of new downloads or completed downloads.

* {{done|New downloads are notified with a brief animation near the indicator.}}
* {{done|Finished or failed downloads make the indicator glow until the panel is displayed.}}
* {{done|The usual screen-level notification is shown when all downloads are completed.}}
** Note that this is shown even when the indicator is visible.

Provides the anchor for the panel.

* {{done|If the indicator is removed from the toolbars, or is located in an invisible toolbar, the panel will never be displayed.}}
** {{done|In this case, the full download management interface will be shown when a new download is started.}}
* {{done|User-initiated requests to show downloads will always open the Downloads view in the Library window, regardless of indicator visibility.}}

=== Downloads panel ===

The entries in the popup panel are just notifications saying that a download is going on, and that a download has finished.

The panel works as follows:

* {{done|The panel should be shown automatically for the first download after the feature is enabled, for discoverability.}}
* {{done|Only a few recent downloads are shown in the panel, thus not all the current downloads can be managed from the panel.}}
** This must ensure that the panel does not expand to the full screen height when opened in a maximized window.
* {{done|Notifications are sorted by start time, most recent first.}}
** It's consistent with notification sorting in other platforms, and the order doesn't change unexpectedly while the panel is open.
* {{done|The panel contains a link to the full list of downloads.}}
* {{done|The panel is fixed-width.}}
** Resizeability is not as much of an issue with the downloads panel as it is with the bookmarks panel, because the downloads panel is less of a "management" interface. The full title of a download is shown in a tooltip.
* {{done|When there are no download items, the panel's width can be smaller.}}

Individual notifications have the following behavior:

* Notifications should disappear as soon as the user is done with them. We can't know the exact moment, so we use a set of heuristics.
** {{done|Completed downloads are removed from the list when the last browser window is closed.}}
*** Active downloads are never removed from the list automatically, though they can be hidden by most recent downloads.
*** Completed downloads are not restored if the previous session is restored. They can still be accessed from the Downloads view in the Library window.
** {{done|Canceling a running download does not make the notification disappear.}}
** {{done|Manually removing a download from the list is possible, but not a top-level interaction.}}
* There are no actions that make sense on more than one notification at a time.
* {{done|The height of each notification does not change when its state changes.}}

The layout of a notification includes a main area with the download's distinctive details, and an optional action button. In some states of the download, the main area can be clicked. Double-clicking the main area, instead, is not a supported interaction.

A context menu for the item can always be displayed. It may contain commands already available through a top-level interaction for consistency.

* {{done|When the main area can be clicked, a link-style mouse cursor is displayed on hover.}}
* When the download is ongoing [not paused or finished or canceled]:
** {{done|The button cancels the download.}}
** {{done|The context menu has commands to pause, open containing folder, go to download page, copy download link.}}
* When the download is paused:
** {{done|The button cancels the download.}}
** {{done|The context menu has commands to resume, open containing folder, go to download page, copy download link.}}
* When the download is failed or canceled:
** {{done|The button retries the download. Often, the download will resume from where it stopped, if supported by the server.}}
** {{done|The context menu has commands to remove from list, go to download page, copy download link.}}
* When the download has finished:
** {{done|Clicking the main area opens the file.}}
*** {{ok|If the target file is missing, the main area should not be clickable. The existence detection should happen in the background.}}
** {{done|The button opens the containing folder.}}
** {{done|The context menu has commands to remove from list, go to download page, copy download link.}}

There are additional items in the context menu that act on all downloads:
** {{done|A context menu item is available for removing completed downloads from the list, without closing the last browser window.}}

=== Library window ===

The Library window allows the user to see the full list of downloads. The user can control ongoing downloads, as well as finding and opening previous downloads.

'''The interaction with ongoing downloads is different from the standalone Downloads window.''' The interaction will be more similar to the Downloads Panel.

* {{done|When the user selects the Downloads folder, the list of history pages is replaced with a different view for handling current downloads.}}
* The Downloads view shows both ongoing downloads and download history.
** <span style="color: orange; font-size: 80%; font-weight: bold">[INPUT]</span> Items are sorted based on the current criteria, selected by the user.
** {{done|Items can be found at least by source location or original target file name.}}
** {{done|Most ongoing downloads should also be present in the browsing history, in which case they are shown in the same position as the history item.}}
*** If there is no specific matching history item, ongoing downloads might be shown in no particular order.
** {{done|History items with no matching current download behave in the same way as completed downloads.}}
* {{done|Download items have an interaction similar to the Downloads Panel items.}}
** {{done|The items contain the same elements as the panel items, based on the current download state.}}
** The interaction will also be different from history items in other Library views.
|Feature implementation notes===== Bugs list and patch queue ====

'''Feature tracking bug:'''

* {{bug|564934}} (see also the [[/Status|status]] page)

'''Relevant patches that are available in nightly builds:'''

The feature is now available in standard release trains. Key implementation bugs are:

* {{bug|726444}}: Implement the Downloads Panel.
* {{bug|675902}}: New Downloads view for Places Library.

'''Additional patches needed to test the feature:'''

* None. The feature is now available in standard release trains.

'''Work required to release and enable the feature for everyone:'''

* Bugs listed as blocking {{bug|747422}} (completed).

==== Follow-ups ====
This section lists non-blocking, suggested follow-ups that need more work before filing a proper bug. Often a search for existing bugs is required before filing a separate bug.

<table class="fullwidth-table sortable">
<tr>
<td style="font-weight: bold; background: #ddd;">Description</td>
<td style="font-weight: bold; background: #ddd;">References</td>
</tr>
<tr>
<td><tt>Cu.import</tt> failures don't show up in the Error Console, or the test logs.</td>
<td>[https://bugzilla.mozilla.org/show_bug.cgi?id=564934#c224 Bug 564934, comment 224]</td>
</tr>
<tr>
<td>No feedback when the "open download page" link is clicked and the target page is not available.</td>
<td>[https://bugzilla.mozilla.org/show_bug.cgi?id=564934#c191 Bug 564934, comment 191]</td>
</tr>
<tr>
<td>Allow asynchronous termination functions in the testing framework.</td>
<td>[https://bugzilla.mozilla.org/show_bug.cgi?id=564934#c259 Bug 564934, comment 259]<br>Scroll to <tt>@@ +47,5 @@</tt></td>
</tr>
<tr>
<td>Move original <tt>nsDownloadManagerUI.js</tt> to <tt>mozapps/downloads</tt>.</td>
<td>[https://bugzilla.mozilla.org/show_bug.cgi?id=564934#c192 Bug 564934, comment 192]</td>
</tr>
<tr>
<td><tt>NetUtil.newURI</tt> should <tt>QueryInterface</tt> to <tt>nsIFileURL</tt> automatically.</td>
<td>[https://bugzilla.mozilla.org/show_bug.cgi?id=564934#c86 Bug 564934, comment 286]</td>
</tr>
<tr>
<td>Move <tt>fileExecutableSecurityWarning</tt> to a common place in Toolkit.</td>
<td></td>
</tr>
</table>
}}
{{FeatureInfo
|Feature priority=P2
|Feature rank=4
|Feature theme=Experience
|Feature roadmap=Firefox Desktop
|Feature list=Desktop
|Feature engineering team=Desktop front-end
}}
{{FeatureTeamStatus
|Feature security status=sec-review-complete
|Feature security health=OK
|Feature security notes=[[Security/Reviews/Firefox10/PanelDownload|Notes]]
|Feature qa notes=[https://wiki.mozilla.org/User:P.A./Panel-based_Download_Manager/TestPlan Test Plan]
}}