From bd7d6864084a5a49d429a415498935c666f324c6 Mon Sep 17 00:00:00 2001 From: Kip Cole Date: Sun, 24 Jul 2022 10:15:31 +0800 Subject: [PATCH] Update readme to show example hreflang usage --- README.md | 76 +++++++++++++++++++++++++++++++++++++++++++++++-------- mix.exs | 2 +- 2 files changed, 66 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 7fb7e48..04e9707 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,7 @@ end Now we can configure the router module to use the `localize/1` macro by adding `use MyApp.Cldr.Routes` to the module and invoke the `localize/1` macro to wrap the required routes. `use MyApp.Cldr.Routes` must be added *after* `use Phoenix.Router`. For example: ```elixir -defmodule MyApp.Router do +defmodule MyAppWeb.Router do use Phoenix.Router use MyApp.Cldr.Routes @@ -109,7 +109,7 @@ iex> MyApp.Router.LocalizedHelpers.page_path %Plug.Conn{}, :show, 1 "/pages/1" iex> MyApp.Cldr.put_locale("fr") iex> MyApp.Router.LocalizedHelpers.page_path %Plug.Conn{}, :show, 1 -"/pages_fr/1 +"/pages_fr/1" ``` *Note* The localized helpers translate the path based upon the `:gettext_locale_name` for the currently set `Cldr` locale. It is the developers responsibility to ensure that the locale is set appropriately before calling any localized path helpers. @@ -119,7 +119,7 @@ iex> MyApp.Router.LocalizedHelpers.page_path %Plug.Conn{}, :show, 1 For convenience in introspecting routes, a module called `MyApp.Router.LocalizedRoutes` is generated that can be used with the `mix phx.routes` mix task. For example: ```bash -% cldr_routes % mix phx.routes MyApp.Router.LocalizedRoutes +% cldr_routes % mix phx.routes MyAppWeb.Router.LocalizedRoutes page_path GET /pages_de/:page PageController :show page_path GET /pages/:page PageController :show page_path GET /pages_fr/:page PageController :show @@ -139,7 +139,7 @@ This information is also used by functions in the [ex_cldr_plugs](https://hex.pm ### Configuring Localized Helpers as default -Since `LocalizedHelpers` have the same semantics and API as the standard `Helpers` module it is possible to update the generated Phoenix configuration to use the `LocalizedHelpers` module by default. Assuming the presence of `myapp_web.ex` defining the module `MyAppWeb` then changing the `view_helpers` function from: +Since `LocalizedHelpers` have the same semantics and API as the standard `Helpers` module it is possible to update the generated Phoenix configuration to use the `LocalizedHelpers` module by default. Assuming the presence of `myapp_web.ex` defining the module `MyAppWeb` then changing the `view_helpers` function to: ```elixir defp view_helpers do quote do @@ -147,23 +147,77 @@ defp view_helpers do import MyAppWeb.ErrorHelpers import MyAppWeb.Gettext - alias MyAppWeb.Router.Helpers, as: Routes + alias MyAppWeb.Router.LocalizedHelpers, as: Routes end end ``` -to +will result in the automatic use of the localized helpers rather than the standard helpers. + +The `contoller/0` function should similarly be updated: + ```elixir -defp view_helpers do +def controller do quote do - ... + use Phoenix.Controller, namespace: MyAppWeb - import MyAppWeb.ErrorHelpers + import Plug.Conn import MyAppWeb.Gettext alias MyAppWeb.Router.LocalizedHelpers, as: Routes end end ``` -will result in the automatic use of the localized helpers rather than the standard helpers. + +## Generating link headers + +When the same content is produced in multiple languages it is important to cross-link the different editions of the content to each other. This is good practise in general but strong advised by [goggle](https://developers.google.com/search/docs/advanced/crawling/localized-versions) to reduce SEO risks for your site. + +This cross-linking can be done with the aid of HTTP headers or with `` tags in the `` section of an HTML document. Helpers are generated by `ex_cldr_routes` to facilitate the creating of these links. These functions are generated in the `MyApp.Router.LocalizedHelpers` module (where `MyApp.Router` is the name of your Phoenix router module). + +* `MyApp.Router.LocalizedHelpers._links` generated a mapping of locales for a given route to the URLs for those locales. +* `MyApp.Router.LocalizedHelpers.hreflang_links/1` take the generated map and produces link headers ready for insertion into an HTML document. + +The functions can be used as follows: + +* Update the controller to generate the links and add them to `:assigns` +```elixir +defmodule MyAppWeb.UserController do + use MyAppWeb, :controller + + # This alias would normally be set in the + # MyAppWeb.controller/0 and MyAppWeb.view_helpers/0 + # functions + alias MyAppWeb.Router.LocalizedHelpers, as: Routes + + alias MyApp.Accounts + alias MyApp.Accounts.User + + def show(conn, %{"id" => id}) do + user = Accounts.get_user!(id) + hreflang_links = Routes.user_links(conn, :show, id) + render(conn, "show.html", user: user, hreflang_links: hreflang_links) + end +end +``` + +* Update the root layout to add the hreflang links +```html + + + + + + <%= Routes.hreflang_links(assigns[:hreflang_links]) %> + <%= csrf_meta_tag() %> + <%= live_title_tag assigns[:page_title] || "Routing", suffix: " ยท Phoenix Framework" %> + + + + + ... + <%= @inner_content %> + + +``` ## Translations @@ -195,7 +249,7 @@ The package can be installed by adding `ex_cldr_routes` to your list of dependen ```elixir def deps do [ - {:ex_cldr_routes, "~> 0.5.0"} + {:ex_cldr_routes, "~> 0.6.0"} ] end ``` diff --git a/mix.exs b/mix.exs index 778ee96..cf96574 100644 --- a/mix.exs +++ b/mix.exs @@ -24,7 +24,7 @@ defmodule CldrRoutes.MixProject do docs: docs(), dialyzer: [ ignore_warnings: ".dialyzer_ignore_warnings", - plt_add_apps: ~w(jason mix phoenix_live_view)a + plt_add_apps: ~w(jason mix phoenix_live_view phoenix_html)a ] ] end