diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 304d625c5..a56e36314 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -6,7 +6,6 @@ on: - "development" paths-ignore: - "**/README.md" - - "docs/**" pull_request: branches: - "**" diff --git a/README.md b/README.md index bb2ab9756..a5a3e49c4 100644 --- a/README.md +++ b/README.md @@ -5,11 +5,11 @@ [![Build Status](https://github.com/parse-community/Parse-SDK-Flutter/workflows/ci/badge.svg?branch=master)](https://github.com/parse-community/Parse-SDK-Flutter/actions?query=workflow%3Aci+branch%3Amaster) [![Coverage](https://img.shields.io/codecov/c/github/parse-community/Parse-SDK-Flutter/master)](https://app.codecov.io/gh/parse-community/Parse-SDK-Flutter/branch/master) +[![Forum](https://img.shields.io/discourse/https/community.parseplatform.org/topics.svg)](https://community.parseplatform.org/c/parse-server) [![Backers on Open Collective](https://opencollective.com/parse-server/backers/badge.svg)][open-collective-link] [![Sponsors on Open Collective](https://opencollective.com/parse-server/sponsors/badge.svg)][open-collective-link] -[![License](https://img.shields.io/badge/license-Apache%202.0-lightgrey.svg)](https://github.com/parse-community/Parse-SDK-Flutter/blob/master/LICENSE) -[![Forum](https://img.shields.io/discourse/https/community.parseplatform.org/topics.svg)](https://community.parseplatform.org/c/parse-server) [![Twitter Follow](https://img.shields.io/twitter/follow/ParsePlatform.svg?label=Follow%20us&style=social)](https://twitter.com/intent/follow?screen_name=ParsePlatform) +[![Chat](https://img.shields.io/badge/Chat-Join!-%23fff?style=social&logo=slack)](https://chat.parseplatform.org) --- @@ -19,9 +19,29 @@ These libraries give you access to the powerful Parse Server backend from your D These packages are available in this repository: -| Type | Name | Pub | +| Type | Name | Pub | |---------|------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Dart | [parse_server_sdk](./packages/dart) | [![pub package](https://img.shields.io/pub/v/parse_server_sdk.svg)](https://pub.dev/packages/parse_server_sdk) [![likes](https://badges.bar/parse_server_sdk/likes)](https://pub.dev/packages/parse_server_sdk/score) [![popularity](https://badges.bar/parse_server_sdk/popularity)](https://pub.dev/packages/parse_server_sdk/score) [![pub points](https://badges.bar/parse_server_sdk/pub%20points)](https://pub.dev/packages/parse_server_sdk/score) | -| Flutter | [parse_server_sdk_flutter](./packages/flutter) | [![pub package](https://img.shields.io/pub/v/parse_server_sdk_flutter.svg)](https://pub.dev/packages/parse_server_sdk_flutter) [![likes](https://badges.bar/parse_server_sdk_flutter/likes)](https://pub.dev/packages/parse_server_sdk_flutter/score) [![popularity](https://badges.bar/parse_server_sdk_flutter/popularity)](https://pub.dev/packages/parse_server_sdk_flutter/score) [![pub points](https://badges.bar/parse_server_sdk_flutter/pub%20points)](https://pub.dev/packages/parse_server_sdk_flutter/score) | +| Dart | [parse_server_sdk](./packages/dart)| [![pub package](https://img.shields.io/pub/v/parse_server_sdk.svg)](https://pub.dev/packages/parse_server_sdk)| +| Flutter | [parse_server_sdk_flutter](./packages/flutter) | [![pub package](https://img.shields.io/pub/v/parse_server_sdk_flutter.svg)](https://pub.dev/packages/parse_server_sdk_flutter)| + +# Contributing + +We want to make contributing to this project as easy and transparent as possible. Please refer to the [Contribution Guidelines](CONTRIBUTING.md). + +# Backers + +Support us with a monthly donation and help us continue our activities. [Become a backer!](https://opencollective.com/parse-server#backer) + + + +# Contributors + +This project exists thanks to all the people who contribute... we'd love to see your face on this list! + + + + + +--- [open-collective-link]: https://opencollective.com/parse-server diff --git a/docs/migrate-1-0-28.md b/docs/migrate-1-0-28.md deleted file mode 120000 index fd18cf428..000000000 --- a/docs/migrate-1-0-28.md +++ /dev/null @@ -1 +0,0 @@ -migrate-2-0-0.md \ No newline at end of file diff --git a/docs/migrate-2-0-0.md b/docs/migrate-2-0-0.md deleted file mode 100644 index 802859310..000000000 --- a/docs/migrate-2-0-0.md +++ /dev/null @@ -1,53 +0,0 @@ -# Migrate your Flutter application to version 2.0.0 - -Starting with version 2.0.0, this repository is now separated in a pure dart (parse_server_sdk) and a flutter package (parse_server_sdk_flutter). -This was done in order to provide a dart package for the parse-server, while keeping maintenance simple. -You can find both packages in the package directory. - -### 1. pubspec.yaml -In your projects pubspec.yaml at the dependencies section, you have to change -``` -dependencies: - parse_server_sdk: ^1.0.27 -``` -to -``` -dependencies: - parse_server_sdk_flutter: ^2.0.0 -``` -This is the current released version of the parse_server_sdk_flutter package: [![pub package](https://img.shields.io/pub/v/parse_server_sdk_flutter.svg)](https://pub.dev/packages/parse_server_sdk_flutter) - -### 2. imports -As the package name changed, you have to change -``` -import 'package:parse_server_sdk/parse_server_sdk.dart'; -``` - to -``` -import 'package:parse_server_sdk_flutter/parse_server_sdk.dart'; -``` -in every file. - -It is recommended to do so by the replacement feature of your IDE. - -### optional: provide app information on web -As flutter web is now in beta, this SDK aims to be web compatible. -But there are some parts completely different on web. For example, the wep-app cant determine it's name, version or packagename. -That's why you should provide this information on web. -```dart -Parse().initialize( - ... - appName: kIsWeb ? "MyApplication" : null, - appVersion: kIsWeb ? "Version 1" : null, - appPackageName: kIsWeb ? "com.example.myapplication" : null, -); -``` - -### optional: adjust your tests -You tests might fail if the package tries to automatically discover facts like you applications name, version, package name or the default file directory. -You can avoid this automatic discovery by providing values for `appName`, `appVersion`, `appPackageName` as well as `fileDirectory` at you `Parse().initialize()` call. - -### changed network library -In order to provide a `ProgressCallback` for heavy file operations, -the network library was switched from [http](https://pub.dev/packages/http) to [dio](https://pub.dev/packages/dio). -There should be no breaking changes regarding this change, except if you are overriding the `ParseHTTPClient`. \ No newline at end of file diff --git a/packages/dart/README.md b/packages/dart/README.md index 6a5b865ab..b43b63d8b 100644 --- a/packages/dart/README.md +++ b/packages/dart/README.md @@ -1,903 +1,56 @@ -![parse-repository-header-sdk-dart](https://user-images.githubusercontent.com/5673677/166120960-ea1f58e3-a62b-4770-b541-f64186859339.png) - ---- - -This library gives you access to the powerful Parse Server backend from your Dart app. For more information on Parse Platform and its features, visit [parseplatform.org](https://parseplatform.org). The Flutter package was moved [here](https://pub.dev/packages/parse_server_sdk_flutter). If you are using Flutter see [this guide](https://github.com/parse-community/Parse-SDK-Flutter/blob/release/2.0.0/docs/migrate-2-0-0.md) for how to migrate. - ---- - -- [Compatibility](#compatibility) -- [Getting Started](#getting-started) - - [Early Web support](#early-web-support) -- [Objects](#objects) -- [Custom Objects](#custom-objects) -- [Add New Values to Objects](#add-new-values-to-objects) -- [Save Objects using Pins](#save-objects-using-pins) -- [Storage](#storage) -- [Increment Counter Values](#increment-counter-values) -- [Array Operator in Objects](#array-operator-in-objects) -- [Queries](#queries) - - [Alternative Query Methods](#alternative-query-methods) -- [Complex Queries](#complex-queries) -- [Relational queries](#relational-queries) -- [Counting objects](#counting-objects) -- [LiveQuery](#livequery) -- [ParseLiveList](#parselivelist) - - [General Use](#general-use) - - [Included Sub-Objects](#included-sub-objects) -- [Users](#users) -- [Facebook, OAuth and 3rd Party Login/User](#facebook-oauth-and-3rd-party-loginuser) -- [Security for Objects - ParseACL](#security-for-objects---parseacl) -- [Config](#config) -- [Cloud Functions](#cloud-functions) -- [Relation](#relation) -- [File](#file) -- [Other Features](#other-features) - ---- - -## Compatibility - -The Parse Dart SDK is continuously tested with the most recent release of the Dart framework to ensure compatibility. To give developers time to upgrade their app to the newest Dart framework, previous Dart framework releases are supported for at least 1 year after their [release date](https://dart.dev/get-dart/archive). - -| Version | Latest Version | End of Support | Compatible | -|-----------|----------------|----------------|----------------------------------------------| -| Dart 3.0 | 3.0.0 | May 2024 | ✅ Yes | -| Dart 2.19 | 2.19.6 | Mar 2024 | ✅ Yes | -| Dart 2.18 | 2.18.7 | Jan 2024 | ✅ Yes | -| Dart 2.17 | 2.17.7 | Aug 2023 | ❌ No (Parse Dart SDK requires Dart >=2.18.0) | - -## Getting Started - -To install, either add [dependency in your pubspec.yaml file](https://pub.dev/packages/parse_server_sdk/install). - -Once you have the library added to your project, upon first call to your app (Similar to what your application class would be) add the following... - -```dart -await Parse().initialize( - keyApplicationId, - keyParseServerUrl, - ); -``` - -If you want to use secure storage or use the Flutter web/desktop SDK, please change to the below instance of CoreStorage as it has no dependencies on Flutter. - -**The `CoreStoreSembastImp` does not encrypt the data on web!** (Web is not safe anyway. Encrypt fields manually as needed.) -```dart - -await Parse().initialize( - keyParseApplicationId, - keyParseServerUrl, - coreStore: await CoreStoreSembastImp.getInstance("/data")); -``` -It's possible to add other parameters to work with your instance of Parse Server:- - -```dart - await Parse().initialize( - keyApplicationId, - keyParseServerUrl, - clientKey: keyParseClientKey, // Required for some setups - debug: true, // When enabled, prints logs to console - liveQueryUrl: keyLiveQueryUrl, // Required if using LiveQuery - autoSendSessionId: true, // Required for authentication and ACL - securityContext: securityContext, // Again, required for some setups - coreStore: CoreStoreMemoryImp()); // Non persistent mode (default): Sdk will store everything in memmore instead of using Sembast as an internal DB. -``` -⚠️ Please note that the master key should only be used in safe environments and never on client side ‼️ Using this package on a server should be fine. - -#### Early Web support -Currently this requires adding `X-Parse-Installation-Id` as an allowed header to parse-server. -When running directly via docker, set the env var `PARSE_SERVER_ALLOW_HEADERS=X-Parse-Installation-Id`. -When running via express, set [ParseServerOptions](https://parseplatform.org/parse-server/api/master/ParseServerOptions.html) `allowHeaders: ['X-Parse-Installation-Id']`. - -Be aware that for web ParseInstallation does include app name, version or package identifier. - -## Objects -You can create custom objects by calling: -```dart -var dietPlan = ParseObject('DietPlan') - ..set('Name', 'Ketogenic') - ..set('Fat', 65); -await dietPlan.save(); -``` -Or update existing object by its objectId by calling: -```dart -var dietPlan = ParseObject('DietPlan') - ..objectId = 'R5EonpUDWy' - ..set('Fat', 70); -await dietPlan.save(); -``` -Verify that the object has been successfully saved using -```dart -var response = await dietPlan.save(); -if (response.success) { - dietPlan = response.results.first; -} -``` -Types supported: - * String - * Double - * Int - * Boolean - * DateTime - * File - * Geopoint - * ParseObject/ParseUser (Pointer) - * Map - * List (all types supported) - -You then have the ability to do the following with that object: -The features available are:- - * Get - * GetAll - * Create - * Save - * Query - By object Id - * Delete - * Complex queries as shown above - * Pin - * Plenty more - * Counters - * Array Operators - -## Custom Objects -You can create your own `ParseObjects` or convert your existing objects into Parse Objects by doing the following: - -```dart -class DietPlan extends ParseObject implements ParseCloneable { - - DietPlan() : super(_keyTableName); - DietPlan.clone(): this(); - - /// Looks strangely hacky but due to Flutter not using reflection, we have to - /// mimic a clone - @override clone(Map map) => DietPlan.clone()..fromJson(map); - - static const String _keyTableName = 'Diet_Plans'; - static const String keyName = 'Name'; - - String get name => get(keyName); - set name(String name) => set(keyName, name); -} - -``` - -When receiving an `ParseObject` from the SDK, you can often provide an instance of your custom object as an copy object. -To always use your custom object class, you can register your subclass at the initialization of the SDK. -```dart -Parse().initialize( - ..., - registeredSubClassMap: { - 'Diet_Plans': () => DietPlan(), - }, - parseUserConstructor: (username, password, emailAddress, {client, debug, sessionToken}) => CustomParseUser(username, password, emailAddress), -); -``` -Additionally you can register `SubClasses` after the initialization of the SDK. -```dart -ParseCoreData().registerSubClass('Diet_Plans', () => DietPlan()); -ParseCoreData().registerUserSubClass((username, password, emailAddress, {client, debug, sessionToken}) => CustomParseUser(username, password, emailAddress)); -``` -Providing a `ParseObject` as described above should still work, even if you have registered a different `SubClass`. - -For custom file classes have a lock at [here](#File). - -## Add New Values to Objects -To add a variable to an object call and retrieve it, call - -```dart -dietPlan.set('RandomInt', 8); -var randomInt = dietPlan.get('RandomInt'); -``` - -## Save Objects using Pins - -You can now save an object by calling `.pin()` on an instance of an object - -```dart -dietPlan.pin(); -``` - -and to retrieve it - -```dart -var dietPlan = DietPlan().fromPin('OBJECT ID OF OBJECT'); -``` - -## Storage - -We now have 2 types of storage, secure and unsecure. We currently rely on 2 third party options: - -- SharedPreferences -- Sembast -Sembast offers secured storage, whilst SharePreferences wraps NSUserDefaults (on iOS) and SharedPreferences (on Android). - -The storage method is defined in the parameter __coreStore__ in Parse().initialize - -Check sample code for options - -## Increment Counter Values - -Retrieve it, call - -```dart -var response = await dietPlan.increment("count", 1); - -``` -or using with save function - -```dart -dietPlan.setIncrement('count', 1); -dietPlan.setDecrement('count', 1); -var response = dietPlan.save() - -``` - -## Array Operator in Objects - -Retrieve it, call - -```dart -var response = await dietPlan.add("listKeywords", ["a", "a","d"]); - -var response = await dietPlan.addUnique("listKeywords", ["a", "a","d"]); - -var response = await dietPlan.remove("listKeywords", ["a"]); - -``` -or using with save function - -```dart -dietPlan.setAdd('listKeywords', ['a','a','d']); -dietPlan.setAddUnique('listKeywords', ['a','a','d']); -dietPlan.setRemove('listKeywords', ['a']); -var response = dietPlan.save() -``` - -## Queries -Once you have setup the project and initialised the instance, you can then retreive data from your server by calling: -```dart -var apiResponse = await ParseObject('ParseTableName').getAll(); - -if (apiResponse.success){ - for (var testObject in apiResponse.result) { - print(ApplicationConstants.APP_NAME + ": " + testObject.toString()); - } -} -``` -Or you can get an object by its objectId: - -```dart -var dietPlan = await DietPlan().getObject('R5EonpUDWy'); - -if (dietPlan.success) { - print(ApplicationConstants.keyAppName + ": " + (dietPlan.result as DietPlan).toString()); -} else { - print(ApplicationConstants.keyAppName + ": " + dietPlan.exception.message); -} -``` - -### Alternative Query Methods - -The standard query method `query()` returns a `ParseResponse` that contains the result or the error. As an alternative, you can also use `Future> find()` for receiving options. -This method returns an `Future` that either resolves in an error (equivalent of the error in the `ParseResponse`) or an `List` containing the queried objects. One difference, you should be aware of, is the fact, that `Future> find()` will return an empty list instead of the 'No results' error you receive in case no object matches you query. - -Choosing between `query()` and `find()` comes down to personal preference. Both methods can be used for querying a `ParseQuery`, just the output method differs. - -Similar to `find()` the `QueryBuilder` also has a function called `Future first()`. Just like `find()` `first()` is just a convenience method that makes querying the first object satisfying the query simpler. `first()` returns an `Future`, that resoles in an error or the first object matching the query. In case no object satisfies the query, the result will be `null`. - -## Complex Queries -You can create complex queries to really put your database to the test: - -```dart -var queryBuilder = QueryBuilder(DietPlan()) - ..startsWith(DietPlan.keyName, "Keto") - ..greaterThan(DietPlan.keyFat, 64) - ..lessThan(DietPlan.keyFat, 66) - ..equals(DietPlan.keyCarbs, 5); - -var response = await queryBuilder.query(); - -if (response.success) { - print(ApplicationConstants.keyAppName + ": " + ((response.results as List).first as DietPlan).toString()); -} else { - print(ApplicationConstants.keyAppName + ": " + response.exception.message); -} -``` - -if you want to find objects that match one of several queries, you can use __QueryBuilder.or__ method to construct a query that is an OR of the queries passed in. For instance if you want to find players who either have a lot of wins or a few wins, you can do: -```dart -ParseObject playerObject = ParseObject("Player"); - -QueryBuilder lotsOfWins = - QueryBuilder(playerObject)) - ..whereGreaterThan('wins', 50); - -QueryBuilder fewWins = - QueryBuilder(playerObject) - ..whereLessThan('wins', 5); - -QueryBuilder mainQuery = QueryBuilder.or( - playerObject, - [lotsOfWins, fewWins], - ); - -var apiResponse = await mainQuery.query(); -``` - -To find objects that match several queries use __QueryBuilder.and__. To find objects that do not match any given query use __QueryBuilder.nor__. - -The features available are:- - * Equals - * Contains - * LessThan - * LessThanOrEqualTo - * GreaterThan - * GreaterThanOrEqualTo - * NotEqualTo - * StartsWith - * EndsWith - * Exists - * Near - * WithinMiles - * WithinKilometers - * WithinRadians - * WithinGeoBox - * WithinPolygon - * MatchesQuery - * DoesNotMatchQuery - * MatchesKeyInQuery - * DoesNotMatchKeyInQuery - * Regex - * Order - * Limit - * Skip - * Ascending - * Descending - * Plenty more! - -## Relational queries -If you want to retrieve objects where a field contains an object that matches another query, you can use the -__whereMatchesQuery__ condition. -For example, imagine you have Post class and a Comment class, where each Comment has a pointer to its parent Post. -You can find comments on posts with images by doing: - -```dart -QueryBuilder queryPost = - QueryBuilder(ParseObject('Post')) - ..whereValueExists('image', true); - -QueryBuilder queryComment = - QueryBuilder(ParseObject('Comment')) - ..whereMatchesQuery('post', queryPost); - -var apiResponse = await queryComment.query(); -``` - -If you want to retrieve objects where a field contains an object that does not match another query, you can use the -__whereDoesNotMatchQuery__ condition. -Imagine you have Post class and a Comment class, where each Comment has a pointer to its parent Post. -You can find comments on posts without images by doing: - -```dart -QueryBuilder queryPost = - QueryBuilder(ParseObject('Post')) - ..whereValueExists('image', true); - -QueryBuilder queryComment = - QueryBuilder(ParseObject('Comment')) - ..whereDoesNotMatchQuery('post', queryPost); - -var apiResponse = await queryComment.query(); -``` - -You can use the __whereMatchesKeyInQuery__ method to get objects where a key matches the value of a key in a set of objects resulting from another query. For example, if you have a class containing sports teams and you store a user’s hometown in the user class, you can issue one query to find the list of users whose hometown teams have winning records. The query would look like:: - -```dart -QueryBuilder teamQuery = - QueryBuilder(ParseObject('Team')) - ..whereGreaterThan('winPct', 0.5); - -QueryBuilder userQuery = - QueryBuilderParseUser.forQuery()) - ..whereMatchesKeyInQuery('hometown', 'city', teamQuery); - -var apiResponse = await userQuery.query(); -``` - -Conversely, to get objects where a key does not match the value of a key in a set of objects resulting from another query, use __whereDoesNotMatchKeyInQuery__. For example, to find users whose hometown teams have losing records: - -```dart -QueryBuilder teamQuery = - QueryBuilder(ParseObject('Team')) - ..whereGreaterThan('winPct', 0.5); - -QueryBuilder losingUserQuery = - QueryBuilderParseUser.forQuery()) - ..whereDoesNotMatchKeyInQuery('hometown', 'city', teamQuery); - -var apiResponse = await losingUserQuery.query(); -``` - -To filter rows based on objectId’s from pointers in a second table, you can use dot notation: -```dart -QueryBuilder rolesOfTypeX = - QueryBuilder(ParseObject('Role')) - ..whereEqualTo('type', 'x'); - -QueryBuilder groupsWithRoleX = - QueryBuilder(ParseObject('Group'))) - ..whereMatchesKeyInQuery('objectId', 'belongsTo.objectId', rolesOfTypeX); - -var apiResponse = await groupsWithRoleX.query(); -``` - -## Counting objects -If you only care about the number of games played by a particular player: - -```dart -QueryBuilder queryPlayers = - QueryBuilder(ParseObject('GameScore')) - ..whereEqualTo('playerName', 'Jonathan Walsh'); -var apiResponse = await queryPlayers.count(); -if (apiResponse.success && apiResponse.result != null) { - int countGames = apiResponse.count; -} -``` - -## LiveQuery - -This tool allows you to subscribe to a QueryBuilder you are interested in. Once subscribed, the server will notify clients -whenever a ParseObject that matches the QueryBuilder is created or updated, in real-time. - -Parse LiveQuery contains two parts, the LiveQuery server and the LiveQuery clients. In order to use live queries, you need -to set up both of them. - -The Parse Server configuration guide on the server is found here https://docs.parseplatform.org/parse-server/guide/#live-queries and is not part of this documentation. - -Initialize the Parse Live Query by entering the parameter liveQueryUrl in Parse().initialize: -```dart -Parse().initialize( - keyApplicationId, - keyParseServerUrl, - clientKey: keyParseClientKey, - debug: true, - liveQueryUrl: keyLiveQueryUrl, - autoSendSessionId: true); -``` - -Declare LiveQuery: -```dart -final LiveQuery liveQuery = LiveQuery(); -``` - -Set the QueryBuilder that will be monitored by LiveQuery: -```dart -QueryBuilder query = - QueryBuilder(ParseObject('TestAPI')) - ..whereEqualTo('intNumber', 1); -``` -__Create a subscription__ -You’ll get the LiveQuery events through this subscription. -The first time you call subscribe, we’ll try to open the WebSocket connection to the LiveQuery server for you. - -```dart -Subscription subscription = await liveQuery.client.subscribe(query); -``` - -__Event Handling__ -We define several types of events you’ll get through a subscription object: - -__Create event__ -When a new ParseObject is created and it fulfills the QueryBuilder you subscribe, you’ll get this event. -The object is the ParseObject which was created. -```dart -subscription.on(LiveQueryEvent.create, (value) { - print('*** CREATE ***: ${DateTime.now().toString()}\n $value '); - print((value as ParseObject).objectId); - print((value as ParseObject).updatedAt); - print((value as ParseObject).createdAt); - print((value as ParseObject).get('objectId')); - print((value as ParseObject).get('updatedAt')); - print((value as ParseObject).get('createdAt')); -}); -``` - -__Update event__ -When an existing ParseObject which fulfills the QueryBuilder you subscribe is updated (The ParseObject fulfills the -QueryBuilder before and after changes), you’ll get this event. -The object is the ParseObject which was updated. Its content is the latest value of the ParseObject. -```dart -subscription.on(LiveQueryEvent.update, (value) { - print('*** UPDATE ***: ${DateTime.now().toString()}\n $value '); - print((value as ParseObject).objectId); - print((value as ParseObject).updatedAt); - print((value as ParseObject).createdAt); - print((value as ParseObject).get('objectId')); - print((value as ParseObject).get('updatedAt')); - print((value as ParseObject).get('createdAt')); -}); -``` - -__Enter event__ -When an existing ParseObject’s old value does not fulfill the QueryBuilder but its new value fulfills the QueryBuilder, -you’ll get this event. The object is the ParseObject which enters the QueryBuilder. -Its content is the latest value of the ParseObject. -```dart -subscription.on(LiveQueryEvent.enter, (value) { - print('*** ENTER ***: ${DateTime.now().toString()}\n $value '); - print((value as ParseObject).objectId); - print((value as ParseObject).updatedAt); - print((value as ParseObject).createdAt); - print((value as ParseObject).get('objectId')); - print((value as ParseObject).get('updatedAt')); - print((value as ParseObject).get('createdAt')); -}); -``` - -__Leave event__ -When an existing ParseObject’s old value fulfills the QueryBuilder but its new value doesn’t fulfill the QueryBuilder, -you’ll get this event. The object is the ParseObject which leaves the QueryBuilder. -Its content is the latest value of the ParseObject. -```dart -subscription.on(LiveQueryEvent.leave, (value) { - print('*** LEAVE ***: ${DateTime.now().toString()}\n $value '); - print((value as ParseObject).objectId); - print((value as ParseObject).updatedAt); - print((value as ParseObject).createdAt); - print((value as ParseObject).get('objectId')); - print((value as ParseObject).get('updatedAt')); - print((value as ParseObject).get('createdAt')); -}); -``` - -__Delete event__ -When an existing ParseObject which fulfills the QueryBuilder is deleted, you’ll get this event. -The object is the ParseObject which is deleted -```dart -subscription.on(LiveQueryEvent.delete, (value) { - print('*** DELETE ***: ${DateTime.now().toString()}\n $value '); - print((value as ParseObject).objectId); - print((value as ParseObject).updatedAt); - print((value as ParseObject).createdAt); - print((value as ParseObject).get('objectId')); - print((value as ParseObject).get('updatedAt')); - print((value as ParseObject).get('createdAt')); -}); -``` - -__Unsubscribe__ -If you would like to stop receiving events from a QueryBuilder, you can just unsubscribe the subscription. -After that, you won’t get any events from the subscription object and will close the WebSocket connection to the -LiveQuery server. - -```dart -liveQuery.client.unSubscribe(subscription); -``` - -__Disconnection__ -In case the client's connection to the server breaks, -LiveQuery will automatically try to reconnect. -LiveQuery will wait at increasing intervals between reconnection attempts. -By default, these intervals are set to `[0, 500, 1000, 2000, 5000, 10000]` for mobile and `[0, 500, 1000, 2000, 5000]` for web. -You can change these by providing a custom list using the `liveListRetryIntervals` parameter at `Parse.initialize()` ("-1" means "do not try to reconnect"). - -## ParseLiveList -ParseLiveList makes implementing a dynamic List as simple as possible. - -### General Use -It ships with the ParseLiveList class itself, this class manages all elements of the list, sorts them, -keeps itself up to date and Notifies you on changes. - -### Included Sub-Objects - -By default, ParseLiveQuery will provide you with all the objects you included in your Query like this: -```dart -queryBuilder.includeObject(/*List of all the included sub-objects*/); -``` -ParseLiveList will not listen for updates on this objects by default. -To activate listening for updates on all included objects, add `listenOnAllSubItems: true` to your ParseLiveListWidgets constructor. -If you want ParseLiveList to listen for updates on only some sub-objects, use `listeningIncludes: const [/*all the included sub-objects*/]` instead. -Just as QueryBuilder, ParseLiveList supports nested sub-objects too. - -**NOTE:** To use this features you have to enable [Live Queries](#live-queries) first. - -## Users - -You can create and control users just as normal using this SDK. - -To register a user, first create one : -```dart -var user = ParseUser().create("TestFlutter", "TestPassword123", "TestFlutterSDK@gmail.com"); -``` -Then have the user sign up: - -```dart -var response = await user.signUp(); -if (response.success) user = response.result; -``` -You can also login with the user: -```dart -var response = await user.login(); -if (response.success) user = response.result; -``` -You can also logout with the user: -```dart -var response = await user.logout(); -if (response.success) { - print('User logout'); -} -``` -Also, once logged in you can manage sessions tokens. This feature can be called after Parse().init() on startup to check for a logged in user. -```dart -user = ParseUser.currentUser(); -``` - -To add additional columns to the user: -```dart -var user = ParseUser("TestFlutter", "TestPassword123", "TestFlutterSDK@gmail.com") - ..set("userLocation", "FlutterLand"); -``` - -Other user features are:- - * Request Password Reset - * Verification Email Request - * Get all users - * Save - * Destroy user - * Queries - - ## Facebook, OAuth and 3rd Party Login/User - - Usually, each provider will provide their own library for logins, but the loginWith method on ParseUser accepts a name of provider, then a Map with the authentication details required. - For Facebook and the example below, we used the library provided at https://pub.dev/packages/flutter_facebook_login - - ``` - Future goToFacebookLogin() async { - final FacebookLogin facebookLogin = FacebookLogin(); - final FacebookLoginResult result = await facebookLogin.logInWithReadPermissions(['email']); - - switch (result.status) { - case FacebookLoginStatus.loggedIn: - final ParseResponse response = await ParseUser.loginWith( - 'facebook', - facebook(result.accessToken.token, - result.accessToken.userId, - result.accessToken.expires)); - - if (response.success) { - // User is logged in, test with ParseUser.currentUser() - } - break; - case FacebookLoginStatus.cancelledByUser: - // User cancelled - break; - case FacebookLoginStatus.error: - // Error - break; - } - } -``` - -For Google and the example below, we used the library provided at https://pub.dev/packages/google_sign_in - -``` -class OAuthLogin { - final GoogleSignIn _googleSignIn = GoogleSignIn( scopes: ['email', 'https://www.googleapis.com/auth/contacts.readonly'] ); - - sigInGoogle() async { - GoogleSignInAccount account = await _googleSignIn.signIn(); - GoogleSignInAuthentication authentication = await account.authentication; - await ParseUser.loginWith( - 'google', - google(_googleSignIn.currentUser.id, - authentication.accessToken, - authentication.idToken)); - } -} -``` - -## Security for Objects - ParseACL -For any object, you can specify which users are allowed to read the object, and which users are allowed to modify an object. -To support this type of security, each object has an access control list, implemented by the __ParseACL__ class. - -If ParseACL is not specified (with the exception of the ParseUser class) all objects are set to Public for read and write. -The simplest way to use a ParseACL is to specify that an object may only be read or written by a single user. -To create such an object, there must first be a logged in ParseUser. Then, new ParseACL(user) generates a ParseACL that -limits access to that user. An object’s ACL is updated when the object is saved, like any other property. - -```dart -ParseUser user = await ParseUser.currentUser() as ParseUser; -ParseACL parseACL = ParseACL(owner: user); - -ParseObject parseObject = ParseObject("TestAPI"); -... -parseObject.setACL(parseACL); -var apiResponse = await parseObject.save(); -``` -Permissions can also be granted on a per-user basis. You can add permissions individually to a ParseACL using -__setReadAccess__ and __setWriteAccess__ -```dart -ParseUser user = await ParseUser.currentUser() as ParseUser; -ParseACL parseACL = ParseACL(); -//grant total access to current user -parseACL.setReadAccess(userId: user.objectId, allowed: true); -parseACL.setWriteAccess(userId: user.objectId, allowed: true); -//grant read access to userId: 'TjRuDjuSAO' -parseACL.setReadAccess(userId: 'TjRuDjuSAO', allowed: true); -parseACL.setWriteAccess(userId: 'TjRuDjuSAO', allowed: false); - -ParseObject parseObject = ParseObject("TestAPI"); -... -parseObject.setACL(parseACL); -var apiResponse = await parseObject.save(); -``` -You can also grant permissions to all users at once using setPublicReadAccess and setPublicWriteAccess. -```dart -ParseACL parseACL = ParseACL(); -parseACL.setPublicReadAccess(allowed: true); -parseACL.setPublicWriteAccess(allowed: true); - -ParseObject parseObject = ParseObject("TestAPI"); -... -parseObject.setACL(parseACL); -var apiResponse = await parseObject.save(); -``` -Operations that are forbidden, such as deleting an object that you do not have write access to, result in a -ParseError with code 101: 'ObjectNotFound'. -For security purposes, this prevents clients from distinguishing which object ids exist but are secured, versus which -object ids do not exist at all. - -You can retrieve the ACL list of an object using: -```dart -ParseACL parseACL = parseObject.getACL(); -``` - -To set the ACL to `ParseRole` use: - -```dart -parseACL.setReadAccess(userId: "role:ROLE_NAME", allowed: true); -parseACL.setWriteAccess(userId: "role:ROLE_NAME", allowed: true); - -``` -## Config -The SDK supports Parse Config. A map of all configs can be grabbed from the server by calling : -```dart -var response = await ParseConfig().getConfigs(); -``` - -and to add a config: -```dart -ParseConfig().addConfig('TestConfig', 'testing'); -``` - -## Cloud Functions -The SDK supports call Cloud Functions. - -Executes a cloud function that returns a ParseObject type -```dart -final ParseCloudFunction function = ParseCloudFunction('hello'); -final ParseResponse result = - await function.executeObjectFunction(); -if (result.success) { - if (result.result is ParseObject) { - final ParseObject parseObject = result.result; - print(parseObject.className); - } -} -``` - -Executes a cloud function with parameters -```dart -final ParseCloudFunction function = ParseCloudFunction('hello'); -final Map params = {'plan': 'paid'}; -function.execute(parameters: params); -``` - -## Relation - -The SDK supports Relation. - -To add relation to object: - -```dart -dietPlan.addRelation('fruits', [ParseObject("Fruits")..set("objectId", "XGadzYxnac")]); -``` - -To remove relation to object: - -```dart -dietPlan.removeRelation('fruits', [ParseObject("Fruits")..set("objectId", "XGadzYxnac")]); -``` - -To Retrive a relation instance for user, call: -```dart -final relation = dietPlan.getRelation('fruits'); -``` - -and then you can add a relation to the passed in object: -``` -relation.add(dietPlan); -final result = await user.save(); -``` - -To retrieve objects that are members of Relation field of a parent object: -```dart -QueryBuilder query = - QueryBuilder(ParseObject('Fruits')) - ..whereRelatedTo('fruits', 'DietPlan', DietPlan.objectId); -``` - -## File -There are three different file classes in this SDK: -- `ParseFileBase` is and abstract class and is the foundation of every file class that can be handled by this SDK. -- `ParseFile` (former the only file class in the SDK) extends ParseFileBase and is by default used as the file class on every platform but web. -This class uses a `File` from `dart:io` for storing the raw file. -- `ParseWebFile` is the equivalent to ParseFile used at Flutter Web. -This class uses an `Uint8List` for storing the raw file. - -These classes are used by default to represent files, but you can also build your own class extending ParseFileBase and provide a custom `ParseFileConstructor` similar to the `SubClasses`. - -Have a look at the example application for a small (non web) example. - -When uploading or downloading a file, you can use the `progressCallback`-parameter to track the progress of the http request. -```dart -//A short example for showing an image from a ParseFileBase -Widget buildImage(ParseFileBase image){ - return FutureBuilder( - future: image.download(), - builder: (BuildContext context, - AsyncSnapshot snapshot) { - if (snapshot.hasData) { - if (kIsWeb) { - return Image.memory((snapshot.data as ParseWebFile).file); - } else { - return Image.file((snapshot.data as ParseFile).file); - } - } else { - return CircularProgressIndicator(); - } - }, - ); -} -``` -```dart -//A short example for storing a selected picture -//libraries: image_picker (https://pub.dev/packages/image_picker), image_picker_for_web (https://pub.dev/packages/image_picker_for_web) -PickedFile pickedFile = await ImagePicker().getImage(source: ImageSource.gallery); -ParseFileBase parseFile; -if (kIsWeb) { - //Seems weird, but this lets you get the data from the selected file as an Uint8List very easily. - ParseWebFile file = ParseWebFile(null, name: null, url: pickedFile.path); - await file.download(); - parseFile = ParseWebFile(file.file, name: file.name); -} else { - parseFile = ParseFile(File(pickedFile.path)); -} -someParseObject.set("image", parseFile); -//This saves the ParseObject as well as all of its children, and the ParseFileBase is such a child. -await someParseObject.save(); -``` -```dart -//progressCallback example -file.upload(progressCallback: (int count, int total) => print("$count of $total")); -``` - -## Other Features - -Main: -* Installation (View the example application) -* GeoPoints (View the example application) -* Persistent storage -* Debug Mode - Logging API calls -* Manage Session ID's tokens - -User: -* Queries -* Anonymous (View the example application) -* 3rd Party Authentication - -Objects: -* Create new object -* Extend Parse Object and create local objects that can be saved and retreived -* Queries +parse-repository-header-sdk-dart + +--- + +[![Build Status](https://github.com/parse-community/Parse-SDK-Flutter/workflows/ci/badge.svg?branch=master)](https://github.com/parse-community/Parse-SDK-Flutter/actions?query=workflow%3Aci+branch%3Amaster) +[![Coverage](https://img.shields.io/codecov/c/github/parse-community/Parse-SDK-Flutter/master)](https://app.codecov.io/gh/parse-community/Parse-SDK-Flutter/branch/master) + +[![pub package](https://img.shields.io/pub/v/parse_server_sdk.svg)](https://pub.dev/packages/parse_server_sdk) + +[![Forum](https://img.shields.io/discourse/https/community.parseplatform.org/topics.svg)](https://community.parseplatform.org/c/parse-server) +[![Backers on Open Collective](https://opencollective.com/parse-server/backers/badge.svg)][open-collective-link] +[![Sponsors on Open Collective](https://opencollective.com/parse-server/sponsors/badge.svg)][open-collective-link] +[![Twitter Follow](https://img.shields.io/twitter/follow/ParsePlatform.svg?label=Follow%20us&style=social)](https://twitter.com/intent/follow?screen_name=ParsePlatform) +[![Chat](https://img.shields.io/badge/Chat-Join!-%23fff?style=social&logo=slack)](https://chat.parseplatform.org) + +--- + +This library gives you access to the powerful Parse Server backend from your Dart app. For more information on Parse Platform and its features, visit [parseplatform.org](https://parseplatform.org). + +--- + +- [Compatibility](#compatibility) +- [Getting Started](#getting-started) +- [Documentation](#documentation) +- [Contributing](#contributing) + +--- + +## Compatibility + +The Parse Dart SDK is continuously tested with the most recent release of the Dart framework to ensure compatibility. To give developers time to upgrade their app to the newest Dart framework, previous Dart framework releases are supported for at least 1 year after their [release date](https://dart.dev/get-dart/archive). + +| Version | Latest Version | End of Support | Compatible | +|-----------|----------------|----------------|----------------------------------------------| +| Dart 3.0 | 3.0.0 | May 2024 | ✅ Yes | +| Dart 2.19 | 2.19.6 | Mar 2024 | ✅ Yes | +| Dart 2.18 | 2.18.7 | Jan 2024 | ✅ Yes | +| Dart 2.17 | 2.17.7 | Aug 2023 | ❌ No (Parse Dart SDK requires Dart >=2.18.0) | + +## Getting Started + +To install, add the Parse Dart SDK as a [dependency](https://pub.dev/packages/parse_server_sdk/install) in your `pubspec.yaml` file. + +## Documentation + +Find the full documentation in the [Parse Dart SDK guide][guide]. + +## Contributing + + +We want to make contributing to this project as easy and transparent as possible. Please refer to the [Contribution Guidelines](../../CONTRIBUTING.md). + +--- + +[guide]: https://docs.parseplatform.org/dart/guide/ +[open-collective-link]: https://opencollective.com/parse-server diff --git a/packages/flutter/PUSH.md b/packages/flutter/PUSH.md deleted file mode 100644 index 52870fd24..000000000 --- a/packages/flutter/PUSH.md +++ /dev/null @@ -1,76 +0,0 @@ -# Push Notifications - -Push notifications are a great way to keep your users engaged and informed about your app. You can reach your user base quickly and effectively. This guide will help you through the setup process and the general usage of Parse Platform to send push notifications. - -To configure push notifications in Parse Server, check out the [push notification guide](https://docs.parseplatform.org/parse-server/guide/#push-notifications). - -## Installation - -1. Install [Firebase Core](https://firebase.flutter.dev/docs/overview) and [Cloud Messaging](https://firebase.flutter.dev/docs/messaging/overview). For more details review the [Firebase Core Manual](https://firebase.flutter.dev/docs/manual-installation/). - -2. Add the following code after `Parse().initialize(...);`: - - ```dart - ParsePush.instance.initialize(FirebaseMessaging.instance); - FirebaseMessaging.onMessage.listen((message) => ParsePush.instance.onMessage(message)); - ``` - -3. For you app to process push notification while in the background, add the following code: - - ```dart - FirebaseMessaging.onBackgroundMessage(onBackgroundMessage); - ``` - - ```dart - Future onBackgroundMessage(RemoteMessage message) async => ParsePush.instance.onMessage(message); - ``` - -## Implementation Example - -The following is a code example for a simple implementation of push notifications: - -```dart -Future main() async { - WidgetsFlutterBinding.ensureInitialized(); - - // Initialize Firebase Core - await Firebase.initializeApp( - options: DefaultFirebaseOptions.currentPlatform, - ); - - // Initialize Parse - await Parse().initialize("applicationId", "serverUrl", - clientKey: "clientKey", debug: true); - - // Initialize Parse push notifications - ParsePush.instance.initialize(FirebaseMessaging.instance); - FirebaseMessaging.onMessage - .listen((message) => ParsePush.instance.onMessage(message)); - - // Process push notifications while app is in the background - FirebaseMessaging.onBackgroundMessage(onBackgroundMessage); - - runApp(const MyApp()); -} - -Future onBackgroundMessage(RemoteMessage message) async => - ParsePush.instance.onMessage(message); - -class MyApp extends StatelessWidget { - const MyApp({super.key}); - - // This widget is the root of your application. - @override - Widget build(BuildContext context) { - return MaterialApp( - title: 'Flutter Demo', - theme: ThemeData( - colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple), - useMaterial3: true, - ), - home: const MyHomePage(title: 'Flutter Demo Home Page'), - ); - } -} -... -``` diff --git a/packages/flutter/README.md b/packages/flutter/README.md index 85396946c..9d9043154 100644 --- a/packages/flutter/README.md +++ b/packages/flutter/README.md @@ -1,4 +1,17 @@ -![parse-repository-header-sdk-flutter](https://user-images.githubusercontent.com/5673677/166121333-2a144ce3-95bc-45d6-8840-d5b2885f2046.png) +parse-repository-header-sdk-flutter + +--- + +[![Build Status](https://github.com/parse-community/Parse-SDK-Flutter/workflows/ci/badge.svg?branch=master)](https://github.com/parse-community/Parse-SDK-Flutter/actions?query=workflow%3Aci+branch%3Amaster) +[![Coverage](https://img.shields.io/codecov/c/github/parse-community/Parse-SDK-Flutter/master)](https://app.codecov.io/gh/parse-community/Parse-SDK-Flutter/branch/master) + +[![pub package](https://img.shields.io/pub/v/parse_server_sdk_flutter.svg)](https://pub.dev/packages/parse_server_sdk_flutter) + +[![Forum](https://img.shields.io/discourse/https/community.parseplatform.org/topics.svg)](https://community.parseplatform.org/c/parse-server) +[![Backers on Open Collective](https://opencollective.com/parse-server/backers/badge.svg)][open-collective-link] +[![Sponsors on Open Collective](https://opencollective.com/parse-server/sponsors/badge.svg)][open-collective-link] +[![Twitter Follow](https://img.shields.io/twitter/follow/ParsePlatform.svg?label=Follow%20us&style=social)](https://twitter.com/intent/follow?screen_name=ParsePlatform) +[![Chat](https://img.shields.io/badge/Chat-Join!-%23fff?style=social&logo=slack)](https://chat.parseplatform.org) --- @@ -7,36 +20,9 @@ This library gives you access to the powerful Parse Server backend from your Flu --- - [Compatibility](#compatibility) -- [Example Apps](#example-apps) - [Getting Started](#getting-started) - - [Web support](#web-support) - - [Desktop Support (macOS)](#desktop-support-macos) - - [Network client](#network-client) -- [Objects](#objects) -- [Custom Objects](#custom-objects) -- [Add new values to objects](#add-new-values-to-objects) -- [Save objects using pins](#save-objects-using-pins) -- [Storage](#storage) -- [Increment Counter Values](#increment-counter-values) -- [Array Operator](#array-operator) -- [Queries](#queries) - - [Alternative Query Methods](#alternative-query-methods) -- [Complex Queries](#complex-queries) -- [Relational queries](#relational-queries) -- [Counting Objects](#counting-objects) -- [Live Queries](#live-queries) -- [ParseLiveList](#parselivelist) - - [General Use](#general-use) - - [Include Sub-Objects](#include-sub-objects) - - [Lazy Loading](#lazy-loading) -- [Users](#users) -- [Facebook, OAuth and 3rd Party Login/User](#facebook-oauth-and-3rd-party-loginuser) -- [Security for Objects - ParseACL](#security-for-objects---parseacl) -- [Config](#config) -- [Cloud Functions](#cloud-functions) -- [Relation](#relation) -- [File](#file) -- [Other Features](#other-features) +- [Documentation](#documentation) +- [Contributing](#contributing) --- @@ -51,974 +37,19 @@ The Parse Flutter SDK is continuously tested with the most recent release of the | Flutter 3.3 | Jan 2024 | ✅ Yes | | Flutter 3.0 | Jul 2023 | ❌ No (Parse Flutter SDK requires Flutter >=3.3.0) | -## Example Apps - -Example Flutter apps can be found in the GitHub repository's [example](https://github.com/parse-community/Parse-SDK-Flutter/tree/master/examples) directory. - ## Getting Started -To install add the dependency to your [pubspec.yaml](https://pub.dev/packages/parse_server_sdk_flutter/install) file. - -Once you have the library added to your project, upon first call to your app (Similar to what your application class would be) add the following... - -```dart -await Parse().initialize( - keyApplicationId, - keyParseServerUrl); -``` - -If you want to use secure storage or use the Flutter web/desktop SDK, please change to the below instance of CoreStorage as it has no dependencies on Flutter. - -**The `CoreStoreSembastImp` does not encrypt the data on web!** (Web is not safe anyway. Encrypt fields manually as needed.) -```dart - -await Parse().initialize( - keyParseApplicationId, - keyParseServerUrl, - coreStore: await CoreStoreSembastImp.getInstance()); -``` -It's possible to add other parameters to work with your instance of Parse Server:- - -```dart - await Parse().initialize( - keyApplicationId, - keyParseServerUrl, - clientKey: keyParseClientKey, // Required for some setups - debug: true, // When enabled, prints logs to console - liveQueryUrl: keyLiveQueryUrl, // Required if using LiveQuery - autoSendSessionId: true, // Required for authentication and ACL - securityContext: securityContext, // Again, required for some setups - coreStore: await CoreStoreSharedPrefsImp.getInstance()); // Local data storage method. Will use SharedPreferences instead of Sembast as an internal DB -``` - -⚠️ Please note that the master key should only be used in safe environments and never on client side ‼️ - -#### Web support -Due to Cross-origin resource sharing (CORS) restrictions, this requires adding `X-Parse-Installation-Id` as an allowed header to parse-server. -When running directly via docker, set the env var `PARSE_SERVER_ALLOW_HEADERS=X-Parse-Installation-Id`. -When running via express, set [ParseServerOptions](https://parseplatform.org/parse-server/api/master/ParseServerOptions.html) `allowHeaders: ['X-Parse-Installation-Id']`. - -#### Desktop Support (macOS) -The security entitlements posed by the macOS framework require that your app is granted permission to open outgoing network connections, so that the Parse Flutter SDK can communicate with Parse Server. To grant this permission, add the following lines: -``` -com.apple.security.network.client - -``` -to the following files: -``` -/macOS/Runner/Release.entitlements -/macOS/Runner/DebugProfile.entitlements -``` -to help the Parse SDK for Flutter communicate with the Web to access the server and send/retrive data. - -#### Network client -By default, this SDK uses the `ParseHTTPClient`. -Another option is use `ParseDioClient`. This client supports the most features (for example a progress callback at the file upload), but a benchmark has shown, that dio is slower than http on web. - -If you want to use the `ParseDioClient`, which uses the dio network library, -you can provide a custom `ParseClientCreator` at the initialization of the SDK. -```dart -await Parse().initialize( - //... - clientCreator: ({bool? sendSessionId, SecurityContext? securityContext}) => ParseDioClient(sendSessionId: sendSessionId, securityContext: securityContext), -); -``` - -## Objects -You can create custom objects by calling: -```dart -var dietPlan = ParseObject('DietPlan') - ..set('Name', 'Ketogenic') - ..set('Fat', 65); -await dietPlan.save(); -``` -Or update existing object by its objectId by calling: -```dart -var dietPlan = ParseObject('DietPlan') - ..objectId = 'R5EonpUDWy' - ..set('Fat', 70); -await dietPlan.save(); -``` -Verify that the object has been successfully saved using -```dart -var response = await dietPlan.save(); -if (response.success) { - dietPlan = response.results.first; -} -``` -Types supported: - * String - * Double - * Int - * Boolean - * DateTime - * File - * Geopoint - * ParseObject/ParseUser (Pointer) - * Map - * List (all types supported) - -You then have the ability to do the following with that object: -The features available are:- - * Get - * GetAll - * Create - * Save - * Query - By object Id - * Delete - * Complex queries as shown above - * Pin - * Plenty more - * Counters - * Array Operators - -## Custom Objects -You can create your own `ParseObjects` or convert your existing objects into Parse Objects by doing the following: - -```dart -class DietPlan extends ParseObject implements ParseCloneable { - - DietPlan() : super(_keyTableName); - DietPlan.clone(): this(); - - /// Looks strangely hacky but due to Flutter not using reflection, we have to - /// mimic a clone - @override clone(Map map) => DietPlan.clone()..fromJson(map); - - static const String _keyTableName = 'Diet_Plans'; - static const String keyName = 'Name'; - - String get name => get(keyName); - set name(String name) => set(keyName, name); -} - -``` - -When receiving an `ParseObject` from the SDK, you can often provide an instance of your custom object as an copy object. -To always use your custom object class, you can register your subclass at the initialization of the SDK. -```dart -Parse().initialize( - ..., - registeredSubClassMap: { - 'Diet_Plans': () => DietPlan(), - }, - parseUserConstructor: (username, password, emailAddress, {client, debug, sessionToken}) => CustomParseUser(username, password, emailAddress), -); -``` -Additionally you can register `SubClasses` after the initialization of the SDK. -```dart -ParseCoreData().registerSubClass('Diet_Plans', () => DietPlan()); -ParseCoreData().registerUserSubClass((username, password, emailAddress, {client, debug, sessionToken}) => CustomParseUser(username, password, emailAddress)); -``` -Providing a `ParseObject` as described above should still work, even if you have registered a different `SubClass`. - -For custom file classes have a lock at [here](#File). - -## Add new values to objects -To add a variable to an object call and retrieve it, call - -```dart -dietPlan.set('RandomInt', 8); -var randomInt = dietPlan.get('RandomInt'); -``` - -## Save objects using pins -You can now save an object by calling `.pin()` on an instance of an object - -```dart -dietPlan.pin(); -``` - -and to retrieve it - -```dart -var dietPlan = DietPlan().fromPin('OBJECT ID OF OBJECT'); -``` - -## Storage -We now have 2 types of storage, secure and unsecure. We currently rely on 2 third party options: - -- SharedPreferences -- Sembast -Sembast offers secured storage, whilst SharePreferences wraps NSUserDefaults (on iOS) and SharedPreferences (on Android). - -The storage method is defined in the parameter __coreStore__ in Parse().initialize - -Check sample code for options - -## Increment Counter Values - -Retrieve it, call - -```dart -var response = await dietPlan.increment("count", 1); - -``` -or using with save function - -```dart -dietPlan.setIncrement('count', 1); -dietPlan.setDecrement('count', 1); -var response = dietPlan.save() - -``` - -## Array Operator - -Retrieve it, call - -```dart -var response = await dietPlan.add("listKeywords", ["a", "a","d"]); - -var response = await dietPlan.addUnique("listKeywords", ["a", "a","d"]); - -var response = await dietPlan.remove("listKeywords", ["a"]); - -``` -or using with save function - -```dart -dietPlan.setAdd('listKeywords', ['a','a','d']); -dietPlan.setAddUnique('listKeywords', ['a','a','d']); -dietPlan.setRemove('listKeywords', ['a']); -var response = dietPlan.save() -``` - -## Queries -Once you have setup the project and initialised the instance, you can then retreive data from your server by calling: -```dart -var apiResponse = await ParseObject('ParseTableName').getAll(); - -if (apiResponse.success){ - for (var testObject in apiResponse.result) { - print(ApplicationConstants.APP_NAME + ": " + testObject.toString()); - } -} -``` -Or you can get an object by its objectId: - -```dart -var dietPlan = await DietPlan().getObject('R5EonpUDWy'); - -if (dietPlan.success) { - print(ApplicationConstants.keyAppName + ": " + (dietPlan.result as DietPlan).toString()); -} else { - print(ApplicationConstants.keyAppName + ": " + dietPlan.exception.message); -} -``` -To query for user objects, you could use the function ```ParseUser.forQuery()``` like this: -```dart -var queryBuilder = QueryBuilder(ParseUser.forQuery()) - ..whereEqualTo('activated', true); - -var response = await queryBuilder.query(); - -if (response.success) { - print(response.results); -} else { - print(response.exception.message); -} -``` - -### Alternative Query Methods - -The standard query method `query()` returns a `ParseResponse` that contains the result or the error. As an alternative, you can also use `Future> find()` for receiving options. -This method returns an `Future` that either resolves in an error (equivalent of the error in the `ParseResponse`) or an `List` containing the queried objects. One difference, you should be aware of, is the fact, that `Future> find()` will return an empty list instead of the 'No results' error you receive in case no object matches you query. - -Choosing between `query()` and `find()` comes down to personal preference. Both methods can be used for querying a `ParseQuery`, just the output method differs. - -Similar to `find()` the `QueryBuilder` also has a function called `Future first()`. Just like `find()` `first()` is just a convenience method that makes querying the first object satisfying the query simpler. `first()` returns an `Future`, that resoles in an error or the first object matching the query. In case no object satisfies the query, the result will be `null`. - -## Complex Queries - -You can create complex queries to really put your database to the test: - -```dart -var queryBuilder = QueryBuilder(DietPlan()) - ..startsWith(DietPlan.keyName, "Keto") - ..greaterThan(DietPlan.keyFat, 64) - ..lessThan(DietPlan.keyFat, 66) - ..equals(DietPlan.keyCarbs, 5); - -var response = await queryBuilder.query(); - -if (response.success) { - print(ApplicationConstants.keyAppName + ": " + ((response.results as List).first as DietPlan).toString()); -} else { - print(ApplicationConstants.keyAppName + ": " + response.exception.message); -} -``` - -if you want to find objects that match one of several queries, you can use __QueryBuilder.or__ method to construct a query that is an OR of the queries passed in. For instance if you want to find players who either have a lot of wins or a few wins, you can do: -```dart -ParseObject playerObject = ParseObject("Player"); - -QueryBuilder lotsOfWins = - QueryBuilder(playerObject)) - ..whereGreaterThan('wins', 50); - -QueryBuilder fewWins = - QueryBuilder(playerObject) - ..whereLessThan('wins', 5); - -QueryBuilder mainQuery = QueryBuilder.or( - playerObject, - [lotsOfWins, fewWins], - ); - -var apiResponse = await mainQuery.query(); -``` - -To find objects that match several queries use __QueryBuilder.and__. To find objects that do not match any given query use __QueryBuilder.nor__. - -The features available are:- - * Equals - * Contains - * LessThan - * LessThanOrEqualTo - * GreaterThan - * GreaterThanOrEqualTo - * NotEqualTo - * StartsWith - * EndsWith - * Exists - * Near - * WithinMiles - * WithinKilometers - * WithinRadians - * WithinGeoBox - * WithinPolygon - * MatchesQuery - * DoesNotMatchQuery - * MatchesKeyInQuery - * DoesNotMatchKeyInQuery - * Regex - * Order - * Limit - * Skip - * Ascending - * Descending - * Plenty more! - -## Relational queries -If you want to retrieve objects where a field contains an object that matches another query, you can use the -__whereMatchesQuery__ condition. -For example, imagine you have Post class and a Comment class, where each Comment has a pointer to its parent Post. -You can find comments on posts with images by doing: - -```dart -QueryBuilder queryPost = - QueryBuilder(ParseObject('Post')) - ..whereValueExists('image', true); - -QueryBuilder queryComment = - QueryBuilder(ParseObject('Comment')) - ..whereMatchesQuery('post', queryPost); - -var apiResponse = await queryComment.query(); -``` +To install, add the Parse Flutter SDK as a [dependency](https://pub.dev/packages/parse_server_sdk_flutter/install) in your `pubspec.yaml` file. -If you want to retrieve objects where a field contains an object that does not match another query, you can use the -__whereDoesNotMatchQuery__ condition. -Imagine you have Post class and a Comment class, where each Comment has a pointer to its parent Post. -You can find comments on posts without images by doing: +## Documentation -```dart -QueryBuilder queryPost = - QueryBuilder(ParseObject('Post')) - ..whereValueExists('image', true); +Find the full documentation in the [Parse Flutter SDK guide][guide]. -QueryBuilder queryComment = - QueryBuilder(ParseObject('Comment')) - ..whereDoesNotMatchQuery('post', queryPost); +## Contributing -var apiResponse = await queryComment.query(); -``` +We want to make contributing to this project as easy and transparent as possible. Please refer to the [Contribution Guidelines](../../CONTRIBUTING.md). -You can use the __whereMatchesKeyInQuery__ method to get objects where a key matches the value of a key in a set of objects resulting from another query. For example, if you have a class containing sports teams and you store a user’s hometown in the user class, you can issue one query to find the list of users whose hometown teams have winning records. The query would look like:: - -```dart -QueryBuilder teamQuery = - QueryBuilder(ParseObject('Team')) - ..whereGreaterThan('winPct', 0.5); - -QueryBuilder userQuery = - QueryBuilderParseUser.forQuery()) - ..whereMatchesKeyInQuery('hometown', 'city', teamQuery); - -var apiResponse = await userQuery.query(); -``` - -Conversely, to get objects where a key does not match the value of a key in a set of objects resulting from another query, use __whereDoesNotMatchKeyInQuery__. For example, to find users whose hometown teams have losing records: - -```dart -QueryBuilder teamQuery = - QueryBuilder(ParseObject('Team')) - ..whereGreaterThan('winPct', 0.5); - -QueryBuilder losingUserQuery = - QueryBuilderParseUser.forQuery()) - ..whereDoesNotMatchKeyInQuery('hometown', 'city', teamQuery); - -var apiResponse = await losingUserQuery.query(); -``` - -To filter rows based on objectId’s from pointers in a second table, you can use dot notation: -```dart -QueryBuilder rolesOfTypeX = - QueryBuilder(ParseObject('Role')) - ..whereEqualTo('type', 'x'); - -QueryBuilder groupsWithRoleX = - QueryBuilder(ParseObject('Group'))) - ..whereMatchesKeyInQuery('objectId', 'belongsTo.objectId', rolesOfTypeX); - -var apiResponse = await groupsWithRoleX.query(); -``` - -## Counting Objects -If you only care about the number of games played by a particular player: - -```dart -QueryBuilder queryPlayers = - QueryBuilder(ParseObject('GameScore')) - ..whereEqualTo('playerName', 'Jonathan Walsh'); -var apiResponse = await queryPlayers.count(); -if (apiResponse.success && apiResponse.result != null) { - int countGames = apiResponse.count; -} -``` - -## Live Queries -This tool allows you to subscribe to a QueryBuilder you are interested in. Once subscribed, the server will notify clients -whenever a ParseObject that matches the QueryBuilder is created or updated, in real-time. - -Parse LiveQuery contains two parts, the LiveQuery server and the LiveQuery clients. In order to use live queries, you need -to set up both of them. - -The Parse Server configuration guide on the server is found here https://docs.parseplatform.org/parse-server/guide/#live-queries and is not part of this documentation. - -Initialize the Parse Live Query by entering the parameter liveQueryUrl in Parse().initialize: -```dart -Parse().initialize( - keyApplicationId, - keyParseServerUrl, - clientKey: keyParseClientKey, - debug: true, - liveQueryUrl: keyLiveQueryUrl, - autoSendSessionId: true); -``` - -Declare LiveQuery: -```dart -final LiveQuery liveQuery = LiveQuery(); -``` - -Set the QueryBuilder that will be monitored by LiveQuery: -```dart -QueryBuilder query = - QueryBuilder(ParseObject('TestAPI')) - ..whereEqualTo('intNumber', 1); -``` -__Create a subscription__ -You’ll get the LiveQuery events through this subscription. -The first time you call subscribe, we’ll try to open the WebSocket connection to the LiveQuery server for you. - -```dart -Subscription subscription = await liveQuery.client.subscribe(query); -``` - -__Event Handling__ -We define several types of events you’ll get through a subscription object: - -__Create event__ -When a new ParseObject is created and it fulfills the QueryBuilder you subscribe, you’ll get this event. -The object is the ParseObject which was created. -```dart -subscription.on(LiveQueryEvent.create, (value) { - print('*** CREATE ***: ${DateTime.now().toString()}\n $value '); - print((value as ParseObject).objectId); - print((value as ParseObject).updatedAt); - print((value as ParseObject).createdAt); - print((value as ParseObject).get('objectId')); - print((value as ParseObject).get('updatedAt')); - print((value as ParseObject).get('createdAt')); -}); -``` - -__Update event__ -When an existing ParseObject which fulfills the QueryBuilder you subscribe is updated (The ParseObject fulfills the -QueryBuilder before and after changes), you’ll get this event. -The object is the ParseObject which was updated. Its content is the latest value of the ParseObject. -```dart -subscription.on(LiveQueryEvent.update, (value) { - print('*** UPDATE ***: ${DateTime.now().toString()}\n $value '); - print((value as ParseObject).objectId); - print((value as ParseObject).updatedAt); - print((value as ParseObject).createdAt); - print((value as ParseObject).get('objectId')); - print((value as ParseObject).get('updatedAt')); - print((value as ParseObject).get('createdAt')); -}); -``` - -__Enter event__ -When an existing ParseObject’s old value does not fulfill the QueryBuilder but its new value fulfills the QueryBuilder, -you’ll get this event. The object is the ParseObject which enters the QueryBuilder. -Its content is the latest value of the ParseObject. -```dart -subscription.on(LiveQueryEvent.enter, (value) { - print('*** ENTER ***: ${DateTime.now().toString()}\n $value '); - print((value as ParseObject).objectId); - print((value as ParseObject).updatedAt); - print((value as ParseObject).createdAt); - print((value as ParseObject).get('objectId')); - print((value as ParseObject).get('updatedAt')); - print((value as ParseObject).get('createdAt')); -}); -``` - -__Leave event__ -When an existing ParseObject’s old value fulfills the QueryBuilder but its new value doesn’t fulfill the QueryBuilder, -you’ll get this event. The object is the ParseObject which leaves the QueryBuilder. -Its content is the latest value of the ParseObject. -```dart -subscription.on(LiveQueryEvent.leave, (value) { - print('*** LEAVE ***: ${DateTime.now().toString()}\n $value '); - print((value as ParseObject).objectId); - print((value as ParseObject).updatedAt); - print((value as ParseObject).createdAt); - print((value as ParseObject).get('objectId')); - print((value as ParseObject).get('updatedAt')); - print((value as ParseObject).get('createdAt')); -}); -``` - -__Delete event__ -When an existing ParseObject which fulfills the QueryBuilder is deleted, you’ll get this event. -The object is the ParseObject which is deleted -```dart -subscription.on(LiveQueryEvent.delete, (value) { - print('*** DELETE ***: ${DateTime.now().toString()}\n $value '); - print((value as ParseObject).objectId); - print((value as ParseObject).updatedAt); - print((value as ParseObject).createdAt); - print((value as ParseObject).get('objectId')); - print((value as ParseObject).get('updatedAt')); - print((value as ParseObject).get('createdAt')); -}); -``` - -__Unsubscribe__ -If you would like to stop receiving events from a QueryBuilder, you can just unsubscribe the subscription. -After that, you won’t get any events from the subscription object and will close the WebSocket connection to the -LiveQuery server. - -```dart -liveQuery.client.unSubscribe(subscription); -``` - -__Disconnection__ -In case the client's connection to the server breaks, -LiveQuery will automatically try to reconnect. -LiveQuery will wait at increasing intervals between reconnection attempts. -By default, these intervals are set to `[0, 500, 1000, 2000, 5000, 10000]` for mobile and `[0, 500, 1000, 2000, 5000]` for web. -You can change these by providing a custom list using the `liveListRetryIntervals` parameter at `Parse.initialize()` ("-1" means "do not try to reconnect"). - -## ParseLiveList -ParseLiveList makes implementing a dynamic List as simple as possible. - -#### General Use -It ships with the ParseLiveList class itself, this class manages all elements of the list, sorts them, -keeps itself up to date and Notifies you on changes. - -ParseLiveListWidget is a widget that handles all the communication with the ParseLiveList for you. -Using ParseLiveListWidget you can create a dynamic List by just providing a QueryBuilder. - -```dart -ParseLiveListWidget( - query: query, - ); -``` -To customize the List Elements, you can provide a childBuilder. -```dart -ParseLiveListWidget( - query: query, - reverse: false, - childBuilder: - (BuildContext context, ParseLiveListElementSnapshot snapshot) { - if (snapshot.failed) { - return const Text('something went wrong!'); - } else if (snapshot.hasData) { - return ListTile( - title: Text( - snapshot.loadedData.get("text"), - ), - ); - } else { - return const ListTile( - leading: CircularProgressIndicator(), - ); - } - }, -); -``` -Similar to the standard ListView, you can provide arguments like reverse or shrinkWrap. -By providing the listLoadingElement, you can show the user something while the list is loading. -```dart -ParseLiveListWidget( - query: query, - childBuilder: childBuilder, - listLoadingElement: Center( - child: CircularProgressIndicator(), - ), -); -``` -By providing the duration argument, you can change the animation speed. -```dart -ParseLiveListWidget( - query: query, - childBuilder: childBuilder, - duration: Duration(seconds: 1), -); -``` -### Include Sub-Objects - -By default, ParseLiveQuery will provide you with all the objects you included in your Query like this: -```dart -queryBuilder.includeObject(/*List of all the included sub-objects*/); -``` -ParseLiveList will not listen for updates on this objects by default. -To activate listening for updates on all included objects, add `listenOnAllSubItems: true` to your ParseLiveListWidgets constructor. -If you want ParseLiveList to listen for updates on only some sub-objects, use `listeningIncludes: const [/*all the included sub-objects*/]` instead. -Just as QueryBuilder, ParseLiveList supports nested sub-objects too. - -### Lazy Loading - -By default, ParseLiveList lazy loads the content. -You can avoid that by setting `lazyLoading: false`. -In case you want to use lazyLoading but you need some columns to be preloaded, you can provide a list of `preloadedColumns`. -Preloading fields of a pointer is supported by using the dot-notation. -You can access the preloaded data is stored in the `preLoadedData` field of the `ParseLiveListElementSnapshot`. -```dart -ParseLiveListWidget( - query: query, - lazyLoading: true, - preloadedColumns: ["test1", "sender.username"], - childBuilder: - (BuildContext context, ParseLiveListElementSnapshot snapshot) { - if (snapshot.failed) { - return const Text('something went wrong!'); - } else if (snapshot.hasData) { - return ListTile( - title: Text( - snapshot.loadedData.get("text"), - ), - ); - } else { - return ListTile( - title: Text( - "loading comment from: ${snapshot.preLoadedData?.get("sender")?.get("username")}", - ), - ); - } - }, -); -``` - -**NOTE:** To use this features you have to enable [Live Queries](#live-queries) first. - -## Users -You can create and control users just as normal using this SDK. - -To register a user, first create one : -```dart -var user = ParseUser().create("TestFlutter", "TestPassword123", "TestFlutterSDK@gmail.com"); -``` -Then have the user sign up: - -```dart -var response = await user.signUp(); -if (response.success) user = response.result; -``` -You can also login with the user: -```dart -var response = await user.login(); -if (response.success) user = response.result; -``` -You can also logout with the user: -```dart -var response = await user.logout(); -if (response.success) { - print('User logout'); -} -``` -Also, once logged in you can manage sessions tokens. This feature can be called after Parse().init() on startup to check for a logged in user. -```dart -user = ParseUser.currentUser(); -``` - -To add additional columns to the user: -```dart -var user = ParseUser("TestFlutter", "TestPassword123", "TestFlutterSDK@gmail.com") - ..set("userLocation", "FlutterLand"); -``` - -Other user features are:- - * Request Password Reset - * Verification Email Request - * Get all users - * Save - * Destroy user - * Queries - - ## Facebook, OAuth and 3rd Party Login/User - - Usually, each provider will provide their own library for logins, but the loginWith method on ParseUser accepts a name of provider, then a Map with the authentication details required. - For Facebook and the example below, we used the library provided at https://pub.dev/packages/flutter_facebook_login - - ``` - Future goToFacebookLogin() async { - final FacebookLogin facebookLogin = FacebookLogin(); - final FacebookLoginResult result = await facebookLogin.logInWithReadPermissions(['email']); - - switch (result.status) { - case FacebookLoginStatus.loggedIn: - final ParseResponse response = await ParseUser.loginWith( - 'facebook', - facebook(result.accessToken.token, - result.accessToken.userId, - result.accessToken.expires)); - - if (response.success) { - // User is logged in, test with ParseUser.currentUser() - } - break; - case FacebookLoginStatus.cancelledByUser: - // User cancelled - break; - case FacebookLoginStatus.error: - // Error - break; - } - } -``` - -For Google and the example below, we used the library provided at https://pub.dev/packages/google_sign_in - -``` -class OAuthLogin { - final GoogleSignIn _googleSignIn = GoogleSignIn( scopes: ['email', 'https://www.googleapis.com/auth/contacts.readonly'] ); - - signInGoogle() async { - GoogleSignInAccount account = await _googleSignIn.signIn(); - GoogleSignInAuthentication authentication = await account.authentication; - await ParseUser.loginWith( - 'google', - google(authentication.accessToken!, _googleSignIn.currentUser!.id, - authentication.idToken!)); - } -} -``` - -## Security for Objects - ParseACL -For any object, you can specify which users are allowed to read the object, and which users are allowed to modify an object. -To support this type of security, each object has an access control list, implemented by the __ParseACL__ class. - -If ParseACL is not specified (with the exception of the ParseUser class) all objects are set to Public for read and write. -The simplest way to use a ParseACL is to specify that an object may only be read or written by a single user. -To create such an object, there must first be a logged in ParseUser. Then, new ParseACL(user) generates a ParseACL that -limits access to that user. An object’s ACL is updated when the object is saved, like any other property. - -```dart -ParseUser user = await ParseUser.currentUser() as ParseUser; -ParseACL parseACL = ParseACL(owner: user); - -ParseObject parseObject = ParseObject("TestAPI"); -... -parseObject.setACL(parseACL); -var apiResponse = await parseObject.save(); -``` -Permissions can also be granted on a per-user basis. You can add permissions individually to a ParseACL using -__setReadAccess__ and __setWriteAccess__ -```dart -ParseUser user = await ParseUser.currentUser() as ParseUser; -ParseACL parseACL = ParseACL(); -//grant total access to current user -parseACL.setReadAccess(userId: user.objectId, allowed: true); -parseACL.setWriteAccess(userId: user.objectId, allowed: true); -//grant read access to userId: 'TjRuDjuSAO' -parseACL.setReadAccess(userId: 'TjRuDjuSAO', allowed: true); -parseACL.setWriteAccess(userId: 'TjRuDjuSAO', allowed: false); - -ParseObject parseObject = ParseObject("TestAPI"); -... -parseObject.setACL(parseACL); -var apiResponse = await parseObject.save(); -``` -You can also grant permissions to all users at once using setPublicReadAccess and setPublicWriteAccess. -```dart -ParseACL parseACL = ParseACL(); -parseACL.setPublicReadAccess(allowed: true); -parseACL.setPublicWriteAccess(allowed: true); - -ParseObject parseObject = ParseObject("TestAPI"); -... -parseObject.setACL(parseACL); -var apiResponse = await parseObject.save(); -``` -Operations that are forbidden, such as deleting an object that you do not have write access to, result in a -ParseError with code 101: 'ObjectNotFound'. -For security purposes, this prevents clients from distinguishing which object ids exist but are secured, versus which -object ids do not exist at all. - -You can retrieve the ACL list of an object using: -```dart -ParseACL parseACL = parseObject.getACL(); -``` - -To set the ACL to `ParseRole` use: - -```dart -parseACL.setReadAccess(userId: "role:ROLE_NAME", allowed: true); -parseACL.setWriteAccess(userId: "role:ROLE_NAME", allowed: true); -``` - -## Config -The SDK supports Parse Config. A map of all configs can be grabbed from the server by calling : -```dart -var response = await ParseConfig().getConfigs(); -``` - -and to add a config: -```dart -ParseConfig().addConfig('TestConfig', 'testing'); -``` - -## Cloud Functions -The SDK supports call Cloud Functions. - -Executes a cloud function that returns a ParseObject type -```dart -final ParseCloudFunction function = ParseCloudFunction('hello'); -final ParseResponse result = - await function.executeObjectFunction(); -if (result.success) { - if (result.result is ParseObject) { - final ParseObject parseObject = result.result; - print(parseObject.className); - } -} -``` - -Executes a cloud function with parameters -```dart -final ParseCloudFunction function = ParseCloudFunction('hello'); -final Map params = {'plan': 'paid'}; -function.execute(parameters: params); -``` - -## Relation - -The SDK supports Relation. - -To add relation to object: - -```dart -dietPlan.addRelation('fruits', [ParseObject("Fruits")..set("objectId", "XGadzYxnac")]); -``` - -To remove relation to object: - -```dart -dietPlan.removeRelation('fruits', [ParseObject("Fruits")..set("objectId", "XGadzYxnac")]); -``` - -To Retrive a relation instance for user, call: -```dart -final relation = dietPlan.getRelation('fruits'); -``` - -and then you can add a relation to the passed in object: -``` -relation.add(dietPlan); -final result = await user.save(); -``` - -To retrieve objects that are members of Relation field of a parent object: -```dart -QueryBuilder query = - QueryBuilder(ParseObject('Fruits')) - ..whereRelatedTo('fruits', 'DietPlan', DietPlan.objectId); -``` - -## File -There are three different file classes in this SDK: -- `ParseFileBase` is and abstract class and is the foundation of every file class that can be handled by this SDK. -- `ParseFile` (former the only file class in the SDK) extends ParseFileBase and is by default used as the file class on every platform but web. -This class uses a `File` from `dart:io` for storing the raw file. -- `ParseWebFile` is the equivalent to ParseFile used at Flutter Web. -This class uses an `Uint8List` for storing the raw file. - -These classes are used by default to represent files, but you can also build your own class extending ParseFileBase and provide a custom `ParseFileConstructor` similar to the `SubClasses`. - -Have a look at the example application for a small (non web) example. - -When uploading or downloading a file, you can use the `progressCallback`-parameter to track the progress of the http request. - -```dart -//A short example for showing an image from a ParseFileBase -Widget buildImage(ParseFileBase image){ - return FutureBuilder( - future: image.download(), - builder: (BuildContext context, - AsyncSnapshot snapshot) { - if (snapshot.hasData) { - if (kIsWeb) { - return Image.memory((snapshot.data as ParseWebFile).file); - } else { - return Image.file((snapshot.data as ParseFile).file); - } - } else { - return CircularProgressIndicator(); - } - }, - ); -} -``` -```dart -//A short example for storing a selected picture -//libraries: image_picker (https://pub.dev/packages/image_picker), image_picker_for_web (https://pub.dev/packages/image_picker_for_web) -PickedFile pickedFile = await ImagePicker().getImage(source: ImageSource.gallery); -ParseFileBase parseFile; -if (kIsWeb) { - //Seems weird, but this lets you get the data from the selected file as an Uint8List very easily. - ParseWebFile file = ParseWebFile(null, name: null, url: pickedFile.path); - await file.download(); - parseFile = ParseWebFile(file.file, name: file.name); -} else { - parseFile = ParseFile(File(pickedFile.path)); -} -someParseObject.set("image", parseFile); -//This saves the ParseObject as well as all of its children, and the ParseFileBase is such a child. -await someParseObject.save(); -``` - -## Other Features - -Main: -* Installation (View the example application) -* GeoPoints (View the example application) -* Persistent storage -* Debug Mode - Logging API calls -* Manage Session ID's tokens - -User: -* Queries -* Anonymous (View the example application) -* 3rd Party Authentication +--- -Objects: -* Create new object -* Extend Parse Object and create local objects that can be saved and retrieved -* Queries +[guide]: https://docs.parseplatform.org/flutter/guide/ +[open-collective-link]: https://opencollective.com/parse-server diff --git a/packages/flutter/example/linux/flutter/generated_plugin_registrant.cc b/packages/flutter/example/linux/flutter/generated_plugin_registrant.cc index e71a16d23..7e7bf28b2 100644 --- a/packages/flutter/example/linux/flutter/generated_plugin_registrant.cc +++ b/packages/flutter/example/linux/flutter/generated_plugin_registrant.cc @@ -6,6 +6,10 @@ #include "generated_plugin_registrant.h" +#include void fl_register_plugins(FlPluginRegistry* registry) { + g_autoptr(FlPluginRegistrar) awesome_notifications_registrar = + fl_plugin_registry_get_registrar_for_plugin(registry, "AwesomeNotificationsPlugin"); + awesome_notifications_plugin_register_with_registrar(awesome_notifications_registrar); } diff --git a/packages/flutter/example/linux/flutter/generated_plugins.cmake b/packages/flutter/example/linux/flutter/generated_plugins.cmake index 2e1de87a7..4c05cc5be 100644 --- a/packages/flutter/example/linux/flutter/generated_plugins.cmake +++ b/packages/flutter/example/linux/flutter/generated_plugins.cmake @@ -3,6 +3,7 @@ # list(APPEND FLUTTER_PLUGIN_LIST + awesome_notifications ) list(APPEND FLUTTER_FFI_PLUGIN_LIST diff --git a/packages/flutter/example/windows/flutter/generated_plugin_registrant.cc b/packages/flutter/example/windows/flutter/generated_plugin_registrant.cc index 8777c93d9..387b16656 100644 --- a/packages/flutter/example/windows/flutter/generated_plugin_registrant.cc +++ b/packages/flutter/example/windows/flutter/generated_plugin_registrant.cc @@ -6,9 +6,12 @@ #include "generated_plugin_registrant.h" +#include #include void RegisterPlugins(flutter::PluginRegistry* registry) { + AwesomeNotificationsPluginCApiRegisterWithRegistrar( + registry->GetRegistrarForPlugin("AwesomeNotificationsPluginCApi")); ConnectivityPlusWindowsPluginRegisterWithRegistrar( registry->GetRegistrarForPlugin("ConnectivityPlusWindowsPlugin")); } diff --git a/packages/flutter/example/windows/flutter/generated_plugins.cmake b/packages/flutter/example/windows/flutter/generated_plugins.cmake index cc1361d8d..8fea54187 100644 --- a/packages/flutter/example/windows/flutter/generated_plugins.cmake +++ b/packages/flutter/example/windows/flutter/generated_plugins.cmake @@ -3,6 +3,7 @@ # list(APPEND FLUTTER_PLUGIN_LIST + awesome_notifications connectivity_plus ) diff --git a/res/values/strings_en.arb b/res/values/strings_en.arb deleted file mode 100644 index 9e26dfeeb..000000000 --- a/res/values/strings_en.arb +++ /dev/null @@ -1 +0,0 @@ -{} \ No newline at end of file diff --git a/tools/flutter-dependencies.bat b/tools/flutter-dependencies.bat deleted file mode 100644 index 62b47bf34..000000000 --- a/tools/flutter-dependencies.bat +++ /dev/null @@ -1,8 +0,0 @@ -call flutter config --no-analytics -cd packages/dart -call flutter pub get -cd ../.. -cd packages/flutter -call flutter pub remove parse_server_sdk -call flutter pub add parse_server_sdk --path ../dart -call flutter pub get \ No newline at end of file diff --git a/tools/flutter-dependencies.sh b/tools/flutter-dependencies.sh deleted file mode 100644 index aeddd7539..000000000 --- a/tools/flutter-dependencies.sh +++ /dev/null @@ -1,11 +0,0 @@ -#!/bin/sh -# This scrip installs the dependencies of the flutter package. -# parse_server_sdk is set to the relative path. - -cd packages/dart -flutter pub get -cd ../.. -cd packages/flutter -flutter pub remove parse_server_sdk -flutter pub add parse_server_sdk --path ../dart -flutter pub get