deprecate "path", replace "file" by "tmpfile"

ctx #67

Author: gre

README.md

@@ -34,38 +34,24 @@ Returns a Promise of the image URI.
 
 - **`view`** is a reference to a React Native component.
 - **`options`** may include:
- - **`width`** / **`height`** *(number)*: the width and height of the final image (resized from the View bound. don't provide it if you want the original pixel size).
- - **`format`** *(string)*: either `png` or `jpg`/`jpeg` or `webm` (Android). Defaults to `png`.
- - **`quality`** *(number)*: the quality. 0.0 - 1.0 (default). (only available on lossy formats like jpeg)
- - **`result`** *(string)*, the method you want to use to save the snapshot, one of:
+  - **`width`** / **`height`** *(number)*: the width and height of the final image (resized from the View bound. don't provide it if you want the original pixel size).
+  - **`format`** *(string)*: either `png` or `jpg`/`jpeg` or `webm` (Android). Defaults to `png`.
+  - **`quality`** *(number)*: the quality. 0.0 - 1.0 (default). (only available on lossy formats like jpeg)
+  - **`result`** *(string)*, the method you want to use to save the snapshot, one of:
     - `"file"` (default): save to a temporary file *(that will only exist for as long as the app is running)*.
     - `"base64"`: encode as base64 and returns the raw string. Use only with small images as this may result of lags (the string is sent over the bridge). *N.B. This is not a data uri, use `data-uri` instead*.
     - `"data-uri"`: same as `base64` but also includes the [Data URI scheme](https://en.wikipedia.org/wiki/Data_URI_scheme) header.
- - **`path`** *(string)*: The absolute path where the file get generated. **Read below before using it!** 
  - **`snapshotContentContainer`** *(bool)*: if true and when view is a ScrollView, the "content container" height will be evaluated instead of the container height.
 
-### `path` option and `dirs` constants
+### DEPRECATED `path` option and `dirs` constants
 
-**IMPORTANT: We might actually drop the path feature because of its complexity in the current codebase (and bugs that are not fixed), please consider using react-native-view-shot with https://github.com/itinance/react-native-fs to solve this.**
+> A feature used to allow to set an arbitrary file path. This has become tricky to maintain because all the edge cases and use-cases of file management so we have decided to drop it, making this library focusing more on solving snapshotting and not file system.
 
-By default, takeSnapshot will export in a temporary folder and the snapshot file will be deleted as soon as the app leaves.
-But if you use the `path` option, you make the snapshot file more permanent and at a specific file location. it is up to you to manage the image file lifecycle, the library won't clean it for you (which might result of leaking files on user's phone if you are not careful). There is also no guarantee the file will be successfully saved: you can reach permissions problem, this also is platform specific.
+To migrate from this old feature, you have a few solutions:
 
-If you still want to do this, we expose a few somewhat universal "constants" to ease the work.
-
-```js
-import { takeSnapshot, dirs } from "react-native-view-shot";
-// cross platform dirs:
-const { CacheDir, DocumentDir, MainBundleDir, MovieDir, MusicDir, PictureDir } = dirs;
-// only available Android:
-const { DCIMDir, DownloadDir, RingtoneDir, SDCardDir } = dirs;
-
-takeSnapshot(viewRef, { path: PictureDir+"/foo.png" })
-.then(
-  uri => console.log("Image saved to", uri),
-  error => console.error("Oops, snapshot failed", error)
-);
-```
+- If you want to save the snapshotted image result to the CameraRoll, just use https://facebook.github.io/react-native/docs/cameraroll.html#savetocameraroll
+- If you want to save it to an arbitrary file path, use something like https://github.com/itinance/react-native-fs
+- For any more advanced needs, you can write your own (or find another) native module that would solve your use-case.
 
 ## Interoperability Table
 

android/src/main/java/fr/greweb/reactnativeviewshot/RNViewShotModule.java

@@ -71,7 +71,7 @@ public void takeSnapshot(int tag, ReadableMap options, Promise promise) {
         DisplayMetrics displayMetrics = context.getResources().getDisplayMetrics();
         Integer width = options.hasKey("width") ? (int)(displayMetrics.density * options.getDouble("width")) : null;
         Integer height = options.hasKey("height") ? (int)(displayMetrics.density * options.getDouble("height")) : null;
-        String result = options.hasKey("result") ? options.getString("result") : "file";
+        String result = options.hasKey("result") ? options.getString("result") : "tmpfile";
         Boolean snapshotContentContainer = options.hasKey("snapshotContentContainer") ? options.getBoolean("snapshotContentContainer") : false;
         try {
             File file = null;
@@ -85,6 +85,9 @@ public void takeSnapshot(int tag, ReadableMap options, Promise promise) {
                     file = createTempFile(getReactApplicationContext(), format);
                 }
             }
+            else if ("tmpfile".equals(result)) {
+                file = createTempFile(getReactApplicationContext(), format);
+            }
             UIManagerModule uiManager = this.reactContext.getNativeModule(UIManagerModule.class);
             uiManager.addUIBlock(new ViewShot(tag, format, compressFormat, quality, width, height, file, result, snapshotContentContainer,reactContext, promise));
         }

android/src/main/java/fr/greweb/reactnativeviewshot/ViewShot.java

@@ -79,7 +79,7 @@ public void execute(NativeViewHierarchyManager nativeViewHierarchyManager) {
             return;
         }
         try {
-            if ("file".equals(result)) {
+            if ("file".equals(result) || "tmpfile".equals(result)) {
                 os = new FileOutputStream(output);
                 captureView(view, os);
                 String uri = Uri.fromFile(output).toString();

index.js

@@ -14,7 +14,7 @@ export const dirs = {
   DCIMDir: RNViewShot.DCIMDir,
   DownloadDir: RNViewShot.DownloadDir,
   RingtoneDir: RNViewShot.RingtoneDir,
-  SDCardDir: RNViewShot.SDCardDir,
+  SDCardDir: RNViewShot.SDCardDir
 };
 
 export function takeSnapshot(
@@ -25,13 +25,25 @@ export function takeSnapshot(
     path?: string,
     format?: "png" | "jpg" | "jpeg" | "webm",
     quality?: number,
-    result?: "file" | "base64" | "data-uri",
-    snapshotContentContainer?: bool
+    result?: "tmpfile" | "file" | "base64" | "data-uri",
+    snapshotContentContainer?: boolean
   } = {}
 ): Promise<string> {
+  if (options.result === "file") {
+    console.warn(
+      "react-native-view-shot: result='file' is deprecated, has been renamed to 'tmpfile' and no longer support any 'path' option. See README for more information"
+    );
+  } else if ("path" in options) {
+    console.warn(
+      "react-native-view-shot: path option is deprecated. See README for more information"
+    );
+  }
   if (typeof view !== "number") {
     const node = findNodeHandle(view);
-    if (!node) return Promise.reject(new Error("findNodeHandle failed to resolve view="+String(view)));
+    if (!node)
+      return Promise.reject(
+        new Error("findNodeHandle failed to resolve view=" + String(view))
+      );
     view = node;
   }
   return RNViewShot.takeSnapshot(view, options);

ios/RNViewShot.m

@@ -42,24 +42,24 @@ - (NSDictionary *)constantsToExport
                   reject:(RCTPromiseRejectBlock)reject)
 {
   [self.bridge.uiManager addUIBlock:^(__unused RCTUIManager *uiManager, NSDictionary<NSNumber *, UIView *> *viewRegistry) {
-    
+
     // Get view
     UIView *view;
     view = viewRegistry[target];
     if (!view) {
       reject(RCTErrorUnspecified, [NSString stringWithFormat:@"No view found with reactTag: %@", target], nil);
       return;
     }
-    
+
     // Get options
     CGSize size = [RCTConvert CGSize:options];
     NSString *format = [RCTConvert NSString:options[@"format"] ?: @"png"];
-    NSString *result = [RCTConvert NSString:options[@"result"] ?: @"file"];
+    NSString *result = [RCTConvert NSString:options[@"result"] ?: @"tmpfile"];
     BOOL snapshotContentContainer = [RCTConvert BOOL:options[@"snapshotContentContainer"] ?: @"false"];
 
     // Capture image
     BOOL success;
-    
+
     UIView* rendered;
     UIScrollView* scrollView;
     if (snapshotContentContainer) {
@@ -74,15 +74,15 @@ - (NSDictionary *)constantsToExport
     else {
       rendered = view;
     }
-    
+
     if (size.width < 0.1 || size.height < 0.1) {
       size = snapshotContentContainer ? scrollView.contentSize : view.bounds.size;
     }
     if (size.width < 0.1 || size.height < 0.1) {
       reject(RCTErrorUnspecified, [NSString stringWithFormat:@"The content size must not be zero or negative. Got: (%g, %g)", size.width, size.height], nil);
       return;
     }
-    
+
     CGPoint savedContentOffset;
     CGRect savedFrame;
     if (snapshotContentContainer) {
@@ -96,13 +96,13 @@ - (NSDictionary *)constantsToExport
     success = [rendered drawViewHierarchyInRect:(CGRect){CGPointZero, size} afterScreenUpdates:YES];
     UIImage *image = UIGraphicsGetImageFromCurrentImageContext();
     UIGraphicsEndImageContext();
-    
+
     if (snapshotContentContainer) {
       // Restore scroll & frame
       scrollView.contentOffset = savedContentOffset;
       scrollView.frame = savedFrame;
     }
-    
+
     if (!success) {
       reject(RCTErrorUnspecified, @"The view cannot be captured. drawViewHierarchyInRect was not successful. This is a potential technical or security limitation.", nil);
       return;
@@ -112,10 +112,10 @@ - (NSDictionary *)constantsToExport
       reject(RCTErrorUnspecified, @"Failed to capture view snapshot. UIGraphicsGetImageFromCurrentImageContext() returned nil!", nil);
       return;
     }
-    
+
     // Convert image to data (on a background thread)
     dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
-      
+
       NSData *data;
       if ([format isEqualToString:@"png"]) {
         data = UIImagePNGRepresentation(image);
@@ -126,13 +126,13 @@ - (NSDictionary *)constantsToExport
         reject(RCTErrorUnspecified, [NSString stringWithFormat:@"Unsupported image format: %@. Try one of: png | jpg | jpeg", format], nil);
         return;
       }
-      
+
       NSError *error = nil;
       NSString *res = nil;
-      if ([result isEqualToString:@"file"]) {
+      if ([result isEqualToString:@"file"] || [result isEqualToString:@"tmpfile"] ) {
         // Save to a temp file
         NSString *path;
-        if (options[@"path"]) {
+        if (options[@"path"] && [result isEqualToString:@"file"]) {
           path = options[@"path"];
           NSString * folder = [path stringByDeletingLastPathComponent];
           NSFileManager * fm = [NSFileManager defaultManager];
@@ -167,7 +167,7 @@ - (NSDictionary *)constantsToExport
         resolve(res);
         return;
       }
-      
+
       // If we reached here, something went wrong
       if (error) reject(RCTErrorUnspecified, error.localizedDescription, error);
       else reject(RCTErrorUnspecified, @"viewshot unknown error", nil);