Better documentation

README.md

@@ -166,6 +166,36 @@ func main() {
 }
 ```
 
+### Another example: query + post form
+
+```
+POST /post?id=1234&page=1 HTTP/1.1
+Content-Type: application/x-www-form-urlencoded
+
+name=manu&message=this_is_great
+```
+
+```go
+func main() {
+	router := gin.Default()
+
+	router.POST("/post", func(c *gin.Context) {
+        id := c.Query("id")
+        page := c.DefaultQuery("id", "0")
+        name := c.PostForm("name")
+        message := c.PostForm("message")
+
+        fmt.Println("id: %s; page: %s; name: %s; message: %s", id, page, name, message)
+	})
+	router.Run(":8080")
+}
+```
+
+```
+id: 1234; page: 0; name: manu; message: this_is_great
+```
+
+
 #### Grouping routes
 ```go
 func main() {
@@ -253,46 +283,41 @@ You can also specify that specific fields are required. If a field is decorated
 
 ```go
 // Binding from JSON
-type LoginJSON struct {
+type Login struct {
-	User     string `json:"user" binding:"required"`
+	User     string `form:"user" json:"user" binding:"required"`
-	Password string `json:"password" binding:"required"`
+	Password string `form:"password" json:"password" binding:"required"`
-}
-
-// Binding from form values
-type LoginForm struct {
-    User     string `form:"user" binding:"required"`
-    Password string `form:"password" binding:"required"`   
 }
 
 func main() {
-	r := gin.Default()
+	router := gin.Default()
 
     // Example for binding JSON ({"user": "manu", "password": "123"})
-	r.POST("/loginJSON", func(c *gin.Context) {
+	router.POST("/loginJSON", func(c *gin.Context) {
-		var json LoginJSON
+		var json Login
-
+        if c.BindJSON(&json) == nil {
-        c.Bind(&json) // This will infer what binder to use depending on the content-type header.
             if json.User == "manu" && json.Password == "123" {
                 c.JSON(http.StatusOK, gin.H{"status": "you are logged in"})
             } else {
                 c.JSON(http.StatusUnauthorized, gin.H{"status": "unauthorized"})
             }
+        }
 	})
 
     // Example for binding a HTML form (user=manu&password=123)
-    r.POST("/loginHTML", func(c *gin.Context) {
+    router.POST("/loginForm", func(c *gin.Context) {
-        var form LoginForm
+        var form Login
-
+        // This will infer what binder to use depending on the content-type header.
-        c.BindWith(&form, binding.Form) // You can also specify which binder to use. We support binding.Form, binding.JSON and binding.XML.
+        if c.Bind(&form) == nil {
             if form.User == "manu" && form.Password == "123" {
                 c.JSON(http.StatusOK, gin.H{"status": "you are logged in"})
             } else {
                 c.JSON(http.StatusUnauthorized, gin.H{"status": "unauthorized"})
             }
+        }
     })
 
 	// Listen and server on 0.0.0.0:8080
-	r.Run(":8080")
+	router.Run(":8080")
 }
 ```
 
@@ -312,25 +337,22 @@ type LoginForm struct {
 }
 
 func main() {
-
 	router := gin.Default()
-
 	router.POST("/login", func(c *gin.Context) {
 		// you can bind multipart form with explicit binding declaration:
 		// c.BindWith(&form, binding.Form)
 		// or you can simply use autobinding with Bind method:
 		var form LoginForm
-		c.Bind(&form) // in this case proper binding will be automatically selected
+        // in this case proper binding will be automatically selected
-
+		if c.Bind(&form) == nil {
             if form.User == "user" && form.Password == "password" {
 			    c.JSON(200, gin.H{"status": "you are logged in"})
             } else {
 			    c.JSON(401, gin.H{"status": "unauthorized"})
             }
+        }
 	})
-
 	router.Run(":8080")
-
 }
 ```
 

context.go

@@ -182,6 +182,11 @@ func (c *Context) MustGet(key string) interface{} {
 /************************************/
 
 // Query is a shortcut for c.Request.URL.Query().Get(key)
+// It is used to return the url query values.
+// ?id=1234&name=Manu
+// c.Query("id") == "1234"
+// c.Query("name") == "Manu"
+// c.Query("wtf") == ""
 func (c *Context) Query(key string) (va string) {
 	va, _ = c.query(key)
 	return