allow recently docs-v2 on extending pages

Author: hideokamoto

extending/adding/index.md

@@ -49,7 +49,7 @@ add_action( 'rest_api_init', function () {
 } );
 ```
 
-Right now, we're only registering the one endpoint for the route. ("Route" is the URL, whereas "endpoint" is the function behind it that corresponds to a method *and* a URL. For more, see the [Glossary](/glossary.html).) Each route can have any number of endpoints, and for each endpoint, you can define the HTTP methods allowed, a callback function for responding to the request and a permissions callback for creating custom permissions. In addition you can define allowed fields in the request and for each field specify a default value, a sanitization callback, a validation callback, and whether the field is required.
+Right now, we're only registering the one endpoint for the route. ("Route" is the URL, whereas "endpoint" is the function behind it that corresponds to a method *and* a URL. For more, see the [Glossary](/glossary.html).) If your site domain is `example.com` and you've kept the API path of `wp-json`, then the full URL would be `http://example.com/wp-json/myplugin/v1/author/(?P<id>\d+)`. Each route can have any number of endpoints, and for each endpoint, you can define the HTTP methods allowed, a callback function for responding to the request and a permissions callback for creating custom permissions. In addition you can define allowed fields in the request and for each field specify a default value, a sanitization callback, a validation callback, and whether the field is required.
 
 
 ### Namespacing
@@ -99,6 +99,7 @@ function my_awesome_func( WP_REST_Request $request ) {
 	$parameters = $request->get_url_params();
 	$parameters = $request->get_query_params();
 	$parameters = $request->get_body_params();
+	$parameters = $request->get_json_params();
 	$parameters = $request->get_default_params();
 
 	// Uploads aren't merged in, but can be accessed separately:
@@ -110,6 +111,8 @@ function my_awesome_func( WP_REST_Request $request ) {
 
 Normally, you'll get every parameter brought in unaltered. However, you can register your arguments when registering your route, which allows you to run sanitization and validation on these.
 
+If the request has the `Content-type: application/json` header set and valid JSON in the body, `get_json_params()` will return the parsed JSON body as an associative array.  
+
 Arguments are defined as a map in the key `args` for each endpoint (next to your `callback` option). This map uses the name of the argument of the key, with the value being a map of options for that argument. This array can contain a key for `default`, `required`, `sanitize_callback` and `validate_callback`.
 
 * `default`: Used as the default value for the argument, if none is supplied.
@@ -240,7 +243,7 @@ The Controller Pattern
 
 The controller pattern is a best practice for working with complex endpoints with the API.
 
-It is recommended that you read "Extending Internal Classes" before reading this section. Doing so will familiarize you with the patterns used by the default routes, which is the best practice. While it is not required that the class you use to process your request extends the `WP_REST_Controller` class or a class that extends it, doing so allows you to inherit work done in those classes. In addition, you can rest assured that you're following best practices based on the controller methods you're using.
+It is recommended that you read ["Extending Internal Classes"](/extending/internal-classes/) before reading this section. Doing so will familiarize you with the patterns used by the default routes, which is the best practice. While it is not required that the class you use to process your request extends the `WP_REST_Controller` class or a class that extends it, doing so allows you to inherit work done in those classes. In addition, you can rest assured that you're following best practices based on the controller methods you're using.
 
 At their core, controllers are nothing more than a set of commonly named methods to match up with REST conventions, along with some handy helpers. Controllers register their routes in a `register_routes` method, respond to requests with `get_items`, `get_item`, `create_item`, `update_item` and `delete_item`, and have similarly named permission check methods. Following this pattern will ensure you don't miss any steps or functionality in your endpoints.
 

extending/custom-content-types/index.md

@@ -37,7 +37,7 @@ Here is an example of registering a post type, with support for the REST API:
   		'not_found'          => __( 'No books found.', 'your-plugin-textdomain' ),
   		'not_found_in_trash' => __( 'No books found in Trash.', 'your-plugin-textdomain' )
   	);
-  
+
   	$args = array(
   		'labels'             => $labels,
   		'description'        => __( 'Description.', 'your-plugin-textdomain' ),
@@ -56,7 +56,7 @@ Here is an example of registering a post type, with support for the REST API:
   		'rest_controller_class' => 'WP_REST_Posts_Controller',
   		'supports'           => array( 'title', 'editor', 'author', 'thumbnail', 'excerpt', 'comments' )
   	);
-  
+
   	register_post_type( 'book', $args );
 }
 ```
@@ -78,7 +78,7 @@ Here is an example of how to register a custom taxonomy, with REST API support:
    */
   add_action( 'init', 'my_book_taxonomy', 30 );
   function my_book_taxonomy() {
-  
+
   	$labels = array(
   		'name'              => _x( 'Genres', 'taxonomy general name' ),
   		'singular_name'     => _x( 'Genre', 'taxonomy singular name' ),
@@ -92,7 +92,7 @@ Here is an example of how to register a custom taxonomy, with REST API support:
   		'new_item_name'     => __( 'New Genre Name' ),
   		'menu_name'         => __( 'Genre' ),
   	);
-  
+
   	$args = array(
   		'hierarchical'      => true,
   		'labels'            => $labels,
@@ -104,9 +104,9 @@ Here is an example of how to register a custom taxonomy, with REST API support:
   		'rest_base'          => 'genre',
   		'rest_controller_class' => 'WP_REST_Terms_Controller',
   	);
-  
+
   	register_taxonomy( 'genre', array( 'book' ), $args );
-  
+
   }
 ```
 
@@ -122,15 +122,15 @@ Here is an example of adding REST API support to an existing custom post type:
   add_action( 'init', 'my_custom_post_type_rest_support', 25 );
   function my_custom_post_type_rest_support() {
   	global $wp_post_types;
-  
+
   	//be sure to set this to the name of your post type!
   	$post_type_name = 'planet';
   	if( isset( $wp_post_types[ $post_type_name ] ) ) {
   		$wp_post_types[$post_type_name]->show_in_rest = true;
   		$wp_post_types[$post_type_name]->rest_base = $post_type_name;
   		$wp_post_types[$post_type_name]->rest_controller_class = 'WP_REST_Posts_Controller';
   	}
-  
+
   }
 ```
 
@@ -143,17 +143,17 @@ Here is an example of how to add REST API support to an already registered custo
   add_action( 'init', 'my_custom_taxonomy_rest_support', 25 );
   function my_custom_taxonomy_rest_support() {
   	global $wp_taxonomies;
-  
+
   	//be sure to set this to the name of your taxonomy!
   	$taxonomy_name = 'planet_class';
-  
+
   	if ( isset( $wp_taxonomies[ $taxonomy_name ] ) ) {
   		$wp_taxonomies[ $taxonomy_name ]->show_in_rest = true;
   		$wp_taxonomies[ $taxonomy_name ]->rest_base = $taxonomy_name;
   		$wp_taxonomies[ $taxonomy_name ]->rest_controller_class = 'WP_REST_Terms_Controller';
   	}
-  
-  
+
+
   }
 ```
 

extending/javascript-client/index.md

@@ -31,7 +31,7 @@ Models:
  * Page
  * PageMeta
  * PageRevision
- * Posts
+ * Post
  * PostMeta
  * PostRevision
  * Schema
@@ -63,7 +63,7 @@ You can use these endpoints as-is to read, update, create and delete items using
 Each model and collection includes a reference to its default values, for example:
 
 ```
-wp.api.models.Posts.defaults
+wp.api.models.Post.prototype.args
  * author: null
  * comment_status: null
  * content: null
@@ -84,7 +84,7 @@ wp.api.models.Posts.defaults
 
 ### Available methods
 
-Each model and collection contains a list of methods the corrosponding endpoint supports. For example, models created from `wp.api.models.Posts` have a method array of:
+Each model and collection contains a list of methods the corresponding endpoint supports. For example, models created from `wp.api.models.Post` have a methods array of:
 
 ```
 ["GET", "POST", "PUT", "PATCH", "DELETE"]
@@ -95,7 +95,7 @@ Each model and collection contains a list of methods the corrosponding endpoint
 Each model and collection contains a list of options the corrosponding endpoint accepts (note that options are passed as the second parameter when creating models or collections), for example:
 
 ```
-wp.api.collections.Posts.options
+wp.api.collections.Posts.prototype.options
  * author
  * context
  * filter
@@ -106,39 +106,48 @@ wp.api.collections.Posts.options
  * search
  * status
 ```
-### Model examples:
 
-To create a post and edit its categories, make sure you are logged in, then:
+### Waiting for the client to load
+Client startup is asynchronous. If the api schema is localized, the client can start immediately; if not the client makes an ajax request to load the schema. The client exposes a load promise for provide a reliable wait to wait for client to be ready:
 
+```js
+wp.api.loadPromise.done( function() {
+	//... use the client here
+} )
 ```
-// Create a new post
-var post = new wp.api.models.Posts( { title: 'This is a test post' } );
-post.save();
 
+### Model examples:
+
+To create a post and edit its categories, make sure you are logged in, then:
+
+```js
 // Create a new post
-var post = new wp.api.models.Posts({ title:'new test' } );
+var post = new wp.api.models.Post( { title: 'This is a test post' } );
 post.save();
 
-// Get a collection of the post's categories
-var postCategories = post.getCategories();
+// Load an existing post
+var post = new wp.api.models.Post( { id: 1 } );
+post.fetch();
 
 // Get a collection of the post's categories (returns a promise)
 // Uses _embedded data if available, in which case promise resolves immediately.
 post.getCategories().done( function( postCategories ) {
 	// ... do something with the categories.
 	// The new post has an single Category: Uncategorized
-	postCategories.at( 0 ).get( 'name' );
+	console.log( postCategories[0].name );
 	// response -> "Uncategorized"
 } );
 
 // Get a posts author User model.
 post.getAuthorUser().done( function( user ){
 	// ... do something with user
+	console.log( user.get( 'name' ) );
 } );
 
 // Get a posts featured image Media model.
 post.getFeaturedImage().done( function( image ){
 	// ... do something with image
+	console.log( image );
 } );
 
 // Set the post categories.
@@ -170,26 +179,26 @@ postCategories.at( 0 ).get( 'name' );
 
 to get the last 10 posts:
 
-```
+```js
 var postsCollection = new wp.api.collections.Posts();
 postsCollection.fetch();
 ```
 
 to get the last 25 posts:
 
-```
+```js
 postsCollection.fetch( { data: { per_page: 25 } } );
 ```
 
 use filter to change the order & orderby options:
 
-```
+```js
 postsCollection.fetch( { data: { 'filter': { 'orderby': 'title', 'order': 'ASC' } } } );
 ```
 
 All collections support pagination automatically, and you can get the next page of results using `more`:
 
-```
+```js
 postsCollection.more();
 ```