Update README.md. Add fetch users list, fetch comments list.

Author: SurajShettigar

.idea/workspace.xml

@@ -1,10 +1,93 @@
-# flutter_wordpress
+# Flutter Wordpress
 
-Flutter Wordpress API
+This library uses [WordPress REST API V2](https://developer.wordpress.org/rest-api/) to provide a way for your application to interact with your WordPress website.
 
 ## Requirements
-- A Wordpress site using V2 REST API https://developer.wordpress.org/rest-api/
-- JWT Authentication for WP REST API V2 https://wordpress.org/plugins/jwt-authentication-for-wp-rest-api/
-- Flutter 1.0 https://flutter.io/docs/get-started/install
+For authentication and usage of administrator level REST APIs, you need to use either of the two popular authentication plugins in your WordPress site:
+1. [Application Passwords](https://wordpress.org/plugins/application-passwords/)
+2. [JWT Authentication for WP REST API](https://wordpress.org/plugins/jwt-authentication-for-wp-rest-api/)
+
+## Getting Started
+
+### 1. Import library
+
+```dart
+import 'package:flutter_wordpress/flutter_wordpress.dart' as wp;
+```
+
+### 2. Instantiate WordPress class
+
+```dart
+wp.WordPress wordPress;
+
+// adminName and adminKey is needed only for admin level APIs
+wordPress = wp.WordPress(
+    baseUrl: 'http://localhost',
+    authenticator: wp.WordPressAuthenticator.ApplicationPasswords,
+    adminName: '', 
+    adminKey: '',
+);
+```
+
+### 3. Authenticate User
+
+```dart
+Future<wp.User> response = wordPress.authenticateUser(
+      username: 'username',
+      password: 'password',
+    );
+
+response.then((user) {
+    print(user.toString());
+}).catchError((err) {
+    print(err.toString());
+});
+```
+
+### 4. Fetch Posts
+
+```dart
+Future<List<wp.Post>> posts = wordPress.fetchPosts(
+      params: wp.ParamsPostList(
+        context: wp.WordPressContext.view,
+        pageNum: 1,
+        perPage: 20,
+        order: wp.Order.desc,
+        orderBy: wp.PostsOrderBy.date,
+      ),
+    );
+```
+
+### 5. Fetch Users
+
+```dart
+Future<List<wp.User>> users = wordPress.fetchUsers(
+      params: wp.ParamsUserList(
+        context: wp.WordPressContext.view,
+        pageNum: 1,
+        perPage: 30,
+        order: wp.Order.asc,
+        orderBy: wp.UsersOrderBy.name,
+        role: wp.UserRole.subscriber,
+      ),
+    );
+```
+
+### 6. Fetch Comments
+
+```dart
+Future<List<wp.Comment>> comments = wordPress.fetchComments(
+      params: wp.ParamsCommentList(
+        context: wp.WordPressContext.view,
+        pageNum: 1,
+        perPage: 30,
+        includePostIDs: [1],
+      ),
+    );
+```
+
+## Future Work
+1. Implementing OAuth 2.0 authentication.
+
 
 

README.md

@@ -66,41 +66,60 @@ class PostsBuilderState extends State<PostsBuilder> {
         adminKey: 'EOjD JsYA hKfM RHNI vufW hyUX',
       );
     } catch (err) {
-      print(err);
+      print(err.toString());
     }
 
-    /*if (wordPress != null)
-      wordPress
-          .authenticateUser(username: 'admin', password: 'hello')
-          .then((user) {
-        print("User: $user");
-      }).catchError((err) {
-        print(err.toString());
-      });*/
+   /* Future<wp.User> response = wordPress.authenticateUser(
+      username: 'username',
+      password: 'password',
+    );
 
-    fetchPosts();
+    response.then((user) {
+      print(user.toString());
+    }).catchError((err) {
+      print(err.toString());
+    });*/
 
-    /* Future<wp.JWTResponse> auth = wordPress.authenticateUser(
-        username: 'admin', password: 'mypassword@123');
+    Future<List<wp.User>> users = wordPress.fetchUsers(
+      params: wp.ParamsUserList(
+        context: wp.WordPressContext.view,
+        pageNum: 1,
+        perPage: 30,
+        order: wp.Order.asc,
+        orderBy: wp.UsersOrderBy.name,
+      ),
+    );
 
-    auth.then((response) {
-      fetchPosts();
+    users.then((response) {
+      print(response);
     }).catchError((err) {
-      print(err.message);
-    });*/
+      print(err.toString());
+    });
+
+    Future<List<wp.Comment>> comments = wordPress.fetchComments(
+      params: wp.ParamsCommentList(
+        context: wp.WordPressContext.view,
+        pageNum: 1,
+        perPage: 30,
+      ),
+    );
+
+    comments.then((response) {
+      print(response);
+    }).catchError((err) {
+      print(err.toString());
+    });
   }
 
   void fetchPosts() {
     setState(() {
-      posts = wordPress.fetchPosts(
-          params:
-              wp.ParamsPostList(order: wp.Order.asc, includeAuthorIDs: [1, 2]));
+      posts = wordPress.fetchPosts(params: wp.ParamsPostList());
     });
   }
 
   void fetchUsers() {
     setState(() {
-      users = wordPress.fetchUsers();
+      users = wordPress.fetchUsers(params: wp.ParamsUserList());
     });
   }
 
@@ -121,7 +140,7 @@ class PostsBuilderState extends State<PostsBuilder> {
                   ),
                   Text(
                     snapshot.data[i].content.rendered,
-                  )
+                  ),
                 ],
               );
             },

example/lib/main.dart

@@ -91,17 +91,25 @@ enum CommentStatus {
   spam,
   trash,
 }
+enum CommentType {
+  comment,
+  //TODO: Add all comment types
+}
 
+/// Converts an enum string to enum value name.
 String enumStringToName(String enumString) {
   return enumString.split('.')[1];
 }
 
+/// Formats a list of [items] to a comma(,) separated string to pass it as a
+/// URL parameter.
 String listToUrlString<T>(List<T> items) {
   if (items == null || items.length == 0) return '';
 
   return items.join(',');
 }
 
+/// Formats a [Map] of parameters to a string of URL friendly parameters.
 String constructUrlParams(Map<String, String> params) {
   StringBuffer p = new StringBuffer('/?');
   params.forEach((key, value) {

lib/constants.dart

@@ -1,3 +1,15 @@
+/// This library uses WordPress REST API V2 to provide a way for your application
+/// to interact with your WordPress website.
+///
+/// We use terminologies similar to the [WordPress REST API](https://developer.wordpress.org/rest-api/)
+///
+/// For authentication and usage of administrator level APIs, we have implemented
+/// two popular authentication plugins:
+///
+/// 1. [Application Passwords](https://wordpress.org/plugins/application-passwords/)
+/// 2. [JWT Authentication for WP REST API](https://wordpress.org/plugins/jwt-authentication-for-wp-rest-api/)
+library flutter_wordpress;
+
 import 'dart:async' as async;
 import 'dart:convert';
 
@@ -29,6 +41,8 @@ import 'schemas/wordpress_error.dart';
 import 'constants.dart';
 
 import 'requests/params_post_list.dart';
+import 'requests/params_user_list.dart';
+import 'requests/params_comment_list.dart';
 
 export 'schemas/jwt_response.dart';
 export 'schemas/avatar_urls.dart';
@@ -55,7 +69,12 @@ export 'schemas/wordpress_error.dart';
 export 'constants.dart';
 
 export 'requests/params_post_list.dart';
+export 'requests/params_user_list.dart';
+export 'requests/params_comment_list.dart';
 
+/// If [WordPressAuthenticator.ApplicationPasswords] is used as an authenticator,
+/// [adminName] and [adminKey] is necessary for authentication.
+/// https://wordpress.org/plugins/application-passwords/
 class WordPress {
   String _baseUrl;
   WordPressAuthenticator _authenticator;
@@ -64,8 +83,6 @@ class WordPress {
     'Authorization': '',
   };
 
-  /// Take in base url and remove trailing '/' from the url if it exists.
-  /// Take in the wordpress context and get the enum name.
   WordPress(
       {@required String baseUrl,
       WordPressAuthenticator authenticator,
@@ -134,6 +151,10 @@ class WordPress {
     }
   }
 
+  /// This returns [User] object if the user with [id], [email] or [username]
+  /// exists. Otherwise throws [WordPressError].
+  ///
+  /// Only one parameter is enough to search for the user.
   async.Future<User> fetchUser({int id, String email, String username}) async {
     final StringBuffer url = new StringBuffer(_baseUrl + URL_USERS);
     final Map<String, String> params = {
@@ -166,12 +187,12 @@ class WordPress {
     }
   }
 
+  /// This methods returns a list of [Post] based on the filter parameters
+  /// specified through [ParamsPostList] object. By default it returns only
+  /// [ParamsPostList.perPage] number of posts in page [ParamsPostList.pageNum].
   async.Future<List<Post>> fetchPosts({@required ParamsPostList params}) async {
     final StringBuffer url = new StringBuffer(_baseUrl + URL_POSTS);
 
-    print(params.toString());
-    print(params.toMap());
-
     url.write(params.toString());
 
     final response = await http.get(url.toString(), headers: _urlHeader);
@@ -195,15 +216,18 @@ class WordPress {
     }
   }
 
-  async.Future<List<User>> fetchUsers(
-      {int pageNum = 1, int perPage = 10}) async {
-    //TODO: Implement parameters
-    final url = _baseUrl + URL_USERS + constructUrlParams(new Map());
+  /// This methods returns a list of [User] based on the filter parameters
+  /// specified through [ParamsUserList] object. By default it returns only
+  /// [ParamsUserList.perPage] number of users in page [ParamsUserList.pageNum].
+  async.Future<List<User>> fetchUsers({@required ParamsUserList params}) async {
+    final StringBuffer url = new StringBuffer(_baseUrl + URL_USERS);
 
-    final response = await http.get(url, headers: _urlHeader);
+    url.write(params.toString());
+
+    final response = await http.get(url.toString(), headers: _urlHeader);
 
     if (response.statusCode == 200) {
-      List<User> users = new List();
+      List<User> users = new List<User>();
       dynamic list = json.decode(response.body);
       list.forEach((user) {
         users.add(User.fromJson(user));
@@ -220,16 +244,19 @@ class WordPress {
     }
   }
 
-  async.Future<List<Comment>> fetchComments({Post post, int id}) async {
-    //TODO: Implement parameters
+  /// This methods returns a list of [Comment] based on the filter parameters
+  /// specified through [ParamsCommentList] object. By default it returns only
+  /// [ParamsCommentList.perPage] number of comments in page [ParamsCommentList.pageNum].
+  async.Future<List<Comment>> fetchComments(
+      {@required ParamsCommentList params}) async {
     final StringBuffer url = new StringBuffer(_baseUrl + URL_COMMENTS);
-    Map<String, String> params;
-    if (post != null) ;
 
-    final response = await http.get(url, headers: _urlHeader);
+    url.write(params.toString());
+
+    final response = await http.get(url.toString(), headers: _urlHeader);
 
     if (response.statusCode == 200) {
-      List<Comment> comments = new List();
+      List<Comment> comments = new List<Comment>();
       dynamic list = json.decode(response.body);
       list.forEach((comment) {
         comments.add(Comment.fromJson(comment));