Update readme to show example hreflang usage

elixir-cldr · Jul 24, 2022 · bd7d686 · bd7d686
1 parent 95e10b5
commit bd7d686
Show file tree

Hide file tree

Showing 2 changed files with 66 additions and 12 deletions.
diff --git 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,31 +139,85 @@ 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
     ...
 
     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 `<link />` tags in the `<head>` 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.<helper>_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
+<html lang="en">
+  <head>
+    <meta charset="utf-8"/>
+    <meta http-equiv="X-UA-Compatible" content="IE=edge"/>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
+    <%= Routes.hreflang_links(assigns[:hreflang_links]) %>
+    <%= csrf_meta_tag() %>
+    <%= live_title_tag assigns[:page_title] || "Routing", suffix: " · Phoenix Framework" %>
+    <link phx-track-static rel="stylesheet" href={Routes.static_path(@conn, "/assets/app.css")}/>
+    <script defer phx-track-static type="text/javascript" src={Routes.static_path(@conn, "/assets/app.js")}></script>
+  </head>
+  <body>
+    ...
+    <%= @inner_content %>
+  </body>
+</html>
+```
 
 ## 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
@@ -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