Skip to content

Commit

Permalink
Updates to Redirect configuration and documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
gaby committed Jul 16, 2024
1 parent 58d07f0 commit a19709a
Show file tree
Hide file tree
Showing 6 changed files with 322 additions and 153 deletions.
2 changes: 1 addition & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ format:

## format: 🎨 Find markdown format issues (Requires markdownlint-cli)
.PHONY: markdown
format:
markdown:
markdownlint-cli2 "**/*.md" "#vendor"

## lint: 🚨 Run lint checks
Expand Down
166 changes: 94 additions & 72 deletions docs/api/redirect.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,17 +6,16 @@ sidebar_position: 5
toc_max_heading_level: 5
---

Is used to redirect the ctx(request) to a different URL/Route.
Fiber's built-in redirect package provides methods to redirect the client to a different URL or route. This can be useful for various purposes, such as redirecting users after form submissions, handling outdated links, or structuring a more user-friendly navigation flow.

## Redirect Methods

### To

Redirects to the URL derived from the specified path, with specified [status](#status), a positive integer that
corresponds to an HTTP status code.
Redirects the client to the URL derived from the specified path, with an optional HTTP status code.

:::info
If **not** specified, status defaults to **302 Found**.
If the status is **not** specified, it defaults to **302 Found**.
:::

```go title="Signature"
Expand All @@ -25,34 +24,34 @@ func (r *Redirect) To(location string) error

```go title="Example"
app.Get("/coffee", func(c fiber.Ctx) error {
// => HTTP - GET 301 /teapot
return c.Redirect().Status(fiber.StatusMovedPermanently).To("/teapot")
// => HTTP - GET 301 /teapot
return c.Redirect().Status(fiber.StatusMovedPermanently).To("/teapot")
})

app.Get("/teapot", func(c fiber.Ctx) error {
return c.Status(fiber.StatusTeapot).Send("🍵 short and stout 🍵")
return c.Status(fiber.StatusTeapot).Send("🍵 short and stout 🍵")
})
```

```go title="More examples"
app.Get("/", func(c fiber.Ctx) error {
// => HTTP - GET 302 /foo/bar
return c.Redirect().To("/foo/bar")
// => HTTP - GET 302 ../login
return c.Redirect().To("../login")
// => HTTP - GET 302 http://example.com
return c.Redirect().To("http://example.com")
// => HTTP - GET 301 https://example.com
return c.Redirect().Status(301).To("http://example.com")
// => HTTP - GET 302 /foo/bar
return c.Redirect().To("/foo/bar")
// => HTTP - GET 302 ../login
return c.Redirect().To("../login")
// => HTTP - GET 302 http://example.com
return c.Redirect().To("http://example.com")
// => HTTP - GET 301 https://example.com
return c.Redirect().Status(301).To("http://example.com")
})
```

### Route

Redirects to the specific route along with the parameters and queries.
Redirects the client to a specific route, along with any parameters and queries.

:::info
If you want to send queries and params to route, you must use the [**RedirectConfig**](#redirectconfig) struct.
To send queries and parameters to the route, use the [**RedirectConfig**](#redirectconfig) struct.
:::

```go title="Signature"
Expand All @@ -61,40 +60,39 @@ func (r *Redirect) Route(name string, config ...RedirectConfig) error

```go title="Example"
app.Get("/", func(c fiber.Ctx) error {
// /user/fiber
return c.Redirect().Route("user", fiber.RedirectConfig{
Params: fiber.Map{
"name": "fiber",
},
})
// /user/fiber
return c.Redirect().Route("user", fiber.RedirectConfig{
Params: fiber.Map{
"name": "fiber",
},
})
})

app.Get("/with-queries", func(c fiber.Ctx) error {
// /user/fiber?data[0][name]=john&data[0][age]=10&test=doe
return c.Route("user", RedirectConfig{
Params: fiber.Map{
"name": "fiber",
},
Queries: map[string]string{
"data[0][name]": "john",
"data[0][age]": "10",
"test": "doe",
},
// /user/fiber?data[0][name]=john&data[0][age]=10&test=doe
return c.Route("user", RedirectConfig{
Params: fiber.Map{
"name": "fiber",
},
Queries: map[string]string{
"data[0][name]": "john",
"data[0][age]": "10",
"test": "doe",
},
})
})

app.Get("/user/:name", func(c fiber.Ctx) error {
return c.SendString(c.Params("name"))
return c.SendString(c.Params("name"))
}).Name("user")
```

### Back

Redirects back to refer URL. It redirects to fallback URL if refer header doesn't exists, with specified status, a
positive integer that corresponds to an HTTP status code.
Redirects the client back to the referring URL. If the referer header does not exist, it redirects to a specified fallback URL, with an optional HTTP status code.

:::info
If **not** specified, status defaults to **302 Found**.
If the status is **not** specified, it defaults to **302 Found**.
:::

```go title="Signature"
Expand All @@ -103,30 +101,30 @@ func (r *Redirect) Back(fallback string) error

```go title="Example"
app.Get("/", func(c fiber.Ctx) error {
return c.SendString("Home page")
return c.SendString("Home page")
})
app.Get("/test", func(c fiber.Ctx) error {
c.Set("Content-Type", "text/html")
return c.SendString(`<a href="/back">Back</a>`)
c.Set("Content-Type", "text/html")
return c.SendString(`<a href="/back">Back</a>`)
})

app.Get("/back", func(c fiber.Ctx) error {
return c.Redirect().Back("/")
return c.Redirect().Back("/")
})
```

## Controls

:::info
Method are **chainable**.
The control methods are **chainable**.
:::

### Status

Sets the HTTP status code for the redirect.

:::info
Is used in conjunction with [**To**](#to), [**Route**](#route) and [**Back**](#back) methods.
This method is used in conjunction with [**To**](#to), [**Route**](#route) and [**Back**](#back) methods.
:::

```go title="Signature"
Expand All @@ -135,14 +133,14 @@ func (r *Redirect) Status(status int) *Redirect

```go title="Example"
app.Get("/coffee", func(c fiber.Ctx) error {
// => HTTP - GET 301 /teapot
return c.Redirect().Status(fiber.StatusMovedPermanently).To("/teapot")
// => HTTP - GET 301 /teapot
return c.Redirect().Status(fiber.StatusMovedPermanently).To("/teapot")
})
```

### RedirectConfig

Sets the configuration for the redirect.
Sets the configuration for the redirect, including route parameters, query strings and cookie configuration.

:::info
Is used in conjunction with the [**Route**](#route) method.
Expand All @@ -151,100 +149,124 @@ Is used in conjunction with the [**Route**](#route) method.
```go
// RedirectConfig A config to use with Redirect().Route()
type RedirectConfig struct {
Params fiber.Map // Route parameters
Queries map[string]string // Query map
Params fiber.Map // Route parameters
Queries map[string]string // Query map
CookieConfig CookieConkie // Cookie configuration
}
```

### Cookie Configuration

The `CookieConfig` struct holds the configuration for cookies used in redirects, particularly for flash messages and old input data.

```go
type CookieConfig struct {
Name string
HTTPOnly bool
Secure bool
SameSite string
}
```

#### Default Configuration

The default cookie configuration is as follows:

```go
var CookieConfigDefault = CookieConfig{
Name: "fiber_flash",
HTTPOnly: true,
Secure: false,
SameSite: "Lax",
}
```

### Flash Message

Similar to [Laravel](https://laravel.com/docs/11.x/redirects#redirecting-with-flashed-session-data) we can flash a message and retrieve it in the next request.
Similar to [Laravel](https://laravel.com/docs/11.x/redirects#redirecting-with-flashed-session-data), Fiber allows you to flash messages and retrieve them in the next request.

#### Messages

Get flash messages. Check [With](#with) for more information.
Retrieves all the messages.

```go title="Signature"
func (r *Redirect) Messages() map[string]string
```

```go title="Example"
app.Get("/", func(c fiber.Ctx) error {
messages := c.Redirect().Messages()
return c.JSON(messages)
messages := c.Redirect().Messages()
return c.JSON(messages)
})
```

#### Message

Get flash message by key. Check [With](#with) for more information.
Retrieve a flash message by key.

```go title="Signature"
func (r *Redirect) Message(key string) *Redirect
```

```go title="Example"
app.Get("/", func(c fiber.Ctx) error {
message := c.Redirect().Message("status")
return c.SendString(message)
message := c.Redirect().Message("status")
return c.SendString(message)
})
```

#### OldInputs

Get old input data. Check [WithInput](#withinput) for more information.
Retrieves all old input data.

```go title="Signature"
func (r *Redirect) OldInputs() map[string]string
```

```go title="Example"
app.Get("/", func(c fiber.Ctx) error {
oldInputs := c.Redirect().OldInputs()
return c.JSON(oldInputs)
oldInputs := c.Redirect().OldInputs()
return c.JSON(oldInputs)
})
```

#### OldInput

Get old input data by key. Check [WithInput](#withinput) for more information.
Retrieves old input data by key.

```go title="Signature"
func (r *Redirect) OldInput(key string) string
```

```go title="Example"
app.Get("/name", func(c fiber.Ctx) error {
oldInput := c.Redirect().OldInput("name")
return c.SendString(oldInput)
soldInput := c.Redirect().OldInput("name")
return c.SendString(oldInput)
})
```

#### With

You can send flash messages by using `With()`.
Sends flash messages using `With()`.

```go title="Signature"
func (r *Redirect) With(key, value string) *Redirect
```

```go title="Example"
app.Get("/login", func(c fiber.Ctx) error {
return c.Redirect().With("status", "Logged in successfully").To("/")
return c.Redirect().With("status", "Logged in successfully").To("/")
})

app.Get("/", func(c fiber.Ctx) error {
// => Logged in successfully
return c.SendString(c.Redirect().Message("status"))
// => Logged in successfully
return c.SendString(c.Redirect().Message("status"))
})
```

#### WithInput

You can send input data by using `WithInput()`.
They will be sent as a cookie.

This method can send form, multipart form, query data to redirected route depending on the request content type.
Sends input data using `WithInput()`. This method can send form, multipart form, or query data to the redirected route, depending on the request content type. The default backend is using cookies.

```go title="Signature"
func (r *Redirect) WithInput() *Redirect
Expand All @@ -253,11 +275,11 @@ func (r *Redirect) WithInput() *Redirect
```go title="Example"
// curl -X POST http://localhost:3000/login -d "name=John"
app.Post("/login", func(c fiber.Ctx) error {
return c.Redirect().WithInput().Route("name")
return c.Redirect().WithInput().Route("name")
})

app.Get("/name", func(c fiber.Ctx) error {
// => John
return c.SendString(c.Redirect().OldInput("name"))
// => John
return c.SendString(c.Redirect().OldInput("name"))
}).Name("name")
```
Loading

0 comments on commit a19709a

Please sign in to comment.