From 248be0938c477e137de672f80ac3f156e6a404ec Mon Sep 17 00:00:00 2001 From: Pablo M Date: Mon, 16 Oct 2023 17:02:26 +0200 Subject: [PATCH 1/5] docs: add routing cheatsheet --- guides/cheatsheets/routing.cheatmd | 83 ++++++++++++++++++++++++++++++ mix.exs | 2 + 2 files changed, 85 insertions(+) create mode 100644 guides/cheatsheets/routing.cheatmd diff --git a/guides/cheatsheets/routing.cheatmd b/guides/cheatsheets/routing.cheatmd new file mode 100644 index 0000000000..dbba02624d --- /dev/null +++ b/guides/cheatsheets/routing.cheatmd @@ -0,0 +1,83 @@ +# Routing cheatsheet + +> Those need to be declared in the correct router module and scope. + +A quick reference to the common routing features' syntax. For an exhaustive overview, refer to the [routing guides](routing-1.html). + +## Routing declaration +{: .col-2} + +### Single route + +```elixir +get "/users", UserController, :index +patch "/users/:id", UserController, :update +``` +```elixir +# generated path helpers +user_path(conn, :index) # /users +user_path(conn, :create, %{id: 9, ...}) # /users/9 +``` +Also accepts `put`, `patch`, `options`, `delete` and `head`. + +### Resources + +#### Simple + +```elixir +resources "/users", UserController +``` +Generates `:index`, `:edit`, `:new`, `:show`, `:create`, `:update` and `:delete`. + +#### Options + +```elixir +resources "/users", UserController, only: [:show] +resources "/users", UserController, except: [:create, :delete] +resources "/users", UserController, as: :person # `person_path(...)` +``` + +#### Nested + +```elixir +resources "/users", UserController do + resources "/posts", PostController +end +``` +```elixir +# generated path helpers +user_post_path(:index, 17) # /users/17/posts +user_post_path(:show, 17, 12) # /users/17/posts/12 +``` +For more info check the [resources docs.](routing-1.html#resources) + +### Scopes + +#### Simple +```elixir +scope "/admin", HelloWeb.Admin do + pipe_through :browser + + resources "/users", UserController +end +``` +```elixir +# generated path helpers +admin_user_path(:index) # /admin/users +``` + +#### Nested +```elixir +scope "/api", HelloWeb.Api, as: :api do + pipe_through :api + + scope "/v1", V1, as: :v1 do + resources "/users", UserController + end +end +``` +```elixir +# generated path helpers +api_v1_user_path(:index) # /api/v1/users +``` +For more info check the [scoped routes](routing-1.html#scoped-routes) docs. diff --git a/mix.exs b/mix.exs index d7dba14ee9..4705959ffd 100644 --- a/mix.exs +++ b/mix.exs @@ -171,6 +171,7 @@ defmodule Phoenix.MixProject do "guides/howto/file_uploads.md", "guides/howto/using_ssl.md", "guides/howto/writing_a_channels_client.md", + "guides/cheatsheets/routing.cheatmd", "CHANGELOG.md" ] end @@ -182,6 +183,7 @@ defmodule Phoenix.MixProject do Authentication: ~r/guides\/authentication\/.?/, "Real-time": ~r/guides\/real_time\/.?/, Testing: ~r/guides\/testing\/.?/, + Cheatsheets: ~r/guides\/cheatsheets\/.?/, Deployment: ~r/guides\/deployment\/.?/, "How-to's": ~r/guides\/howto\/.?/ ] From 21d0d3f9ff2312139f130754e3222abbea70eabf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Valim?= Date: Tue, 24 Oct 2023 08:38:29 +0200 Subject: [PATCH 2/5] Update mix.exs --- mix.exs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mix.exs b/mix.exs index 4705959ffd..56d75b1451 100644 --- a/mix.exs +++ b/mix.exs @@ -183,8 +183,8 @@ defmodule Phoenix.MixProject do Authentication: ~r/guides\/authentication\/.?/, "Real-time": ~r/guides\/real_time\/.?/, Testing: ~r/guides\/testing\/.?/, - Cheatsheets: ~r/guides\/cheatsheets\/.?/, Deployment: ~r/guides\/deployment\/.?/, + Cheatsheets: ~r/guides\/cheatsheets\/.?/, "How-to's": ~r/guides\/howto\/.?/ ] end From 6568a527db95e00e60837dd44067a74d7b2e87f3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Valim?= Date: Tue, 24 Oct 2023 08:40:16 +0200 Subject: [PATCH 3/5] Update and rename routing.cheatmd to router.cheatmd --- guides/cheatsheets/{routing.cheatmd => router.cheatmd} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename guides/cheatsheets/{routing.cheatmd => router.cheatmd} (96%) diff --git a/guides/cheatsheets/routing.cheatmd b/guides/cheatsheets/router.cheatmd similarity index 96% rename from guides/cheatsheets/routing.cheatmd rename to guides/cheatsheets/router.cheatmd index dbba02624d..97e82a0e31 100644 --- a/guides/cheatsheets/routing.cheatmd +++ b/guides/cheatsheets/router.cheatmd @@ -2,7 +2,7 @@ > Those need to be declared in the correct router module and scope. -A quick reference to the common routing features' syntax. For an exhaustive overview, refer to the [routing guides](routing-1.html). +A quick reference to the common routing features' syntax. For an exhaustive overview, refer to the [routing guides](routing.md). ## Routing declaration {: .col-2} From 6898bc6173510ca68543538fdf3e5d94314813ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Valim?= Date: Tue, 24 Oct 2023 08:40:55 +0200 Subject: [PATCH 4/5] Apply suggestions from code review --- guides/cheatsheets/router.cheatmd | 2 +- mix.exs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/guides/cheatsheets/router.cheatmd b/guides/cheatsheets/router.cheatmd index 97e82a0e31..44998fc192 100644 --- a/guides/cheatsheets/router.cheatmd +++ b/guides/cheatsheets/router.cheatmd @@ -80,4 +80,4 @@ end # generated path helpers api_v1_user_path(:index) # /api/v1/users ``` -For more info check the [scoped routes](routing-1.html#scoped-routes) docs. +For more info check the [scoped routes](routing.md#scoped-routes) docs. diff --git a/mix.exs b/mix.exs index 56d75b1451..5557199d74 100644 --- a/mix.exs +++ b/mix.exs @@ -171,7 +171,7 @@ defmodule Phoenix.MixProject do "guides/howto/file_uploads.md", "guides/howto/using_ssl.md", "guides/howto/writing_a_channels_client.md", - "guides/cheatsheets/routing.cheatmd", + "guides/cheatsheets/router.cheatmd", "CHANGELOG.md" ] end From d295bdda4ae5ed4d1eb5752a31a9a21fc5b983e4 Mon Sep 17 00:00:00 2001 From: Pablo M Date: Tue, 31 Oct 2023 10:52:12 +0100 Subject: [PATCH 5/5] docs: replace router helper with verified routes --- guides/cheatsheets/router.cheatmd | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/guides/cheatsheets/router.cheatmd b/guides/cheatsheets/router.cheatmd index 44998fc192..1f0af13e72 100644 --- a/guides/cheatsheets/router.cheatmd +++ b/guides/cheatsheets/router.cheatmd @@ -14,9 +14,9 @@ get "/users", UserController, :index patch "/users/:id", UserController, :update ``` ```elixir -# generated path helpers -user_path(conn, :index) # /users -user_path(conn, :create, %{id: 9, ...}) # /users/9 +# generated routes +~p"/users" +~p"/users/9" # user_id is 9 ``` Also accepts `put`, `patch`, `options`, `delete` and `head`. @@ -34,7 +34,7 @@ Generates `:index`, `:edit`, `:new`, `:show`, `:create`, `:update` and `:delete` ```elixir resources "/users", UserController, only: [:show] resources "/users", UserController, except: [:create, :delete] -resources "/users", UserController, as: :person # `person_path(...)` +resources "/users", UserController, as: :person # ~p"/person" ``` #### Nested @@ -45,9 +45,9 @@ resources "/users", UserController do end ``` ```elixir -# generated path helpers -user_post_path(:index, 17) # /users/17/posts -user_post_path(:show, 17, 12) # /users/17/posts/12 +# generated routes +~p"/users/3/posts" # user_id is 3 +~p"/users/3/posts/17" # user_id is 3 and post_id = 17 ``` For more info check the [resources docs.](routing-1.html#resources) @@ -63,7 +63,7 @@ end ``` ```elixir # generated path helpers -admin_user_path(:index) # /admin/users +~p"/admin/users" ``` #### Nested @@ -78,6 +78,6 @@ end ``` ```elixir # generated path helpers -api_v1_user_path(:index) # /api/v1/users +~p"/api/v1/users" ``` For more info check the [scoped routes](routing.md#scoped-routes) docs.