diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 21a93d7..4386abb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,12 +8,12 @@ # "License"); you may not use this file except in compliance # with the License. You may obtain a copy of the License at # -# http://www.apache.org/licenses/LICENSE-2.0 +# http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, # software distributed under the License is distributed on an # "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -# KIND, either express or implied. See the License for the +# KIND, either express or implied. See the License for the # specific language governing permissions and limitations # under the License. # @@ -21,17 +21,25 @@ # Contributing to Apache Cordova -Anyone can contribute to Cordova. And we need your contributions. +Anyone can contribute to Cordova. We welcome your contributions. -There are multiple ways to contribute: report bugs, improve the docs, and -contribute code. - -For instructions on this, start with the -[contribution overview](http://cordova.apache.org/contribute/). +There are multiple ways to contribute: -The details are explained there, but the important items are: - - Check for Github issues that corresponds to your contribution and link or create them if necessary. - - Run the tests so your patch doesn't break existing functionality. +* Reporting bugs +* Improving documentation +* Contributing source code +* And more... + +For instructions on how to start, please take a look at our [contribution overview](https://cordova.apache.org/contribute/) page. + +Details are explained there, but the important items are: + +* Check for GitHub issues that correspond to your contribution, and link or create them if necessary. +* Run the tests so your patch doesn't break existing functionality. + +> [!NOTE] +> Large contributions to the project require an Individual Contributor License Agreement (ICLA) to be signed and submitted to the Secretary of the Apache Software Foundation (ASF). Please read the [ASF Contributor Agreements](https://www.apache.org/licenses/contributor-agreements.html) for more information. +> +> Small contributions should be covered by clause 5 of the Apache-2.0 license. We look forward to your contributions! - diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 0000000..3052d74 --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,100 @@ + + +# Development + +## Using a Cloned Repo as a Linked Plugin + +By default, when you add a plugin to a Cordova project, the plugin files are copied into the project. However, during development, it can be easier to link the plugin instead. + +Using the `--link` option creates symbolic links to your local copy of the plugin repository instead of copying the files into the project. This means the project uses the same files, so any changes you make, whether from the app's workspace or directly in the plugin, are immediately reflected. + +To add a linked plugin, run: + +```bash +cordova plugin add --link /path/to/cordova-plugin-camera +``` + +## Testing Main Branch Without Cloning (Unstable) + +It is possible to install the plugin from the GitHub repository URL. + +```bash +cordova plugin add https://github.com/apache/cordova-plugin-camera.git +``` + +While this is possible, the preferred approach for development is to clone and link the plugin's repository, as this makes it easier to prepare changes for potential pull requests. + +## Linting + +During development, you should run the linter to ensure the code follows our coding standards: + +```bash +npm run lint +``` + +### Fixing Lint Issues + +In many cases, lint warnings can be fixed automatically with: + +```bash +npm run lint:fix +``` + +If an issue cannot be resolved automatically, it will require manual review and correction. + +## Building from Source + +1. **Clone the repository** locally. + +2. **Change to the repository directory.** + +3. **Install dependencies:** + + ```bash + npm install + ``` + + Installs all production and development dependencies required for using and developing the package. + +4. **Update sub-dependencies:** + + ```bash + npm update + ``` + + Over time, `package-lock.json` can become stale and may trigger audit warnings. `npm update` refreshes dependencies within the pinned versions. + + Under normal circumstances, users install the published package from the npm registry, which does **not** include its own `package-lock.json`. Instead, npm resolves and installs the latest compatible dependency versions at install time, which may result in no audit warnings. + + Running `npm update` locally can provide a more accurate representation of current npm audit results for the project. + +5. **Generate a tarball:** + + ```bash + npm pack + ``` + + Creates a `.tgz` tarball file in the `.asf-release` directory. This tarball file can be installed in a Cordova project via: + + ```bash + cordova plugin add /path/to/package.tgz + ``` diff --git a/README.md b/README.md index b2b8b47..91c395e 100644 --- a/README.md +++ b/README.md @@ -23,12 +23,17 @@ description: Take pictures with the device camera. # cordova-plugin-camera -[![Android Testsuite](https://github.com/apache/cordova-plugin-camera/actions/workflows/android.yml/badge.svg)](https://github.com/apache/cordova-plugin-camera/actions/workflows/android.yml) [![Chrome Testsuite](https://github.com/apache/cordova-plugin-camera/actions/workflows/chrome.yml/badge.svg)](https://github.com/apache/cordova-plugin-camera/actions/workflows/chrome.yml) [![iOS Testsuite](https://github.com/apache/cordova-plugin-camera/actions/workflows/ios.yml/badge.svg)](https://github.com/apache/cordova-plugin-camera/actions/workflows/ios.yml) [![Lint Test](https://github.com/apache/cordova-plugin-camera/actions/workflows/lint.yml/badge.svg)](https://github.com/apache/cordova-plugin-camera/actions/workflows/lint.yml) +[![npm - Latest](https://img.shields.io/npm/v/cordova-plugin-camera/latest?label=Latest%20Release%20(npm))](https://npmjs.com/package/cordova-plugin-camera) -This plugin defines a global `navigator.camera` object, which provides an API for taking pictures and for choosing images from -the system's image library. +[![GitHub](https://img.shields.io/github/package-json/v/apache/cordova-plugin-camera?label=Development%20(Git))](https://github.com/apache/cordova-plugin-camera) +[![GitHub - Android Workflow](https://github.com/apache/cordova-plugin-camera/actions/workflows/android.yml/badge.svg?branch=master)](https://github.com/apache/cordova-plugin-camera/actions/workflows/android.yml?query=branch%3Amaster) +[![GitHub - Chrome Workflow](https://github.com/apache/cordova-plugin-camera/actions/workflows/chrome.yml/badge.svg?branch=master)](https://github.com/apache/cordova-plugin-camera/actions/workflows/chrome.yml?query=branch%3Amaster) +[![GitHub - iOS Workflow](https://github.com/apache/cordova-plugin-camera/actions/workflows/ios.yml/badge.svg?branch=master)](https://github.com/apache/cordova-plugin-camera/actions/workflows/ios.yml?query=branch%3Amaster) +[![GitHub - Lint](https://github.com/apache/cordova-plugin-camera/actions/workflows/lint.yml/badge.svg?branch=master)](https://github.com/apache/cordova-plugin-camera/actions/workflows/lint.yml?query=branch%3Amaster) -Although the object is attached to the global scoped `navigator`, it is not available until after the `deviceready` event. +This plugin defines a global `navigator.camera` object, which provides an API for taking pictures and choosing images from the device's image library. + +Although the object is attached to the global `navigator` object, it is not available until after the `deviceready` event. ```js document.addEventListener("deviceready", onDeviceReady, false); @@ -38,38 +43,65 @@ function onDeviceReady() { } ``` +## Supported Platforms + +- Android +- Browser +- iOS + ## Installation - cordova plugin add cordova-plugin-camera +```bash +cordova plugin add cordova-plugin-camera +``` -It is also possible to install via repo url directly ( unstable ) +### Plugin Variables - cordova plugin add https://github.com/apache/cordova-plugin-camera.git +Plugin variables let you configure parts of a plugin and must be set during installation. To set these variables, append `--variable {VARIABLE_NAME}={VALUE}` to the `cordova plugin add` command for each variable. If you wish you change or remove any of the plugin variables, uninstall and reinstall with the updated variables. -## Plugin variables +- **`ANDROIDX_CORE_VERSION`** -The plugin uses the `ANDROIDX_CORE_VERSION` variable to configure `androidx.core:core` dependency. This allows to avoid conflicts with other plugins that have the dependency hardcoded. -If no value is passed, it will use `1.18.0` as the default value. + **Default:** `1.6.+` -The variable is configured on install time + This variable allows you to configure the `androidx.core:core` dependency for this plugin only. Some plugins may include this dependency with hard-coded versions, so you can use this variable to try to match those versions and reduce conflicts. - cordova plugin add cordova-plugin-camera --variable ANDROIDX_CORE_VERSION=1.18.0 + **Example:** -## How to Contribute + ```bash + cordova plugin add cordova-plugin-camera --variable ANDROIDX_CORE_VERSION=1.8.0 + ``` -Contributors are welcome! And we need your contributions to keep the project moving forward. You can[report bugs, improve the documentation, or [contribute code](https://github.com/apache/cordova-plugin-camera/pulls). +## App Configuration -There is a specific [contributor workflow](http://wiki.apache.org/cordova/ContributorWorkflow) we recommend. Start reading there. More information is available on [our wiki](http://wiki.apache.org/cordova). +The following preferences can be set in the app's `config.xml` file to configure the plugin. -**Have a solution?** Send a [Pull Request](https://github.com/apache/cordova-plugin-camera/pulls). +### Android-Specific -In order for your changes to be accepted, you need to sign and submit an Apache [ICLA](http://www.apache.org/licenses/#clas) (Individual Contributor License Agreement). Then your name will appear on the list of CLAs signed by [non-committers](https://people.apache.org/committer-index.html#unlistedclas) or [Cordova committers](http://people.apache.org/committers-by-project.html#cordova). +#### Supporting `saveToPhotoAlbum` on Android 9 (API 28) & Lower -**And don't forget to test and document your code.** +> [!WARNING] +> If you support Android 9 (API 28) and lower and need `saveToPhotoAlbum`, then this step is required. +> +> If you support only Android 10 (API 29) and later, or do not need `saveToPhotoAlbum`, then skip this step. +> +> Configuring the `WRITE_EXTERNAL_STORAGE` permission for Android 10 or later has no effect. -### iOS Specifics +To declare the `WRITE_EXTERNAL_STORAGE` permission, add the following: -Since iOS 10 it's mandatory to provide a usage description in the `info.plist` when accessing privacy-sensitive data. The required keys depend on how you use the plugin and which iOS versions you support: +```xml + + + +``` + +### iOS-Specific + +#### Mandatory Usage Description + +> [!WARNING] +> Since iOS 10, you must provide usage descriptions in the `info.plist` when accessing privacy-sensitive data. + +The required keys depend on how you use the plugin and which iOS versions you support: | Key | Description | | ------------------------------ | ----------- | @@ -100,25 +132,37 @@ To add these entries into the `info.plist`, you can use the `edit-config` tag in ``` +#### Preferences + +- **`CameraUsesGeolocation`** + + **Default:** `false` (boolean) + + Enables geolocation data in the EXIF header when capturing JPEG images. When set to `true`, the app will request for geolocation permissions . + + To set this preference, add the following: + + ```xml + + ``` + --- # API Reference +- [camera](#module_camera) + - [.getPicture(successCallback, errorCallback, options)](#module_camera.getPicture) + - [.cleanup()](#module_camera.cleanup) + - [.onError](#module_camera.onError) : function + - [.onSuccess](#module_camera.onSuccess) : function + - [.CameraOptions](#module_camera.CameraOptions) : Object -* [camera](#module_camera) - * [.getPicture(successCallback, errorCallback, options)](#module_camera.getPicture) - * [.cleanup()](#module_camera.cleanup) - * [.onError](#module_camera.onError) : function - * [.onSuccess](#module_camera.onSuccess) : function - * [.CameraOptions](#module_camera.CameraOptions) : Object - - -* [Camera](#module_Camera) - * [.DestinationType](#module_Camera.DestinationType) : enum - * [.EncodingType](#module_Camera.EncodingType) : enum - * [.MediaType](#module_Camera.MediaType) : enum - * [.PictureSourceType](#module_Camera.PictureSourceType) : enum - * [.Direction](#module_Camera.Direction) : enum +- [Camera](#module_Camera) + - [.DestinationType](#module_Camera.DestinationType) : enum + - [.EncodingType](#module_Camera.EncodingType) : enum + - [.MediaType](#module_Camera.MediaType) : enum + - [.PictureSourceType](#module_Camera.PictureSourceType) : enum + - [.Direction](#module_Camera.Direction) : enum --- @@ -178,18 +222,6 @@ quality, even if a `quality` parameter is specified. To avoid common memory problems, set `Camera.destinationType` to `FILE_URI` rather than `DATA_URL`. -__NOTE__: To use `saveToPhotoAlbum` option on Android 9 (API 28) and lower, the `WRITE_EXTERNAL_STORAGE` permission must be declared. - -To do this, add the following in your `config.xml`: - -```xml - - - -``` - -Android 10 (API 29) and later devices does not require `WRITE_EXTERNAL_STORAGE` permission. If your application only supports Android 10 or later, then this step is not necessary. - #### FILE_URI Usage When `FILE_URI` is used, the returned path is not directly usable. The file path needs to be resolved into @@ -291,7 +323,8 @@ function cameraCallback(imageData) { ### camera.CameraOptions : Object Optional parameters to customize the camera settings. -* [Quirks](#CameraOptions-quirks) + +- [Quirks](#CameraOptions-quirks) **Kind**: static typedef of [camera](#module_camera) **Properties** @@ -425,12 +458,6 @@ function onFail(message) { } ``` -#### Preferences (iOS) - -- __CameraUsesGeolocation__ (boolean, defaults to false). For capturing JPEGs, set to true to get geolocation data in the EXIF header. This will trigger a request for geolocation permissions if set to true. - - - #### Android Quirks Android uses intents to launch the camera activity on the device to capture @@ -477,12 +504,12 @@ setTimeout(function() { The Camera plugin allows you to do things like open the device's Camera app and take a picture, or open the file picker and select one. The code snippets in this section demonstrate different tasks including: -* Open the Camera app and [take a Picture](#takePicture) -* Take a picture and [return thumbnails](#getThumbnails) (resized picture) -* Take a picture and [generate a FileEntry object](#convert) -* [Select a file](#selectFile) from the picture library -* Select a JPEG image and [return thumbnails](#getFileThumbnails) (resized image) -* Select an image and [generate a FileEntry object](#convert) +- Open the Camera app and [take a Picture](#takePicture) +- Take a picture and [return thumbnails](#getThumbnails) (resized picture) +- Take a picture and [generate a FileEntry object](#convert) +- [Select a file](#selectFile) from the picture library +- Select a JPEG image and [return thumbnails](#getFileThumbnails) (resized image) +- Select an image and [generate a FileEntry object](#convert) ## Take a Picture diff --git a/package.json b/package.json index 132fbcd..b75136f 100644 --- a/package.json +++ b/package.json @@ -23,7 +23,8 @@ ], "scripts": { "test": "npm run lint", - "lint": "eslint ." + "lint": "eslint .", + "lint:fix": "npm run lint -- --fix" }, "author": "Apache Software Foundation", "license": "Apache-2.0",