brut 0.0.29 → 0.2.0

data/docs/assets/forms.md.B-koVgyw.lean.js

@@ -1 +0,0 @@
-import{_ as i,c as a,o as n,ag as t}from"./chunks/framework.1L-BeKqY.js";const g=JSON.parse('{"title":"Forms","description":"","frontmatter":{},"headers":[],"relativePath":"forms.md","filePath":"forms.md"}'),e={name:"forms.md"};function l(h,s,p,k,r,d){return n(),a("div",null,s[0]||(s[0]=[t("",164)]))}const E=i(e,[["render",l]]);export{g as __pageData,E as default};

data/docs/assets/handlers.md.089DVD3v.js

@@ -1,69 +0,0 @@
-import{_ as i,c as a,o as e,ag as n}from"./chunks/framework.1L-BeKqY.js";const c=JSON.parse('{"title":"Handlers & Actions","description":"","frontmatter":{},"headers":[],"relativePath":"handlers.md","filePath":"handlers.md"}'),t={name:"handlers.md"};function h(l,s,p,r,k,d){return e(),a("div",null,s[0]||(s[0]=[n(`<h1 id="handlers-actions" tabindex="-1">Handlers &amp; Actions <a class="header-anchor" href="#handlers-actions" aria-label="Permalink to &quot;Handlers &amp; Actions&quot;">​</a></h1><p>Handlers process form submissions, and <em>actions</em> work similarly to process any arbitrary HTTP request.</p><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to &quot;Overview&quot;">​</a></h2><p>Where a <a href="/pages.html">page</a> renders a web page in HTML, a <em>handler</em> responds to all other HTTP requests. To respond to such HTTP requests, you&#39;d first create a <a href="/routes.html">route</a>, using <code>form</code>, <code>action</code>, or <code>path</code>.</p><h3 id="declaring-routes" tabindex="-1">Declaring Routes <a class="header-anchor" href="#declaring-routes" aria-label="Permalink to &quot;Declaring Routes&quot;">​</a></h3><p><code>form</code> and <code>action</code> are intended to be used when an HTTP form is being submitted. The latter—<code>action</code>—is for when your form has no user-editable elements. This is akin to Rails&#39; <code>button_to</code> helper, where the contents of the URL contains everything needed to service the request.</p><p><code>path</code> is for arbitrary HTTP requests and methods, so to create a webhook that responds to a PUT, you&#39;d use:</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># inside app/src/app.rb</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">path </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;/webhooks/stripe&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">method:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> :put</span></span></code></pre></div><p>In all cases, the class to receive and process these requests is a handler, whose name is conventional based on the route. For example, the webhook above would be handled by <code>Webhooks::StripeHandler</code>.</p><h3 id="implementing-handlers" tabindex="-1">Implementing Handlers <a class="header-anchor" href="#implementing-handlers" aria-label="Permalink to &quot;Implementing Handlers&quot;">​</a></h3><p>A handler works like a page, in that its initializer can receive any injectible arguments. These would include a form object, dynamic elements of the route, or anything else available from the request. See <a href="/keyword-injection.html">Keyword Injection</a> for the details, noting that your handler can be inejcted with custom objects you&#39;ve configured in a route hook.</p><p>After the handler is created, it&#39;s <code>before_handle</code> method is called. If it returns <code>nil</code>, <code>handle</code> is called to trigger whatever logic the handler needs to trigger.</p><p>Both <code>handle</code> and <code>before_handle</code> can return a variety of objects that determine what will happen:</p><ul><li>An instance of a page or component means that page or component is rendered. This is not a redirect to the page, so it is more like Rails&#39; <code>render :new</code> and <strong>not</strong> a <code>redirect_to(new_widgets_path)</code>.</li><li>A <a href="/api/Brut/FrontEnd/HttpStatus.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::HttpStatus</code></a> which sends that status and an empty body back. This object can be created from an integer using the <code>http_status</code> helper, available to all handlers.</li><li>A <code>URI</code>, which will cause a redirect to that URI. You can create the <code>URI</code> yourself, or use the helper <code>redirect_to</code>, which accepts a string.</li><li>A two-element array with a page or component as the first element and an <a href="/api/Brut/FrontEnd/HttpStatus.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::HttpStatus</code></a> as the second. This will render that page or component&#39;s HTML, but use the given status instead of 200. This can be useful for Ajax requests where you want to use HTML your respond format, but also, say, a 422 status to indicate a constraint violation has occured.</li><li>A <a href="/api/Brut/FrontEnd/Download.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Download</code></a>, which encapsulates a file to be downloaded.</li><li>A <a href="/api/Brut/FrontEnd/GenericResponse.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::GenericResponse</code></a>, which wraps any Rack response with a defined type.</li></ul><p><code>before_handle</code> may also return <code>nil</code> to indicate that <code>handle</code> should be called. <code>handle</code> may not return <code>nil</code>.</p><p>Supposing our <code>LoginForm</code> and <code>LoginHandler</code> wanted to use a common pattern of re-rendering <code>LoginPage</code> on constraint violations, and forwarding on to, say, a <code>DashboardPage</code>. Your handler might look like so:</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># app/src/front_end/handlers/login_handler.rb</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">class</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> LoginHandler</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> AppHandler</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> initialize</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">form:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">session:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># We&#39;ll discuss the session later</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    @form    </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> form</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    @session </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> session</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> handle</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    if</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> !</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">@form.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">constraint_violations?</span></span>
-<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">      authorized_user</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> = </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">AuthorizedUser</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">login</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">        email:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> form.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">email</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">        password:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> form.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">password</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      )</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> authorized_user.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">nil?</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        @form.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">server_side_constraint_violation</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">          input_name:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> :email</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">          key:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> :login_not_found</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        )</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      else</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        session.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">authorized_user</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> authorized_user</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    end</span></span>
-<span class="line highlighted"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> @form.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">constraint_violations?</span></span>
-<span class="line highlighted"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      LoginPage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">new</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">form:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> @form)</span></span>
-<span class="line highlighted"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    else</span></span>
-<span class="line highlighted"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">      redirect_to</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">DashboardPage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">routing</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
-<span class="line highlighted"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><div class="important custom-block github-alert"><p class="custom-block-title">IMPORTANT</p><p>The only way to render something other than HTML is to do so as a <code>GenericResponse</code>, which is basically the low-level Rack API. Brut encourages Ajax responses to be HTML and for you to use the browser&#39;s APIs to interact with that HTML. Brut may make it easier to work with other types of content in the future.</p></div><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h2><p>Testing handlers requires calling their <em>public API</em>, which is <code>handle!</code>. This is not the method you implement (which is the non-bang <code>handle</code>). The reason is that <code>handle!</code> manages the logic around calling <code>before_handle</code>, which allows your tests to always call <code>handle!</code> and know they are testing how the handler would be used in produciton.</p><p>Each handler spec includes <a href="/api/Brut/SpecSupport/HandlerSupport.html" target="_self" rel="noopener" data-no-router><code>Brut::SpecSupport::HandlerSupport</code></a>, which allows you to create production-like flash, clock, and session objects. To assert the results of calling <code>handle!</code>, there are several RSpec matchers you can use to make your tests easier to write.</p><ul><li><code>have_redirected_to</code> will check that the handler redirected to a give URI.</li><li><code>have_rendered</code> will check that the handler rendered a specific page</li><li><code>have_returned_http_status</code> will check that the handler returned an HTTP status</li><li><code>have_constraint_violation</code> will check if a form had a particular constraint violation set on it</li></ul><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">require</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;spec_helper&quot;</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">RSpec</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">describe</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> LoginPage</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> do</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  describe </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;#handle!&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> do</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    context </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;when login is not valid&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> do</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      it </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;re-renders LoginPage&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> do</span></span>
-<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">        form</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> = </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">LoginForm</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">new</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">params:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">          email:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;nonexistent@example.com&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">          password:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;not a password&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        })</span></span>
-<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">        result</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> = described_class.</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">new</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">          form:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">          session:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> empty_session </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># empty_session provided by HandlerSupport</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        )</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">        expect</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(result).</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">to</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> have_rendered</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">LoginPage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">        expect</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(form).</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">to</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> have_constraint_violation</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:email</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">key:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> :login_not_found</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    end</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    context </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;when login is valid&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> do</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      it </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;forward to the DashboardPage&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> do</span></span>
-<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">        user</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> = </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">create</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:user</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Assume this is set up via FactoryBot</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">                      email:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;pat@example.com&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">                      password:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;1q2w3e4r5t6y7u8i9o&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">        form</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> = </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">LoginForm</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">new</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">params:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">          email:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;pat@example.com&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">          password:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;1q2w3e4r5t6y7u8i9o&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        })</span></span>
-<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">        session</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> = empty_session</span></span>
-<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">        result</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> = described_class.</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">new</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">          form:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">          session:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        )</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">        expect</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(result).</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">to</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> have_redirected_to</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">DashboardPage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">routing</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">        expect</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(session.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">authorized_user</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">).</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">not_to</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> eq</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">nil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">        # Session will be explained later</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><h2 id="recommended-practices" tabindex="-1">Recommended Practices <a class="header-anchor" href="#recommended-practices" aria-label="Permalink to &quot;Recommended Practices&quot;">​</a></h2><p>You should avoid having business logic in your handlers. Since handlers bridge the gap between HTTP and your app, their API is naturally simplistic and String-based. The handler should defer to business logic (which can be done by either passing the form object directly, or extracting its data and passing that). Based on the response, the handler will then decide what HTTP response is approriate.</p><p>This means that your handlers will be relatively simple and their tests will as well. It does mean that their tests may require the use of mocks or stubs, but that&#39;s fine. Mocks and stubs exist for a reason.</p><h2 id="technical-notes" tabindex="-1">Technical Notes <a class="header-anchor" href="#technical-notes" aria-label="Permalink to &quot;Technical Notes&quot;">​</a></h2><div class="important custom-block github-alert"><p class="custom-block-title">IMPORTANT</p><p>Technical Notes are for deeper understanding and debugging. While we will try to keep them up-to-date with changes to Brut&#39;s internals, the source code is always more correct.</p></div><p><em>Last Updated May 5, 2025</em></p><p>None at this time.</p>`,30)]))}const E=i(t,[["render",h]]);export{c as __pageData,E as default};

data/docs/assets/handlers.md.089DVD3v.lean.js

@@ -1 +0,0 @@
-import{_ as i,c as a,o as e,ag as n}from"./chunks/framework.1L-BeKqY.js";const c=JSON.parse('{"title":"Handlers & Actions","description":"","frontmatter":{},"headers":[],"relativePath":"handlers.md","filePath":"handlers.md"}'),t={name:"handlers.md"};function h(l,s,p,r,k,d){return e(),a("div",null,s[0]||(s[0]=[n("",30)]))}const E=i(t,[["render",h]]);export{c as __pageData,E as default};

data/docs/assets/index.md.CuBB-BdM.js

@@ -1 +0,0 @@
-import{_ as a,c as o,o as n,j as t}from"./chunks/framework.1L-BeKqY.js";const s="/assets/LogoStop.X8x-4riz.png",g=JSON.parse(`{"title":"","description":"","frontmatter":{"layout":"home","hero":{"name":"Brut RB","text":"Raw Ruby Web Apps","tagline":"Standards-based, No-nonsense, HTML-first, Low Ceremony","ximage":{"src":"/images/LogoTall.png","alt":"A Ruby gemstone embedded into a concrete, brutalist building"},"actions":[{"theme":"brand","text":"Brut is Not Yet Released","link":"/not-released"},{"theme":"brand","text":"Getting Started","link":"/getting-started"},{"theme":"alt","text":"Conceptual Overview","link":"/overview"}]},"xfeatures":[{"title":"Standards-Based","icon":"📄","details":"Brut leverages HTML, HTTP, SQL, and the Ruby standard library to let you write apps using standards you already know…or could quickly learn"},{"title":"Convention-Oriented","icon":"🎚️","details":"In a Brut app, there's usually just one way to do something. Learn things once, and you won't forget how your app works."},{"title":"Objects and Methods","icon":"💻","details":"Author classes to create objects on which to call methods. Nothing fancy."},{"title":"Builds on Community Libraries","icon":"🏘️","details":"Sequel, Phlex, I18n, RSpec. They do it best"}]},"headers":[],"relativePath":"index.md","filePath":"index.md"}`),i={name:"index.md"};function r(d,e,l,c,u,p){return n(),o("div",null,e[0]||(e[0]=[t("p",null,[t("img",{src:s,alt:"logo"})],-1)]))}const h=a(i,[["render",r]]);export{g as __pageData,h as default};

data/docs/assets/index.md.CuBB-BdM.lean.js

@@ -1 +0,0 @@
-import{_ as a,c as o,o as n,j as t}from"./chunks/framework.1L-BeKqY.js";const s="/assets/LogoStop.X8x-4riz.png",g=JSON.parse(`{"title":"","description":"","frontmatter":{"layout":"home","hero":{"name":"Brut RB","text":"Raw Ruby Web Apps","tagline":"Standards-based, No-nonsense, HTML-first, Low Ceremony","ximage":{"src":"/images/LogoTall.png","alt":"A Ruby gemstone embedded into a concrete, brutalist building"},"actions":[{"theme":"brand","text":"Brut is Not Yet Released","link":"/not-released"},{"theme":"brand","text":"Getting Started","link":"/getting-started"},{"theme":"alt","text":"Conceptual Overview","link":"/overview"}]},"xfeatures":[{"title":"Standards-Based","icon":"📄","details":"Brut leverages HTML, HTTP, SQL, and the Ruby standard library to let you write apps using standards you already know…or could quickly learn"},{"title":"Convention-Oriented","icon":"🎚️","details":"In a Brut app, there's usually just one way to do something. Learn things once, and you won't forget how your app works."},{"title":"Objects and Methods","icon":"💻","details":"Author classes to create objects on which to call methods. Nothing fancy."},{"title":"Builds on Community Libraries","icon":"🏘️","details":"Sequel, Phlex, I18n, RSpec. They do it best"}]},"headers":[],"relativePath":"index.md","filePath":"index.md"}`),i={name:"index.md"};function r(d,e,l,c,u,p){return n(),o("div",null,e[0]||(e[0]=[t("p",null,[t("img",{src:s,alt:"logo"})],-1)]))}const h=a(i,[["render",r]]);export{g as __pageData,h as default};

data/docs/assets/keyword-injection.md.Dt2tKREs.js

@@ -1,25 +0,0 @@
-import{_ as i,c as s,o as a,ag as t}from"./chunks/framework.1L-BeKqY.js";const u=JSON.parse('{"title":"Keyword Injection","description":"","frontmatter":{},"headers":[],"relativePath":"keyword-injection.md","filePath":"keyword-injection.md"}'),n={name:"keyword-injection.md"};function o(l,e,h,r,d,p){return a(),s("div",null,e[0]||(e[0]=[t(`<h1 id="keyword-injection" tabindex="-1">Keyword Injection <a class="header-anchor" href="#keyword-injection" aria-label="Permalink to &quot;Keyword Injection&quot;">​</a></h1><p>Brut is desiged around classes and objects, as compared to modules and DSLs. Almost everything you do when building your app is to create a class that has an initializer and implements one or more methods. But, these initalizers and methods often need information from the request that Brut is managing.</p><p>In a basic Rack or Sinatra app, you would access this information via Rack&#39;s API, which is essentially a <code>Hash</code> of whatever. It&#39;s error-prone and requires consulting documentation, source code, or runtime information to figure out what&#39;s stored where.</p><p>Brut can instead inject these values explicitly into the classes of yours it creates. It does this based on the names of keyword arguments declared by your class&#39; intializer or a template method Brut will call.</p><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to &quot;Overview&quot;">​</a></h2><p>For example, a <a href="/pages.html">Page</a> requires you to implement an initializer. That initializer&#39;s keyword arguments define what information is needed. Brut provides that information when it creates the object. This is a form of dependency injection and it can simplify your code if used effectively.</p><p>Consider this route:</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">page </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;/widgets/:id&quot;</span></span></code></pre></div><p>Brut will expect to find <code>WidgetsByIdPage</code>. Your initializer can declare <code>id:</code> as a keyword arg and this will be passed when the class is created:</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">class</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> WidgetsByIdPage</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> AppPage</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> initialize</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">id:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    @widget </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> DB</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">Widget</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">find</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(id)</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><p>If the page requires access to the session, it can declare that:</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">class</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> WidgetsByIdPage</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> AppPage</span></span>
-<span class="line highlighted"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> initialize</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">id:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">session:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    @widget       </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> DB</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">Widget</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">find</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(id)</span></span>
-<span class="line highlighted"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    @current_user </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> session.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">current_user</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><p>Because <code>session:</code> is a required argument, Brut cannot instantiate the page without it, so it will always be passed in and availbale.</p><h3 id="standard-injectible-information" tabindex="-1">Standard Injectible Information <a class="header-anchor" href="#standard-injectible-information" aria-label="Permalink to &quot;Standard Injectible Information&quot;">​</a></h3><p>In any request, the following information is available to be injected:</p><ul><li><code>session:</code> - An instance of your app&#39;s <a href="/api/Brut/FrontEnd/Session.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Session</code></a> subclass for the current visitor&#39;s session.</li><li><code>flash:</code> - An instance of your app&#39;s <a href="/api/Brut/FrontEnd/Flash.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Flash</code></a> subclass.</li><li><code>xhr:</code> - true if this was an Ajax request.</li><li><code>body:</code> - the body submitted, if any.</li><li><code>csrf_token:</code> - The current CSRF token.</li><li><code>clock:</code> - A <code>Clock</code> to be used to access the current time in the visitor&#39;s time zone.</li><li><code>http_*</code> - any parameter that starts with <code>http_</code> is assumed to be for an HTTP header. For example, <code>http_accept_language</code> would be given the value for the &quot;Accept-Language&quot; header. See the section on HTTP headers below.</li><li><code>env:</code> - The Rack env. This is discouraged, but available if you can&#39;t get what you want directly</li></ul><p>Depending on the context, other information is available:</p><ul><li><code>form:</code> - If a form was submitted, this is the <a href="/api/Brut/FrontEnd/Form.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Form</code></a> subclass containing the data. See <a href="/forms.html">Forms</a>.</li><li>Any query string paramter - Note that if these conflict with existing Brut values, the behavior is undefined. Name your query string parameters carefully. These should have default values or your page won&#39;t work if they are omitted.</li><li>Any route parameter - These should not have default values, since they are required for Brut to match the route.</li></ul><p>A <a href="/api/Brut/FrontEnd/RouteHook.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::RouteHook</code></a> is slightly different. Only the following data is available to be injected:</p><ul><li><code>request_context:</code> - The current request context, thought it may be <code>nil</code> depending on when the hook runs</li><li><code>session:</code> - An instance of your app&#39;s <a href="/api/Brut/FrontEnd/Session.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Session</code></a> subclass for the current visitor&#39;s session.</li><li><code>request:</code> - The Rack request</li><li><code>response:</code> - The Rack response</li><li><code>env:</code> - The Rack env.</li></ul><h3 id="http-headers" tabindex="-1">HTTP Headers <a class="header-anchor" href="#http-headers" aria-label="Permalink to &quot;HTTP Headers&quot;">​</a></h3><p>Since any header can be sent with a request, Brut allows you to access them, including non-standard ones. Rack (which is based on CGI), provides access to all HTTP headers in the <code>env</code> by taking the header name, replacing dashes (&quot;-&quot;) with underscores (&quot;_&quot;), and prepending <code>http_</code> to the name, then uppercasing it. Thus, &quot;User-Agent&quot; becomes <code>HTTP_USER_AGENT</code>.</p><p>Because Ruby parameters and variables must start with a lower-case letter, Brut uses the lowercased version of the Rack/CGI variable. Thus, to receive the &quot;User-Agent&quot;, you would declare the keyword parameter <code>http_user_agent</code>.</p><p>Further, because headers come from the client and may not be under your control, the value that is actually injected depends on a few things:</p><ul><li>If your keyword arg is required, i.e. there is no default value: <ul><li>If the header was not provided, <code>nil</code> is injected.</li><li>If the header <em>was</em> provided, it&#39;s value is injected, even if it&#39;s the empty string.</li></ul></li><li>If your keyword arg is optional, i.e. it has a default value <ul><li>If the header was not provided, no value is injected, and your code will receive the default value.</li><li>If the header <em>was</em> provided, it&#39;s value is injected, even if it&#39;s the empty string.</li></ul></li></ul><h3 id="ordering-and-disambiguation" tabindex="-1">Ordering and Disambiguation <a class="header-anchor" href="#ordering-and-disambiguation" aria-label="Permalink to &quot;Ordering and Disambiguation&quot;">​</a></h3><p>You are discouraged from using builtin keys for your own data or request parameters. For example, you should not have a query string parameter named <code>env</code> as this conflicts with the builtin <code>env</code> that Brut will inject.</p><p>Since you can inject your own data (see below), you are free to corrupt the request context. Please don&#39;t do this. Brut may actively prevent this in the future.</p><p>You can also use the request context to put your own data that can be injected.</p><h3 id="injecting-custom-data" tabindex="-1">Injecting Custom Data <a class="header-anchor" href="#injecting-custom-data" aria-label="Permalink to &quot;Injecting Custom Data&quot;">​</a></h3><p>The correct place to inject your own data into the request is in a <a href="/hooks.html">before hook</a>. When you configure a before hook, it will run after Brut&#39;s internal <a href="/api/Brut/FrontEnd/RouteHooks/SetupRequestContext.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::RouteHooks::SetupRequestContext</code></a>, which ensures the request context exists and is ready for use.</p><p>For example, here is how you might inject the currently logged-in account based on the session:</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">class</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> AuthBeforeHook</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> Brut</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">FrontEnd</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">RouteHook</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> before</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">request_context:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">session:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> session.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">authenticated_account</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      request_context[</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:authenticated_account</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> session.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">authenticated_account</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    end</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    continue</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><p>Note that the value is only injected if it exists. It&#39;s important not to inject <code>nil</code> for values that don&#39;t exist.</p><p>You may be thinking that this particular example is unnecessary. You could simply inject <code>session:</code> and call <code>session.authenticated_account</code>:</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">class</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> DashboardPage</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> AppPage</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> initialize</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">session:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    @widgets </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> session.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">authenticated_account</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">widgets</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # e.g.</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><p>If <code>DashboardPage</code> requires an authenticated account, by only injecting the session, you&#39;ll need to handle the case where <code>session.authenticated_account</code> is <code>nil</code>. Instead, if you configure the <code>AuthBeforeHook</code> as above, then inject <code>authenticated_account</code>, you avoid the need for this logic:</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">class</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> DashboardPage</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> AppPage</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> initialize</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">authenticated_account:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    @widgets </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> authenticated_account.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">widgets</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # e.g.</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><p>Because <code>AuthBeforeHook</code> never injects <code>nil</code>, <code>DashboardPage</code> can rely on <code>authenticated_account</code> always being present. Further, if a visitor tried to access <code>/dashboard_page</code> without having been authenticated, Brut would be unable to create an instance of <code>DashboardPage</code> and generate an error.</p><h3 id="nil-and-empty-strings" tabindex="-1"><code>nil</code> and Empty Strings <a class="header-anchor" href="#nil-and-empty-strings" aria-label="Permalink to &quot;\`nil\` and Empty Strings&quot;">​</a></h3><p>When a keyword argument has no default value, Brut will require that value to exist and be available for injection. If the keyword is not one of the canned always-available values, it will look in the request context, then in the query string.</p><p>If the request has the keyword as a key, <em>it will inject whatever value it finds, including <code>nil</code></em>. In general, you should avoid injecting <code>nil</code> when you actually intend to not have a value.</p><p>For example, the <code>AuthBeforeHook</code> above, you could implement it like so:</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">request_context[</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:authenticated_account</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> session.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">authenticated_account</span></span></code></pre></div><p>The problem is that if the visitor is not logged in, the <code>:authenticated_account</code> <em>will</em> have a value, and that value will be <code>nil</code>. This is almost certainly not what you want.</p><p>For query string parameters, the HTTP spec says that they are strings. Thus, if a query string parameter is present in ther request URL, it will <em>always</em> have a value and <em>never</em> be <code>nil</code>. If the paramter doesn&#39;t have a value after the <code>=</code> (e.g. for <code>foo</code> in <code>?foo=&amp;bar=quux</code>), the value will be the empty string.</p><p>This means you must write code to explicitly handle the cases you care about.</p><h3 id="when-values-aren-t-available" tabindex="-1">When Values Aren&#39;t Available <a class="header-anchor" href="#when-values-aren-t-available" aria-label="Permalink to &quot;When Values Aren&#39;t Available&quot;">​</a></h3><p>When a value is not available for injection, and the keyword doesn&#39;t provide a default, Brut will raise an error. This is because such a situation represents a design error.</p><p>For example, the <code>DashboardPage</code> above requires an <code>authenticated_account</code>. Your app should never route a logged-out visitor to that page. This allows the <code>DashboardPage</code> to avoid having to check for <code>nil</code> and figure out what to do.</p><p>This is most relevant for query string parameters, since they can be easily manipulated by the visitor in their browser. Query string parameters should always have a default value, even if it&#39;s <code>nil</code>.</p><p><em>Path</em> parameters (like <code>:id</code> in <code>WidgetsByIdPage</code>) should <em>never</em> have a default value as their absence means a different URL was requested. For example, <code>/widgets</code> would trigger a <code>WidgetsPage</code>. <em>Only</em> if the <code>:id</code> path parameter is present would the <code>WidgetsByIdPage</code> be triggered, so it&#39;s safe to omit the default value for <code>id:</code> (and pointless to include one).</p><p>See <a href="/hooks.html">route hooks</a>.</p><h3 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h3><p>Brut will not create your classes in a test. Instead, you must pass in the values you want. There are various helpers in <a href="/api/Brut/SpecSupport.html" target="_self" rel="noopener" data-no-router><code>Brut::SpecSupport</code></a> to create blank or empty versions of the special classes.</p><p>In particular, A basic <code>request_context</code> is setup per test and injected into the Thread local storage. This means that if your test should trigger a codepath that <em>does</em> cause Brut to use keyword injection, useful values will be injected.</p><p>For your tests, however, you should pass in directly what you need:</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">page</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> = </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">WidgetsByIdPage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">new</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">id:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> widget.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">id</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">session:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> empty_session)</span></span></code></pre></div><h2 id="recommended-practices" tabindex="-1">Recommended Practices <a class="header-anchor" href="#recommended-practices" aria-label="Permalink to &quot;Recommended Practices&quot;">​</a></h2><p>Consider a method like so:</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> create_widget</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">name:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">organization:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> nil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">quantity:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 10</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span></code></pre></div><p>Outside of Brut, the way to interpret this arguments is as follows:</p><ul><li><code>name</code> is required</li><li><code>organization</code> is optional</li><li><code>quantity</code> has a default value of 10 if not provided</li></ul><p>Any method or intializer that will be keyword-injected should be designed with this in mind. Thus, the following guidelines will be helpful in managing your app:</p><ul><li><strong>Choose arguments based on the needs of the class:</strong><ul><li>If a value is optional, default it to either <code>nil</code> or a symbol that indicates what happens when the value is omitted</li><li>If an optional value has a default, use that (this should be rare for pages, handlers, components, and hooks)</li><li>Otherwise, do not provide a default for the keyword</li></ul></li><li><strong>Design for non-<code>nil</code> values instead of allowing <code>nil</code> and checking for it</strong><ul><li>If a page needs, say, the currently logged-in user, set that up as injectible with no default.</li><li>If a codepath creates that page without the logged-in user, you will get a very obvious error and can figure out how it happened. Your page&#39;s code doesn&#39;t need to figure out what to do with <code>nil</code></li></ul></li><li><strong>Do not inject <code>nil</code> into the request context.</strong> When your code requires a value for a keyword, you want to rely on that value being non-nil. Thus, avoid injecting <code>nil</code> into the request context. Brut will allow it as a sort-of escape hatch, but you should design your app to avoid it</li><li><strong>Be careful injecting global data.</strong> The request context instance is per request, but you could certainly put global data into it. For example, you may put an initialized API client into the request context as a convieniece. <strong>Be careful</strong> because your app is multi-threaded. Any object that is not scoped to the request must be thread-safe.</li></ul><h2 id="technical-notes" tabindex="-1">Technical Notes <a class="header-anchor" href="#technical-notes" aria-label="Permalink to &quot;Technical Notes&quot;">​</a></h2><div class="important custom-block github-alert"><p class="custom-block-title">IMPORTANT</p><p>Technical Notes are for deeper understanding and debugging. While we will try to keep them up-to-date with changes to Brut&#39;s internals, the source code is always more correct.</p></div><p><em>Last Updated May 7, 2025</em></p><p>Keyword injection is currently implemented in a few places and not available via public API. It could be useful as an API and it will be exposed at some point. For now, it&#39;s only available for Brut-managed classes as documented here.</p>`,69)]))}const k=i(n,[["render",o]]);export{u as __pageData,k as default};

data/docs/assets/layouts.md.cPnh3NId.lean.js

@@ -1 +0,0 @@
-import{_ as i,c as a,o as t,ag as n}from"./chunks/framework.1L-BeKqY.js";const y=JSON.parse('{"title":"Layouts","description":"","frontmatter":{},"headers":[],"relativePath":"layouts.md","filePath":"layouts.md"}'),e={name:"layouts.md"};function l(h,s,p,k,r,o){return t(),a("div",null,s[0]||(s[0]=[n("",26)]))}const c=i(e,[["render",l]]);export{y as __pageData,c as default};

data/docs/assets/not-released.md.BBy28McC.js

@@ -1 +0,0 @@
-import{_ as a,c as s,o as r,j as e,a as o}from"./chunks/framework.1L-BeKqY.js";const p=JSON.parse('{"title":"Brut is Not Released Software","description":"","frontmatter":{},"headers":[],"relativePath":"not-released.md","filePath":"not-released.md"}'),n={name:"not-released.md"};function i(l,t,d,c,u,f){return r(),s("div",null,t[0]||(t[0]=[e("h1",{id:"brut-is-not-released-software",tabindex:"-1"},[o("Brut is Not Released Software "),e("a",{class:"header-anchor",href:"#brut-is-not-released-software","aria-label":'Permalink to "Brut is Not Released Software"'},"​")],-1),e("div",{class:"warning custom-block github-alert"},[e("p",{class:"custom-block-title"},"WARNING"),e("p",null,"Brut is not considered released. It is still in development and some of what is in this doc site is inaccurate.")],-1)]))}const h=a(n,[["render",i]]);export{p as __pageData,h as default};

data/docs/assets/not-released.md.BBy28McC.lean.js

@@ -1 +0,0 @@
-import{_ as a,c as s,o as r,j as e,a as o}from"./chunks/framework.1L-BeKqY.js";const p=JSON.parse('{"title":"Brut is Not Released Software","description":"","frontmatter":{},"headers":[],"relativePath":"not-released.md","filePath":"not-released.md"}'),n={name:"not-released.md"};function i(l,t,d,c,u,f){return r(),s("div",null,t[0]||(t[0]=[e("h1",{id:"brut-is-not-released-software",tabindex:"-1"},[o("Brut is Not Released Software "),e("a",{class:"header-anchor",href:"#brut-is-not-released-software","aria-label":'Permalink to "Brut is Not Released Software"'},"​")],-1),e("div",{class:"warning custom-block github-alert"},[e("p",{class:"custom-block-title"},"WARNING"),e("p",null,"Brut is not considered released. It is still in development and some of what is in this doc site is inaccurate.")],-1)]))}const h=a(n,[["render",i]]);export{p as __pageData,h as default};

data/docs/assets/overview.md.DVKRM8zl.js

@@ -1,133 +0,0 @@
-import{_ as i,c as a,o as e,ag as t}from"./chunks/framework.1L-BeKqY.js";const n="/assets/OverviewMetro.DUS-5fUZ.png",g=JSON.parse('{"title":"Conceptual Overview","description":"","frontmatter":{},"headers":[],"relativePath":"overview.md","filePath":"overview.md"}'),l={name:"overview.md"};function h(p,s,r,o,d,k){return e(),a("div",null,s[0]||(s[0]=[t('<h1 id="conceptual-overview" tabindex="-1">Conceptual Overview <a class="header-anchor" href="#conceptual-overview" aria-label="Permalink to &quot;Conceptual Overview&quot;">​</a></h1><p>Brut is a web framework that provides the ability to receive HTTP requests and respond to them. It includes facilities for generating HTML, interacting with a database, managing assets and more. Pretty much everything you need, though not much that you don&#39;t.</p><p>Brut&#39;s approach and design are built on three core values:</p><ul><li><strong>Leverage Standards</strong> - The web platform is great, and Brut wants you to use it.</li><li><strong>There&#39;s One Best Way To Do It</strong> - Flexibility leads to chaos.</li><li><strong>Simple over Easy</strong> - Verbose code that can be quickly understood beats impenetrable compact DSLs every day.</li></ul><p>As such, Brut&#39;s API and concepts are intended to mirror concepts that exist in the domain of building web sites. For example, when you go to a URL, you are viewing a web page. In Brut, a page is rendered by using a subclass of <a href="/api/Brut/FrontEnd/Page.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Page</code></a>, called a <em>page</em>.</p><p>Brut also avoids creating abstractions on top of existing standards you already need to know to build websites. For example, instead of creating a resource/verb abstraction on top of submitting forms over HTTP, Brut instead has you implement a <a href="/api/Brut/FrontEnd/Form.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Form</code></a> that describes the form&#39;s inputs—just like you&#39;d have in HTML.</p><h2 id="basic-elements-of-a-brut-powered-app" tabindex="-1">Basic Elements of a Brut-Powered App <a class="header-anchor" href="#basic-elements-of-a-brut-powered-app" aria-label="Permalink to &quot;Basic Elements of a Brut-Powered App&quot;">​</a></h2><p>Below is a diagram showing the high level parts of a Brut app. It shows four important terms with respect to how Brut is organized:</p><ul><li><em>Client</em> or <em>Client Side</em> is the web browser (or HTTP client). This is where CSS is applied to HTML and where JavaScript is executed. HTTP requests are initiated here.</li><li><em>Server</em> or <em>Server Side</em> is where any code not in the browser runs. In Brut, this includes HTML generation, SQL queries, and everything in between.</li><li><em>Front End</em> is the code that deals with producing your user interface or HTTP API. A lot of this code runs on the <em>server side</em>, however it exists to provide a user interface of some sort.</li><li><em>Back End</em> is the code that deals with everything else, such as accessing a database, executing business logic, or managing background jobs.</li></ul><p><img src="'+n+`" alt="Architectural Overview"></p><ul><li><strong>Visitor</strong> is someone visiting your web site or app.</li><li><strong>Browser</strong> is, well, a web browser</li><li><a href="/pages.html"><strong>Pages</strong></a> generate web pages, which is what happens when a browser&#39;s UI navigates to a URL.</li><li><a href="/forms.html"><strong>Forms</strong></a> describe the inputs of an HTML <code>&lt;form&gt;</code> element, and hold a form&#39;s submitted data for server-side processing. Browser submit forms to the server.</li><li><a href="/components.html"><strong>Components</strong></a> generate HTML fragments and are used to generate the HTML of a page or for re-use across pages.</li><li><a href="/handlers.html"><strong>Handlers</strong></a> receive non-GET HTTP requests from the browser, notably form submissions.</li><li><a href="/javascript.html"><strong>JavaScript</strong></a> and <a href="/assets.html"><strong>Assets</strong></a> (including <a href="/css.html">CSS</a>) are bundled on the server and sent to the client.</li><li><a href="/business-logic.html"><strong>Domain Logic</strong></a> as where your business and domain logic lives and can be implemented however you like.</li><li><a href="/database-access.html"><strong>DB Models</strong></a> are objects that provide access to your database.</li><li><strong>Relational Database</strong> is your database, where data is stored.</li></ul><h2 id="brut-is-not-a-resource-oriented-mvc-framework" tabindex="-1">Brut is Not a Resource-Oriented MVC Framework. <a class="header-anchor" href="#brut-is-not-a-resource-oriented-mvc-framework" aria-label="Permalink to &quot;Brut is Not a Resource-Oriented MVC Framework.&quot;">​</a></h2><p>You will note that Brut is <em>not</em> an MVC framework. Rather than creating an often confusing abstraction on top of HTTP, browsers, and HTML, Brut provides a more direct set of primitives.</p><p>Further, Brut is not <em>resource-oriented</em>. While HTTP does include the concept of resources and verbs to operate on those resources, in the context of building a web application, these two abstractions cause more problems than they solve.</p><p>Although Brut can can certainly respond to any URL and any verb, the core set of abstractions mirror the observed behavior of a web browser: <em>Pages</em> generate HTML (with the help of <em>Components</em>). <em>Forms</em> describe data to collect from the user, which is submitted to <em>Handlers</em> for processing by the back-end. Ajax requests (and arbitrary HTTP requests) can also be responded-to by <em>Handlers</em>.</p><p>In practice, this means that you do not have to perform mental gymnastics to decide exactly what verb and/or resource best represents the use-case you are trying to build. When your partners want to build an &quot;account management page&quot;, you will be able to implement this with a class named <code>AccountManagementPage</code>. When discussing enhancements to the &quot;user settings form&quot;, you will making changes to the <code>UserSettingsForm</code> and <code>UserSettingsHandler</code>. If that form is on the page everyone calls the &quot;preferences page&quot;, you&#39;ll be dealing with <code>PreferencesPage</code>, and not &quot;the index method of the <code>UserSettingsController</code>.</p><p>Let&#39;s go one step deeper to see how these primitives work.</p><h2 id="quick-tour-of-brut-s-primitives" tabindex="-1">Quick Tour of Brut&#39;s Primitives <a class="header-anchor" href="#quick-tour-of-brut-s-primitives" aria-label="Permalink to &quot;Quick Tour of Brut&#39;s Primitives&quot;">​</a></h2><h3 id="pages" tabindex="-1">Pages <a class="header-anchor" href="#pages" aria-label="Permalink to &quot;Pages&quot;">​</a></h3><p>The <em>Page</em> is the best example of Brut&#39;s value system. When you fetch a URL in a web browser, that is referred to as a web page. Thus, in Brut, a route accessed via an HTTP <code>GET</code> is managed by an instance of a <em>page class</em>.</p><p>Instead of a routing system where you must map http-like verbs to resource, Brut&#39;s routes are more direct. For a page, you&#39;d use the <code>page</code> method (we&#39;ll explain more what <code>class App</code> and <code>routes do</code> are doing later):</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">class</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> App</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> Brut</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">Framework</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">App</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> id</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">           =</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;my-app&quot;</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> organization</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;my-org&quot;</span></span>
-<span class="line"></span>
-<span class="line highlighted"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  routes </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">do</span></span>
-<span class="line highlighted"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    page </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;/dashboard&quot;</span></span>
-<span class="line highlighted"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><p>Brut is convention-based, so when this route is requested by the browser, Brut will instantiate the class <code>DashboardPage</code> to handle the request. The page is an enhanced Phlex component that supports layouts. You implement <code>page_template</code> and make calls to Phlex&#39;s API to generate your page&#39;s HTML.</p><p>You will write an initializer (using keyword arguments) that describes all the data your page needs in order to generate its HTML. Brut will instantiate your page class into an object and use Phlex&#39;s API to generate HTML.</p><p>There is great variety in what your initializer can be given by Brut. For example, if we want to show the current time as well as respond to the query-string parameter &quot;compact&quot;, we&#39;d write our class like so:</p><div class="vp-code-group vp-adaptive-theme"><div class="tabs"><input type="radio" name="group--qXMx" id="tab-KZvr-oY" checked><label data-title="pages/dashboard_page.rb" for="tab-KZvr-oY">pages/dashboard_page.rb</label><input type="radio" name="group--qXMx" id="tab-cgtxeqq"><label data-title="layouts/default_layout.rb" for="tab-cgtxeqq">layouts/default_layout.rb</label></div><div class="blocks"><div class="language-ruby vp-adaptive-theme active"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">class</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> DashboardPage</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> AppPage</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> initialize</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">clock:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">compact:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    @now     </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> clock.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">now</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    @compact </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> compact </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;true&quot;</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> page_template</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    main </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">do</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">     h1 { </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Hello!&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">     h2 </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">do</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">       plain</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;It&#39;s &quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">       time</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">datetime:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> l</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(@now, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">format:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> iso_8601)) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">do</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">         l</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(@now, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">format:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> date)</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">       end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">     end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">     if</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> !</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">@compact</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">       p</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Do you know where your web framework is?&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">     end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">class</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> DefaultLayout</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> Brut</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">FrontEnd</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">Layout</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> view_template</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    doctype</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    html </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">do</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      head </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">do</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        title { </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;My Awesome Site&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        body </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">do</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">          yield</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div></div></div><p>This would all produce HTML like so:</p><div class="vp-code-group vp-adaptive-theme"><div class="tabs"><input type="radio" name="group-eDHyu" id="tab-f9HHgvF" checked><label data-title="/dashboard" for="tab-f9HHgvF">/dashboard</label><input type="radio" name="group-eDHyu" id="tab-LFQcgeQ"><label data-title="/dashboard?compact=true" for="tab-LFQcgeQ">/dashboard?compact=true</label></div><div class="blocks"><div class="language-html vp-adaptive-theme active"><button title="Copy Code" class="copy"></button><span class="lang">html</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;!</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">DOCTYPE</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> html</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">html</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  &lt;</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">head</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    &lt;</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">title</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;My Awesome Site&lt;/</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">title</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  &lt;/</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">head</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  &lt;</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">body</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    &lt;</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">main</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      &lt;</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">h1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;Hello!&lt;/</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">h1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      &lt;</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">h2</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;It&#39;s</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        &lt;</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">time</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> datetime</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;2025-02-17&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">          Monday, Feb 17</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        &lt;/</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">time</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      &lt;/</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">h2</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      &lt;</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">p</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        Do you know where your web framework is?</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      &lt;/</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">p</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    &lt;/</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">main</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  &lt;/</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">body</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;/</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">html</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span></code></pre></div><div class="language-html vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">html</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;!</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">DOCTYPE</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> html</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">html</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  &lt;</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">head</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    &lt;</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">title</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;My Awesome Site&lt;/</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">title</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  &lt;/</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">head</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  &lt;</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">body</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    &lt;</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">main</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      &lt;</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">h1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;Hello!&lt;/</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">h1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      &lt;</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">h2</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;It&#39;s</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        &lt;</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">time</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> datetime</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;2025-02-17&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">          Monday, Feb 17</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        &lt;/</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">time</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      &lt;/</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">h2</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    &lt;/</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">main</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  &lt;/</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">body</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;/</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">html</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span></code></pre></div></div></div><h3 id="components" tabindex="-1">Components <a class="header-anchor" href="#components" aria-label="Permalink to &quot;Components&quot;">​</a></h3><p><em>Components</em> are a way to manage the complexity of HTML generation. A component is exactly like a page: it&#39;s Phlex Component that powers dynamic HTML generation. The only difference is that a page has a <em>layout</em>, whereas a component does not.</p><p>In the example below, a flash is passed into <code>FlashMessage</code> by Brut and <code>t</code> translates a string. More on both of those later. Note the components use Phlex API more directly by asking you to implement <code>view_template</code>. Brut tries to defer or mimic APIs of standard libraries classes rather than create its own wrappers unless there is a compelling reason.</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># components/flash_message.rb</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">class</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> FlashMessage</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> AppComponent</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> initialize</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">flash:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> flash.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">notice?</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      @message_key </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> flash.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">notice</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      @role </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> :info</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    elsif</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> flash.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">alert?</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      @message_key </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> flash.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">alert</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      @role </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> :alert</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> any_message?</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> !</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">@message_key.nil?</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> view_template</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    if</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> !</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">@message_key.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">nil?</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">      div</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">role:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> @role) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">do</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">        t</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">([ </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:flash</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, @message_key ])</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><p>You can then use this in any other view using <code>render</code>, provided by Phlex.</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> page_template</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  header </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">do</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    render </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">FlashMessage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">new</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">flash:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><h3 id="forms" tabindex="-1">Forms <a class="header-anchor" href="#forms" aria-label="Permalink to &quot;Forms&quot;">​</a></h3><p>To allow data to be submitted from the browser, you&#39;d use an HTML <code>&lt;form&gt;</code> that contains many <code>&lt;inputs&gt;</code>, as has been the case since the birth of the web. To declare a form that will be submitted, use <code>form</code>:</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  routes </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">do</span></span>
-<span class="line highlighted"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    form </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;/login&quot;</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span></code></pre></div><p>Brut is convention-based, so it will expect a class named <code>LoginForm</code> to exist to hold a programmatic description of the form. This description allows the form&#39;s data to be managed during the submission process. That form is passed to an instance of <code>LoginHandler</code>, which contains the logic for processing the submission.</p><p>The idea behind form classes is to avoid dealing with Hashes containing magical strings or symbols and instead deal with a more strictly defined type. This means, among other benefits, you don&#39;t have maintain a separate list of allowed parameters. Your form defines them and is used to generate HTML, so it&#39;s all just one list of parameters. Forms aren&#39;t that fancy, though. Just as HTML <code>FormData</code> is string keys and string values, so it is with Brut forms.</p><p>To define the inputs, class methods are used in the form class&#39; definition. When the form is submitted <code>LoginHandler#handle</code> is called, and passed an instance of the form. The form has methods to access the inputs&#39; values</p><div class="vp-code-group vp-adaptive-theme"><div class="tabs"><input type="radio" name="group-N0YMR" id="tab-p_t9M_a" checked><label data-title="forms/login_form.rb" for="tab-p_t9M_a">forms/login_form.rb</label><input type="radio" name="group-N0YMR" id="tab--3a9l7j"><label data-title="handlers/login_handler.rb" for="tab--3a9l7j">handlers/login_handler.rb</label></div><div class="blocks"><div class="language-ruby vp-adaptive-theme active"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">class</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> LoginForm</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> AppForm</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  input </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:email</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  input </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:password</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">class</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> LoginHandler</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> AppHandler</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> handle</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">form:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    # form.email    =&gt; value from &lt;input name=email&gt;</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    # form.password =&gt; value from &lt;input name=password&gt;</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div></div></div><p>A handler is like a controller in Rails, except it only handles one action. The <code>handle</code> method&#39;s return value indicates what should happen. For example, you may want to re-validate the client-side constraints. If any have been violated, you&#39;d want to re-generate the HTML for the <code>LoginPage</code>. If everything looks good, you&#39;ll redirect to the <code>DashboardPage</code>:</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">class</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> LoginHandler</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> AppHandler</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> handle</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">form:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
-<span class="line highlighted"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> form.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">constraint_violations?</span></span>
-<span class="line highlighted"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      LoginPage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">new</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">form:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
-<span class="line highlighted"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    else</span></span>
-<span class="line highlighted"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">      redirect_to</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">DashboardPage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
-<span class="line highlighted"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><h3 id="javascript-and-css" tabindex="-1">JavaScript and CSS <a class="header-anchor" href="#javascript-and-css" aria-label="Permalink to &quot;JavaScript and CSS&quot;">​</a></h3><p>Brut does not include a front-end framework, however it doesn&#39;t prevent you from using one. Brut <em>does</em> include a configuration of esbuild that will serve you well for most situations. esbuild is also configured to bundle and manage your CSS. This, coupled with recent advancements in CSS means that you don&#39;t need something like SASS. You can use standard <code>@import</code> statements to manage your CSS across multiple files and use CSS nesting to namespace your classes.</p><p>Brut provides a JavaScript <em>library</em> called BrutJS. BrutJS is mostly a set of custom elements that act as HTML Web Components, progressively enhancing markup you manage and style with common behaviors. Some of these components are used to provide localized messaging for client-side constraint violations. You can use these with any other client-side framework, or just use them on their own. You can also skip using them entirely and provide your own solution.</p><h3 id="database-schema" tabindex="-1">Database Schema <a class="header-anchor" href="#database-schema" aria-label="Permalink to &quot;Database Schema&quot;">​</a></h3><p>Brut provides access to an SQL database via Sequel. Brut uses Sequel&#39;s database schema management, however it is enhanced to encourage good practices by default.</p><div class="note custom-block github-alert"><p class="custom-block-title">NOTE</p><p>Brut currently <em>only supports</em> PostgreSQL. It may support all RDBMSes that Sequel supports, but as of now, it&#39;s just Postgres.</p></div><p>Consider a <code>households</code> table that relates to an <code>accounts</code> table.</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">create_table </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:households</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">             comment:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;Family unit managing the data&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> do</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  column </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:timezone</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:text</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  column </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:dinner_time_of_day</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:text</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  constraint</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">    :time_must_be_time</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">    %{</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">      (dinner_time_of_day ~ &#39;^[01][0-9]:[0-5][0-9]$&#39;) OR</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">      (dinner_time_of_day ~ &#39;^2[0-3]:[0-5][0-9]$&#39;)</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">    }</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  )</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">create_table </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:accounts</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">             comment:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;People or systems who can access this system&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">external_id:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> true</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> do</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  column </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:email</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,             </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:email_address</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">unique:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> true</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  column </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:deactivated_at</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,    </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:timestamptz</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">null:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> true</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  foreign_key </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:household_id</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:households</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><p>This is mostly using <a href="https://sequel.jeremyevans.net/rdoc/files/doc/schema_modification_rdoc.html" target="_blank" rel="noreferrer">Sequel&#39;s built-in migrations API</a>. But, a few additional behaviors are happening:</p><ul><li>Columns default to <code>NOT NULL</code></li><li>Tables require comments</li><li>Foreign keys default to having constraints and indexes</li></ul><p>There are other quality-of-life features of Brut&#39;s migration system, all designed to default to a good practice, with a way to do it however you want when needed.</p><h3 id="database-access" tabindex="-1">Database Access <a class="header-anchor" href="#database-access" aria-label="Permalink to &quot;Database Access&quot;">​</a></h3><p>Brut uses <code>Sequel::Model</code> to access data in your database. To discourage the conflation of &quot;models of database tables&quot; with &quot;models of your application&#39;s domain&quot;, these classes are in the <code>DB</code> namespace. Thus, the class <code>DB::Household</code> would be able to access the <code>households</code> table defined above. This frees you up to create a <code>Household</code> class to model your domain&#39;s logic without being coupled to how you store some data in a database.</p><h3 id="domain-and-business-logic" tabindex="-1">Domain and Business Logic <a class="header-anchor" href="#domain-and-business-logic" aria-label="Permalink to &quot;Domain and Business Logic&quot;">​</a></h3><p>Brut uses Zeitwerk for code loading, so any directories you create will be auto-loaded and refreshed during development. This means that you can create a class named <code>Household</code> in <code>app/src/back_end/domain/household.rb</code> and it would be loaded. Or, you could create <code>HouseholdService</code> in <code>app/src/back_end/services/household_service.rb</code> if you like.</p><div class="tip custom-block github-alert"><p class="custom-block-title">TIP</p><p>Providing a generally-useful abstraction for business or domain logic is not usually feasible. Thus, Brut doesn&#39;t provide much beyond Zeitwerk&#39;s auto-loading feature. It may provide more assistance in the future, but for now, Brut&#39;s approach is to free you from any prescription or moral imperative. Manage your domain and business logic how you see fit. You know your domain and team better than we do.</p></div><h3 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h3><p>Brut provides support for three types of tests:</p><ul><li>Unit Tests, using RSpec</li><li>End-to-end tests, using RSpec and Playwright</li><li>Custom Element tests, written in JavaScript, using Mocha</li></ul><p>Since almost every class you create is a plain Ruby class, testing the classes is usually straightforward. That said, it&#39;s often better to test Pages and Components through their generated HTML. Brut provides help to do that, based on Nokogiri.</p><h3 id="tasks" tabindex="-1">Tasks <a class="header-anchor" href="#tasks" aria-label="Permalink to &quot;Tasks&quot;">​</a></h3><p>Brut doesn&#39;t use Rake tasks. It uses CLI apps powered by Ruby&#39;s <code>OptionParser</code>. Brut provides bootstrapping classes to make your own CLIs, as well as some light abstractions to make <code>OptionParser</code> a little more ergonomic. Brut&#39;s dev and production management CLIs are built using this support.</p><h3 id="observability" tabindex="-1">Observability <a class="header-anchor" href="#observability" aria-label="Permalink to &quot;Observability&quot;">​</a></h3><p>Brut has built-in support for OpenTelemetry. Brut includes configuration for the otel-desktop-viewer or a text-based viewere suitable for develompent. For production, most observability vendors provide OpenTelemetry ingestion any many have free tiers.</p><p>Brut does support logging, however you are encouraged to use OpenTelemetry instead.</p><h2 id="directory-structure" tabindex="-1">Directory Structure <a class="header-anchor" href="#directory-structure" aria-label="Permalink to &quot;Directory Structure&quot;">​</a></h2><p>At the top level:</p><table tabindex="0"><thead><tr><th>Directory</th><th>Purpose</th></tr></thead><tbody><tr><td><code>app/</code></td><td>Contains all configuration and source code specific to your app</td></tr><tr><td><code>bin/</code></td><td>Contains tasks and other CLIs to do development of your app, such as <code>bin/test</code></td></tr><tr><td><code>dx/</code></td><td>Contains scripts to manage your development environment</td></tr><tr><td><code>specs/</code></td><td>Contains all tests</td></tr></tbody></table><p>Inside <code>app</code>/</p><table tabindex="0"><thead><tr><th>Directory</th><th>Purpose</th></tr></thead><tbody><tr><td><code>bootstrap.rb</code></td><td>A ruby file that sets up your app and ensures everything is <code>require</code>d in the right way.</td></tr><tr><td><code>config/</code></td><td>Configuration for your app, such as localizations and translations. Brut tries very hard to make sure there is no YAML in here at all. YAML is not good for you.</td></tr><tr><td><code>public/</code></td><td>Root of public assets served by the app.</td></tr><tr><td><code>src/</code></td><td>All source code for your app</td></tr></tbody></table><p>Inside <code>app/src</code></p><table tabindex="0"><thead><tr><th>Directory</th><th>Purpose</th></tr></thead><tbody><tr><td><code>app.rb</code></td><td>The core of your app, mostly configuration, such as routes, hooks, middleware, etc.</td></tr><tr><td><code>back_end/</code></td><td>Back end classes for your app including database schema, DB models, seed data, and your domain logic</td></tr><tr><td><code>cli/</code></td><td>Any CLIs or tasks for your app</td></tr><tr><td><code>front_end/</code></td><td>The front-end for your app, including pages, components, forms, handlers, JavaScript, and assets</td></tr></tbody></table><p>Inside <code>app/src/back_end</code></p><table tabindex="0"><thead><tr><th>Directory</th><th>Purpose</th></tr></thead><tbody><tr><td><code>data_models/app_data_model.rb</code></td><td>Base class for all DB model classes</td></tr><tr><td><code>data_models/db</code></td><td>DB model classes</td></tr><tr><td><code>data_models/db.rb</code></td><td>Namespace module for DB model classes</td></tr><tr><td><code>data_models/migrations</code></td><td>Database schema migrations</td></tr><tr><td><code>data_models/seed</code></td><td>Seed data used for local development</td></tr></tbody></table><p>Inside <code>app/src/front_end</code></p><table tabindex="0"><thead><tr><th>Directory</th><th>Purpose</th></tr></thead><tbody><tr><td><code>components/</code></td><td>Component classes</td></tr><tr><td><code>css/</code></td><td>CSS, managed by esbuild and <code>bin/build-assets</code></td></tr><tr><td><code>fonts/</code></td><td>Custom fonts, managed by esbuild and <code>bin/build-assets</code></td></tr><tr><td><code>forms/</code></td><td>Form classes</td></tr><tr><td><code>handlers/</code></td><td>Handler classes</td></tr><tr><td><code>images/</code></td><td>Images, copied to <code>app/public</code> by <code>bin/build-assets</code></td></tr><tr><td><code>js/</code></td><td>JavaScript, managed by esbuild and <code>bin/build-assets</code></td></tr><tr><td><code>layouts/</code></td><td>Layout classes</td></tr><tr><td><code>middlewares/</code></td><td>Rack Middleware, if any</td></tr><tr><td><code>pages/</code></td><td>Page classes</td></tr><tr><td><code>route_hooks/</code></td><td>Route hooks, if any</td></tr><tr><td><code>support/</code></td><td>General support classes/junk drawer.</td></tr><tr><td><code>svgs/</code></td><td>SVGs you want to render inline</td></tr></tbody></table>`,79)]))}const E=i(l,[["render",h]]);export{g as __pageData,E as default};

data/docs/assets/overview.md.DVKRM8zl.lean.js

@@ -1 +0,0 @@
-import{_ as i,c as a,o as e,ag as t}from"./chunks/framework.1L-BeKqY.js";const n="/assets/OverviewMetro.DUS-5fUZ.png",g=JSON.parse('{"title":"Conceptual Overview","description":"","frontmatter":{},"headers":[],"relativePath":"overview.md","filePath":"overview.md"}'),l={name:"overview.md"};function h(p,s,r,o,d,k){return e(),a("div",null,s[0]||(s[0]=[t("",79)]))}const E=i(l,[["render",h]]);export{g as __pageData,E as default};