brut 0.17.0 → 0.18.0

data/docs/assets/jobs.md.Bi3qb3v6.js

@@ -1,25 +0,0 @@
-import{_ as e,c as i,o as a,ag as t}from"./chunks/framework.C4nOkCZI.js";const k=JSON.parse('{"title":"Background Jobs","description":"","frontmatter":{},"headers":[],"relativePath":"jobs.md","filePath":"jobs.md"}'),n={name:"jobs.md"};function o(p,s,l,d,h,r){return a(),i("div",null,[...s[0]||(s[0]=[t(`<h1 id="background-jobs" tabindex="-1">Background Jobs <a class="header-anchor" href="#background-jobs" aria-label="Permalink to &quot;Background Jobs&quot;">​</a></h1><p>Brut ships without any background job system, however it should work with any system you&#39;d like to use. Brut can install/configure Sidekiq for you, however you are expected to understand Sidekiq in order to use it.</p><h2 id="setting-up-sidekiq" tabindex="-1">Setting up Sidekiq <a class="header-anchor" href="#setting-up-sidekiq" aria-label="Permalink to &quot;Setting up Sidekiq&quot;">​</a></h2><p>Brut&#39;s code-generation system used for installing capabilities are called <em>segments</em>, and Brut provides a Sidekiq segment you can use to get an initial working setup of Sidekiq in your Brut app.</p><h3 id="adding-the-segment" tabindex="-1">Adding the Segment <a class="header-anchor" href="#adding-the-segment" aria-label="Permalink to &quot;Adding the Segment&quot;">​</a></h3><ol><li><p>Ensure your project files are all committed. This is so you can easily see (and, if needed, undo) the changes <code>mkbrut</code> will make.</p></li><li><p>Use <code>mkbrut</code> to add the segment:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>docker run \\</span></span>
-<span class="line"><span>       --pull always \\</span></span>
-<span class="line"><span>       -v &quot;$PWD&quot;:&quot;$PWD&quot; \\</span></span>
-<span class="line"><span>       -w &quot;$PWD&quot; \\</span></span>
-<span class="line"><span>       -u $(id -u):$(id -g) \\</span></span>
-<span class="line"><span>       -it \\</span></span>
-<span class="line"><span>       thirdtank/mkbrut \\</span></span>
-<span class="line"><span>       mkbrut add-segment -r /path/to/your/project sidekiq</span></span></code></pre></div></li><li><p>This will modify and create various files in your project. Check them out if you like:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>&gt; git status</span></span></code></pre></div></li><li><p>Exit your dev environment (i.e. hit <code>Ctrl-C</code> wherever you ran <code>dx/start</code>).</p></li><li><p>Rebuild and restart your dev environment. This may take a moment, since Valkey will be downloaded.</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>your-computer&gt; dx/build</span></span>
-<span class="line"><span>your-computer&gt; dx/start</span></span></code></pre></div></li><li><p>In another Terminal, connect to your dev container and run <code>bin/setup</code></p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>your-computer&gt; dx/exec bash</span></span>
-<span class="line"><span>devcontainer&gt; bin/setup</span></span></code></pre></div></li><li><p>The segment provides an integration test that will use the actual Sidekiq server and client, running against the actual Valkey database that was installed:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>devcontainer&gt; bin/test e2e specs/integration/sidekiq_works.spec.rb</span></span></code></pre></div></li></ol><p>If this test passes, you are ready to go.</p><h3 id="using-sidekiq-in-brut" tabindex="-1">Using Sidekiq in Brut <a class="header-anchor" href="#using-sidekiq-in-brut" aria-label="Permalink to &quot;Using Sidekiq in Brut&quot;">​</a></h3><p>Jobs live in <code>app/src/back_end/jobs</code>, however this is just a convention and is not enforced - you can place a job anywhere that Zeitwerk will find the class. Brut also provides basic configuration and a base job.</p><table tabindex="0"><thead><tr><th>File</th><th>Purpose</th></tr></thead><tbody><tr><td><code>app/config/sidekiq.yml</code></td><td>Standard configuration for Sidekiq</td></tr><tr><td><code>app/src/back-end/jobs/app_job.r</code></td><td>Base class for your jobs that includes <code>Sidekiq::Job</code></td></tr><tr><td><code>app/src/back-end/segments/sidekiq_segment.rb</code></td><td>Initial client and server configuration for Sidekiq (that you can&#39;t do with <code>sidekiq.yml</code>. This sets up basic observability for your jobs</td></tr></tbody></table><h3 id="accessing-the-web-ui" tabindex="-1">Accessing the Web UI <a class="header-anchor" href="#accessing-the-web-ui" aria-label="Permalink to &quot;Accessing the Web UI&quot;">​</a></h3><p>The Sidekiq segment mounts the Sidekiq Web UI to your app inside <code>config.ru</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:#6A737D;--shiki-dark:#6A737D;"># ...</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">map </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;/sidekiq&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> do</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  use </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">Rack</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">Auth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">Basic</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Sidekiq&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> do</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> |username, password|</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    [username, password] </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">==</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">ENV</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">fetch</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;SIDEKIQ_BASIC_AUTH_USER&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">), </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">ENV</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">fetch</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;SIDEKIQ_BASIC_AUTH_PASSWORD&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:#24292E;--shiki-dark:#E1E4E8;">  run </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">Sidekiq</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">Web</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">new</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># ...</span></span></code></pre></div><p>Values for <code>SIDEKIQ_BASIC_AUTH_USER</code> and <code>SIDEKIQ_BASIC_AUTH_PASSWORD</code> for dev and test are placed into <code>.env.development</code> and <code>.env.test</code>, respectively. You must provide these values for production, based on however you are managing environment variables.</p><p>Once you start the app, navigat to <code>http://localhost:6502/sidekiq</code> and enter the username/password from <code>.env.development</code>. You should see the web UI.</p><h3 id="deploying-with-the-heroku-segment" tabindex="-1">Deploying with The Heroku Segment <a class="header-anchor" href="#deploying-with-the-heroku-segment" aria-label="Permalink to &quot;Deploying with The Heroku Segment&quot;">​</a></h3><p>If you have set up <a href="/deployment.html#heroku-container-based-deployment">Heroku Container-based Deployment</a>, you may need to modify <code>deploy/heroku_config.rb</code>. The Sidekiq segement should have edited this, however if you installed the Heroku segment after setting up Sidekiq, you&#39;ll need to add to the file:</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;"> HerokuConfig</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> self.additional_images</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    {</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">      &quot;sidekiq&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> =&gt; {</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">        cmd:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;bin/run sidekiq&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:#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><h2 id="setting-up-other-job-systems" tabindex="-1">Setting Up Other Job Systems <a class="header-anchor" href="#setting-up-other-job-systems" aria-label="Permalink to &quot;Setting Up Other Job Systems&quot;">​</a></h2><p>To use another job system, you&#39;ll likely want to start with <code>app/src/app.rb</code>. You can place all your initialize code in <code>#boot!</code> to get things working, then factor it out from there. <code>App</code>, the class in that file, is a normal class, so you can extract your setup to other normal classes and bring them in as you would in any other Ruby app.</p><p>Just note that <code>App</code>&#39;s <code>initialize</code> method should avoid making network connections, so while you are safe to create objects and configuration here, do not connect to databases or anything like that. You <em>can</em> do that inside <code>boot!</code>.</p>`,21)])])}const u=e(n,[["render",o]]);export{k as __pageData,u as default};

data/docs/assets/jobs.md.Bi3qb3v6.lean.js

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

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

@@ -1,21 +0,0 @@
-import{_ as t,c as s,o as a,ag as i}from"./chunks/framework.C4nOkCZI.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(r,e,l,d,h,p){return a(),s("div",null,[...e[0]||(e[0]=[i(`<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 classes 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 Hash 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.</p><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to &quot;Overview&quot;">​</a></h2><p>A <a href="/pages.html">Page</a> may need the session, flash, HTTP headers, query string parameters, or placeholder values from the URI. These can all be provided by declaring them as keyword arguments to the page&#39;s initializer:</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;">clas </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 style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># &quot;:id&quot; from /widgets/:id</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 style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># AppSession instance for this request</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">                 flash:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,             </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Flash for this request</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">                 http_user_agent:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,   </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Value of User-Agent header</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">                 compact:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)           </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># query string param &quot;compact&quot;</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    # ...</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>Brut uses this technique in multiple places. It allows you to design classes whose dependencies are clear and explicit, but without having to dig around into hashes or manually construct higher-level objects.</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><table tabindex="0"><thead><tr><th>Value</th><th>Always Present?</th><th>Description</th></tr></thead><tbody><tr><td><code>session:</code></td><td>✅ Yes</td><td>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.</td></tr><tr><td><code>flash:</code></td><td>✅ Yes</td><td>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.</td></tr><tr><td><code>xhr:</code></td><td>✅ Yes</td><td>true if this was an Ajax request.</td></tr><tr><td><code>body:</code></td><td>✅ Yes</td><td>the body submitted, if any.</td></tr><tr><td><code>csrf_token:</code></td><td>✅ Yes</td><td>The current CSRF token.</td></tr><tr><td><code>clock:</code></td><td>✅ Yes</td><td>A <code>Clock</code> to be used to access the current time in the visitor&#39;s time zone.</td></tr><tr><td><code>http_*</code></td><td>❌ No</td><td>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.</td></tr><tr><td><code>rack_request_*:</code></td><td>❌ No</td><td>Any value from the <a href="https://rubydoc.info/gems/rack/3.1.16/Rack/Request" target="_blank" rel="noreferrer"><code>Rack::Request</code></a> or, more likely, from the <a href="https://rubydoc.info/gems/rack/3.1.16/Rack/Request/Helpers" target="_blank" rel="noreferrer"><code>Helpers</code></a> module.</td></tr><tr><td><code>env:</code></td><td>✅ Yes</td><td>The Rack env. This is discouraged, but available if you can&#39;t get what you want directly</td></tr><tr><td><code>form:</code></td><td>❌ No</td><td>The <a href="/forms.html">form</a> that was submitted, for <a href="/handlers.html">handlers</a> only</td></tr><tr><td>Any query string parameter</td><td>❌ No</td><td>For <a href="/pages.html">pages</a> only</td></tr><tr><td>Any route placeholder</td><td>✅ Yes</td><td>For <a href="/pages.html">pages</a> and <a href="/handlers.html">handlers</a></td></tr></tbody></table><h4 id="route-hooks" tabindex="-1">Route Hooks <a class="header-anchor" href="#route-hooks" aria-label="Permalink to &quot;Route Hooks&quot;">​</a></h4><p><a href="/hooks.html">Route hooks</a> are slightly different. They have access to only these values:</p><table tabindex="0"><thead><tr><th>Name</th><th>Always Present?</th><th>Description</th></tr></thead><tbody><tr><td><code>request_context:</code></td><td>❌ No</td><td>The current <a href="/api/Brut/FrontEnd/RequestContext.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::RequestContext</code></a>, thought it may be <code>nil</code> if the hook runs before <a href="/api/Brut/FrontEnd/InlineSvgLocator.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::InlineSvgLocator</code></a></td></tr><tr><td><code>session:</code></td><td>✅ Yes</td><td>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.</td></tr><tr><td><code>request:</code></td><td>✅ Yes</td><td>The Rack request</td></tr><tr><td><code>response:</code></td><td>✅ Yes</td><td>The Rack response</td></tr><tr><td><code>env:</code></td><td>✅ Yes</td><td>The Rack env.</td></tr></tbody></table><h4 id="http-headers" tabindex="-1">HTTP Headers <a class="header-anchor" href="#http-headers" aria-label="Permalink to &quot;HTTP Headers&quot;">​</a></h4><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="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 true power of keyword injection is that you can store your own data into the request context and have it injected into classes when Brut instantiates them.</p><p>The place to do this is in a <a href="/hooks.html">before hook</a>, since that happens before any page or handler is created, but <em>after</em> the <a href="/api/Brut/FrontEnd/RequestContext.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::RequestContext</code></a> is created (which is where all of this information is stored).</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>With this in place, any page that requires an authenticated account can declare it:</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;"> PreferencesPage</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:#6A737D;--shiki-dark:#6A737D;">    # ...</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 request context has no value for <code>authenticated_account</code>, the page cannot be instantiated. Thus, the page&#39;s code can always rely on a non-<code>nil</code> value for <code>authenticated_account</code> (provided you don&#39;t inject <code>nil</code>).</p><div class="warning custom-block github-alert"><p class="custom-block-title">WARNING</p><p>Do not inject <code>nil</code> into the request context. Brut currently allows it, but may prevent it in a future update. <code>nil</code> is no good for nobody.</p></div><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>The tables above document which values should always be available. You should never provide a default value for these, e.g. <code>session:</code> or <code>env:</code>. For values that are not always available, you should provide a default value unless you are sure there will be no routing to the page or handler without the value set.</p><p>This is most important for query string parameters. Since a user can easily manipulate these, if your page accepts, say, the parameter <code>use_detailed_view</code>, but that parameter isn&#39;t present, Brut will not be able to instantiate your page unless <code>use_detailed_view:</code> has a default value in the initializer&#39;s keyword arguments.</p><p>See <a href="/hooks.html">route hooks</a>.</p><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h2><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>Do not provide default values when Brut documents the value is always available</strong><ul><li>If your page needs the session, it will always be there. Don&#39;t default <code>session:</code> to some other value (especially <code>nil</code>!)</li></ul></li><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>`,50)])])}const k=t(n,[["render",o]]);export{u as __pageData,k as default};

data/docs/assets/keyword-injection.md.CqLnnzIz.lean.js

@@ -1 +0,0 @@
-import{_ as t,c as s,o as a,ag as i}from"./chunks/framework.C4nOkCZI.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(r,e,l,d,h,p){return a(),s("div",null,[...e[0]||(e[0]=[i("",50)])])}const k=t(n,[["render",o]]);export{u as __pageData,k as default};

data/docs/assets/layouts.md.HEbeK7Jr.js

@@ -1,68 +0,0 @@
-import{_ as i,c as a,o as t,ag as n}from"./chunks/framework.C4nOkCZI.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,d){return t(),a("div",null,[...s[0]||(s[0]=[n(`<h1 id="layouts" tabindex="-1">Layouts <a class="header-anchor" href="#layouts" aria-label="Permalink to &quot;Layouts&quot;">​</a></h1><p>Brut supports <em>layouts</em>, which are a way to centralizing common HTML amongst many different pages. Conceptually, they are the same as a Rails layout. Technically, they are a Phlex component designed to render a page from a <code>yield</code> block.</p><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to &quot;Overview&quot;">​</a></h2><p>Your app should include <code>app/src/front_end/layouts/default_layout.rb</code>. The name &quot;default&quot; isn&#39;t special, it&#39;s just what the <code>layout</code> method from <a href="/api/Brut/FrontEnd/Page.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Page</code></a> returns.</p><p>A layout is a Phlex component that&#39;s expected to have a single call to <code>yield</code> in its <code>view_template</code> method.</p><h3 id="default-layout-and-common-layout-needs" tabindex="-1">Default Layout and Common Layout Needs <a class="header-anchor" href="#default-layout-and-common-layout-needs" aria-label="Permalink to &quot;Default Layout and Common Layout Needs&quot;">​</a></h3><p>Here is the <code>DefaultLayout</code> provided to new Brut apps:</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;"> 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;">  include</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;">Components</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;"> initialize</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">page:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    @page </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> page</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;"> 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:#6F42C1;--shiki-dark:#B392F0;">    html</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">lang:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;en&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </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:#6F42C1;--shiki-dark:#B392F0;">        meta</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">charset:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;utf-8&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">        meta</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">content:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;width=device-width,initial-scale=1&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">name:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;viewport&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">        meta</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">content:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;website&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">property:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;og:type&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">        link</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">rel:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;manifest&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,  </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">href:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;/static/manifest.json&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">        link</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">rel:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;preload&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">as:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;style&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">href:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> asset_path</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;/css/styles.css&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">))</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">        link</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">rel:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;stylesheet&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,           </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">href:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> asset_path</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;/css/styles.css&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">))</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">        script</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">defer:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">src:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> asset_path</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;/js/app.js&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">))</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        title { app_name }</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">        PageIdentifier</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(page)</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">        I18nTranslations</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;cv.cs&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">        I18nTranslations</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;cv.this_field&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">        Traceparent</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">()</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">        render</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
-<span class="line"><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;">RequestContext</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">inject</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
-<span class="line"><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;">Components</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">LocaleDetection</span></span>
-<span class="line"><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:#D73A49;--shiki-dark:#F97583;">      end</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:#24292E;--shiki-dark:#E1E4E8;">        brut_tracing </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">url:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;/__brut/instrumentation&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">show_warnings:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> true</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        main </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">class:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> page.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">page_name</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> do</span></span>
-<span class="line highlighted"><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><p>You will likely want to customize what&#39;s in your layout, but a few components included by default are important for other features of Brut:</p><table tabindex="0"><thead><tr><th>Component</th><th>Purpose</th></tr></thead><tbody><tr><td><a href="/api/Brut/FrontEnd/Components/PageIdentifier.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Components::PageIdentifier</code></a></td><td>Creates a <code>&lt;meta&gt;</code> tag with the page&#39;s name in it, which is handy for managing your end-to-end tests.</td></tr><tr><td><a href="/api/Brut/FrontEnd/Components/I18nTranslations.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Components::I18nTranslations</code></a></td><td>Includes translatsion for common client-side constraint violations. These are used by <a href="/brut-js/api/ConstraintViolationMessages.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-cv-messages&gt;</code></a> and <code>,brut-cv&gt;</code>. See <a href="/forms.html">Forms</a>, <a href="/i18n.html">I18n</a>, and <a href="/javascript.html">JavaScript</a> for more details</td></tr><tr><td><a href="/api/Brut/FrontEnd/Components/Traceparent.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Components::Traceparent</code></a></td><td>Includes the OpenTelemetry <em>traceparent</em> on the page so that client-side telemetry is reported back to the server. See <a href="/brut-js/api/Tracing.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-tracing&gt;</code></a> and <a href="/instrumentation.html">observability</a></td></tr><tr><td><a href="/brut-js/api/Tracing.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-tracing&gt;</code></a> / <code>brut_tracing</code></td><td>Custom element that collects the client-side telemetry and sends it back to the server. See <a href="/instrumentation.html">observability</a></td></tr></tbody></table><h3 id="adding-logic-dynamic-behavior-to-layouts" tabindex="-1">Adding Logic/Dynamic Behavior to Layouts <a class="header-anchor" href="#adding-logic-dynamic-behavior-to-layouts" aria-label="Permalink to &quot;Adding Logic/Dynamic Behavior to Layouts&quot;">​</a></h3><p>Often, your pages will need to make slight tweaks to the layout that don&#39;t apply to all pages. For example, you may wish for a certain page to refresh on a schedule and you want to do that with a <a href="https://en.wikipedia.org/wiki/Meta_refresh" target="_blank" rel="noreferrer">meta refresh</a>, which must appear in the <code>&lt;head&gt;</code> of the page.</p><p>Unlike Rails, which uses named blocks to render optional or dynamic content, Brut allows you to use methods and normal Ruby-based flow logic. Since your layouts have access to the page they are laying out, you can use your pages&#39; APIs to do whatever it is you need.</p><p>Taking the meta refresh example, suppose your <code>AppPage</code> defines a method, <code>auto_refresh_seconds</code> that, if non-<code>nil</code> means your page should automatically reload itself after that many seconds. By default, you don&#39;t refresh, so it returns <code>nil</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;"> AppPage</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:#6F42C1;--shiki-dark:#B392F0;">page</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # ...</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;"> auto_refresh_seconds</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> nil</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # ...</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><p>Your layout can refrence this API, since it&#39;s just a method on a class:</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;"> 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>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # ...</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:#24292E;--shiki-dark:#E1E4E8;">    doctype</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">    html</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">lang:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;en&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </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:#D73A49;--shiki-dark:#F97583;">        if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> page.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">auto_refresh_seconds</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">          meta</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">http_equiv:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> safe</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;refresh&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">), </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">content:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> page.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">auto_refresh_seconds</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>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">        # ...</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # ...</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><p>Since your pages are a class hierarchy, you can override <code>auto_refresh_seconds</code> in any page, and that page will automatically refresh itself:</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>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> auto_refresh_seconds</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 60</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> *</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 60</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # ...</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><h3 id="alternate-layouts" tabindex="-1">Alternate Layouts <a class="header-anchor" href="#alternate-layouts" aria-label="Permalink to &quot;Alternate Layouts&quot;">​</a></h3><p>If you used <code>mkbrut</code>, you should have access to a <code>BlankLayout</code> that is useful for allowing a page to respond to Ajax requests:</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;"> SomePage</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;"> layout</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;blank&quot;</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><p>See <a href="/recipes/alternate-layouts.html">creating alternate layouts</a> for more information on creating alternate layouts based on your needs.</p><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h2><p>You generally don&#39;t test a layout, aside from end-to-end tests. If your layout needs complex logic, you are encouraged to extract that to a <a href="/components.html">component</a> and test that instead.</p><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>Layouts can use components, just keep in mind that any data a component needs must be passed to its initializer. Since the layout doesn&#39;t have access to the page, this implies that components used in your layout must either not require dynamic data or be <a href="/components.html#global-components">global components</a></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 Sep 9, 2025</em></p><p>Layouts work due to the implementation of the method <code>view_template</code> in <a href="/api/Brut/FrontEnd/Page.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Page</code></a>. This is why a page class must provide <code>page_template</code> instead.</p>`,31)])])}const c=i(e,[["render",l]]);export{y as __pageData,c as default};

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

@@ -1 +0,0 @@
-import{_ as i,c as a,o as t,ag as n}from"./chunks/framework.C4nOkCZI.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,d){return t(),a("div",null,[...s[0]||(s[0]=[n("",31)])])}const c=i(e,[["render",l]]);export{y as __pageData,c as default};

data/docs/assets/lsp.md.bE9dW8n9.js

@@ -1 +0,0 @@
-import{_ as t,c as o,o as r,ag as a}from"./chunks/framework.C4nOkCZI.js";const h=JSON.parse('{"title":"Language Server Protocol (LSP) Support","description":"","frontmatter":{},"headers":[],"relativePath":"lsp.md","filePath":"lsp.md"}'),s={name:"lsp.md"};function d(i,e,n,l,c,u){return r(),o("div",null,[...e[0]||(e[0]=[a('<h1 id="language-server-protocol-lsp-support" tabindex="-1">Language Server Protocol (LSP) Support <a class="header-anchor" href="#language-server-protocol-lsp-support" aria-label="Permalink to &quot;Language Server Protocol (LSP) Support&quot;">​</a></h1><p>Because Brut development happens inside Docker, but your editor likely runs on your computer, getting LSP servers running takes a few more steps.</p><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to &quot;Overview&quot;">​</a></h2><p>When you created your app with <code>mkbrut</code>, the following LSP-related modules are set up and/or installed:</p><ul><li>Shopify&#39;s Ruby LSP server (installed from <code>bin/setup</code>)</li><li>Microsoft&#39;s TypeScript/JavaScript and CSS LSP serfvers (specified in <code>package.json</code>, installed when <code>npm install</code> runs from <code>bin/setup</code>)</li></ul><p>In order to use them from your computer a few configurations are needed, some of which Brut has done, and some you will need to do.</p><table tabindex="0"><thead><tr><th>Configuration</th><th>Description</th><th>Brut Handled?</th></tr></thead><tbody><tr><td>Paths inside Docker Must Match Your Computer</td><td>When an LSP server communicates about a file, it does so with a path. That means that paths inside the Docker container must be the same as those on your computer. Brut achievecs this by using <code>${CWD}</code> inside <code>docker-compose.dx.yml</code></td><td>✅</td></tr><tr><td>Third party libraries must <em>also</em> be installed in a path that is the same in both places</td><td>When jumping to a definition, the LSP server will again use paths, which must match. Because Node modules are installed local to your app, they already work. Ruby Gems, however, are configured to be installed in <code>local-gems</code> in your app. Brut should&#39;ve added this to <code>.gitignore</code> and setup everything inside Docker to use it.</td><td>✅</td></tr><tr><td>Your editor must use <code>dx/exec</code> to execute LSP commands</td><td>Your editor will need to know that the LSP servers are running inside Docker. If your editor allows configuring the commands used to do this, you must prefix them with <code>dx/exec</code>. See <a href="https://naildrivin5.com/blog/2025/06/12/neovim-and-lsp-servers-working-with-docker-based-development.html" target="_blank" rel="noreferrer">my blog post</a> for details.</td><td>❌</td></tr><tr><td>Other languages or plugins to existing LSP servers</td><td>I haven&#39;t used these, so no idea how well they work.</td><td>❌</td></tr></tbody></table>',7)])])}const m=t(s,[["render",d]]);export{h as __pageData,m as default};

data/docs/assets/lsp.md.bE9dW8n9.lean.js

@@ -1 +0,0 @@
-import{_ as t,c as o,o as r,ag as a}from"./chunks/framework.C4nOkCZI.js";const h=JSON.parse('{"title":"Language Server Protocol (LSP) Support","description":"","frontmatter":{},"headers":[],"relativePath":"lsp.md","filePath":"lsp.md"}'),s={name:"lsp.md"};function d(i,e,n,l,c,u){return r(),o("div",null,[...e[0]||(e[0]=[a("",7)])])}const m=t(s,[["render",d]]);export{h as __pageData,m as default};

data/docs/assets/markdown-examples.md.BPmtHlc-.js

@@ -1,33 +0,0 @@
-import{_ as a,c as i,o as n,ag as t}from"./chunks/framework.C4nOkCZI.js";const E=JSON.parse('{"title":"Markdown Extension Examples","description":"","frontmatter":{},"headers":[],"relativePath":"markdown-examples.md","filePath":"markdown-examples.md"}'),e={name:"markdown-examples.md"};function l(p,s,h,k,r,d){return n(),i("div",null,[...s[0]||(s[0]=[t(`<h1 id="markdown-extension-examples" tabindex="-1">Markdown Extension Examples <a class="header-anchor" href="#markdown-extension-examples" aria-label="Permalink to &quot;Markdown Extension Examples&quot;">​</a></h1><p>This page demonstrates some of the built-in markdown extensions provided by VitePress.</p><h2 id="syntax-highlighting" tabindex="-1">Syntax Highlighting <a class="header-anchor" href="#syntax-highlighting" aria-label="Permalink to &quot;Syntax Highlighting&quot;">​</a></h2><p>VitePress provides Syntax Highlighting powered by <a href="https://github.com/shikijs/shiki" target="_blank" rel="noreferrer">Shiki</a>, with additional features like line-highlighting:</p><p><strong>Input</strong></p><div class="language-md vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">md</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;">\`\`\`js{4}</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  data</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> () {</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      msg: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;Highlighted!&#39;</span></span>
-<span class="line"><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:#24292E;--shiki-dark:#E1E4E8;">}</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">\`\`\`</span></span></code></pre></div><p><strong>Output</strong></p><div class="language-js vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">js</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;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  data</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> () {</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
-<span class="line highlighted"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      msg: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;Highlighted!&#39;</span></span>
-<span class="line"><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:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h2 id="custom-containers" tabindex="-1">Custom Containers <a class="header-anchor" href="#custom-containers" aria-label="Permalink to &quot;Custom Containers&quot;">​</a></h2><p><strong>Input</strong></p><div class="language-md vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">md</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;">::: info</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">This is an info box.</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:::</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::: tip</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">This is a tip.</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:::</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::: warning</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">This is a warning.</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:::</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::: danger</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">This is a dangerous warning.</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:::</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::: details</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">This is a details block.</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:::</span></span></code></pre></div><p><strong>Output</strong></p><div class="info custom-block"><p class="custom-block-title">INFO</p><p>This is an info box.</p></div><div class="tip custom-block"><p class="custom-block-title">TIP</p><p>This is a tip.</p></div><div class="warning custom-block"><p class="custom-block-title">WARNING</p><p>This is a warning.</p></div><div class="danger custom-block"><p class="custom-block-title">DANGER</p><p>This is a dangerous warning.</p></div><details class="details custom-block"><summary>Details</summary><p>This is a details block.</p></details><h2 id="more" tabindex="-1">More <a class="header-anchor" href="#more" aria-label="Permalink to &quot;More&quot;">​</a></h2><p>Check out the documentation for the <a href="https://vitepress.dev/guide/markdown" target="_blank" rel="noreferrer">full list of markdown extensions</a>.</p>`,19)])])}const c=a(e,[["render",l]]);export{E as __pageData,c as default};

data/docs/assets/markdown-examples.md.BPmtHlc-.lean.js

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

data/docs/assets/middleware.md.BhOIsg59.js

@@ -1,20 +0,0 @@
-import{_ as a,c as i,o as e,ag as t}from"./chunks/framework.C4nOkCZI.js";const c=JSON.parse('{"title":"Middleware","description":"","frontmatter":{},"headers":[],"relativePath":"middleware.md","filePath":"middleware.md"}'),n={name:"middleware.md"};function l(h,s,p,d,r,o){return e(),i("div",null,[...s[0]||(s[0]=[t(`<h1 id="middleware" tabindex="-1">Middleware <a class="header-anchor" href="#middleware" aria-label="Permalink to &quot;Middleware&quot;">​</a></h1><p>Brut supports Rack Middleware.</p><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to &quot;Overview&quot;">​</a></h2><p>Similar to <a href="/hooks.html">route hooks</a>, Brut supports Rack Middleware, which is a lower-level way of modifying a request or changing behavior.</p><p>Middleware is recommended if what you want to do is not dependent on your application&#39;s code or classes and is relatively simple.</p><p>To use a middleware, create the class in <code>app/src/front_end/middleware/</code>. You are encouraged to extend <a href="/api/Brut/FrontEnd/Middleware.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Middleware</code></a>, however this is an empty class currently. It could grow to have helper methods you&#39;ll find useful.</p><p>The class itself should conform to Rack&#39;s specification, which is typically that it will be given the Rack &quot;app&quot; in the initializer, and then have a method <code>call</code> which will be given the Rack environment.</p><p>Here&#39;s a middleware that adds a tag to the environment for paths that are &quot;special&quot; to our app, which in this case means they start with <code>/special</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;"> TagSpecialPathsMiddleware</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;">Middleware</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;"> initializer</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(app)</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    @app </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> app</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;"> call</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(env)</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> env[</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;PATH_INFO&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=~</span><span style="--shiki-light:#032F62;--shiki-dark:#DBEDFF;"> /^</span><span style="--shiki-light:#22863A;--shiki-light-font-weight:bold;--shiki-dark:#85E89D;--shiki-dark-font-weight:bold;">\\/</span><span style="--shiki-light:#032F62;--shiki-dark:#DBEDFF;">special</span><span style="--shiki-light:#22863A;--shiki-light-font-weight:bold;--shiki-dark:#85E89D;--shiki-dark-font-weight:bold;">\\/</span><span style="--shiki-light:#032F62;--shiki-dark:#DBEDFF;">/</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      env[</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;app.special_path&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> true</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;">    @app.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">call</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(env)</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>To use this middleware, call <code>use</code> with the class name as a string inside <code>App</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;"> 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>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # ...</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  use </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:TagSpecialPathsMiddleware</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # ...</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><p>Don&#39;t use the actual class as this can create load order issues.</p><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h2><p>Like hooks, Rack middleware can be tested as a normal class. That said, you are encouraged to test the middleware as part of an end-to-end test if possible, since this will ensure it&#39;s configured properly in the context of your app.</p><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>Middleware should be used when its logic can be entirely based on the Rack environment passed-in. While your database models and other classes should be available, excessive use of your domain logic in a middleware can create a confusing situation.</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 June 12, 2025</em></p><p>Route hooks and Middlewares do not share implementations, however they are similar in concept. These concepts may be unified in the future.</p><p><code>use</code> and the way Middleware behaves follows Sinatra&#39;s implementation as Brut is currently based on Sinatra. This may not always be the case, however as things change, we will do our best to ensure the semantics remain the same. Nevertheless, it&#39;s advisable to have end to end tests assert the behavior of your configured middleware and not just a unit test of the class itself.</p>`,21)])])}const g=a(n,[["render",l]]);export{c as __pageData,g as default};

data/docs/assets/middleware.md.BhOIsg59.lean.js

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

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

@@ -1 +0,0 @@
-import{_ as a,c as r,o as s,ag as t,j as o}from"./chunks/framework.C4nOkCZI.js";const i="/assets/OverviewMetro.DUS-5fUZ.png",g=JSON.parse('{"title":"Conceptual Overview","description":"","frontmatter":{},"headers":[],"relativePath":"overview.md","filePath":"overview.md"}'),n={name:"overview.md"};function l(d,e,c,h,u,p){return s(),r("div",null,[...e[0]||(e[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 way to build web apps that generate HTML, have JavaScript and CSS, and interact with a Database. It&#39;s built on Ruby standard libraries and community libraries like <a href="https://sequel.jeremyevans.net/" target="_blank" rel="noreferrer">Sequel</a> and <a href="https://phlex.fun" target="_blank" rel="noreferrer">Phlex</a>.</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>Brut&#39;s abstractions tend to mirror concepts found in the domain of web sites. For example, a browser serves up a web page at a URL. In Brut, that&#39;s called a <em>page</em> and you&#39;d create a subclass of <a href="/api/Brut/FrontEnd/Page.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Page</code></a> to implement it.</p><p>Brut tries to avoid abstractions that simply translate existing standards into a more aestheticly pleasing form. You already need to know CSS, HTML, the Web Platform, and SQL, so there&#39;s little to gain by requiring you to learn a different way to use them.</p><h2 id="yes-you-can-build-a-blog-in-15-minutes" tabindex="-1">Yes, You Can Build a Blog in 15 Minutes <a class="header-anchor" href="#yes-you-can-build-a-blog-in-15-minutes" aria-label="Permalink to &quot;Yes, You Can Build a Blog in 15 Minutes&quot;">​</a></h2>',7),o("iframe",{title:"Make a Blog App in 15(ish) minutes With BrutRB - A New Ruby Web Framework",width:"560",height:"315",src:"https://video.hardlimit.com/videos/embed/ae7EMhwjDq9kSH5dqQ9swV",frameborder:"0",allowfullscreen:"",sandbox:"allow-same-origin allow-scripts allow-popups allow-forms"},null,-1),t('<p><a href="https://github.com/thirdtank/blog-demo" target="_blank" rel="noreferrer">Check out the source code</a> if you want to dive right in.</p><h2 id="basic-elements" tabindex="-1">Basic Elements <a class="header-anchor" href="#basic-elements" aria-label="Permalink to &quot;Basic Elements&quot;">​</a></h2><p>Brut organizes its code and behavior around four basic concepts:</p><ul><li><strong>Client</strong> 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><strong>Server</strong> 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><strong>Front End</strong> 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><strong>Back End</strong> 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="'+i+'" 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> are submitted by the browser to the server. In Brut, a form describes the contents of a <code>&lt;form&gt;</code> as well as provides access to the submitted data.</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="/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="/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><p>Brut doesn&#39;t prevent the addition of more pieces of infrastructure or code. You can add a Redis cache, a Sidekiq job backend, or integrate with third party APIs.</p><h2 id="brut-is-not-mvc" tabindex="-1">Brut is Not MVC <a class="header-anchor" href="#brut-is-not-mvc" aria-label="Permalink to &quot;Brut is Not MVC&quot;">​</a></h2><p>Brut is <em>not</em> an MVC framework, nor does it use the concept of <em>resources</em> as an abstraction. Although HTTP does include this concept, we find it&#39;s not as useful for managing web apps as it may seem.</p><p>We&#39;ve found that teams often struggle with mapping what everyone else calls pages to resources and HTTP verbs. We also find that the consonance of features, resources, actions, and database tables never materializes. We&#39;re basically not going to debate what the meaning of the <code>DELETE</code> verb on the <code>widgets</code> resource is actually supposed to mean.</p><h2 id="brut-is-hippocratic-licensed" tabindex="-1">Brut is Hippocratic Licensed <a class="header-anchor" href="#brut-is-hippocratic-licensed" aria-label="Permalink to &quot;Brut is Hippocratic Licensed&quot;">​</a></h2><p>It&#39;s important to me that Brut is used to make the world a better place. Please take a note of <a href="https://firstdonoharm.dev/version/3/0/cl-eco-media-my-tal-xuar.txt" target="_blank" rel="noreferrer">its license</a></p>',12)])])}const b=a(n,[["render",l]]);export{g as __pageData,b as default};

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

@@ -1 +0,0 @@
-import{_ as a,c as r,o as s,ag as t,j as o}from"./chunks/framework.C4nOkCZI.js";const i="/assets/OverviewMetro.DUS-5fUZ.png",g=JSON.parse('{"title":"Conceptual Overview","description":"","frontmatter":{},"headers":[],"relativePath":"overview.md","filePath":"overview.md"}'),n={name:"overview.md"};function l(d,e,c,h,u,p){return s(),r("div",null,[...e[0]||(e[0]=[t("",7),o("iframe",{title:"Make a Blog App in 15(ish) minutes With BrutRB - A New Ruby Web Framework",width:"560",height:"315",src:"https://video.hardlimit.com/videos/embed/ae7EMhwjDq9kSH5dqQ9swV",frameborder:"0",allowfullscreen:"",sandbox:"allow-same-origin allow-scripts allow-popups allow-forms"},null,-1),t("",12)])])}const b=a(n,[["render",l]]);export{g as __pageData,b as default};