|
| 1 | +# Middleware |
| 2 | + |
| 3 | +This guide gives an overview of the different Rack middleware used by Utopia. |
| 4 | + |
| 5 | +## Static |
| 6 | + |
| 7 | +The {ruby Utopia::Static} middleware services static files efficiently. By default, it works with `Rack::Sendfile` and supports `ETag` based caching. Normally, you'd prefer to put static files into `public/_static` but it's also acceptable to put static content into `pages/` if it makes sense. |
| 8 | + |
| 9 | +~~~ ruby |
| 10 | +use Utopia::Static, |
| 11 | + # The root path to serve files from: |
| 12 | + root: "path/to/root", |
| 13 | + # The mime-types to recognize/serve: |
| 14 | + types: [:default, :xiph], |
| 15 | + # Cache-Control header for files: |
| 16 | + cache_control: 'public, max-age=7200' |
| 17 | +~~~ |
| 18 | + |
| 19 | +## Redirection |
| 20 | + |
| 21 | +The {ruby Utopia::Redirection} middleware is used for redirecting requests based on patterns and status codes. |
| 22 | + |
| 23 | +~~~ ruby |
| 24 | +# String (fast hash lookup) rewriting: |
| 25 | +use Utopia::Redirection::Rewrite, |
| 26 | + '/' => '/welcome/index' |
| 27 | + |
| 28 | +# Redirect directories (e.g. /) to an index file (e.g. /index): |
| 29 | +use Utopia::Redirection::DirectoryIndex, |
| 30 | + index: 'index.html' |
| 31 | + |
| 32 | +# Redirect (error) status codes to actual pages: |
| 33 | +use Utopia::Redirection::Errors, |
| 34 | + 404 => '/errors/file-not-found' |
| 35 | +~~~ |
| 36 | + |
| 37 | +## Localization |
| 38 | + |
| 39 | +The {ruby Utopia::Localization} middleware provides non-intrusive localization on top of the controller and view layers. The middleware uses the `accept-language` header to guess the preferred locale out of the given options. If a request path maps to a resource, that resource is returned. Otherwise, a non-localized request is made. |
| 40 | + |
| 41 | +~~~ ruby |
| 42 | +use Utopia::Localization, |
| 43 | + :default_locale => 'en', |
| 44 | + :locales => ['en', 'de', 'ja', 'zh'] |
| 45 | +~~~ |
| 46 | + |
| 47 | +To localize a specific `xnode`, append the locale as a postfix: |
| 48 | + |
| 49 | +~~~ |
| 50 | +pages/index.xnode |
| 51 | +pages/index.de.xnode |
| 52 | +pages/index.ja.xnode |
| 53 | +pages/index.zh.xnode |
| 54 | +~~~ |
| 55 | + |
| 56 | +You can also access the current locale in the view via {ruby Utopia::Content::Node::Context#localization}. |
| 57 | + |
| 58 | +## Controller |
| 59 | + |
| 60 | +The {ruby Utopia::Controller} middleware provides flexible nested controllers with efficient behaviour. Controllers are nested in the `pages` directory and are matched against the incoming request path recursively, from outer most to inner most. |
| 61 | + |
| 62 | +```ruby |
| 63 | +use Utopia::Controller, |
| 64 | + # The root directory where `controller.rb` files can be found. |
| 65 | + root: "path/to/root", |
| 66 | + # The base class to use for all controllers: |
| 67 | + base: Utopia::Controller::Base |
| 68 | +``` |
| 69 | + |
| 70 | +A controller is a file within the specified root directory (typically `pages`) with the name `controller.rb`. This code is dynamically loaded into an anonymous class and executed. The default controller has only a single function: |
| 71 | + |
| 72 | +```ruby |
| 73 | +def passthrough(request, path) |
| 74 | + # Call one of: |
| 75 | + |
| 76 | + # This will cause the middleware to generate a response. |
| 77 | + # def respond!(response) |
| 78 | + |
| 79 | + # This will cause the controller to skip the request. |
| 80 | + # def ignore! |
| 81 | + |
| 82 | + # Request relative redirect. Respond with a redirect to the given target. |
| 83 | + # def redirect! (target, status = 302) |
| 84 | + |
| 85 | + # Controller relative redirect. |
| 86 | + # def goto!(target, status = 302) |
| 87 | + |
| 88 | + # Respond with an error which indiciates some kind of failure. |
| 89 | + # def fail!(error = 400, message = nil) |
| 90 | + |
| 91 | + # Succeed the request and immediately respond. |
| 92 | + # def succeed!(status: 200, headers: {}, **options) |
| 93 | + # options may include content: string or body: Enumerable (as per Rack specifications |
| 94 | + |
| 95 | + suceed! |
| 96 | +end |
| 97 | +``` |
| 98 | + |
| 99 | +The controller layer can do more complex operations by prepending modules into it. |
| 100 | + |
| 101 | +```ruby |
| 102 | +prepend Rewrite, Actions |
| 103 | + |
| 104 | +# Extracts an Integer |
| 105 | +rewrite.extract_prefix id: Integer do |
| 106 | + @user = User.find_by_id(@id) |
| 107 | +end |
| 108 | + |
| 109 | +on "edit" do |request, path| |
| 110 | + if request.post? |
| 111 | + @user.update_attributes(request[:user]) |
| 112 | + end |
| 113 | +end |
| 114 | + |
| 115 | +otherwise do |request, path| |
| 116 | + # Executed if no specific named actions were executed. |
| 117 | + succeed! |
| 118 | +end |
| 119 | +``` |
| 120 | + |
| 121 | +The incoming path is relative to the path of the controller itself. |
| 122 | + |
| 123 | +## Content |
| 124 | + |
| 125 | +The {ruby Utopia::Content} middleware parses XML-style templates with using attributes provided by the controller layer. Dynamic tags can be used to build modular content. |
| 126 | + |
| 127 | +~~~ ruby |
| 128 | +use Utopia::Content |
| 129 | +~~~ |
| 130 | + |
| 131 | +A basic template `create.xnode` looks something like: |
| 132 | + |
| 133 | +~~~trenni |
| 134 | +<content:page> |
| 135 | + <content:heading>Create User</content:heading> |
| 136 | + <form action="#"> |
| 137 | + <input name="name" /> |
| 138 | + <input type="submit" /> |
| 139 | + </form> |
| 140 | +</content:page> |
| 141 | +~~~ |
| 142 | + |
| 143 | +This template would typically be designed with supporting `_page.xnode` and `_heading.xnode` in the same directory or, more typically, somewhere further up the directory hierarchy. |
| 144 | + |
| 145 | +## Session |
| 146 | + |
| 147 | +The {ruby Utopia::Session} middleware provides session storage using encrypted client-side cookies. The session management uses symmetric private key encryption to store data on the client and avoid tampering. |
| 148 | + |
| 149 | +```ruby |
| 150 | +use Utopia::Session, |
| 151 | + expires_after: 3600 * 24, |
| 152 | + # The private key is retried from the `environment.yaml` file: |
| 153 | + secret: UTOPIA.secret_for(:session), |
| 154 | + secure: true |
| 155 | +``` |
| 156 | + |
| 157 | +All session data is stored on the client, but it's encrypted with a salt and the secret key. It is impossible for the client to decrypt the data without the secret stored on the server. |
0 commit comments