WHATWG Wiki - User contributions [en]

DragAndDropEntries

2012-06-24T16:54:12Z

Kinuko: /* Benefits */

Proposing exposing dropped files/folders as {File,Directory}Entry defined in FileSystem API [1] for better folders/files drag-and-drop support (this proposal was originally proposed on whatwg mailing list).

[1] File API: Directories and System http://www.w3.org/TR/file-system-api/
[2] Original proposal email: http://lists.whatwg.org/pipermail/whatwg-whatwg.org/2011-November/033814.html

== Background ==

Many sites have 'upload your files' feature, like for your photo images. HTML5 allows you to do this via <input type="file" multiple> or drag-and-drop feature, but the current solution does not provide clean solution for cases with folders, files/folder mixed cases, or folders with subfolders cases.

== Proposing API ==

Add a new field 'entries' to <input type=files> element <ref>http://www.whatwg.org/specs/web-apps/current-work/multipage/states-of-the-type-attribute.html#file-upload-state-(type=file)</ref> and a new accessor method 'getAsEntry()' to DataTransferItem object<ref>http://www.whatwg.org/specs/web-apps/current-work/multipage/dnd.html#the-datatransferitem-interface</ref>. Populate the field with or return an 'Entry' object defined in FileSystem API upon file selection or drop events.

Since we didn't use to have a good interface to represent directories/folders, all webapps could access for file drag-and-drop was one or multiple files given as '''File''' objects.

On the other hand, this API proposes returning '''Entry''' instances <ref>http://dev.w3.org/2009/dap/file-system/file-dir-sys.html#the-entry-interface</ref>, which can represent either file or directory. Via the '''Entry''' interface webapps can easily distinguish if a dropped entity is a file or directory by examining '.isFile' or '.isDirectory' field of the entry. If the entry is a directory, webapps can recursively walk over nested files and directories included in the directory by calling '.readEntries()' method of the directory reader for the entry.

This approach allows webapps to directly interact with the local folder structure, and also allows them to control the enumerating part so that the apps can show nice progress meter if they want.

=== Benefits ===

* '''Enables folder drag-and-drop''': Most obvious and direct advantage of this API is it enables folder/directories drag-and-drop both in <input type=file> and HTML5 native drag-and-drop, which was purely not possible in the current HTML5 specification.

* '''Enables folders/files mixtured drag-and-drop''': Similarly, since '''Entry''' interface can represent files and directories, the API naturally enables more advanced mixed cases in drag-and-drop, like multiple folders, multiple folders and files and so on.

* '''Gives webapps full control of when and what to traverse''': Unlike previous proposals for folder drag-and-drop<ref>http://lists.w3.org/Archives/Public/public-whatwg-archive/2010Apr/0240.html</ref>, this approach does not require full-traversal of the dropped folder(s) by the user agent, but instead simply exposes an interface with which webapps can asynchronously interact with the dropped folder(s). This gives the webapps a greater control of when and what to traverse directories, or when to stop the traversal, or how to ''show a neat progress indicator'' to the users. This also means that users no longer need to worry about sluggish browser behavior when s/he has wrongly dropped a directory which contains a millions of nested files/directories.

* '''Gives webapps direct read-only access to the user's local file tree''': Since the API exposes a selected user's local folder with its complete tree structure, it opens up various interesting possibilities to webapps which was not possible without accessing directory structures. E.g. importing a user's Photos folders with album-like subfolders to a photo-album app, importing a user's source code tree to a web-based IDE, showing a nice file browser on a dropped media drive in a cover-flow like interface etc.

=== HTMLInputElement.entries ===

interface HTMLInputElement : HTMLElement {
// allows scripts to access the element's selected files as an array of Entry defined in FileSystem API.
// On getting, if the IDL attribute applies, it must return a Entry array that represents the current selected files and/or folders.
// If the IDL attribute does not apply, then it must instead return null.
// Unless the multiple attribute is set, there must be no more than one file in the list of selected files.
readonly attribute Entry[] entries;
}

=== DataTransferItem.getAsEntry() ===

interface DataTransferItem {
// Like DataTransferItem.getAsFile(), getAsEntry() method runs following steps:
// 1. If the DataTransferItem object is not in the read/write mode or the read-only mode, return null and abort these steps.
// 2. If the drag data item kind is not File, then return null and abort these steps.
// 3. Return a new Entry object representing the actual file or directory represented by the DataTransferItem object.
Entry getAsEntry();
};

== Isolated FileSystem ==

The Entry exposed by this feature is created in an '''Isolated''' filesystem, which is '''read-only''', isolated and transient. The filesystem only contains the dropped items and can only be accessed by the site where the drag-and-drop event has happened. Webapps cannot access any other files or folders outside the filesystem.

=== Restrictions ===

* The Entry in isolated filesystem '''does not support toURL()''' or is not resolvable by resolveFileSystemURL(), since its filesystem is transient and has limited life time (while toURL URL's do not work as live references like Blob URLs). The dropped entries are only accessible while the app has live instance for the entries.
* The Entry's '''fullPath does not (and should not) expose the file's full platform path''' as it could contain a sensitive information. Instead it MAY contain a relative path to the top directory that the user dropped.

== Example ==

Assume a user has following files and folders in his/her 'Photos' folder:

/Users/username/Photos/trip/1.jpg
/Users/username/Photos/trip/2.jpg
/Users/username/Photos/trip/3.jpg
/Users/username/Photos/halloween/2011/a.jpg
/Users/username/Photos/halloween/2011/b.jpg
/Users/username/Photos/halloween/2012/plan.jpg
/Users/username/Photos/tokyo/1.jpg
/Users/username/Photos/tokyo/2.jpg

When the user drag-and-drops or selects the two folders, '''trip''', '''halloween''' and one photo file '''tokyo/1.jpg''', the webapp will get following entries via 'entries' field of the input element or via DataTransferItem.getAsEntry():

DirectoryEntry for 'trip',
DirectoryEntry for 'halloween'
FileEntry for '1.jpg'

Via the new 'entries' field the app can access children files or subfolders in the selected entries, and can properly organize and process pictures using the local folder structure. Even if the dropped directory is on a slow removable media, or it contains tons of subdirectories and files, the app can recursively traverse each of them while showing a nice progress information, or can show an interactive file tree which lets the user freely expand or select some of the contents.

We can think of similar interesting usage scenarios like local-cloud sync app or bulk 'importer', e.g. importing local source directory to cloud IDE etc.

=== Example Code (Drag and Drop) ===

var droptarget = document.getElementById('droptarget');

droptarget.addEventListener('dop', function (e) {
e.stopPropagation();
e.preventDefault();

var items = e.dataTransfer.items;
for (var i = 0; i < items.length; ++i) {
if (items[i].kind != "file")
continue;

var entry = items[i].webkitGetAsEntry(); // WebKit/chromium needs 'webkit' prefix (since Chrome 21)

// import the dropped files/folders into temporary filesystem
entry.copyTo(temporaryFs.root, entry.name, successCallback, errorCallback);
});

=== Example Code (Input) ===

<input type="file" multiple />

var input = document.querySelector("input[type='file']");

input.addEventListener('change', function (e) {
e.stopPropagation();
e.preventDefault();

var entries = e.target.webkitEntries; // WebKit/chromium needs 'webkit' prefix (since Chrome 22)

for (var i = 0; i < entries.length; ++i) {
if (entries[i].isDirectory) {
traverseDirectoryTree(entry);
} else {
showFileEntry(entries[i]);
}
});

== References ==

<references />

[[Category:Proposals]]

DragAndDropEntries

2012-06-24T16:52:13Z

Kinuko:

Proposing exposing dropped files/folders as {File,Directory}Entry defined in FileSystem API [1] for better folders/files drag-and-drop support (this proposal was originally proposed on whatwg mailing list).

[1] File API: Directories and System http://www.w3.org/TR/file-system-api/
[2] Original proposal email: http://lists.whatwg.org/pipermail/whatwg-whatwg.org/2011-November/033814.html

== Background ==

Many sites have 'upload your files' feature, like for your photo images. HTML5 allows you to do this via <input type="file" multiple> or drag-and-drop feature, but the current solution does not provide clean solution for cases with folders, files/folder mixed cases, or folders with subfolders cases.

== Proposing API ==

Add a new field 'entries' to <input type=files> element <ref>http://www.whatwg.org/specs/web-apps/current-work/multipage/states-of-the-type-attribute.html#file-upload-state-(type=file)</ref> and a new accessor method 'getAsEntry()' to DataTransferItem object<ref>http://www.whatwg.org/specs/web-apps/current-work/multipage/dnd.html#the-datatransferitem-interface</ref>. Populate the field with or return an 'Entry' object defined in FileSystem API upon file selection or drop events.

Since we didn't use to have a good interface to represent directories/folders, all webapps could access for file drag-and-drop was one or multiple files given as '''File''' objects.

On the other hand, this API proposes returning '''Entry''' instances <ref>http://dev.w3.org/2009/dap/file-system/file-dir-sys.html#the-entry-interface</ref>, which can represent either file or directory. Via the '''Entry''' interface webapps can easily distinguish if a dropped entity is a file or directory by examining '.isFile' or '.isDirectory' field of the entry. If the entry is a directory, webapps can recursively walk over nested files and directories included in the directory by calling '.readEntries()' method of the directory reader for the entry.

This approach allows webapps to directly interact with the local folder structure, and also allows them to control the enumerating part so that the apps can show nice progress meter if they want.

=== Benefits ===

* '''Enables folder drag-and-drop''': Most obvious and direct advantage of this API is it enables folder/directories drag-and-drop both in <input type=file> and HTML5 native drag-and-drop, which was purely not possible in the current HTML5 specification.

* '''Enables folders/files mixtured drag-and-drop''': Similarly, since '''Entry''' interface can represent files and directories, the API naturally enables more advanced mixed cases in drag-and-drop, like multiple folders, multiple folders and files and so on.

* '''Gives webapps full control of when and what to traverse''': Unlike previous proposals for folder drag-and-drop<ref>http://lists.w3.org/Archives/Public/public-whatwg-archive/2010Apr/0240.html</ref>, this approach does not require full-traversal of the dropped folder(s) by the user agent, but instead simply exposes an interface with which webapps can asynchronously interact with the dropped folder(s). This gives the webapps a greater control of when and what to traverse directories, or when to stop the traversal, or how to show a progress indicator to the users. This also means that users no longer need to worry about sluggish browser behavior when s/he has wrongly dropped a directory which contains a millions of nested files/directories.

* '''Gives webapps direct read-only access to the user's local file system''': Since the API exposes a selected user's local folder with its complete tree structure, it opens up various interesting possibilities to webapps which was not possible without accessing directory structures. E.g. importing a user's Photos folders with album-like subfolders to a photo-album app, importing a user's source code tree to a web-based IDE, showing a nice file browser on a dropped media drive etc.

=== HTMLInputElement.entries ===

interface HTMLInputElement : HTMLElement {
// allows scripts to access the element's selected files as an array of Entry defined in FileSystem API.
// On getting, if the IDL attribute applies, it must return a Entry array that represents the current selected files and/or folders.
// If the IDL attribute does not apply, then it must instead return null.
// Unless the multiple attribute is set, there must be no more than one file in the list of selected files.
readonly attribute Entry[] entries;
}

=== DataTransferItem.getAsEntry() ===

interface DataTransferItem {
// Like DataTransferItem.getAsFile(), getAsEntry() method runs following steps:
// 1. If the DataTransferItem object is not in the read/write mode or the read-only mode, return null and abort these steps.
// 2. If the drag data item kind is not File, then return null and abort these steps.
// 3. Return a new Entry object representing the actual file or directory represented by the DataTransferItem object.
Entry getAsEntry();
};

== Isolated FileSystem ==

The Entry exposed by this feature is created in an '''Isolated''' filesystem, which is '''read-only''', isolated and transient. The filesystem only contains the dropped items and can only be accessed by the site where the drag-and-drop event has happened. Webapps cannot access any other files or folders outside the filesystem.

=== Restrictions ===

* The Entry in isolated filesystem '''does not support toURL()''' or is not resolvable by resolveFileSystemURL(), since its filesystem is transient and has limited life time (while toURL URL's do not work as live references like Blob URLs). The dropped entries are only accessible while the app has live instance for the entries.
* The Entry's '''fullPath does not (and should not) expose the file's full platform path''' as it could contain a sensitive information. Instead it MAY contain a relative path to the top directory that the user dropped.

== Example ==

Assume a user has following files and folders in his/her 'Photos' folder:

/Users/username/Photos/trip/1.jpg
/Users/username/Photos/trip/2.jpg
/Users/username/Photos/trip/3.jpg
/Users/username/Photos/halloween/2011/a.jpg
/Users/username/Photos/halloween/2011/b.jpg
/Users/username/Photos/halloween/2012/plan.jpg
/Users/username/Photos/tokyo/1.jpg
/Users/username/Photos/tokyo/2.jpg

When the user drag-and-drops or selects the two folders, '''trip''', '''halloween''' and one photo file '''tokyo/1.jpg''', the webapp will get following entries via 'entries' field of the input element or via DataTransferItem.getAsEntry():

DirectoryEntry for 'trip',
DirectoryEntry for 'halloween'
FileEntry for '1.jpg'

Via the new 'entries' field the app can access children files or subfolders in the selected entries, and can properly organize and process pictures using the local folder structure. Even if the dropped directory is on a slow removable media, or it contains tons of subdirectories and files, the app can recursively traverse each of them while showing a nice progress information, or can show an interactive file tree which lets the user freely expand or select some of the contents.

We can think of similar interesting usage scenarios like local-cloud sync app or bulk 'importer', e.g. importing local source directory to cloud IDE etc.

=== Example Code (Drag and Drop) ===

var droptarget = document.getElementById('droptarget');

droptarget.addEventListener('dop', function (e) {
e.stopPropagation();
e.preventDefault();

var items = e.dataTransfer.items;
for (var i = 0; i < items.length; ++i) {
if (items[i].kind != "file")
continue;

var entry = items[i].webkitGetAsEntry(); // WebKit/chromium needs 'webkit' prefix (since Chrome 21)

// import the dropped files/folders into temporary filesystem
entry.copyTo(temporaryFs.root, entry.name, successCallback, errorCallback);
});

=== Example Code (Input) ===

<input type="file" multiple />

var input = document.querySelector("input[type='file']");

input.addEventListener('change', function (e) {
e.stopPropagation();
e.preventDefault();

var entries = e.target.webkitEntries; // WebKit/chromium needs 'webkit' prefix (since Chrome 22)

for (var i = 0; i < entries.length; ++i) {
if (entries[i].isDirectory) {
traverseDirectoryTree(entry);
} else {
showFileEntry(entries[i]);
}
});

== References ==

<references />

[[Category:Proposals]]

DragAndDropEntries

2012-06-24T16:49:26Z

Kinuko:

Proposing exposing dropped files/folders as {File,Directory}Entry defined in FileSystem API [1] for better folders/files drag-and-drop support (this proposal was originally proposed on whatwg mailing list).

[1] File API: Directories and System http://www.w3.org/TR/file-system-api/
[2] Original proposal email: http://lists.whatwg.org/pipermail/whatwg-whatwg.org/2011-November/033814.html

== Background ==

Many sites have 'upload your files' feature, like for your photo images. HTML5 allows you to do this via <input type="file" multiple> or drag-and-drop feature, but the current solution does not provide clean solution for cases with folders, files/folder mixed cases, or folders with subfolders cases.

== Proposing API ==

Add a new field 'entries' to <input type=files> element [1] and a new accessor method 'getAsEntry()' to DataTransferItem object [2]. Populate the field with or return an 'Entry' object defined in FileSystem API upon file selection or drop events.

[1] http://www.whatwg.org/specs/web-apps/current-work/multipage/states-of-the-type-attribute.html#file-upload-state-(type=file)

[2] http://www.whatwg.org/specs/web-apps/current-work/multipage/dnd.html#the-datatransferitem-interface

Since we didn't use to have a good interface to represent directories/folders, all webapps could access for file drag-and-drop was one or multiple files given as '''File''' objects.

On the other hand, this API proposes returning '''Entry''' instances (http://dev.w3.org/2009/dap/file-system/file-dir-sys.html#the-entry-interface), which can represent either file or directory. Via the '''Entry''' interface webapps can easily distinguish if a dropped entity is a file or directory by examining '.isFile' or '.isDirectory' field of the entry. If the entry is a directory, webapps can recursively walk over nested files and directories included in the directory by calling '.readEntries()' method of the directory reader for the entry.

This approach allows webapps to directly interact with the local folder structure, and also allows them to control the enumerating part so that the apps can show nice progress meter if they want.

=== Benefits ===

* '''Enables folder drag-and-drop''': Most obvious and direct advantage of this API is it enables folder/directories drag-and-drop both in <input type=file> and HTML5 native drag-and-drop, which was purely not possible in the current HTML5 specification.

* '''Enables folders/files mixtured drag-and-drop''': Similarly, since '''Entry''' interface can represent files and directories, the API naturally enables more advanced mixed cases in drag-and-drop, like multiple folders, multiple folders and files and so on.

* '''Gives webapps full control of when and what to traverse''': Unlike previous proposals for folder drag-and-drop [1], this approach does not require full-traversal of the dropped folder(s) by the user agent, but instead simply exposes an interface with which webapps can asynchronously interact with the dropped folder(s). This gives the webapps a greater control of when and what to traverse directories, or when to stop the traversal, or how to show a progress indicator to the users. This also means that users no longer need to worry about sluggish browser behavior when s/he has wrongly dropped a directory which contains a millions of nested files/directories.

* '''Gives webapps direct read-only access to the user's local file system''': Since the API exposes a selected user's local folder with its complete tree structure, it opens up various interesting possibilities to webapps which was not possible without accessing directory structures. E.g. importing a user's Photos folders with album-like subfolders to a photo-album app, importing a user's source code tree to a web-based IDE, showing a nice file browser on a dropped media drive etc.

[1] http://lists.w3.org/Archives/Public/public-whatwg-archive/2010Apr/0240.html

=== HTMLInputElement.entries ===

interface HTMLInputElement : HTMLElement {
// allows scripts to access the element's selected files as an array of Entry defined in FileSystem API.
// On getting, if the IDL attribute applies, it must return a Entry array that represents the current selected files and/or folders.
// If the IDL attribute does not apply, then it must instead return null.
// Unless the multiple attribute is set, there must be no more than one file in the list of selected files.
readonly attribute Entry[] entries;
}

=== DataTransferItem.getAsEntry() ===

interface DataTransferItem {
// Like DataTransferItem.getAsFile(), getAsEntry() method runs following steps:
// 1. If the DataTransferItem object is not in the read/write mode or the read-only mode, return null and abort these steps.
// 2. If the drag data item kind is not File, then return null and abort these steps.
// 3. Return a new Entry object representing the actual file or directory represented by the DataTransferItem object.
Entry getAsEntry();
};

== Isolated FileSystem ==

The Entry exposed by this feature is created in an '''Isolated''' filesystem, which is '''read-only''', isolated and transient. The filesystem only contains the dropped items and can only be accessed by the site where the drag-and-drop event has happened. Webapps cannot access any other files or folders outside the filesystem.

=== Restrictions ===

* The Entry in isolated filesystem '''does not support toURL()''' or is not resolvable by resolveFileSystemURL(), since its filesystem is transient and has limited life time (while toURL URL's do not work as live references like Blob URLs). The dropped entries are only accessible while the app has live instance for the entries.
* The Entry's '''fullPath does not (and should not) expose the file's full platform path''' as it could contain a sensitive information. Instead it MAY contain a relative path to the top directory that the user dropped.

== Example ==

Assume a user has following files and folders in his/her 'Photos' folder:

/Users/username/Photos/trip/1.jpg
/Users/username/Photos/trip/2.jpg
/Users/username/Photos/trip/3.jpg
/Users/username/Photos/halloween/2011/a.jpg
/Users/username/Photos/halloween/2011/b.jpg
/Users/username/Photos/halloween/2012/plan.jpg
/Users/username/Photos/tokyo/1.jpg
/Users/username/Photos/tokyo/2.jpg

When the user drag-and-drops or selects the two folders, '''trip''', '''halloween''' and one photo file '''tokyo/1.jpg''', the webapp will get following entries via 'entries' field of the input element or via DataTransferItem.getAsEntry():

DirectoryEntry for 'trip',
DirectoryEntry for 'halloween'
FileEntry for '1.jpg'

Via the new 'entries' field the app can access children files or subfolders in the selected entries, and can properly organize and process pictures using the local folder structure. Even if the dropped directory is on a slow removable media, or it contains tons of subdirectories and files, the app can recursively traverse each of them while showing a nice progress information, or can show an interactive file tree which lets the user freely expand or select some of the contents.

We can think of similar interesting usage scenarios like local-cloud sync app or bulk 'importer', e.g. importing local source directory to cloud IDE etc.

=== Example Code (Drag and Drop) ===

var droptarget = document.getElementById('droptarget');

droptarget.addEventListener('dop', function (e) {
e.stopPropagation();
e.preventDefault();

var items = e.dataTransfer.items;
for (var i = 0; i < items.length; ++i) {
if (items[i].kind != "file")
continue;

var entry = items[i].webkitGetAsEntry(); // WebKit/chromium needs 'webkit' prefix (since Chrome 21)

// import the dropped files/folders into temporary filesystem
entry.copyTo(temporaryFs.root, entry.name, successCallback, errorCallback);
});

=== Example Code (Input) ===

<input type="file" multiple />

var input = document.querySelector("input[type='file']");

input.addEventListener('change', function (e) {
e.stopPropagation();
e.preventDefault();

var entries = e.target.webkitEntries; // WebKit/chromium needs 'webkit' prefix (since Chrome 22)

for (var i = 0; i < entries.length; ++i) {
if (entries[i].isDirectory) {
traverseDirectoryTree(entry);
} else {
showFileEntry(entries[i]);
}
});

[[Category:Proposals]]

DragAndDropEntries

2012-06-20T15:39:24Z

Kinuko: /* Isolated FileSystem */

Proposing exposing dropped files/folders as {File,Directory}Entry defined in FileSystem API [1] for better folders/files drag-and-drop support (this proposal was originally proposed on whatwg mailing list).

[1] File API: Directories and System http://www.w3.org/TR/file-system-api/
[2] Original proposal email: http://lists.whatwg.org/pipermail/whatwg-whatwg.org/2011-November/033814.html

== Background ==

Many sites have 'upload your files' feature, like for your photo images. HTML5 allows you to do this via <input type="file" multiple> or drag-and-drop feature, but the current solution does not provide clean solution for cases with folders, files/folder mixed cases, or folders with subfolders cases.

== Proposing API ==

Add a new field 'entries' to <input type=files> element [1] and a new accessor method 'getAsEntry()' to DataTransferItem object [2]. Populate the field with or return an 'Entry' object defined in FileSystem API upon file selection or drop events.

[1] http://www.whatwg.org/specs/web-apps/current-work/multipage/states-of-the-type-attribute.html#file-upload-state-(type=file)
[2] http://www.whatwg.org/specs/web-apps/current-work/multipage/dnd.html#the-datatransferitem-interface

Since FileSystem API naturally supports tree-structured folder hierarchy, Entry object exposes handy fields like 'isFile' and 'isDirectory', and allows webapps to recursively walk over the nested entries in subfolders via ReadDirectory() method.

This approach allows webapps to directly interact with the local folder structure, and also allows them to control the enumerating part so that the apps can show nice progress meter if they want.

=== HTMLInputElement.entries ===

interface HTMLInputElement : HTMLElement {
// allows scripts to access the element's selected files as an array of Entry defined in FileSystem API.
// On getting, if the IDL attribute applies, it must return a Entry array that represents the current selected files and/or folders.
// If the IDL attribute does not apply, then it must instead return null.
// Unless the multiple attribute is set, there must be no more than one file in the list of selected files.
readonly attribute Entry[] entries;
}

=== DataTransferItem.getAsEntry() ===

interface DataTransferItem {
// Like DataTransferItem.getAsFile(), getAsEntry() method runs following steps:
// 1. If the DataTransferItem object is not in the read/write mode or the read-only mode, return null and abort these steps.
// 2. If the drag data item kind is not File, then return null and abort these steps.
// 3. Return a new Entry object representing the actual file or directory represented by the DataTransferItem object.
Entry getAsEntry();
};

== Isolated FileSystem ==

The Entry exposed by this feature is created in an '''Isolated''' filesystem, which is '''read-only''', isolated and transient. The filesystem only contains the dropped items and can only be accessed by the site where the drag-and-drop event has happened. Webapps cannot access any other files or folders outside the filesystem.

=== Restrictions ===

* The Entry in isolated filesystem '''does not support toURL()''' or is not resolvable by resolveFileSystemURL(), since its filesystem is transient and has limited life time (while toURL URL's do not work as live references like Blob URLs). The dropped entries are only accessible while the app has live instance for the entries.
* The Entry's '''fullPath does not (and should not) expose the file's full platform path''' as it could contain a sensitive information. Instead it MAY contain a relative path to the top directory that the user dropped.

== Example ==

Assume a user has following files and folders in his/her 'Photos' folder:

/Users/username/Photos/trip/1.jpg
/Users/username/Photos/trip/2.jpg
/Users/username/Photos/trip/3.jpg
/Users/username/Photos/halloween/2011/a.jpg
/Users/username/Photos/halloween/2011/b.jpg
/Users/username/Photos/halloween/2012/plan.jpg
/Users/username/Photos/tokyo/1.jpg
/Users/username/Photos/tokyo/2.jpg

When the user drag-and-drops or selects the two folders, '''trip''', '''halloween''' and one photo file '''tokyo/1.jpg''', the webapp will get following entries via 'entries' field of the input element or via DataTransferItem.getAsEntry():

DirectoryEntry for 'trip',
DirectoryEntry for 'halloween'
FileEntry for '1.jpg'

Via the new 'entries' field the app can access children files or subfolders in the selected entries, and can properly organize and process pictures using the local folder structure. Even if the dropped directory is on a slow removable media, or it contains tons of subdirectories and files, the app can recursively traverse each of them while showing a nice progress information, or can show an interactive file tree which lets the user freely expand or select some of the contents.

We can think of similar interesting usage scenarios like local-cloud sync app or bulk 'importer', e.g. importing local source directory to cloud IDE etc.

=== Example Code (Drag and Drop) ===

var droptarget = document.getElementById('droptarget');

droptarget.addEventListener('dop', function (e) {
e.stopPropagation();
e.preventDefault();

var items = e.dataTransfer.items;
for (var i = 0; i < items.length; ++i) {
if (items[i].kind != "file")
continue;

var entry = items[i].webkitGetAsEntry(); // WebKit/chromium needs 'webkit' prefix (since Chrome 21)

// import the dropped files/folders into temporary filesystem
entry.copyTo(temporaryFs.root, entry.name, successCallback, errorCallback);
});

=== Example Code (Input) ===

<input type="file" multiple />

var input = document.querySelector("input[type='file']");

input.addEventListener('change', function (e) {
e.stopPropagation();
e.preventDefault();

var entries = e.target.webkitEntries; // WebKit/chromium needs 'webkit' prefix (since Chrome 22)

for (var i = 0; i < entries.length; ++i) {
if (entries[i].isDirectory) {
traverseDirectoryTree(entry);
} else {
showFileEntry(entries[i]);
}
});

[[Category:Proposals]]

DragAndDropEntries

2012-06-20T12:52:37Z

Kinuko: /* Example Code (Input) */

Proposing exposing dropped files/folders as {File,Directory}Entry defined in FileSystem API [1] for better folders/files drag-and-drop support (this proposal was originally proposed on whatwg mailing list).

[1] File API: Directories and System http://www.w3.org/TR/file-system-api/
[2] Original proposal email: http://lists.whatwg.org/pipermail/whatwg-whatwg.org/2011-November/033814.html

== Background ==

Many sites have 'upload your files' feature, like for your photo images. HTML5 allows you to do this via <input type="file" multiple> or drag-and-drop feature, but the current solution does not provide clean solution for cases with folders, files/folder mixed cases, or folders with subfolders cases.

== Proposing API ==

Add a new field 'entries' to <input type=files> element [1] and a new accessor method 'getAsEntry()' to DataTransferItem object [2]. Populate the field with or return an 'Entry' object defined in FileSystem API upon file selection or drop events.

[1] http://www.whatwg.org/specs/web-apps/current-work/multipage/states-of-the-type-attribute.html#file-upload-state-(type=file)
[2] http://www.whatwg.org/specs/web-apps/current-work/multipage/dnd.html#the-datatransferitem-interface

Since FileSystem API naturally supports tree-structured folder hierarchy, Entry object exposes handy fields like 'isFile' and 'isDirectory', and allows webapps to recursively walk over the nested entries in subfolders via ReadDirectory() method.

This approach allows webapps to directly interact with the local folder structure, and also allows them to control the enumerating part so that the apps can show nice progress meter if they want.

=== HTMLInputElement.entries ===

interface HTMLInputElement : HTMLElement {
// allows scripts to access the element's selected files as an array of Entry defined in FileSystem API.
// On getting, if the IDL attribute applies, it must return a Entry array that represents the current selected files and/or folders.
// If the IDL attribute does not apply, then it must instead return null.
// Unless the multiple attribute is set, there must be no more than one file in the list of selected files.
readonly attribute Entry[] entries;
}

=== DataTransferItem.getAsEntry() ===

interface DataTransferItem {
// Like DataTransferItem.getAsFile(), getAsEntry() method runs following steps:
// 1. If the DataTransferItem object is not in the read/write mode or the read-only mode, return null and abort these steps.
// 2. If the drag data item kind is not File, then return null and abort these steps.
// 3. Return a new Entry object representing the actual file or directory represented by the DataTransferItem object.
Entry getAsEntry();
};

== Isolated FileSystem ==

The Entry exposed by this feature is created in an '''Isolated''' filesystem, which is read-only, isolated and transient. The filesystem only contains the dropped items and can only be accessed by the site where the drag-and-drop event has happened. Webapps cannot access any other files or folders outside the filesystem.

=== Restrictions ===

* The Entry in isolated filesystem '''does not support toURL()''' or is not resolvable by resolveFileSystemURL(), since its filesystem is transient and has limited life time (while toURL URL's do not work as live references like Blob URLs). The dropped entries are only accessible while the app has live instance for the entries.
* The Entry's '''fullPath does not (and should not) expose the file's full platform path''' as it could contain a sensitive information. Instead it MAY contain a relative path to the top directory that the user dropped.

== Example ==

Assume a user has following files and folders in his/her 'Photos' folder:

/Users/username/Photos/trip/1.jpg
/Users/username/Photos/trip/2.jpg
/Users/username/Photos/trip/3.jpg
/Users/username/Photos/halloween/2011/a.jpg
/Users/username/Photos/halloween/2011/b.jpg
/Users/username/Photos/halloween/2012/plan.jpg
/Users/username/Photos/tokyo/1.jpg
/Users/username/Photos/tokyo/2.jpg

When the user drag-and-drops or selects the two folders, '''trip''', '''halloween''' and one photo file '''tokyo/1.jpg''', the webapp will get following entries via 'entries' field of the input element or via DataTransferItem.getAsEntry():

DirectoryEntry for 'trip',
DirectoryEntry for 'halloween'
FileEntry for '1.jpg'

Via the new 'entries' field the app can access children files or subfolders in the selected entries, and can properly organize and process pictures using the local folder structure. Even if the dropped directory is on a slow removable media, or it contains tons of subdirectories and files, the app can recursively traverse each of them while showing a nice progress information, or can show an interactive file tree which lets the user freely expand or select some of the contents.

We can think of similar interesting usage scenarios like local-cloud sync app or bulk 'importer', e.g. importing local source directory to cloud IDE etc.

=== Example Code (Drag and Drop) ===

var droptarget = document.getElementById('droptarget');

droptarget.addEventListener('dop', function (e) {
e.stopPropagation();
e.preventDefault();

var items = e.dataTransfer.items;
for (var i = 0; i < items.length; ++i) {
if (items[i].kind != "file")
continue;

var entry = items[i].webkitGetAsEntry(); // WebKit/chromium needs 'webkit' prefix (since Chrome 21)

// import the dropped files/folders into temporary filesystem
entry.copyTo(temporaryFs.root, entry.name, successCallback, errorCallback);
});

=== Example Code (Input) ===

<input type="file" multiple />

var input = document.querySelector("input[type='file']");

input.addEventListener('change', function (e) {
e.stopPropagation();
e.preventDefault();

var entries = e.target.webkitEntries; // WebKit/chromium needs 'webkit' prefix (since Chrome 22)

for (var i = 0; i < entries.length; ++i) {
if (entries[i].isDirectory) {
traverseDirectoryTree(entry);
} else {
showFileEntry(entries[i]);
}
});

[[Category:Proposals]]

DragAndDropEntries

2012-06-20T12:52:20Z

Kinuko: /* Example Code (Drag and Drop) */

Proposing exposing dropped files/folders as {File,Directory}Entry defined in FileSystem API [1] for better folders/files drag-and-drop support (this proposal was originally proposed on whatwg mailing list).

[1] File API: Directories and System http://www.w3.org/TR/file-system-api/
[2] Original proposal email: http://lists.whatwg.org/pipermail/whatwg-whatwg.org/2011-November/033814.html

== Background ==

Many sites have 'upload your files' feature, like for your photo images. HTML5 allows you to do this via <input type="file" multiple> or drag-and-drop feature, but the current solution does not provide clean solution for cases with folders, files/folder mixed cases, or folders with subfolders cases.

== Proposing API ==

Add a new field 'entries' to <input type=files> element [1] and a new accessor method 'getAsEntry()' to DataTransferItem object [2]. Populate the field with or return an 'Entry' object defined in FileSystem API upon file selection or drop events.

[1] http://www.whatwg.org/specs/web-apps/current-work/multipage/states-of-the-type-attribute.html#file-upload-state-(type=file)
[2] http://www.whatwg.org/specs/web-apps/current-work/multipage/dnd.html#the-datatransferitem-interface

Since FileSystem API naturally supports tree-structured folder hierarchy, Entry object exposes handy fields like 'isFile' and 'isDirectory', and allows webapps to recursively walk over the nested entries in subfolders via ReadDirectory() method.

This approach allows webapps to directly interact with the local folder structure, and also allows them to control the enumerating part so that the apps can show nice progress meter if they want.

=== HTMLInputElement.entries ===

interface HTMLInputElement : HTMLElement {
// allows scripts to access the element's selected files as an array of Entry defined in FileSystem API.
// On getting, if the IDL attribute applies, it must return a Entry array that represents the current selected files and/or folders.
// If the IDL attribute does not apply, then it must instead return null.
// Unless the multiple attribute is set, there must be no more than one file in the list of selected files.
readonly attribute Entry[] entries;
}

=== DataTransferItem.getAsEntry() ===

interface DataTransferItem {
// Like DataTransferItem.getAsFile(), getAsEntry() method runs following steps:
// 1. If the DataTransferItem object is not in the read/write mode or the read-only mode, return null and abort these steps.
// 2. If the drag data item kind is not File, then return null and abort these steps.
// 3. Return a new Entry object representing the actual file or directory represented by the DataTransferItem object.
Entry getAsEntry();
};

== Isolated FileSystem ==

The Entry exposed by this feature is created in an '''Isolated''' filesystem, which is read-only, isolated and transient. The filesystem only contains the dropped items and can only be accessed by the site where the drag-and-drop event has happened. Webapps cannot access any other files or folders outside the filesystem.

=== Restrictions ===

* The Entry in isolated filesystem '''does not support toURL()''' or is not resolvable by resolveFileSystemURL(), since its filesystem is transient and has limited life time (while toURL URL's do not work as live references like Blob URLs). The dropped entries are only accessible while the app has live instance for the entries.
* The Entry's '''fullPath does not (and should not) expose the file's full platform path''' as it could contain a sensitive information. Instead it MAY contain a relative path to the top directory that the user dropped.

== Example ==

Assume a user has following files and folders in his/her 'Photos' folder:

/Users/username/Photos/trip/1.jpg
/Users/username/Photos/trip/2.jpg
/Users/username/Photos/trip/3.jpg
/Users/username/Photos/halloween/2011/a.jpg
/Users/username/Photos/halloween/2011/b.jpg
/Users/username/Photos/halloween/2012/plan.jpg
/Users/username/Photos/tokyo/1.jpg
/Users/username/Photos/tokyo/2.jpg

When the user drag-and-drops or selects the two folders, '''trip''', '''halloween''' and one photo file '''tokyo/1.jpg''', the webapp will get following entries via 'entries' field of the input element or via DataTransferItem.getAsEntry():

DirectoryEntry for 'trip',
DirectoryEntry for 'halloween'
FileEntry for '1.jpg'

Via the new 'entries' field the app can access children files or subfolders in the selected entries, and can properly organize and process pictures using the local folder structure. Even if the dropped directory is on a slow removable media, or it contains tons of subdirectories and files, the app can recursively traverse each of them while showing a nice progress information, or can show an interactive file tree which lets the user freely expand or select some of the contents.

We can think of similar interesting usage scenarios like local-cloud sync app or bulk 'importer', e.g. importing local source directory to cloud IDE etc.

=== Example Code (Drag and Drop) ===

var droptarget = document.getElementById('droptarget');

droptarget.addEventListener('dop', function (e) {
e.stopPropagation();
e.preventDefault();

var items = e.dataTransfer.items;
for (var i = 0; i < items.length; ++i) {
if (items[i].kind != "file")
continue;

var entry = items[i].webkitGetAsEntry(); // WebKit/chromium needs 'webkit' prefix (since Chrome 21)

// import the dropped files/folders into temporary filesystem
entry.copyTo(temporaryFs.root, entry.name, successCallback, errorCallback);
});

=== Example Code (Input) ===

<input type="file" multiple />

var input = document.querySelector("input[type='file']");
input.addEventListener('change', function (e) {
e.stopPropagation();
e.preventDefault();
var entries = e.target.webkitEntries; // WebKit/chromium needs 'webkit' prefix (since Chrome 22)
for (var i = 0; i < entries.length; ++i) {
if (entries[i].isDirectory) {
traverseDirectoryTree(entry);
} else {
showFileEntry(entries[i]);
}
});

[[Category:Proposals]]

DragAndDropEntries

2012-06-20T12:51:47Z

Kinuko: /* Example Code (Drag and Drop) */

Proposing exposing dropped files/folders as {File,Directory}Entry defined in FileSystem API [1] for better folders/files drag-and-drop support (this proposal was originally proposed on whatwg mailing list).

[1] File API: Directories and System http://www.w3.org/TR/file-system-api/
[2] Original proposal email: http://lists.whatwg.org/pipermail/whatwg-whatwg.org/2011-November/033814.html

== Background ==

Many sites have 'upload your files' feature, like for your photo images. HTML5 allows you to do this via <input type="file" multiple> or drag-and-drop feature, but the current solution does not provide clean solution for cases with folders, files/folder mixed cases, or folders with subfolders cases.

== Proposing API ==

Add a new field 'entries' to <input type=files> element [1] and a new accessor method 'getAsEntry()' to DataTransferItem object [2]. Populate the field with or return an 'Entry' object defined in FileSystem API upon file selection or drop events.

[1] http://www.whatwg.org/specs/web-apps/current-work/multipage/states-of-the-type-attribute.html#file-upload-state-(type=file)
[2] http://www.whatwg.org/specs/web-apps/current-work/multipage/dnd.html#the-datatransferitem-interface

Since FileSystem API naturally supports tree-structured folder hierarchy, Entry object exposes handy fields like 'isFile' and 'isDirectory', and allows webapps to recursively walk over the nested entries in subfolders via ReadDirectory() method.

This approach allows webapps to directly interact with the local folder structure, and also allows them to control the enumerating part so that the apps can show nice progress meter if they want.

=== HTMLInputElement.entries ===

interface HTMLInputElement : HTMLElement {
// allows scripts to access the element's selected files as an array of Entry defined in FileSystem API.
// On getting, if the IDL attribute applies, it must return a Entry array that represents the current selected files and/or folders.
// If the IDL attribute does not apply, then it must instead return null.
// Unless the multiple attribute is set, there must be no more than one file in the list of selected files.
readonly attribute Entry[] entries;
}

=== DataTransferItem.getAsEntry() ===

interface DataTransferItem {
// Like DataTransferItem.getAsFile(), getAsEntry() method runs following steps:
// 1. If the DataTransferItem object is not in the read/write mode or the read-only mode, return null and abort these steps.
// 2. If the drag data item kind is not File, then return null and abort these steps.
// 3. Return a new Entry object representing the actual file or directory represented by the DataTransferItem object.
Entry getAsEntry();
};

== Isolated FileSystem ==

The Entry exposed by this feature is created in an '''Isolated''' filesystem, which is read-only, isolated and transient. The filesystem only contains the dropped items and can only be accessed by the site where the drag-and-drop event has happened. Webapps cannot access any other files or folders outside the filesystem.

=== Restrictions ===

* The Entry in isolated filesystem '''does not support toURL()''' or is not resolvable by resolveFileSystemURL(), since its filesystem is transient and has limited life time (while toURL URL's do not work as live references like Blob URLs). The dropped entries are only accessible while the app has live instance for the entries.
* The Entry's '''fullPath does not (and should not) expose the file's full platform path''' as it could contain a sensitive information. Instead it MAY contain a relative path to the top directory that the user dropped.

== Example ==

Assume a user has following files and folders in his/her 'Photos' folder:

/Users/username/Photos/trip/1.jpg
/Users/username/Photos/trip/2.jpg
/Users/username/Photos/trip/3.jpg
/Users/username/Photos/halloween/2011/a.jpg
/Users/username/Photos/halloween/2011/b.jpg
/Users/username/Photos/halloween/2012/plan.jpg
/Users/username/Photos/tokyo/1.jpg
/Users/username/Photos/tokyo/2.jpg

When the user drag-and-drops or selects the two folders, '''trip''', '''halloween''' and one photo file '''tokyo/1.jpg''', the webapp will get following entries via 'entries' field of the input element or via DataTransferItem.getAsEntry():

DirectoryEntry for 'trip',
DirectoryEntry for 'halloween'
FileEntry for '1.jpg'

Via the new 'entries' field the app can access children files or subfolders in the selected entries, and can properly organize and process pictures using the local folder structure. Even if the dropped directory is on a slow removable media, or it contains tons of subdirectories and files, the app can recursively traverse each of them while showing a nice progress information, or can show an interactive file tree which lets the user freely expand or select some of the contents.

We can think of similar interesting usage scenarios like local-cloud sync app or bulk 'importer', e.g. importing local source directory to cloud IDE etc.

=== Example Code (Drag and Drop) ===

var droptarget = document.getElementById('droptarget');

droptarget.addEventListener('dop', function (e) {
e.stopPropagation();
e.preventDefault();

var items = e.dataTransfer.items;
for (var i = 0; i < items.length; ++i) {
if (items[i].kind != "file")
continue;

var entry = items[i].webkitGetAsEntry(); // WebKit/chromium needs 'webkit' prefix (since Chrome 21)
entry.copyTo(temporaryFs.root, entry.name, successCallback, errorCallback); // import the dropped files/folders into temporary filesystem
});

=== Example Code (Input) ===

<input type="file" multiple />

var input = document.querySelector("input[type='file']");
input.addEventListener('change', function (e) {
e.stopPropagation();
e.preventDefault();
var entries = e.target.webkitEntries; // WebKit/chromium needs 'webkit' prefix (since Chrome 22)
for (var i = 0; i < entries.length; ++i) {
if (entries[i].isDirectory) {
traverseDirectoryTree(entry);
} else {
showFileEntry(entries[i]);
}
});

[[Category:Proposals]]

DragAndDropEntries

2012-06-20T12:17:41Z

Kinuko:

Proposing exposing dropped files/folders as {File,Directory}Entry defined in FileSystem API [1] for better folders/files drag-and-drop support (this proposal was originally proposed on whatwg mailing list).

[1] File API: Directories and System http://www.w3.org/TR/file-system-api/
[2] Original proposal email: http://lists.whatwg.org/pipermail/whatwg-whatwg.org/2011-November/033814.html

== Background ==

Many sites have 'upload your files' feature, like for your photo images. HTML5 allows you to do this via <input type="file" multiple> or drag-and-drop feature, but the current solution does not provide clean solution for cases with folders, files/folder mixed cases, or folders with subfolders cases.

== Proposing API ==

Add a new field 'entries' to <input type=files> element [1] and a new accessor method 'getAsEntry()' to DataTransferItem object [2]. Populate the field with or return an 'Entry' object defined in FileSystem API upon file selection or drop events.

[1] http://www.whatwg.org/specs/web-apps/current-work/multipage/states-of-the-type-attribute.html#file-upload-state-(type=file)
[2] http://www.whatwg.org/specs/web-apps/current-work/multipage/dnd.html#the-datatransferitem-interface

Since FileSystem API naturally supports tree-structured folder hierarchy, Entry object exposes handy fields like 'isFile' and 'isDirectory', and allows webapps to recursively walk over the nested entries in subfolders via ReadDirectory() method.

This approach allows webapps to directly interact with the local folder structure, and also allows them to control the enumerating part so that the apps can show nice progress meter if they want.

=== HTMLInputElement.entries ===

interface HTMLInputElement : HTMLElement {
// allows scripts to access the element's selected files as an array of Entry defined in FileSystem API.
// On getting, if the IDL attribute applies, it must return a Entry array that represents the current selected files and/or folders.
// If the IDL attribute does not apply, then it must instead return null.
// Unless the multiple attribute is set, there must be no more than one file in the list of selected files.
readonly attribute Entry[] entries;
}

=== DataTransferItem.getAsEntry() ===

interface DataTransferItem {
// Like DataTransferItem.getAsFile(), getAsEntry() method runs following steps:
// 1. If the DataTransferItem object is not in the read/write mode or the read-only mode, return null and abort these steps.
// 2. If the drag data item kind is not File, then return null and abort these steps.
// 3. Return a new Entry object representing the actual file or directory represented by the DataTransferItem object.
Entry getAsEntry();
};

== Isolated FileSystem ==

The Entry exposed by this feature is created in an '''Isolated''' filesystem, which is read-only, isolated and transient. The filesystem only contains the dropped items and can only be accessed by the site where the drag-and-drop event has happened. Webapps cannot access any other files or folders outside the filesystem.

=== Restrictions ===

* The Entry in isolated filesystem '''does not support toURL()''' or is not resolvable by resolveFileSystemURL(), since its filesystem is transient and has limited life time (while toURL URL's do not work as live references like Blob URLs). The dropped entries are only accessible while the app has live instance for the entries.
* The Entry's '''fullPath does not (and should not) expose the file's full platform path''' as it could contain a sensitive information. Instead it MAY contain a relative path to the top directory that the user dropped.

== Example ==

Assume a user has following files and folders in his/her 'Photos' folder:

/Users/username/Photos/trip/1.jpg
/Users/username/Photos/trip/2.jpg
/Users/username/Photos/trip/3.jpg
/Users/username/Photos/halloween/2011/a.jpg
/Users/username/Photos/halloween/2011/b.jpg
/Users/username/Photos/halloween/2012/plan.jpg
/Users/username/Photos/tokyo/1.jpg
/Users/username/Photos/tokyo/2.jpg

When the user drag-and-drops or selects the two folders, '''trip''', '''halloween''' and one photo file '''tokyo/1.jpg''', the webapp will get following entries via 'entries' field of the input element or via DataTransferItem.getAsEntry():

DirectoryEntry for 'trip',
DirectoryEntry for 'halloween'
FileEntry for '1.jpg'

Via the new 'entries' field the app can access children files or subfolders in the selected entries, and can properly organize and process pictures using the local folder structure. Even if the dropped directory is on a slow removable media, or it contains tons of subdirectories and files, the app can recursively traverse each of them while showing a nice progress information, or can show an interactive file tree which lets the user freely expand or select some of the contents.

We can think of similar interesting usage scenarios like local-cloud sync app or bulk 'importer', e.g. importing local source directory to cloud IDE etc.

=== Example Code (Drag and Drop) ===

var droptarget = document.getElementById('droptarget');
droptarget.addEventListener('dop', function (e) {
e.stopPropagation();
e.preventDefault();
var items = e.dataTransfer.items;
for (var i = 0; i < items.length; ++i) {
if (items[i].kind != "file")
continue;
var entry = items[i].webkitGetAsEntry(); // WebKit/chromium needs 'webkit' prefix (since Chrome 21)
if (entry.isDirectory) {
traverseDirectoryTree(entry);
} else {
showFileEntry(entry);
}
});

=== Example Code (Input) ===

<input type="file" multiple />

var input = document.querySelector("input[type='file']");
input.addEventListener('change', function (e) {
e.stopPropagation();
e.preventDefault();
var entries = e.target.webkitEntries; // WebKit/chromium needs 'webkit' prefix (since Chrome 22)
for (var i = 0; i < entries.length; ++i) {
if (entries[i].isDirectory) {
traverseDirectoryTree(entry);
} else {
showFileEntry(entries[i]);
}
});

[[Category:Proposals]]

DragAndDropEntries

2012-06-20T12:06:17Z

Kinuko: /* Proposing API */

DragAndDropEntries

2012-06-20T12:05:11Z

Kinuko: /* Restrictions */

DragAndDropEntries

2012-06-18T14:48:20Z

Kinuko: /* Restrictions */

DragAndDropEntries

2012-06-18T04:18:41Z

Kinuko:

DragAndDropEntries

2012-06-15T18:48:08Z

Kinuko:

DragAndDropEntries

2012-06-15T18:46:53Z

Kinuko: /* Proposal */

Proposing exposing dropped files/folders as {File,Directory}Entry defined in FileSystem API [1] for better folders/files drag-and-drop support.

[1] File API: Directories and System http://www.w3.org/TR/file-system-api/

== Background ==

Many sites have 'upload your files' feature, like for your photo images. HTML5 allows you to do this via <input type="file" multiple> or drag-and-drop feature, but the current solution does not provide clean solution for cases with folders, files/folder mixed cases, or folders with subfolders cases.

== Proposing API ==

Add a new field 'entries' to <input type=files> element [1] and a new accessor method 'getAsEntry()' to DataTransferItem object [2]. Populate the field with or return an 'Entry' object defined in FileSystem API upon file selection or drop events.

interface HTMLInputElement : HTMLElement {
// allows scripts to access the element's selected files as an array of Entry defined in FileSystem API.
// On getting, if the IDL attribute applies, it must return a Entry array that represents the current selected files and/or folders.
// If the IDL attribute does not apply, then it must instead return null.
// Unless the multiple attribute is set, there must be no more than one file in the list of selected files.
readonly attribute Entry[] entries;
}

interface DataTransferItem {
// Like DataTransferItem.getAsFile(), getAsEntry() method runs following steps:
// 1. If the DataTransferItem object is not in the read/write mode or the read-only mode, return null and abort these steps.
// 2. If the drag data item kind is not File, then return null and abort these steps.
// 3. Return a new Entry object representing the actual file or directory represented by the DataTransferItem object.
Entry getAsEntry();
};

[1] http://www.whatwg.org/specs/web-apps/current-work/multipage/states-of-the-type-attribute.html#file-upload-state-(type=file)
[2] http://www.whatwg.org/specs/web-apps/current-work/multipage/dnd.html#the-datatransferitem-interface

Since FileSystem API naturally supports tree-structured folder hierarchy, Entry object exposes handy fields like 'isFile' and 'isDirectory', and allows webapps to recursively walk over the nested entries in subfolders via ReadDirectory() method.

This approach allows webapps to directly interact with the local folder structure, and also allows them to control the enumerating part so that the apps can show nice progress meter if they want.

== Isolated FileSystem ==

The Entry exposed by this feature is created in an '''Isolated''' filesystem, which is read-only, isolated and transient. The filesystem only contains the dropped items and can only be accessed by the site where the drag-and-drop event has happened. Webapps cannot access any other files or folders outside the filesystem.

The Entry does not support toURL() or is not resolvable by resolveFileSystemURL(), since its filesystem is transient and has limited life time (while toURL URL's do not work as live references like Blob URLs).

== Example ==

Assume a user has following files and folders in his/her 'Photos' folder:

/Users/username/Photos/trip/1.jpg
/Users/username/Photos/trip/2.jpg
/Users/username/Photos/trip/3.jpg
/Users/username/Photos/halloween/2011/a.jpg
/Users/username/Photos/halloween/2011/b.jpg
/Users/username/Photos/halloween/2012/plan.jpg
/Users/username/Photos/tokyo/1.jpg
/Users/username/Photos/tokyo/2.jpg

When the user drag-and-drops or selects the two folders, '''trip''', '''halloween''' and one photo file '''tokyo/1.jpg''', the webapp will get following entries via 'entries' field of the input element or via DataTransferItem.getAsEntry():

DirectoryEntry for 'trip',
DirectoryEntry for 'halloween'
FileEntry for '1.jpg'

Via the new 'entries' field the app can access children files or subfolders in the selected entries, and can properly organize and process pictures using the local folder structure. Even if the dropped directory is on a slow removable media, or it contains tons of subdirectories and files, the app can recursively traverse each of them while showing a nice progress information, or can show an interactive file tree which lets the user freely expand or select some of the contents.

We can think of similar interesting usage scenarios like local-cloud sync app or bulk 'importer', e.g. importing local source directory to cloud IDE etc.

=== Example Code (Drag and Drop) ===

var droptarget = document.getElementById('droptarget');
droptarget.addEventListener('dop', function (e) {
e.stopPropagation();
e.preventDefault();
var items = e.dataTransfer.items;
for (var i = 0; i < items.length; ++i) {
if (items[i].kind != "file")
continue;
var entry = items[i].getAsEntry();
if (entry.isDirectory) {
traverseDirectoryTree(entry);
} else {
showFileEntry(entry);
}
});

=== Example Code (Input) ===

<input type="file" multiple />

var input = document.querySelector("input[type='file']");
input.addEventListener('change', function (e) {
e.stopPropagation();
e.preventDefault();
var entries = e.target.entries;
for (var i = 0; i < entries.length; ++i) {
if (entries[i].isDirectory) {
traverseDirectoryTree(entry);
} else {
showFileEntry(entries[i]);
}
});

[[Category:Proposals]]

DragAndDropEntries

2012-06-15T18:46:08Z

Kinuko: /* Example Code (Drag and Drop) */

Proposing exposing dropped files/folders as {File,Directory}Entry defined in FileSystem API [1] for better folders/files drag-and-drop support.

[1] File API: Directories and System http://www.w3.org/TR/file-system-api/

== Background ==

Many sites have 'upload your files' feature, like for your photo images. HTML5 allows you to do this via <input type="file" multiple> or drag-and-drop feature, but the current solution does not provide clean solution for cases with folders, files/folder mixed cases, or folders with subfolders cases.

== Proposal ==

Add a new field 'entries' to <input type=files> element [1] and a new accessor method 'getAsEntry()' to DataTransferItem object [2]. Populate the field with or return an 'Entry' object defined in FileSystem API upon file selection or drop events.

interface HTMLInputElement : HTMLElement {
// allows scripts to access the element's selected files as an array of Entry defined in FileSystem API.
// On getting, if the IDL attribute applies, it must return a Entry array that represents the current selected files and/or folders.
// If the IDL attribute does not apply, then it must instead return null.
// Unless the multiple attribute is set, there must be no more than one file in the list of selected files.
readonly attribute Entry[] entries;
}

interface DataTransferItem {
// Like DataTransferItem.getAsFile(), getAsEntry() method runs following steps:
// 1. If the DataTransferItem object is not in the read/write mode or the read-only mode, return null and abort these steps.
// 2. If the drag data item kind is not File, then return null and abort these steps.
// 3. Return a new Entry object representing the actual file or directory represented by the DataTransferItem object.
Entry getAsEntry();
};

[1] http://www.whatwg.org/specs/web-apps/current-work/multipage/states-of-the-type-attribute.html#file-upload-state-(type=file)
[2] http://www.whatwg.org/specs/web-apps/current-work/multipage/dnd.html#the-datatransferitem-interface

Since FileSystem API naturally supports tree-structured folder hierarchy, Entry object exposes handy fields like 'isFile' and 'isDirectory', and allows webapps to recursively walk over the nested entries in subfolders via ReadDirectory() method.

This approach allows webapps to directly interact with the local folder structure, and also allows them to control the enumerating part so that the apps can show nice progress meter if they want.

=== Isolated FileSystem ===

The Entry exposed by this feature is created in an '''Isolated''' filesystem, which is read-only, isolated and transient. The filesystem only contains the dropped items and can only be accessed by the site where the drag-and-drop event has happened. Webapps cannot access any other files or folders outside the filesystem.

The Entry does not support toURL() or is not resolvable by resolveFileSystemURL(), since its filesystem is transient and has limited life time (while toURL URL's do not work as live references like Blob URLs).

=== Usage Scenario ===

Assume a user has following files and folders in his/her 'Photos' folder:

/Users/username/Photos/trip/1.jpg
/Users/username/Photos/trip/2.jpg
/Users/username/Photos/trip/3.jpg
/Users/username/Photos/halloween/2011/a.jpg
/Users/username/Photos/halloween/2011/b.jpg
/Users/username/Photos/halloween/2012/plan.jpg
/Users/username/Photos/tokyo/1.jpg
/Users/username/Photos/tokyo/2.jpg

When the user drag-and-drops or selects the two folders, '''trip''', '''halloween''' and one photo file '''tokyo/1.jpg''', the webapp will get following entries via 'entries' field of the input element or via DataTransferItem.getAsEntry():

DirectoryEntry for 'trip',
DirectoryEntry for 'halloween'
FileEntry for '1.jpg'

Via the new 'entries' field the app can access children files or subfolders in the selected entries, and can properly organize and process pictures using the local folder structure. Even if the dropped directory is on a slow removable media, or it contains tons of subdirectories and files, the app can recursively traverse each of them while showing a nice progress information, or can show an interactive file tree which lets the user freely expand or select some of the contents.

We can think of similar interesting usage scenarios like local-cloud sync app or bulk 'importer', e.g. importing local source directory to cloud IDE etc.

=== Example Code (Drag and Drop) ===

var droptarget = document.getElementById('droptarget');
droptarget.addEventListener('dop', function (e) {
e.stopPropagation();
e.preventDefault();
var items = e.dataTransfer.items;
for (var i = 0; i < items.length; ++i) {
if (items[i].kind != "file")
continue;
var entry = items[i].getAsEntry();
if (entry.isDirectory) {
traverseDirectoryTree(entry);
} else {
showFileEntry(entry);
}
});

=== Example Code (Input) ===

<input type="file" multiple />

var input = document.querySelector("input[type='file']");
input.addEventListener('change', function (e) {
e.stopPropagation();
e.preventDefault();
var entries = e.target.entries;
for (var i = 0; i < entries.length; ++i) {
if (entries[i].isDirectory) {
traverseDirectoryTree(entry);
} else {
showFileEntry(entries[i]);
}
});

[[Category:Proposals]]

DragAndDropEntries

2012-06-15T18:45:55Z

Kinuko: /* Example Code (Input) */

Proposing exposing dropped files/folders as {File,Directory}Entry defined in FileSystem API [1] for better folders/files drag-and-drop support.

[1] File API: Directories and System http://www.w3.org/TR/file-system-api/

== Background ==

Many sites have 'upload your files' feature, like for your photo images. HTML5 allows you to do this via <input type="file" multiple> or drag-and-drop feature, but the current solution does not provide clean solution for cases with folders, files/folder mixed cases, or folders with subfolders cases.

== Proposal ==

Add a new field 'entries' to <input type=files> element [1] and a new accessor method 'getAsEntry()' to DataTransferItem object [2]. Populate the field with or return an 'Entry' object defined in FileSystem API upon file selection or drop events.

interface HTMLInputElement : HTMLElement {
// allows scripts to access the element's selected files as an array of Entry defined in FileSystem API.
// On getting, if the IDL attribute applies, it must return a Entry array that represents the current selected files and/or folders.
// If the IDL attribute does not apply, then it must instead return null.
// Unless the multiple attribute is set, there must be no more than one file in the list of selected files.
readonly attribute Entry[] entries;
}

interface DataTransferItem {
// Like DataTransferItem.getAsFile(), getAsEntry() method runs following steps:
// 1. If the DataTransferItem object is not in the read/write mode or the read-only mode, return null and abort these steps.
// 2. If the drag data item kind is not File, then return null and abort these steps.
// 3. Return a new Entry object representing the actual file or directory represented by the DataTransferItem object.
Entry getAsEntry();
};

[1] http://www.whatwg.org/specs/web-apps/current-work/multipage/states-of-the-type-attribute.html#file-upload-state-(type=file)
[2] http://www.whatwg.org/specs/web-apps/current-work/multipage/dnd.html#the-datatransferitem-interface

Since FileSystem API naturally supports tree-structured folder hierarchy, Entry object exposes handy fields like 'isFile' and 'isDirectory', and allows webapps to recursively walk over the nested entries in subfolders via ReadDirectory() method.

This approach allows webapps to directly interact with the local folder structure, and also allows them to control the enumerating part so that the apps can show nice progress meter if they want.

=== Isolated FileSystem ===

The Entry exposed by this feature is created in an '''Isolated''' filesystem, which is read-only, isolated and transient. The filesystem only contains the dropped items and can only be accessed by the site where the drag-and-drop event has happened. Webapps cannot access any other files or folders outside the filesystem.

The Entry does not support toURL() or is not resolvable by resolveFileSystemURL(), since its filesystem is transient and has limited life time (while toURL URL's do not work as live references like Blob URLs).

=== Usage Scenario ===

Assume a user has following files and folders in his/her 'Photos' folder:

/Users/username/Photos/trip/1.jpg
/Users/username/Photos/trip/2.jpg
/Users/username/Photos/trip/3.jpg
/Users/username/Photos/halloween/2011/a.jpg
/Users/username/Photos/halloween/2011/b.jpg
/Users/username/Photos/halloween/2012/plan.jpg
/Users/username/Photos/tokyo/1.jpg
/Users/username/Photos/tokyo/2.jpg

When the user drag-and-drops or selects the two folders, '''trip''', '''halloween''' and one photo file '''tokyo/1.jpg''', the webapp will get following entries via 'entries' field of the input element or via DataTransferItem.getAsEntry():

DirectoryEntry for 'trip',
DirectoryEntry for 'halloween'
FileEntry for '1.jpg'

Via the new 'entries' field the app can access children files or subfolders in the selected entries, and can properly organize and process pictures using the local folder structure. Even if the dropped directory is on a slow removable media, or it contains tons of subdirectories and files, the app can recursively traverse each of them while showing a nice progress information, or can show an interactive file tree which lets the user freely expand or select some of the contents.

We can think of similar interesting usage scenarios like local-cloud sync app or bulk 'importer', e.g. importing local source directory to cloud IDE etc.

=== Example Code (Drag and Drop) ===

var droptarget = document.getElementById('droptarget');

droptarget.addEventListener('dop', function (e) {
e.stopPropagation();
e.preventDefault();
var items = e.dataTransfer.items;
for (var i = 0; i < items.length; ++i) {
if (items[i].kind != "file")
continue;
var entry = items[i].getAsEntry();
if (entry.isDirectory) {
traverseDirectoryTree(entry);
} else {
showFileEntry(entry);
}
});

=== Example Code (Input) ===

<input type="file" multiple />

var input = document.querySelector("input[type='file']");
input.addEventListener('change', function (e) {
e.stopPropagation();
e.preventDefault();
var entries = e.target.entries;
for (var i = 0; i < entries.length; ++i) {
if (entries[i].isDirectory) {
traverseDirectoryTree(entry);
} else {
showFileEntry(entries[i]);
}
});

[[Category:Proposals]]

DragAndDropEntries

2012-06-15T18:45:30Z

Kinuko: /* Proposal */

Proposing exposing dropped files/folders as {File,Directory}Entry defined in FileSystem API [1] for better folders/files drag-and-drop support.

[1] File API: Directories and System http://www.w3.org/TR/file-system-api/

== Background ==

Many sites have 'upload your files' feature, like for your photo images. HTML5 allows you to do this via <input type="file" multiple> or drag-and-drop feature, but the current solution does not provide clean solution for cases with folders, files/folder mixed cases, or folders with subfolders cases.

== Proposal ==

Add a new field 'entries' to <input type=files> element [1] and a new accessor method 'getAsEntry()' to DataTransferItem object [2]. Populate the field with or return an 'Entry' object defined in FileSystem API upon file selection or drop events.

interface HTMLInputElement : HTMLElement {
// allows scripts to access the element's selected files as an array of Entry defined in FileSystem API.
// On getting, if the IDL attribute applies, it must return a Entry array that represents the current selected files and/or folders.
// If the IDL attribute does not apply, then it must instead return null.
// Unless the multiple attribute is set, there must be no more than one file in the list of selected files.
readonly attribute Entry[] entries;
}

interface DataTransferItem {
// Like DataTransferItem.getAsFile(), getAsEntry() method runs following steps:
// 1. If the DataTransferItem object is not in the read/write mode or the read-only mode, return null and abort these steps.
// 2. If the drag data item kind is not File, then return null and abort these steps.
// 3. Return a new Entry object representing the actual file or directory represented by the DataTransferItem object.
Entry getAsEntry();
};

[1] http://www.whatwg.org/specs/web-apps/current-work/multipage/states-of-the-type-attribute.html#file-upload-state-(type=file)
[2] http://www.whatwg.org/specs/web-apps/current-work/multipage/dnd.html#the-datatransferitem-interface

Since FileSystem API naturally supports tree-structured folder hierarchy, Entry object exposes handy fields like 'isFile' and 'isDirectory', and allows webapps to recursively walk over the nested entries in subfolders via ReadDirectory() method.

This approach allows webapps to directly interact with the local folder structure, and also allows them to control the enumerating part so that the apps can show nice progress meter if they want.

=== Isolated FileSystem ===

The Entry exposed by this feature is created in an '''Isolated''' filesystem, which is read-only, isolated and transient. The filesystem only contains the dropped items and can only be accessed by the site where the drag-and-drop event has happened. Webapps cannot access any other files or folders outside the filesystem.

The Entry does not support toURL() or is not resolvable by resolveFileSystemURL(), since its filesystem is transient and has limited life time (while toURL URL's do not work as live references like Blob URLs).

=== Usage Scenario ===

Assume a user has following files and folders in his/her 'Photos' folder:

/Users/username/Photos/trip/1.jpg
/Users/username/Photos/trip/2.jpg
/Users/username/Photos/trip/3.jpg
/Users/username/Photos/halloween/2011/a.jpg
/Users/username/Photos/halloween/2011/b.jpg
/Users/username/Photos/halloween/2012/plan.jpg
/Users/username/Photos/tokyo/1.jpg
/Users/username/Photos/tokyo/2.jpg

When the user drag-and-drops or selects the two folders, '''trip''', '''halloween''' and one photo file '''tokyo/1.jpg''', the webapp will get following entries via 'entries' field of the input element or via DataTransferItem.getAsEntry():

DirectoryEntry for 'trip',
DirectoryEntry for 'halloween'
FileEntry for '1.jpg'

Via the new 'entries' field the app can access children files or subfolders in the selected entries, and can properly organize and process pictures using the local folder structure. Even if the dropped directory is on a slow removable media, or it contains tons of subdirectories and files, the app can recursively traverse each of them while showing a nice progress information, or can show an interactive file tree which lets the user freely expand or select some of the contents.

We can think of similar interesting usage scenarios like local-cloud sync app or bulk 'importer', e.g. importing local source directory to cloud IDE etc.

=== Example Code (Drag and Drop) ===

var droptarget = document.getElementById('droptarget');

droptarget.addEventListener('dop', function (e) {
e.stopPropagation();
e.preventDefault();
var items = e.dataTransfer.items;
for (var i = 0; i < items.length; ++i) {
if (items[i].kind != "file")
continue;
var entry = items[i].getAsEntry();
if (entry.isDirectory) {
traverseDirectoryTree(entry);
} else {
showFileEntry(entry);
}
});

=== Example Code (Input) ===

<input type="file" multiple />

var input = document.querySelector("input[type='file']");
input.addEventListener('change', function (e) {
e.stopPropagation();
e.preventDefault();
var entries = e.target.entries;
for (var i = 0; i < entries.length; ++i) {
if (entries[i].isDirectory) {
traverseDirectoryTree(entry);
} else {
showFileEntry(entries[i]);
}
});

[[Category:Proposals]]

DragAndDropEntries

2012-06-15T18:36:48Z

Kinuko: Created page with 'Proposing exposing dropped files/folders as {File,Directory}Entry defined in FileSystem API [1] for better folders/files drag-and-drop support. [1] File API: Directories and Sys...'

Proposing exposing dropped files/folders as {File,Directory}Entry defined in FileSystem API [1] for better folders/files drag-and-drop support.

[1] File API: Directories and System http://www.w3.org/TR/file-system-api/

== Background ==

Many sites have 'upload your files' feature, like for your photo images. HTML5 allows you to do this via <input type="file" multiple> or drag-and-drop feature, but the current solution does not provide clean solution for cases with folders, files/folder mixed cases, or folders with subfolders cases.

== Proposal ==

Add a new field 'entries' to <input type=files> element and a new accessor method 'getAsEntry()' to DataTransferItem object, and populate the field with or return a file or directory 'Entry' defined in FileSystem API [1] upon file selection or drop events.

Since FileSystem API naturally supports tree-structured folder hierarchy, Entry object exposes handy fields like 'isFile' and 'isDirectory', and allows webapps to recursively walk over the nested entries in subfolders via ReadDirectory() method.

This approach allows webapps to directly interact with the local folder structure, and also allows them to control the enumerating part so that the apps can show nice progress meter if they want.

interface HTMLInputElement : HTMLElement {
// allows scripts to access the element's selected files as an array of Entry defined in FileSystem API.
// On getting, if the IDL attribute applies, it must return a Entry array that represents the current selected files and/or folders.
// If the IDL attribute does not apply, then it must instead return null.
// Unless the multiple attribute is set, there must be no more than one file in the list of selected files.
readonly attribute Entry[] entries;
}

http://www.whatwg.org/specs/web-apps/current-work/multipage/states-of-the-type-attribute.html#file-upload-state-(type=file)

interface DataTransferItem {
// Like DataTransferItem.getAsFile(), getAsEntry() method runs following steps:
// 1. If the DataTransferItem object is not in the read/write mode or the read-only mode, return null and abort these steps.
// 2. If the drag data item kind is not File, then return null and abort these steps.
// 3. Return a new Entry object representing the actual file or directory represented by the DataTransferItem object.
Entry getAsEntry();
};

http://www.whatwg.org/specs/web-apps/current-work/multipage/dnd.html#the-datatransferitem-interface

=== Isolated FileSystem ===

The Entry exposed by this feature is created in an '''Isolated''' filesystem, which is read-only, isolated and transient. The filesystem only contains the dropped items and can only be accessed by the site where the drag-and-drop event has happened. Webapps cannot access any other files or folders outside the filesystem.

The Entry does not support toURL() or is not resolvable by resolveFileSystemURL(), since its filesystem is transient and has limited life time (while toURL URL's do not work as live references like Blob URLs).

=== Example ===

Assume a user has following files and folders in his/her 'Photos' folder:

/Users/username/Photos/trip/1.jpg
/Users/username/Photos/trip/2.jpg
/Users/username/Photos/trip/3.jpg
/Users/username/Photos/halloween/2011/a.jpg
/Users/username/Photos/halloween/2011/b.jpg
/Users/username/Photos/halloween/2012/plan.jpg
/Users/username/Photos/tokyo/1.jpg
/Users/username/Photos/tokyo/2.jpg

When the user drag-and-drops or selects the two folders, '''trip''', '''halloween''' and one photo file '''tokyo/1.jpg''', the webapp will get following entries via 'entries' field of the input element or via DataTransferItem.getAsEntry():

DirectoryEntry for 'trip',
DirectoryEntry for 'halloween'
FileEntry for '1.jpg'

Via the new 'entries' field the app can access children files or subfolders in the selected entries, and can properly organize and process pictures using the local folder structure. Even if the dropped directory is on a slow removable media, or it contains tons of subdirectories and files, the app can recursively traverse each of them while showing a nice progress information, or can show an interactive file tree which lets the user freely expand or select some of the contents.

We can think of similar interesting usage scenarios like local-cloud sync app or bulk 'importer', e.g. importing local source directory to cloud IDE etc.

=== Example Code ===

(coming soon)

[[Category:Proposals]]

Quota

2012-06-15T17:50:59Z

Kinuko:

Proposing Quota management API for offline storage APIs

Note: now the proposal draft is moved to: https://dvcs.w3.org/hg/quota/raw-file/tip/Overview.html

== Abstract ==

Today we have a lot of useful offline storage APIs (including proposing/obsolete ones), i.e. IndexedDB, FileSystem API, AppCache and SQL DB, but the storage allocation decision for the offline storage APIs has been a big unresolved pain among the UA.
This proposal is to establish a clear protocol between apps, the UA and the user so that the UA can make an appropriate decision about how much it should allocate the storage and about whether the UA could delete the offline data at its discretion or not.

The proposal is:

# introduce two different storage categories, '''temporary/evictable/transient''' and '''persistent/non-evictable'''.
#* The '''temporary''' storage can be viewed as '/tmp' space in the traditional filesystem, and can be used without explicit quota request but the data may get deleted at any time at the UA's discretion.
#* The '''persistent''' storage should never deleted by the UA without the user’s instruction, but should require up-front quota request to use, which may in turn require explicit user intervention.
# introduce a new app-facing API to request or query quota/usage. The API includes two primary methods, one is to '''request more (persistent) storage quota''' and the other is to '''query the current quota and used amount'''.

The requested or granted quota should work in a unified way across different storage APIs, so that apps do not need to take care of storage space for each API.

== API ==

Window implements QuotaStorageEnvironment;
[NoInterfaceObject]
interface QuotaStorageEnvironment {
readonly attribute StorageInfo storageInfo;
};

=== StorageInfo interface ===

interface StorageInfo {
const unsigned short TEMPORARY = 0;
const unsigned short PERSISTENT = 1;

// Queries the current quota and how much data is stored for the host.
void queryUsageAndQuota(
unsigned short storageType,
optional StorageInfoUsageCallback successCallback,
optional StorageInfoErrorCallback errorCallback);

// Requests a new quota. Requesting a larger quota may require user's
// explicit permission via UI prompting / infobar.
void requestQuota(
unsigned short storageType,
unsigned long long newQuotaInBytes,
optional StorageInfoQuotaCallback successCallback,
optional StorageInfoErrorCallback errorCallback);
};

[NoInterfaceObject, Callback=FunctionOnly]
interface StorageInfoUsageCallback {
void handleEvent(unsigned long long currentUsageInBytes,
unsigned long long currentQuotaInBytes);
};

[NoInterfaceObject, Callback=FunctionOnly]
interface StorageInfoQuotaCallback {
void handleEvent(unsigned long long grantedQuotaInBytes);
};

[NoInterfaceObject, Callback=FunctionOnly]
interface StorageInfoErrorCallback {
void handleEvent(DOMCoreException error);
};

Notes about TEMPORARY / PERSISTENT storageType const values: in general using string would be more preferable than enum, but for now we're proposing short const values to make it match with the type parameters of [http://www.w3.org/TR/file-system-api/ File API: Directories and System].

=== Example Code ===

The app can get the current quota and usage for the apps' origin by calling:

storageInfo.queryUsageAndQuota(
storageInfo.PERSISTENT, // or TEMPORARY
function (usage, quota) { log("Current usage/quota:" + usage + "/" + quota); },
function (error) { log("Querying quota got error: " + error); });

The app can also request more quota by calling:

storageInfo.requestQuota(
storageInfo.PERSISTENT,
requestingQuota,
function (quota) { log("Requested " + requestingQuota + " => got " + quota); },
function (error) { log("Requesting quota got error: " + error); });

[[Category:Proposals]]

Quota

2011-12-14T06:00:02Z

Kinuko: /* StorageInfo interface */

Proposing Quota management API for offline storage APIs

== Abstract ==

Today we have a lot of useful offline storage APIs (including proposing/obsolete ones), i.e. IndexedDB, FileSystem API, AppCache and SQL DB, but the storage allocation decision for the offline storage APIs has been a big unresolved pain among the UA.
This proposal is to establish a clear protocol between apps, the UA and the user so that the UA can make an appropriate decision about how much it should allocate the storage and about whether the UA could delete the offline data at its discretion or not.

The proposal is:

# introduce two different storage categories, '''temporary/evictable/transient''' and '''persistent/non-evictable'''.
#* The '''temporary''' storage can be viewed as '/tmp' space in the traditional filesystem, and can be used without explicit quota request but the data may get deleted at any time at the UA's discretion.
#* The '''persistent''' storage should never deleted by the UA without the user’s instruction, but should require up-front quota request to use, which may in turn require explicit user intervention.
# introduce a new app-facing API to request or query quota/usage. The API includes two primary methods, one is to '''request more (persistent) storage quota''' and the other is to '''query the current quota and used amount'''.

The requested or granted quota should work in a unified way across different storage APIs, so that apps do not need to take care of storage space for each API.

== API ==

Window implements QuotaStorageEnvironment;
[NoInterfaceObject]
interface QuotaStorageEnvironment {
readonly attribute StorageInfo storageInfo;
};

=== StorageInfo interface ===

interface StorageInfo {
const unsigned short TEMPORARY = 0;
const unsigned short PERSISTENT = 1;

// Queries the current quota and how much data is stored for the host.
void queryUsageAndQuota(
unsigned short storageType,
optional StorageInfoUsageCallback successCallback,
optional StorageInfoErrorCallback errorCallback);

// Requests a new quota. Requesting a larger quota may require user's
// explicit permission via UI prompting / infobar.
void requestQuota(
unsigned short storageType,
unsigned long long newQuotaInBytes,
optional StorageInfoQuotaCallback successCallback,
optional StorageInfoErrorCallback errorCallback);
};

[NoInterfaceObject, Callback=FunctionOnly]
interface StorageInfoUsageCallback {
void handleEvent(unsigned long long currentUsageInBytes,
unsigned long long currentQuotaInBytes);
};

[NoInterfaceObject, Callback=FunctionOnly]
interface StorageInfoQuotaCallback {
void handleEvent(unsigned long long grantedQuotaInBytes);
};

[NoInterfaceObject, Callback=FunctionOnly]
interface StorageInfoErrorCallback {
void handleEvent(DOMCoreException error);
};

Notes about TEMPORARY / PERSISTENT storageType const values: in general using string would be more preferable than enum, but for now we're proposing short const values to make it match with the type parameters of [http://www.w3.org/TR/file-system-api/ File API: Directories and System].

=== Example Code ===

The app can get the current quota and usage for the apps' origin by calling:

storageInfo.queryUsageAndQuota(
storageInfo.PERSISTENT, // or TEMPORARY
function (usage, quota) { log("Current usage/quota:" + usage + "/" + quota); },
function (error) { log("Querying quota got error: " + error); });

The app can also request more quota by calling:

storageInfo.requestQuota(
storageInfo.PERSISTENT,
requestingQuota,
function (quota) { log("Requested " + requestingQuota + " => got " + quota); },
function (error) { log("Requesting quota got error: " + error); });

[[Category:Proposals]]

Quota

2011-12-13T04:53:17Z

Kinuko:

Quota

2011-12-13T04:48:26Z

Kinuko: /* Example Code */

Proposing Quota management API for offline storage APIs

== Editors ==

* Kinuko Yasuda (Google, Inc)

== Abstract ==

Today we have a lot of useful offline storage APIs (including proposing/obsolete ones), i.e. IndexedDB, FileSystem API, AppCache and SQL DB, but the storage allocation decision for the offline storage APIs has been a big unresolved pain among the UA.
This proposal is to establish a clear protocol between apps, the UA and the user so that the UA can make an appropriate decision about how much it should allocate the storage and about whether the UA could delete the offline data at its discretion or not.

The proposal is:

# introduce two different storage categories, '''temporary/evictable/transient''' and '''persistent/non-evictable'''.
#* The '''temporary''' storage can be viewed as '/tmp' space in the traditional filesystem, and can be used without explicit quota request but the data may get deleted at any time at the UA's discretion.
#* The '''persistent''' storage should never deleted by the UA without the user’s instruction, but should require up-front quota request to use, which may in turn require explicit user intervention.
# introduce a new app-facing API to request or query quota/usage. The API includes two primary methods, one is to '''request more (persistent) storage quota''' and the other is to '''query the current quota and used amount'''.

The requested or granted quota should work in a unified way across different storage APIs, so that apps do not need to take care of storage space for each API.

== API ==

Window implements QuotaStorageEnvironment;
[NoInterfaceObject]
interface QuotaStorageEnvironment {
readonly attribute StorageInfo storageInfo;
};

=== StorageInfo interface ===

interface StorageInfo {
const unsigned short TEMPORARY = 0;
const unsigned short PERSISTENT = 1;

// Queries the current quota and how much data is stored for the host.
void queryUsageAndQuota(
unsigned short storageType,
optional StorageInfoUsageCallback successCallback,
optional StorageInfoErrorCallback errorCallback);

// Requests a new quota. Requesting a larger quota may require user's
// explicit permission via UI prompting / infobar.
void requestQuota(
unsigned short storageType,
unsigned long long newQuotaInBytes,
optional StorageInfoQuotaCallback successCallback,
optional StorageInfoErrorCallback errorCallback);
};

[NoInterfaceObject, Callback=FunctionOnly]
interface StorageInfoUsageCallback {
void handleEvent(unsigned long long currentUsageInBytes,
unsigned long long currentQuotaInBytes);
};

[NoInterfaceObject, Callback=FunctionOnly]
interface StorageInfoQuotaCallback {
void handleEvent(unsigned long long grantedQuotaInBytes);
};

[NoInterfaceObject, Callback=FunctionOnly]
interface StorageInfoErrorCallback {
void handleEvent(DOMCoreException error);
};

Notes about TEMPORARY / PERSISTENT storageType const values: in general using string would be more preferable than enum, but for now we're proposing short const values to make it match with the type parameters of [http://www.w3.org/TR/file-system-api/ File API: Directories and System].

=== Example Code ===

The app can get the current quota and usage for the apps' origin by calling:

storageInfo.queryUsageAndQuota(
storageInfo.PERSISTENT, // or TEMPORARY
function (usage, quota) { log("Current usage/quota:" + usage + "/" + quota); },
function (error) { log("Querying quota got error: " + error); });

The app can also request more quota by calling:

storageInfo.requestQuota(
storageInfo.PERSISTENT,
requestingQuota,
function (quota) { log("Requested " + requestingQuota + " => got " + quota); },
function (error) { log("Requesting quota got error: " + error); });

[[Category:Proposals]]

Quota

2011-12-13T04:47:36Z

Kinuko:

Quota

2011-12-13T04:44:54Z

Kinuko: Quota management API proposal