docs: add guide/response

Signed-off-by: Vishal Rana <vr@labstack.com>

context.go

@@ -139,7 +139,7 @@ type (
 		// XMLPretty sends a pretty-print XML with status code.
 		XMLPretty(code int, i interface{}, indent string) error
 
-		// XMLBlob sends a XML blob response with status code.
+		// XMLBlob sends an XML blob response with status code.
 		XMLBlob(code int, b []byte) error
 
 		// Blob sends a blob response with status code and content type.
@@ -161,7 +161,7 @@ type (
 		// NoContent sends a response with no body and a status code.
 		NoContent(code int) error
 
-		// Redirect redirects the request with status code.
+		// Redirect redirects the request to a provided URL with status code.
 		Redirect(code int, url string) error
 
 		// Error invokes the registered HTTP error handler. Generally used by middleware.

website/content/guide/error-handling.md

@@ -8,10 +8,8 @@ description = "Error handling in Echo"
 +++
 
 Echo advocates centralized HTTP error handling by returning error from middleware
-or handlers.
-
-- Log errors from a unified location
-- Send customized HTTP responses
+and handlers. It allows us to log/report errors to external services from a unified
+location and send customized HTTP responses.
 
 For example, when basic auth middleware finds invalid credentials it returns
 `401 - Unauthorized` error, aborting the current HTTP request.

website/content/guide/response.md

@@ -0,0 +1,300 @@
++++
+title = "Response"
+description = "Sending HTTP response in Echo"
+[menu.main]
+  name = "Response"
+  parent = "guide"
+  weight = 6
++++
+
+## Send String
+
+`Context#String(code int, s string)` can be used to send plain text response with status
+code.
+
+*Example*
+
+```go
+```
+
+## Send HTML (Reference to templates)
+
+`Context#HTML(code int, html string)` can be used to send simple HTML response with
+status code. If you are looking to send dynamically generate HTML see [templates](/guide/templates).
+
+*Example*
+
+```go
+func(c echo.Context) error {
+  return c.HTML(http.StatusOK, "<strong>Hello, World!</strong>")
+}
+```
+
+### Send HTML Blob
+
+`Context#HTMLBlob(code int, b []byte)` can be used to send HTML blob with status
+code. You may find it handy using with a template engine which outputs `[]byte`.
+
+## Send JSON
+
+`Context#JSON(code int, i interface{})` can be used to encode a provided Go type into
+JSON and send it as response with status code.
+
+*Example*
+
+```go
+// User
+type User struct {
+  Name  string `json:"name" xml:"name"`
+  Email string `json:"email" xml:"email"`
+}
+
+// Handler
+func(c echo.Context) error {
+  u := &User{
+    Name:  "Jon",
+    Email: "jon@labstack.com",
+  }
+  return c.JSON(http.StatusOK, u)
+}
+```
+
+### Stream JSON
+
+`Context#JSON()` internally uses `json.Marshal` which may not be efficient to large JSON,
+in that case you can directly stream JSON.
+
+*Example*
+
+```go
+func(c echo.Context) error {
+  u := &User{
+    Name:  "Jon",
+    Email: "jon@labstack.com",
+  }
+  c.Response().Header().Set(echo.HeaderContentType, echo.MIMEApplicationJSONCharsetUTF8)
+  c.Response().WriteHeader(http.StatusOK)
+  return json.NewEncoder(c.Response()).Encode(u)
+}
+```
+
+### JSON Pretty
+
+`Context#JSONPretty(code int, i interface{}, indent string)` can be used to a send
+a JSON response which is pretty printed based on indent, which could spaces or tabs.
+
+Example below sends a pretty print JSON indented with spaces:
+
+```go
+func(c echo.Context) error {
+  u := &User{
+    Name:  "Jon",
+    Email: "joe@labstack.com",
+  }
+  return c.JSONPretty(http.StatusOK, u, "  ")
+}
+```
+
+```js
+{
+  "email": "joe@labstack.com",
+  "name": "Jon"
+}
+```
+
+### JSON Blob
+
+`Context#JSONBlob(code int, b []byte)` can be used to send pre-encoded JSON blob directly
+from external source, for example, database.
+
+*Example*
+
+```go
+func(c echo.Context) error {
+  encodedJSON := []byte{} // Encoded JSON from external source
+  return c.JSONBlob(http.StatusOK, encodedJSON)
+}
+```
+
+## Send JSONP
+
+`Context#JSONP(code int, callback string, i interface{})` can be used to encode a provided
+Go type into JSON and send it as JSONP payload constructed using a callback, with
+status code.
+
+[*Example*](/recipes/jsonp)
+
+## Send XML
+
+`Context#XML(code int, i interface{})` can be used to encode a provided Go type into
+XML and send it as response with status cod.
+
+*Example*
+
+```go
+func(c echo.Context) error {
+  u := &User{
+    Name:  "Jon",
+    Email: "jon@labstack.com",
+  }
+  return c.XML(http.StatusOK, u)
+}
+```
+
+### Stream XML
+
+`Context#XML` internally uses `xml.Marshal` which may not be efficient to large XML,
+in that case you can directly stream XML.
+
+*Example*
+
+```go
+func(c echo.Context) error {
+  u := &User{
+    Name:  "Jon",
+    Email: "jon@labstack.com",
+  }
+  c.Response().Header().Set(echo.HeaderContentType, echo.MIMEApplicationXMLCharsetUTF8)
+  c.Response().WriteHeader(http.StatusOK)
+  return xml.NewEncoder(c.Response()).Encode(u)
+}
+```
+
+### XML Pretty
+
+`Context#XMLPretty(code int, i interface{}, indent string)` can be used to a send
+an XML response which is pretty printed based on indent, which could spaces or tabs.
+
+Example below sends a pretty print XML indented with spaces:
+
+```go
+func(c echo.Context) error {
+  u := &User{
+    Name:  "Jon",
+    Email: "joe@labstack.com",
+  }
+  return c.XMLPretty(http.StatusOK, u, "  ")
+}
+```
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<User>
+  <Name>Jon</Name>
+  <Email>joe@labstack.com</Email>
+</User>
+```
+
+### XML Blob
+
+`Context#XMLBlob(code int, b []byte)` can be used to send pre-encoded XML blob directly
+from external source, for example, database.
+
+*Example*
+
+```go
+func(c echo.Context) error {
+  encodedXML := []byte{} // Encoded XML from external source
+  return c.XMLBlob(http.StatusOK, encodedXML)
+}
+```
+
+## Send File
+
+`Context#File(file string)` can be used to send the content of file as response.
+It automatically sets the correct content type and handles caching gracefully.
+
+*Example*
+
+```go
+func(c echo.Context) error {
+  return c.File("<PATH_TO_YOUR_FILE>")
+}
+```
+
+## Send Attachment
+
+`Context#Attachment(file, name string)` is similar to `File()` except that it is
+used to send file as attachment with provided name.
+
+*Example*
+
+```go
+func(c echo.Context) error {
+  return c.Attachment("<PATH_TO_YOUR_FILE>")
+}
+```
+
+## Send Inline
+
+`Context#Inline(file, name string)` is similar to `File()` except that it is
+used to send file as inline with provided name.
+
+*Example*
+
+```go
+func(c echo.Context) error {
+  return c.Inline("<PATH_TO_YOUR_FILE>")
+}
+```
+
+## Send Blob
+
+`Context#Blob(code int, contentType string, b []byte)` can be used to send an arbitrary
+data response with provided content type and status code.
+
+*Example*
+
+```go
+func(c echo.Context) (err error) {
+  data := []byte(`0306703,0035866,NO_ACTION,06/19/2006
+	  0086003,"0005866",UPDATED,06/19/2006`)
+	return c.Blob(http.StatusOK, "text/csv", data)
+}
+```
+
+// Stream sends a streaming response with status code and content type.
+		Stream(code int, contentType string, r io.Reader) error
+
+## Send Stream
+
+`Context#Stream(code int, contentType string, r io.Reader)` can be used to send an
+arbitrary data stream response with provided content type, `io.Reader` and status
+code.
+
+*Example*
+
+```go
+func(c echo.Context) error {
+  f, err := os.Open("<PATH_TO_IMAGE>")
+  if err != nil {
+    return err
+  }
+  return c.Stream(http.StatusOK, "image/png", f)
+}
+```
+
+## Send No Content
+
+`Context#NoContent(code int)` can be used to send empty body with status code.
+
+*Example*
+
+```go
+func(c echo.Context) error {
+  return c.NoContent(http.StatusOK)
+}
+```
+
+## Redirect Request
+
+`Context#Redirect(code int, url string)` can be used to redirect the request to
+a provided URL with status code.
+
+*Example*
+
+```go
+func(c echo.Context) error {
+  return c.Redirect(http.StatusMovedPermanently, "<URL>")
+}
+```

website/content/recipes/auto-tls.md

@@ -10,7 +10,7 @@ description = "Automatic TLS certificates from Let's Encrypt example for Echo"
 This recipe shows how to obtain TLS certificates for a domain automatically from
 Let's Encrypt. `Echo#StartAutoTLS` accepts an address which should listen on port `443`.
 
-Browse to `https://<your_domain>`. If everything goes fine, you should see a welcome
+Browse to `https://<DOMAIN>`. If everything goes fine, you should see a welcome
 message with TLS enabled on the website.
 
 >