tell people to use variables

Author: lacker

site/docs/Tutorial-GraphQLClients.md

@@ -34,7 +34,7 @@ xhr.setRequestHeader("Accept", "application/json");
 xhr.onload = function () {
   console.log('data returned:', xhr.response);
 }
-xhr.send(JSON.stringify({query:"{ hello }"}));
+xhr.send(JSON.stringify({query: "{ hello }"}));
 ```
 
 You should see the data returned, logged in the console:
@@ -43,6 +43,37 @@ You should see the data returned, logged in the console:
 data returned: Object { hello: "Hello world!" }
 ```
 
+In this example, the query was just a hardcoded string. As your application becomes more complex, and you add GraphQL endpoints that take arguments as described in [Passing Arguments](/graphql-js/passing-arguments/), you will want to construct GraphQL queries using variables in client code. You can do this by including a keyword prefixed with a dollar sign in the query, and passing an extra `variables` field on the payload.
+
+For example, let's say you're running the example server from [Passing Arguments](/graphql-js/passing-arguments/) that has a schema of
+
+```javascript
+type Query {
+  rollDice(numDice: Int!, numSides: Int): [Int]
+}
+```
+
+You could access this from JavaScript with the code:
+
+```javascript
+var dice = 3;
+var sides = 6;
+var xhr = new XMLHttpRequest();
+xhr.responseType = 'json';
+xhr.open("POST", "/graphql");
+xhr.setRequestHeader("Content-Type", "application/json");
+xhr.setRequestHeader("Accept", "application/json");
+xhr.onload = function () {
+  console.log('data returned:', xhr.response);
+}
+xhr.send(JSON.stringify({
+  query: "{ rollDice(numDice: $dice, numSides: $sides) }",
+  variables: { dice: dice, sides: sides },
+}));
+```
+
+Using this syntax for variables is a good idea because it automatically prevents bugs due to escaping, and it makes it easier to monitor your server.
+
 In general, it will take a bit more time to set up a GraphQL client like Relay, but it's worth it to get more features as your application grows. You might want to start out just using HTTP requests as the underlying transport layer, and switching to a more complex client as your application gets more complex.
 
 At this point you can write a client and server in GraphQL for an API that receives a single string. To do more, you will want to [learn how to use the other basic data types](/graphql-js/basic-types/).

site/docs/Tutorial-PassingArguments.md

@@ -99,4 +99,27 @@ When you call this API, you have to pass each argument by name. So for the serve
 
 If you run this code with `node server.js` and browse to [http://localhost:4000/graphql](http://localhost:4000/graphql) you can try out this API.
 
+When you're passing arguments in code, it's generally better to avoid constructing the whole query string yourself. Instead, you can use `$` syntax to define variables in your query, and pass the variables as a separate map.
+
+For example, some JavaScript code that calls our server above is:
+
+```javascript
+var dice = 3;
+var sides = 6;
+var xhr = new XMLHttpRequest();
+xhr.responseType = 'json';
+xhr.open("POST", "/graphql");
+xhr.setRequestHeader("Content-Type", "application/json");
+xhr.setRequestHeader("Accept", "application/json");
+xhr.onload = function () {
+  console.log('data returned:', xhr.response);
+}
+xhr.send(JSON.stringify({
+  query: "{ rollDice(numDice: $dice, numSides: $sides) }",
+  variables: { dice: dice, sides: sides },
+}));
+```
+
+Using `$dice` and `$sides` as variables in GraphQL means we don't have to worry about escaping on the client side.
+
 With basic types and argument passing, you can implement anything you can implement in a REST API. But GraphQL supports even more powerful queries. You can replace multiple API calls with a single API call if you learn how to [define your own object types](/graphql-js/object-types/).