Add notes for the new lead maintainer of the open-source iris project and align with @get-ion/ion by @hiveminded

Former-commit-id: da4f38eb9034daa49446df3ee529423b98f9b331

_examples/http_responsewriter/README.md

@@ -0,0 +1 @@
+The `context.ResponseWriter()` returns an enchament version of a http.ResponseWriter, the examples show some places where the Context uses this object. Besides that you can use it as you did before iris.

_examples/http_responsewriter/stream-writer/main.go

@@ -0,0 +1,52 @@
+package main
+
+import (
+	"fmt" // just an optional helper
+	"io"
+	"time" // showcase the delay
+
+	"github.com/kataras/iris"
+	"github.com/kataras/iris/context"
+)
+
+func main() {
+	app := iris.New()
+
+	timeWaitForCloseStream := 4 * time.Second
+
+	app.Get("/", func(ctx context.Context) {
+		i := 0
+		// goroutine in order to no block and just wait,
+		// goroutine is OPTIONAL and not a very good option but it depends on the needs
+		// Look the streaming_simple_2 for an alternative code style
+		// Send the response in chunks and wait for a second between each chunk.
+		go ctx.StreamWriter(func(w io.Writer) bool {
+			i++
+			fmt.Fprintf(w, "this is a message number %d\n", i) // write
+			time.Sleep(time.Second)                            // imaginary delay
+			if i == 4 {
+				return false // close and flush
+			}
+			return true // continue write
+		})
+
+		// when this handler finished the client should be see the stream writer's contents
+		// simulate a job here...
+		time.Sleep(timeWaitForCloseStream)
+	})
+
+	app.Get("/alternative", func(ctx context.Context) {
+		// Send the response in chunks and wait for a second between each chunk.
+		ctx.StreamWriter(func(w io.Writer) bool {
+			for i := 1; i <= 4; i++ {
+				fmt.Fprintf(w, "this is a message number %d\n", i) // write
+				time.Sleep(time.Second)
+			}
+
+			// when this handler finished the client should be see the stream writer's contents
+			return false // stop and flush the contents
+		})
+	})
+
+	app.Run(iris.Addr(":8080"))
+}

_examples/http_responsewriter/transactions/main.go

@@ -0,0 +1,54 @@
+package main
+
+import (
+	"github.com/kataras/iris"
+	"github.com/kataras/iris/context"
+)
+
+func main() {
+	app := iris.New()
+
+	// subdomains works with all available routers, like other features too.
+
+	app.Get("/", func(ctx context.Context) {
+		ctx.BeginTransaction(func(t *context.Transaction) {
+			// OPTIONAl STEP: , if true then the next transictions will not be executed if this transiction fails
+			// t.SetScope(context.RequestTransactionScope)
+
+			// OPTIONAL STEP:
+			// create a new custom type of error here to keep track of the status code and reason message
+			err := context.NewTransactionErrResult()
+
+			// we should use t.Context if we want to rollback on any errors lives inside this function clojure.
+			t.Context().Text("Blablabla this should not be sent to the client because we will fill the err with a message and status")
+
+			// virtualize a fake error here, for the shake of the example
+			fail := true
+			if fail {
+				err.StatusCode = iris.StatusInternalServerError
+				// NOTE: if empty reason then the default or the custom http error will be fired (like ctx.FireStatusCode)
+				err.Reason = "Error: Virtual failure!!"
+			}
+
+			// OPTIONAl STEP:
+			// but useful if we want to post back an error message to the client if the transaction failed.
+			// if the reason is empty then the transaction completed successfully,
+			// otherwise we rollback the whole response writer's body,
+			// headers and cookies, status code and everything lives inside this transaction
+			t.Complete(err)
+		})
+
+		ctx.BeginTransaction(func(t *context.Transaction) {
+			t.Context().HTML("<h1>This will sent at all cases because it lives on different transaction and it doesn't fails</h1>")
+			// * if we don't have any 'throw error' logic then no need of scope.Complete()
+		})
+
+		// OPTIONALLY, depends on the usage:
+		// at any case, what ever happens inside the context's transactions send this to the client
+		ctx.HTML("<h1>Let's add a second html message to the response, " +
+			"if the transaction was failed and it was request scoped then this message would " +
+			"not been shown. But it has a transient scope(default) so, it is visible as expected!</h1>")
+	})
+
+	app.Run(iris.Addr(":8080"))
+}

_examples/http_responsewriter/write-rest/main.go

@@ -0,0 +1,87 @@
+package main
+
+import (
+	"encoding/xml"
+
+	"github.com/kataras/iris"
+	"github.com/kataras/iris/context"
+)
+
+// User bind struct
+type User struct {
+	Firstname string `json:"firstname"`
+	Lastname  string `json:"lastname"`
+	City      string `json:"city"`
+	Age       int    `json:"age"`
+}
+
+// ExampleXML just a test struct to view represents xml content-type
+type ExampleXML struct {
+	XMLName xml.Name `xml:"example"`
+	One     string   `xml:"one,attr"`
+	Two     string   `xml:"two,attr"`
+}
+
+func main() {
+	app := iris.New()
+
+	// Read
+	app.Post("/decode", func(ctx context.Context) {
+		var user User
+		ctx.ReadJSON(&user)
+
+		ctx.Writef("%s %s is %d years old and comes from %s!", user.Firstname, user.Lastname, user.Age, user.City)
+	})
+
+	// Write
+	app.Get("/encode", func(ctx context.Context) {
+		peter := User{
+			Firstname: "John",
+			Lastname:  "Doe",
+			City:      "Neither FBI knows!!!",
+			Age:       25,
+		}
+
+		ctx.StatusCode(iris.StatusOK)
+		// Manually setting a content type: ctx.ContentType("application/javascript")
+		ctx.JSON(peter)
+	})
+
+	// Other content types,
+
+	app.Get("/binary", func(ctx context.Context) {
+		// useful when you want force-download of contents of raw bytes form.
+		ctx.Binary([]byte("Some binary data here."))
+	})
+
+	app.Get("/text", func(ctx context.Context) {
+		ctx.Text("Plain text here")
+	})
+
+	app.Get("/json", func(ctx context.Context) {
+		ctx.JSON(map[string]string{"hello": "json"}) // or myjsonStruct{hello:"json}
+	})
+
+	app.Get("/jsonp", func(ctx context.Context) {
+		ctx.JSONP(map[string]string{"hello": "jsonp"}, context.JSONP{Callback: "callbackName"})
+	})
+
+	app.Get("/xml", func(ctx context.Context) {
+		ctx.XML(ExampleXML{One: "hello", Two: "xml"}) // or context.Map{"One":"hello"...}
+	})
+
+	app.Get("/markdown", func(ctx context.Context) {
+		ctx.Markdown([]byte("# Hello Dynamic Markdown -- iris"))
+	})
+
+	// http://localhost:8080/decode
+	// http://localhost:8080/encode
+	//
+	// http://localhost:8080/binary
+	// http://localhost:8080/text
+	// http://localhost:8080/json
+	// http://localhost:8080/jsonp
+	// http://localhost:8080/xml
+	// http://localhost:8080/markdown
+	app.Run(iris.Addr(":8080"))
+}