Skip to content

Commit

Permalink
feat: add outsystems javascript wrapper for both capacitor and cordov…
Browse files Browse the repository at this point in the history
…a plugins
  • Loading branch information
OS-martacarlos authored Jan 6, 2025
2 parents 0f1bb47 + 2fcd073 commit fc11136
Show file tree
Hide file tree
Showing 26 changed files with 9,701 additions and 4,087 deletions.
3 changes: 1 addition & 2 deletions packages/android-lib/src/main/AndroidManifest.xml
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.outsystems.plugins.osgeolocation">
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
</manifest>
160 changes: 154 additions & 6 deletions packages/capacitor-plugin/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,25 +13,173 @@ npx cap sync

<docgen-index>

* [`ping(...)`](#ping)
* [`getCurrentPosition(...)`](#getcurrentposition)
* [`watchPosition(...)`](#watchposition)
* [`clearWatch(...)`](#clearwatch)
* [`checkPermissions()`](#checkpermissions)
* [`requestPermissions(...)`](#requestpermissions)
* [Interfaces](#interfaces)
* [Type Aliases](#type-aliases)

</docgen-index>

<docgen-api>
<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->

### ping(...)
### getCurrentPosition(...)

```typescript
ping(options: { value: string; }) => Promise<string>
getCurrentPosition(options?: PositionOptions | undefined) => Promise<Position>
```

| Param | Type |
| ------------- | ------------------------------- |
| **`options`** | <code>{ value: string; }</code> |
Get the current GPS location of the device

| Param | Type |
| ------------- | ----------------------------------------------------------- |
| **`options`** | <code><a href="#positionoptions">PositionOptions</a></code> |

**Returns:** <code>Promise&lt;<a href="#position">Position</a>&gt;</code>

**Since:** 1.0.0

--------------------


### watchPosition(...)

```typescript
watchPosition(options: PositionOptions, callback: WatchPositionCallback) => Promise<CallbackID>
```

Set up a watch for location changes. Note that watching for location changes
can consume a large amount of energy. Be smart about listening only when you need to.

| Param | Type |
| -------------- | ----------------------------------------------------------------------- |
| **`options`** | <code><a href="#positionoptions">PositionOptions</a></code> |
| **`callback`** | <code><a href="#watchpositioncallback">WatchPositionCallback</a></code> |

**Returns:** <code>Promise&lt;string&gt;</code>

**Since:** 1.0.0

--------------------


### clearWatch(...)

```typescript
clearWatch(options: ClearWatchOptions) => Promise<void>
```

Clear a given watch

| Param | Type |
| ------------- | --------------------------------------------------------------- |
| **`options`** | <code><a href="#clearwatchoptions">ClearWatchOptions</a></code> |

**Since:** 1.0.0

--------------------


### checkPermissions()

```typescript
checkPermissions() => Promise<PermissionStatus>
```

Check location permissions. Will throw if system location services are disabled.

**Returns:** <code>Promise&lt;<a href="#permissionstatus">PermissionStatus</a>&gt;</code>

**Since:** 1.0.0

--------------------


### requestPermissions(...)

```typescript
requestPermissions(permissions?: GeolocationPluginPermissions | undefined) => Promise<PermissionStatus>
```

Request location permissions. Will throw if system location services are disabled.

| Param | Type |
| ----------------- | ------------------------------------------------------------------------------------- |
| **`permissions`** | <code><a href="#geolocationpluginpermissions">GeolocationPluginPermissions</a></code> |

**Returns:** <code>Promise&lt;<a href="#permissionstatus">PermissionStatus</a>&gt;</code>

**Since:** 1.0.0

--------------------


### Interfaces


#### Position

| Prop | Type | Description | Since |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ----- |
| **`timestamp`** | <code>number</code> | Creation timestamp for coords | 1.0.0 |
| **`coords`** | <code>{ latitude: number; longitude: number; accuracy: number; altitudeAccuracy: number \| null; altitude: number \| null; speed: number \| null; heading: number \| null; }</code> | The GPS coordinates along with the accuracy of the data | 1.0.0 |


#### PositionOptions

| Prop | Type | Description | Default | Since |
| --------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----- |
| **`enableHighAccuracy`** | <code>boolean</code> | High accuracy mode (such as GPS, if available) On Android 12+ devices it will be ignored if users didn't grant ACCESS_FINE_LOCATION permissions (can be checked with location alias). | <code>false</code> | 1.0.0 |
| **`timeout`** | <code>number</code> | The maximum wait time in milliseconds for location updates. In Android, since version 4.0.0 of the plugin, timeout gets ignored for getCurrentPosition. | <code>10000</code> | 1.0.0 |
| **`maximumAge`** | <code>number</code> | The maximum age in milliseconds of a possible cached position that is acceptable to return | <code>0</code> | 1.0.0 |
| **`minimumUpdateInterval`** | <code>number</code> | The minumum update interval for location updates. If location updates are available faster than this interval then an update will only occur if the minimum update interval has expired since the last location update. This parameter is only available for Android. It has no effect on iOS or Web platforms. | <code>5000</code> | 1.0.0 |


#### ClearWatchOptions

| Prop | Type |
| -------- | ------------------------------------------------- |
| **`id`** | <code><a href="#callbackid">CallbackID</a></code> |


#### PermissionStatus

| Prop | Type | Description | Since |
| -------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| **`location`** | <code><a href="#permissionstate">PermissionState</a></code> | Permission state for location alias. On Android it requests/checks both ACCESS_COARSE_LOCATION and ACCESS_FINE_LOCATION permissions. On iOS and web it requests/checks location permission. | 1.0.0 |
| **`coarseLocation`** | <code><a href="#permissionstate">PermissionState</a></code> | Permission state for coarseLocation alias. On Android it requests/checks ACCESS_COARSE_LOCATION. On Android 12+, users can choose between Approximate location (ACCESS_COARSE_LOCATION) or Precise location (ACCESS_FINE_LOCATION), so this alias can be used if the app doesn't need high accuracy. On iOS and web it will have the same value as location alias. | 1.0.0 |


#### GeolocationPluginPermissions

| Prop | Type |
| ----------------- | ---------------------------------------- |
| **`permissions`** | <code>GeolocationPermissionType[]</code> |


### Type Aliases


#### WatchPositionCallback

<code>(position: <a href="#position">Position</a> | null, err?: any): void</code>


#### CallbackID

<code>string</code>


#### PermissionState

<code>'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'</code>


#### GeolocationPermissionType

<code>'location' | 'coarseLocation'</code>

</docgen-api>
24 changes: 3 additions & 21 deletions packages/capacitor-plugin/src/definitions.ts
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ export interface PermissionStatus {
*
* On iOS and web it will have the same value as location alias.
*
* @since 1.2.0
* @since 1.0.0
*/
coarseLocation: PermissionState;
}
Expand Down Expand Up @@ -190,30 +190,12 @@ export interface PositionOptions {
* This parameter is only available for Android. It has no effect on iOS or Web platforms.
*
* @default 5000
* @since 6.1.0
* @since 1.0.0
*/
minimumUpdateInterval?: number;
}

export type WatchPositionCallback = (
position: Position | null,
err?: any,
) => void;

/**
* @deprecated Use `PositionOptions`.
* @since 1.0.0
*/
export type GeolocationOptions = PositionOptions;

/**
* @deprecated Use `WatchPositionCallback`.
* @since 1.0.0
*/
export type GeolocationWatchCallback = WatchPositionCallback;

/**
* @deprecated Use `Position`.
* @since 1.0.0
*/
export type GeolocationPosition = Position;
) => void;
68 changes: 57 additions & 11 deletions packages/capacitor-plugin/src/web.ts
Original file line number Diff line number Diff line change
@@ -1,21 +1,67 @@
import { WebPlugin } from '@capacitor/core';

import type { CallbackID, ClearWatchOptions, GeolocationPluginPermissions, IGeolocationPlugin, PermissionStatus, Position, PositionOptions, WatchPositionCallback } from './definitions';
import type { CallbackID, IGeolocationPlugin, PermissionStatus, Position, PositionOptions, WatchPositionCallback } from './definitions';

export class GeolocationPluginWeb extends WebPlugin implements IGeolocationPlugin {
getCurrentPosition(options?: PositionOptions): Promise<Position> {
throw new Error('Method not implemented.');
async getCurrentPosition(options?: PositionOptions): Promise<Position> {
return new Promise((resolve, reject) => {
navigator.geolocation.getCurrentPosition(
pos => {
resolve(pos);
},
err => {
reject(err);
},
{
enableHighAccuracy: false,
timeout: 10000,
maximumAge: 0,
...options,
},
);
});
}
watchPosition(options: PositionOptions, callback: WatchPositionCallback): Promise<CallbackID> {
throw new Error('Method not implemented.');

async watchPosition(options: PositionOptions, callback: WatchPositionCallback): Promise<CallbackID> {
const id = navigator.geolocation.watchPosition(
pos => {
callback(pos);
},
err => {
callback(null, err);
},

{
enableHighAccuracy: false,
timeout: 10000,
maximumAge: 0,
minimumUpdateInterval: 5000,
...options,
},
);

return `${id}`;
}
clearWatch(options: ClearWatchOptions): Promise<void> {
throw new Error('Method not implemented.');
async clearWatch(options: { id: string }): Promise<void> {
navigator.geolocation.clearWatch(parseInt(options.id, 10));
}
checkPermissions(): Promise<PermissionStatus> {
throw new Error('Method not implemented.');

async checkPermissions(): Promise<PermissionStatus> {
if (typeof navigator === 'undefined' || !navigator.permissions) {
throw this.unavailable('Permissions API not available in this browser');
}

const permission = await navigator.permissions.query({
name: 'geolocation',
});
return { location: permission.state, coarseLocation: permission.state };
}
requestPermissions(permissions?: GeolocationPluginPermissions): Promise<PermissionStatus> {
throw new Error('Method not implemented.');

async requestPermissions(): Promise<PermissionStatus> {
throw this.unimplemented('Not implemented on web.');
}
}

const Geolocation = new GeolocationPluginWeb();

export { Geolocation };
3 changes: 1 addition & 2 deletions packages/cordova-plugin/.gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -23,5 +23,4 @@ node_modules/

# Generated by Cordova
/plugins/
/platforms/
dist/
/platforms/
5 changes: 5 additions & 0 deletions packages/cordova-plugin/dist/defaults.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
import { ClearWatchOptions, CurrentPositionOptions, WatchPositionOptions } from './definitions';

export declare const CurrentPositionOptionsDefault: CurrentPositionOptions;
export declare const ClearWatchOptionsDefault: ClearWatchOptions;
export declare const WatchPositionOptionsDefault: WatchPositionOptions;
Loading

0 comments on commit fc11136

Please sign in to comment.