From e7875022d444800f4f0e9bb74568c91771045751 Mon Sep 17 00:00:00 2001
From: "Gerasimos (Makis) Maropoulos" <kataras2006@hotmail.com>
Date: Thu, 4 Jul 2019 06:05:51 +0300
Subject: [PATCH] add FileServer section

---
 File-server.md                                | 106 ++++++++++++++++++
 Home.md                                       |   3 +-
 ...-methods.md => Routing-override-context.md |   0
 _Sidebar.md                                   |   3 +-
 4 files changed, 110 insertions(+), 2 deletions(-)
 create mode 100644 File-server.md
 rename Routing-override-context-methods.md => Routing-override-context.md (100%)

diff --git a/File-server.md b/File-server.md
new file mode 100644
index 0000000..5fa7b73
--- /dev/null
+++ b/File-server.md
@@ -0,0 +1,106 @@
+Serve static files from a specific directory (system physical or embedded to the application) is done by the `Party.HandleDir` method.
+
+`HandleDir` registers a handler that serves HTTP requests
+with the contents of a file system (physical or embedded).
+
+* First parameter  : the route path
+* Second parameter : the system or the embedded directory that needs to be served
+* Third parameter  : not required, the directory options, set fields is optional.
+
+Returns the GET *Route.
+
+```go
+HandleDir(requestPath, directory string, opts ...DirOptions) (getRoute *Route)
+```
+
+The `DirOptions` structure looks like this:
+
+```go
+type DirOptions struct {
+    // Defaults to "/index.html", if request path is ending with **/*/$IndexName
+    // then it redirects to **/*(/) which another handler is handling it,
+    // that another handler, called index handler, is auto-registered by the framework
+    // if end developer wasn't managed to handle it manually/by hand.
+    IndexName string
+    // Should files served under gzip compression?
+    Gzip bool
+
+    // List the files inside the current requested directory if `IndexName` not found.
+    ShowList bool
+    // If `ShowList` is true then this function will be used instead
+    // of the default one to show the list of files of a current requested directory(dir).
+    DirList func(ctx context.Context, dirName string, dir http.File) error
+
+    // When embedded.
+    Asset      func(name string) ([]byte, error)   
+    AssetInfo  func(name string) (os.FileInfo, error)
+    AssetNames func() []string
+
+    // Optional validator that loops through each found requested resource.
+    AssetValidator func(ctx context.Context, name string) bool
+}
+```
+
+Let's say that you have an `./assets` folder near to your executable and you want the files to be served through `http://localhost:8080/static/**/*` route.
+
+```go
+app := iris.New()
+
+app.HandleDir("/static", "./assets")
+
+app.Run(iris.Addr(":8080"))
+```
+
+Now, if you want to embedd the static files inside the executable build and don't depend on a system directory you can use a tool like [go-bindata](https://github.com/go-bindata/go-bindata) to convert the files into `[]byte` inside your program. Let's take a quick tutorial on this and how Iris helps to serve those data.
+
+Install go-bindata:
+
+```sh
+go get -u github.com/go-bindata/go-bindata/...
+```
+
+Navigate to your system directory, let's say `./assets` and execute:
+
+```sh
+$ go-bindata ./assets/...
+```
+
+The above creates a genereated go file which contains three main functions: `Asset`, `AssetInfo` and `AssetNames`. Use them on the `DirOptions`:
+
+```go
+// [app := iris.New...]
+
+app.HandleDir("/static", "./assets", iris.DirOptions {
+    Asset: Asset,
+    AssetInfo: AssetInfo,
+    AssetNames: AssetNames,
+    Gzip: false,
+})
+```
+
+Build your app:
+
+```sh
+$ go build
+```
+
+The `HandleDir` supports all the standards, including content-range, for both physical and embedded directories.
+
+However, if you just need a handler to work with, without register a route, you can use the `iris.FileServer` package-level function instead.
+
+The `FileServer` function returns a Handler which serves files from a specific system, phyisical, directory or an embedded one.
+
+* First parameter:  is the directory.
+* Second parameter: optional parameter is any optional settings that the caller can use.
+
+```go
+iris.FileServer(directory string, options ...DirOptions)
+```
+
+**Usage**
+
+```go
+handler := iris.FileServer("./assets", iris.DirOptions {ShowList: true, Gzip: true, IndexName: "index.html"})
+```
+
+Examples can be found at: https://github.com/kataras/iris/tree/v11.2.0/_examples/file-server
diff --git a/Home.md b/Home.md
index f823fe6..135520b 100644
--- a/Home.md
+++ b/Home.md
@@ -17,9 +17,10 @@ This wiki is the main source of documentation for **developers** working with (o
     * [[Handle HTTP errors|Routing-error-handlers]]
     * [[Subdomains|Routing-subdomains]]
     * [[Wrap the Router|Routing-wrap-the-router]]
-    * [[Override Context Methods|Routing-override-context-methods]]
+    * [[Override Context|Routing-override-context]]
     * [[Dependency Injection|Routing-dependency-injection]]
 * [[API Versioning]]
+* [[File Server]]
 * [[Cookies]]
 
 > This new wiki is a `Work In Progress` in an effort to centralize the documentation and concepts explanation into a single place.
diff --git a/Routing-override-context-methods.md b/Routing-override-context.md
similarity index 100%
rename from Routing-override-context-methods.md
rename to Routing-override-context.md
diff --git a/_Sidebar.md b/_Sidebar.md
index a529906..9f15200 100644
--- a/_Sidebar.md
+++ b/_Sidebar.md
@@ -12,7 +12,8 @@
     * [[Handle HTTP errors|Routing-error-handlers]]
     * [[Subdomains|Routing-subdomains]]
     * [[Wrap the Router|Routing-wrap-the-router]]
-    * [[Override Context Methods|Routing-override-context-methods]]
+    * [[Override Context|Routing-override-context]]
     * [[Dependency Injection|Routing-dependency-injection]]
 * [[API Versioning]]
+* [[File Server]]
 * [[Cookies]]