(#111) Add CHANGELOG.md and docs for new and deprecated APIs

alexcmgit · Nov 16, 2022 · b806fbd · b806fbd
1 parent e3ed468
commit b806fbd
Show file tree

Hide file tree

Showing 5 changed files with 76 additions and 2 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,10 +1,28 @@
+## 0.7.0
+
+- New APIs and options.
+- There's no major breaking changes when updating to `v0.7.0` but there are deprecation notices over Media Store and Environment API.
+
+### New
+
+- `openDocument` API with single and multiple files support @honjow.
+- `openDocumentTree` it now also supports `persistablePermission` option which flags an one-time operation to avoid unused permission issues.
+
+### Deprecation notices
+
+- All non SAF APIs are deprecated (Media Store and Environment APIs), if you are using them, let us know by [opening an issue](https://github.com/alexrintt/shared-storage/issues/new) with your use-case so we can implement a new compatible API using a cross-platform approach.
+
+### Example project
+
+- Added a new button that implements `openDocument` API.
+
 ## 0.6.0
 
 This release contains a severe API fixes and some minor doc changes:
 
 ### Breaking changes
 
-- Unused arguments in `DocumentFile.getContent` and `DocumentFile.getContentAsString`. [#107](https://github.com/alexrintt/shared-storage/issues/107).
+- Unused arguments in `DocumentFile.getContent` and `DocumentFile.getContentAsString`. [#107](https://github.com/alexrintt/shared-storage/issues/107) @clragon.
 - Package import it's now done through a single import.
 
 ## 0.5.0
@@ -170,7 +188,7 @@ See the label [reference here](/docs/Usage/API%20Labeling.md).
 
 - <samp>Mirror</samp> `getStorageDirectory` from [`Environment.getStorageDirectory`](https://developer.android.com/reference/android/os/Environment#getStorageDirectory%28%29).
 
-### Deprecation Notices
+### Deprecation notices
 
 - `getExternalStoragePublicDirectory` was marked as deprecated and should be replaced with an equivalent API depending on your use-case, see [how to migrate `getExternalStoragePublicDirectory`](https://stackoverflow.com/questions/56468539/getexternalstoragepublicdirectory-deprecated-in-android-q). This deprecation is originated from official Android documentation and not by the plugin itself.
 

diff --git a/docs/Migrate notes/Migrate to v0.7.0.md b/docs/Migrate notes/Migrate to v0.7.0.md
@@ -0,0 +1,12 @@
+There's no major breaking changes when updating to `v0.7.0` but there are deprecation notices if you are using Media Store and Environment API.
+
+Update your `pubspec.yaml`:
+
+```yaml
+dependencies:
+  shared_storage: ^0.7.0
+```
+
+## Deprecation notices
+
+All non SAF APIs are deprecated, if you are using them, let us know by [opening an issue](https://github.com/alexrintt/shared-storage/issues/new) with your use-case so we can implement a new compatible API using a cross-platform approach.
diff --git a/docs/Usage/Environment.md b/docs/Usage/Environment.md
@@ -1,3 +1,5 @@
+> **WARNING** This API is deprecated and will be removed soon. If you need it, please open an issue with your use-case to include in the next release as part of the new original cross-platform API.
+
 ## Import package
 
 ```dart

diff --git a/docs/Usage/Media Store.md b/docs/Usage/Media Store.md
@@ -1,3 +1,5 @@
+> **WARNING** This API is deprecated and will be removed soon. If you need it, please open an issue with your use-case to include in the next release as part of the new original cross-platform API.
+
 ## Import package
 
 ```dart

diff --git a/docs/Usage/Storage Access Framework.md b/docs/Usage/Storage Access Framework.md
@@ -64,6 +64,46 @@ if (grantedUri != null) {
 }
 ```
 
+### <samp>openDocument</samp>
+
+Same as `openDocumentTree` but for file URIs, you can request user to select a file and filter by:
+
+- Single or multiple files.
+- Mime type.
+
+You can also specify if you want a one-time operation (`persistablePermission` = false) and if you don't need write access (`grantWritePermission` = false).
+
+```dart
+const kDownloadsFolder =
+    'content://com.android.externalstorage.documents/tree/primary%3ADownloads/document/primary%3ADownloads';
+
+final List<Uri>? selectedDocumentUris = await openDocument(
+  // if you have a previously saved URI,
+  // you can use the specify the tree you user will see at startup of the file picker.
+  initialUri: Uri.parse(kDownloadsFolder),
+
+  // whether or not allow the user select multiple files.
+  multiple: true,
+
+  // whether or not the selected URIs should be persisted across app and device reboots.
+  persistablePermission: true,
+
+  // whether or not grant write permission required to edit file metadata (name) and it's contents.
+  grantWritePermission: true,
+
+  // whether or not filter by mime type.
+  mimeType: 'image/*' // default '*/*'
+);
+
+if (selectedDocumentUris == null) {
+  return print('User cancelled the operation.');
+}
+
+// If [selectedDocumentUris] are [persistablePermission]s then it will be returned by this function
+// along with any another URIs you've got permission over.
+final List<UriPermission> persistedUris = await persistedUriPermissions();
+```
+
 ### <samp>listFiles</samp>
 
 This method list files lazily **over a granted uri:**