brut 0.14.0 → 0.15.0

data/docs/assets/form-constraints.md.KlfXSKm2.lean.js

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

data/docs/assets/{forms.md.v9qIbmUM.js → forms.md.Bii91k3E.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as a,o as t,ag as e}from"./chunks/framework.1L-BeKqY.js";const c=JSON.parse('{"title":"Forms","description":"","frontmatter":{},"headers":[],"relativePath":"forms.md","filePath":"forms.md"}'),n={name:"forms.md"};function h(l,s,p,r,k,o){return t(),a("div",null,s[0]||(s[0]=[e(`<h1 id="forms" tabindex="-1">Forms <a class="header-anchor" href="#forms" aria-label="Permalink to &quot;Forms&quot;">​</a></h1><p>In HTML, forms are the way data is submit to the server. Forms attract complexity since they interact with user experience, data validation, and interaction with a back-end database.</p><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to &quot;Overview&quot;">​</a></h2><p>Forms in Brut accomplish three things:</p><ul><li>Forms model the data elements of a <code>&lt;form&gt;</code>, including client-side constraints (which Brut can check server-side as well).</li><li>Forms assist in HTML generation, to ensure the HTML elements are consistent and correct.</li><li>Forms hold data submitted to the server. No need for strong parameters or digging into a Hash of Whatever.</li></ul><p>Since forms can lead to a lot of complexity, this module will stick to the very basics. There are several recipes we&#39;ll link to that explain more complex interactions with forms.</p><h3 id="declaring-form-data-elements" tabindex="-1">Declaring Form Data/Elements <a class="header-anchor" href="#declaring-form-data-elements" aria-label="Permalink to &quot;Declaring Form Data/Elements&quot;">​</a></h3><p>When you <a href="/routes.html">create a form route</a>, this imlplies a form class exists to specify the data:</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/app.rb</span></span>
+import{_ as i,c as a,o as t,ag as e}from"./chunks/framework.C4nOkCZI.js";const c=JSON.parse('{"title":"Forms","description":"","frontmatter":{},"headers":[],"relativePath":"forms.md","filePath":"forms.md"}'),n={name:"forms.md"};function h(l,s,p,r,k,o){return t(),a("div",null,[...s[0]||(s[0]=[e(`<h1 id="forms" tabindex="-1">Forms <a class="header-anchor" href="#forms" aria-label="Permalink to &quot;Forms&quot;">​</a></h1><p>In HTML, forms are the way data is submit to the server. Forms attract complexity since they interact with user experience, data validation, and interaction with a back-end database.</p><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to &quot;Overview&quot;">​</a></h2><p>Forms in Brut accomplish three things:</p><ul><li>Forms model the data elements of a <code>&lt;form&gt;</code>, including client-side constraints (which Brut can check server-side as well).</li><li>Forms assist in HTML generation, to ensure the HTML elements are consistent and correct.</li><li>Forms hold data submitted to the server. No need for strong parameters or digging into a Hash of Whatever.</li></ul><p>Since forms can lead to a lot of complexity, this module will stick to the very basics. There are several recipes we&#39;ll link to that explain more complex interactions with forms.</p><h3 id="declaring-form-data-elements" tabindex="-1">Declaring Form Data/Elements <a class="header-anchor" href="#declaring-form-data-elements" aria-label="Permalink to &quot;Declaring Form Data/Elements&quot;">​</a></h3><p>When you <a href="/routes.html">create a form route</a>, this imlplies a form class exists to specify the data:</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/app.rb</span></span>
 <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"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  form </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;new_widget&quot;</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span>
@@ -31,7 +31,7 @@ import{_ as i,c as a,o as t,ag as e}from"./chunks/framework.1L-BeKqY.js";const c
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  &lt;</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">input</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;number&quot;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;quantity&quot;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> required</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> min</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;0&quot;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> step</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;1&quot;</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;">textarea</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;description&quot;</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;">textarea</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;">form</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span></code></pre></div><p>Forms accept a single initializer parameter, <code>params</code> that is a <code>Hash</code>. <a href="/api/Brut/FrontEnd/Form.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Form</code></a> implements this initializer, and will pluck values from the hash to initialize the inputs:</p><div class="vp-code-group vp-adaptive-theme"><div class="tabs"><input type="radio" name="group-GTtoI" id="tab-gWl4X_N" checked><label data-title="Form Class" for="tab-gWl4X_N">Form Class</label><input type="radio" name="group-GTtoI" id="tab-F2DGi8-"><label data-title="HTML Generated" for="tab-F2DGi8-">HTML Generated</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;"> NewWidgetPage</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:#24292E;--shiki-dark:#E1E4E8;">&lt;/</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">form</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span></code></pre></div><p>Forms accept a single initializer parameter, <code>params</code> that is a <code>Hash</code>. <a href="/api/Brut/FrontEnd/Form.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Form</code></a> implements this initializer, and will pluck values from the hash to initialize the inputs:</p><div class="vp-code-group vp-adaptive-theme"><div class="tabs"><input type="radio" name="group-XvMsS" id="tab-7ExvMtJ" checked><label data-title="Form Class" for="tab-7ExvMtJ">Form Class</label><input type="radio" name="group-XvMsS" id="tab-o8IkcAX"><label data-title="HTML Generated" for="tab-o8IkcAX">HTML Generated</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;"> NewWidgetPage</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;">  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;">form:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> nil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
@@ -61,4 +61,4 @@ import{_ as i,c as a,o as t,ag as e}from"./chunks/framework.1L-BeKqY.js";const c
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    form.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">quantity</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    # =&gt; whatever quantity was submitted</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    form.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">description</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # =&gt; description provided</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>A few things to note about how this works:</p><ul><li>Only those inputs declared in the form class can be accessed. All other values are discarded. No need for &quot;strong parameters&quot;.</li><li>All values are strings, because this is what HTML provides.</li><li>Blank values are coerced to <code>nil</code>.</li></ul><p>The next module will deal with form constraints and validations, in particular how to manage the user experience around client-side constraint violations, how to re-check them server side, and how to perform server-side checks.</p><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h2><p>Form classes don&#39;t need any logic on them, but they can be given helper methods or other logic if it makes sense. To test them, test them like any other class - instantiate an object and examine the behavior of its methods.</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><h3 id="create-components-to-generate-form-controls" tabindex="-1">Create Components to Generate Form Controls <a class="header-anchor" href="#create-components-to-generate-form-controls" aria-label="Permalink to &quot;Create Components to Generate Form Controls&quot;">​</a></h3><p><a href="/api/Brut/FrontEnd/Components/Inputs.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Components::Inputs</code></a> will generate the basic tags like <code>&lt;input&gt;</code> or <code>&lt;select&gt;</code>. Everything else like <code>&lt;label&gt;</code> is up to you. We recommend that you create <a href="/components.html">components</a> to generate the markup required for <em>your</em> inputs and controls.</p><p>The recipe <a href="/recipes/text-field-component.html">&quot;Creating a Text Field&quot;</a> will walk you through the steps and considerations.</p><h3 id="take-advantage-of-client-side-constraints" tabindex="-1">Take Advantage of Client Side Constraints <a class="header-anchor" href="#take-advantage-of-client-side-constraints" aria-label="Permalink to &quot;Take Advantage of Client Side Constraints&quot;">​</a></h3><p>Even though client-side constraints can sometimes be awkward in certain browsers, they are going to be eminently usable and accessible, and you can easily re-validate them on the server side.</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 13, 2025</em></p><p>For HTML generation, there are few classes that work together:</p><ul><li><em>input definitions</em> define an input and tend to provide an API similar to HTML&#39;s. See <a href="/api/Brut/FrontEnd/Forms/InputDefinition.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Forms::InputDefinition</code></a>.</li><li><em>inputs</em> represent the runtime state of an input from the browser. Whereas an input definition has no state, the input does. It delegates much of its behavior to the underlying input definition. It&#39;s <code>value=</code> method performs client-side constraint validations by creating a <a href="/api/Brut/FrontEnd/Forms/ValidityState.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Forms::ValidityState</code></a> internally. See <a href="/api/Brut/FrontEnd/Forms/Input.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Forms::Input</code></a>.</li><li><a href="/api/Brut/FrontEnd/Forms/InputDeclarations.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Forms::InputDeclarations</code></a> is a module that allows creating input definitions inside your form class. It implements the class methods like <code>input</code>.</li><li><a href="/api/Brut/FrontEnd/Components/Inputs.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Components::Inputs</code></a> contains components used to generate <code>&lt;input&gt;</code> fields. These classes will coerce the value of the <code>input</code> they are given to generate the correct HTML.</li></ul>`,48)]))}const g=i(n,[["render",h]]);export{c as __pageData,g as default};
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><p>A few things to note about how this works:</p><ul><li>Only those inputs declared in the form class can be accessed. All other values are discarded. No need for &quot;strong parameters&quot;.</li><li>All values are strings, because this is what HTML provides.</li><li>Blank values are coerced to <code>nil</code>.</li></ul><p>The next module will deal with form constraints and validations, in particular how to manage the user experience around client-side constraint violations, how to re-check them server side, and how to perform server-side checks.</p><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h2><p>Form classes don&#39;t need any logic on them, but they can be given helper methods or other logic if it makes sense. To test them, test them like any other class - instantiate an object and examine the behavior of its methods.</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><h3 id="create-components-to-generate-form-controls" tabindex="-1">Create Components to Generate Form Controls <a class="header-anchor" href="#create-components-to-generate-form-controls" aria-label="Permalink to &quot;Create Components to Generate Form Controls&quot;">​</a></h3><p><a href="/api/Brut/FrontEnd/Components/Inputs.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Components::Inputs</code></a> will generate the basic tags like <code>&lt;input&gt;</code> or <code>&lt;select&gt;</code>. Everything else like <code>&lt;label&gt;</code> is up to you. We recommend that you create <a href="/components.html">components</a> to generate the markup required for <em>your</em> inputs and controls.</p><p>The recipe <a href="/recipes/text-field-component.html">&quot;Creating a Text Field&quot;</a> will walk you through the steps and considerations.</p><h3 id="take-advantage-of-client-side-constraints" tabindex="-1">Take Advantage of Client Side Constraints <a class="header-anchor" href="#take-advantage-of-client-side-constraints" aria-label="Permalink to &quot;Take Advantage of Client Side Constraints&quot;">​</a></h3><p>Even though client-side constraints can sometimes be awkward in certain browsers, they are going to be eminently usable and accessible, and you can easily re-validate them on the server side.</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 13, 2025</em></p><p>For HTML generation, there are few classes that work together:</p><ul><li><em>input definitions</em> define an input and tend to provide an API similar to HTML&#39;s. See <a href="/api/Brut/FrontEnd/Forms/InputDefinition.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Forms::InputDefinition</code></a>.</li><li><em>inputs</em> represent the runtime state of an input from the browser. Whereas an input definition has no state, the input does. It delegates much of its behavior to the underlying input definition. It&#39;s <code>value=</code> method performs client-side constraint validations by creating a <a href="/api/Brut/FrontEnd/Forms/ValidityState.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Forms::ValidityState</code></a> internally. See <a href="/api/Brut/FrontEnd/Forms/Input.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Forms::Input</code></a>.</li><li><a href="/api/Brut/FrontEnd/Forms/InputDeclarations.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Forms::InputDeclarations</code></a> is a module that allows creating input definitions inside your form class. It implements the class methods like <code>input</code>.</li><li><a href="/api/Brut/FrontEnd/Components/Inputs.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Components::Inputs</code></a> contains components used to generate <code>&lt;input&gt;</code> fields. These classes will coerce the value of the <code>input</code> they are given to generate the correct HTML.</li></ul>`,48)])])}const g=i(n,[["render",h]]);export{c as __pageData,g as default};

data/docs/assets/forms.md.Bii91k3E.lean.js

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

data/docs/assets/{getting-started.md.DTOl4c2g.js → getting-started.md.ChAvueK7.js}

@@ -1,4 +1,4 @@
-import{_ as s,c as e,o as t,ag as n}from"./chunks/framework.1L-BeKqY.js";const u=JSON.parse('{"title":"Getting Started","description":"","frontmatter":{},"headers":[],"relativePath":"getting-started.md","filePath":"getting-started.md"}'),i={name:"getting-started.md"};function p(l,a,o,r,d,h){return t(),e("div",null,a[0]||(a[0]=[n(`<h1 id="getting-started" tabindex="-1">Getting Started <a class="header-anchor" href="#getting-started" aria-label="Permalink to &quot;Getting Started&quot;">​</a></h1><p>Brut is developed alongside a separate gem called <code>mkbrut</code>, which allows you to create a new Brut app. It will set up your dev environment as well.</p><h2 id="get-mkbrut" tabindex="-1">Get <code>mkbrut</code> <a class="header-anchor" href="#get-mkbrut" aria-label="Permalink to &quot;Get \`mkbrut\`&quot;">​</a></h2><p>The simplest way to use <code>mkbrut</code> is to use an existing <a href="https://hub.docker.com/repository/docker/thirdtank/mkbrut/general" target="_blank" rel="noreferrer">Docker image</a>. You don&#39;t have to install or configure Ruby:</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>
+import{_ as s,c as e,o as t,ag as n}from"./chunks/framework.C4nOkCZI.js";const u=JSON.parse('{"title":"Getting Started","description":"","frontmatter":{},"headers":[],"relativePath":"getting-started.md","filePath":"getting-started.md"}'),i={name:"getting-started.md"};function p(l,a,o,r,d,h){return t(),e("div",null,[...a[0]||(a[0]=[n(`<h1 id="getting-started" tabindex="-1">Getting Started <a class="header-anchor" href="#getting-started" aria-label="Permalink to &quot;Getting Started&quot;">​</a></h1><p>Brut is developed alongside a separate gem called <code>mkbrut</code>, which allows you to create a new Brut app. It will set up your dev environment as well.</p><h2 id="get-mkbrut" tabindex="-1">Get <code>mkbrut</code> <a class="header-anchor" href="#get-mkbrut" aria-label="Permalink to &quot;Get \`mkbrut\`&quot;">​</a></h2><p>The simplest way to use <code>mkbrut</code> is to use an existing <a href="https://hub.docker.com/repository/docker/thirdtank/mkbrut/general" target="_blank" rel="noreferrer">Docker image</a>. You don&#39;t have to install or configure Ruby:</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>
@@ -6,14 +6,14 @@ import{_ as s,c as e,o as t,ag as n}from"./chunks/framework.1L-BeKqY.js";const u
 <span class="line"><span>       -it \\</span></span>
 <span class="line"><span>       thirdtank/mkbrut \\</span></span>
 <span class="line"><span>       mkbrut my-new-app</span></span></code></pre></div><p>If you already have Ruby 3.4 installed, you can install <code>mkbrut</code> directly:</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; gem install mkbrut</span></span>
-<span class="line"><span>&gt; mkbrut my-new-app</span></span></code></pre></div><h2 id="init-your-app" tabindex="-1">Init Your App <a class="header-anchor" href="#init-your-app" aria-label="Permalink to &quot;Init Your App&quot;">​</a></h2><p>A Brut app just needs a name, which will be used to derive a few more useful values. For now:</p><div class="vp-code-group vp-adaptive-theme"><div class="tabs"><input type="radio" name="group-6y8D1" id="tab-s1hUM7J" checked><label data-title="Docker-based" for="tab-s1hUM7J">Docker-based</label><input type="radio" name="group-6y8D1" id="tab-fRCRS6Q"><label data-title="RubyGems-based" for="tab-fRCRS6Q">RubyGems-based</label></div><div class="blocks"><div class="language- vp-adaptive-theme active"><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>&gt; mkbrut my-new-app</span></span></code></pre></div><h2 id="init-your-app" tabindex="-1">Init Your App <a class="header-anchor" href="#init-your-app" aria-label="Permalink to &quot;Init Your App&quot;">​</a></h2><p>A Brut app just needs a name, which will be used to derive a few more useful values. For now:</p><div class="vp-code-group vp-adaptive-theme"><div class="tabs"><input type="radio" name="group-bpPaC" id="tab-7whTmb-" checked><label data-title="Docker-based" for="tab-7whTmb-">Docker-based</label><input type="radio" name="group-bpPaC" id="tab-NRnFRfO"><label data-title="RubyGems-based" for="tab-NRnFRfO">RubyGems-based</label></div><div class="blocks"><div class="language- vp-adaptive-theme active"><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 my-new-app</span></span></code></pre></div><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>mkbrut my-new-app</span></span></code></pre></div></div></div><p>This will create your new app, along with some demo routes, components, handlers, and tests. If this is your first time using Brut, we recommend you examine these demo components.</p><p>To create your app without the demo components:</p><div class="vp-code-group vp-adaptive-theme"><div class="tabs"><input type="radio" name="group-Mhemx" id="tab-eMdxFs4" checked><label data-title="Docker-based" for="tab-eMdxFs4">Docker-based</label><input type="radio" name="group-Mhemx" id="tab-0y2w3J5"><label data-title="RubyGems-based" for="tab-0y2w3J5">RubyGems-based</label></div><div class="blocks"><div class="language- vp-adaptive-theme active"><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>       mkbrut my-new-app</span></span></code></pre></div><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>mkbrut my-new-app</span></span></code></pre></div></div></div><p>This will create your new app, along with some demo routes, components, handlers, and tests. If this is your first time using Brut, we recommend you examine these demo components.</p><p>To create your app without the demo components:</p><div class="vp-code-group vp-adaptive-theme"><div class="tabs"><input type="radio" name="group-6QXPS" id="tab-pzn0MLg" checked><label data-title="Docker-based" for="tab-pzn0MLg">Docker-based</label><input type="radio" name="group-6QXPS" id="tab-i9TQMHy"><label data-title="RubyGems-based" for="tab-i9TQMHy">RubyGems-based</label></div><div class="blocks"><div class="language- vp-adaptive-theme active"><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>
@@ -28,4 +28,4 @@ import{_ as s,c as e,o as t,ag as n}from"./chunks/framework.1L-BeKqY.js";const u
 <span class="line highlighted"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">        &quot;Welcome to My New App!&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:#6A737D;--shiki-dark:#6A737D;">      # ...</span></span></code></pre></div><p>When you reload your browser, you&#39;ll see your change</p><h2 id="run-the-tests" tabindex="-1">Run the Tests <a class="header-anchor" href="#run-the-tests" aria-label="Permalink to &quot;Run the Tests&quot;">​</a></h2><p>There are a few tests you can run, as well as some checks that you aren&#39;t using RubyGems with security vulnerabilities. Run it all now with <code>bin/ci</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>dx/exec bin/ci</span></span></code></pre></div><h2 id="now-build-the-rest-of-your-app-🦉" tabindex="-1">Now Build The Rest of Your App 🦉 <a class="header-anchor" href="#now-build-the-rest-of-your-app-🦉" aria-label="Permalink to &quot;Now Build The Rest of Your App 🦉&quot;">​</a></h2><p>You can <a href="/tutorial.html">follow the tutorial</a>, check out the <a href="/overview.html">conceptual overview</a>, or dive straight into the <a href="/api/index.html">API docs</a>. You might also want to check out the docs for <a href="/lsp.html">LSP Support</a>.</p>`,29)]))}const k=s(i,[["render",p]]);export{u as __pageData,k as default};
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">      # ...</span></span></code></pre></div><p>When you reload your browser, you&#39;ll see your change</p><h2 id="run-the-tests" tabindex="-1">Run the Tests <a class="header-anchor" href="#run-the-tests" aria-label="Permalink to &quot;Run the Tests&quot;">​</a></h2><p>There are a few tests you can run, as well as some checks that you aren&#39;t using RubyGems with security vulnerabilities. Run it all now with <code>bin/ci</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>dx/exec bin/ci</span></span></code></pre></div><h2 id="now-build-the-rest-of-your-app-🦉" tabindex="-1">Now Build The Rest of Your App 🦉 <a class="header-anchor" href="#now-build-the-rest-of-your-app-🦉" aria-label="Permalink to &quot;Now Build The Rest of Your App 🦉&quot;">​</a></h2><p>You can <a href="/tutorial.html">follow the tutorial</a>, check out the <a href="/overview.html">conceptual overview</a>, or dive straight into the <a href="/api/index.html">API docs</a>. You might also want to check out the docs for <a href="/lsp.html">LSP Support</a>.</p>`,29)])])}const k=s(i,[["render",p]]);export{u as __pageData,k as default};

data/docs/assets/getting-started.md.ChAvueK7.lean.js

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

data/docs/assets/{handlers.md.h84MMB1R.js → handlers.md.C5tUwmmo.js}

@@ -1,4 +1,4 @@
-import{_ as a,c as i,o as e,ag as t}from"./chunks/framework.1L-BeKqY.js";const c=JSON.parse('{"title":"Handlers & Actions","description":"","frontmatter":{},"headers":[],"relativePath":"handlers.md","filePath":"handlers.md"}'),n={name:"handlers.md"};function l(h,s,r,o,d,p){return e(),i("div",null,s[0]||(s[0]=[t(`<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="handler-structure" tabindex="-1">Handler Structure <a class="header-anchor" href="#handler-structure" aria-label="Permalink to &quot;Handler Structure&quot;">​</a></h3><p>A handler&#39;s initializer is subject to <a href="/keyword-injection.html">keyword injection</a>, with the addition of the <code>form:</code> keyword, which, if present, will be an instance of the associated form class, populated with the data in the form submission (not available for <code>path</code> or <code>action</code> routes).</p><p>You must implement <code>handle</code> to process the form. <strong>A handler&#39;s public API, as called by Brut and your tests, is <code>handle!</code></strong>, however you implement <code>handle</code>, which <code>handle!</code> calls.</p><p><code>handle</code>&#39;s return value dictates what will happen next:</p><table tabindex="0"><thead><tr><th>Return Value</th><th>Behavior</th></tr></thead><tbody><tr><td>Instance of a page or component</td><td>That page or component&#39;s HTML is generated and returned. This is not a redirect, but more like <code>render :new</code> in a Rails controller</td></tr><tr><td><a href="/api/Brut/FrontEnd/HttpStatus.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::HttpStatus</code></a></td><td>This HTTP status is returned with no body. Use <code>http_status</code> from <a href="/api/Brut/FrontEnd/HandlingResults.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::HandlingResults</code></a> (included in all handlers) to create an instance from a number</td></tr><tr><td><code>URI</code></td><td>Redirect to the URI. Use <code>redirect_to</code> from <a href="/api/Brut/FrontEnd/HandlingResults.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::HandlingResults</code></a> (included in all handlers) to generate a URI from a page class and parameters</td></tr><tr><td>Two element array with <em>element 0</em> being a <a href="/api/Brut/FrontEnd/HttpStatus.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::HttpStatus</code></a>, and <em>element 1</em> being a page or component instance</td><td>Generates the page or component&#39;s HTML, but sets the given status instead of 200. Useful for Ajax responses where the HTTP status affects client-side behavior</td></tr><tr><td><a href="/api/Brut/FrontEnd/Download.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Download</code></a></td><td>Download a file</td></tr><tr><td><a href="/api/Brut/FrontEnd/GenericResponse.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::GenericResponse</code></a></td><td>wrap any Rack response</td></tr></tbody></table><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><h3 id="handling-a-form-submission" tabindex="-1">Handling a Form Submission <a class="header-anchor" href="#handling-a-form-submission" aria-label="Permalink to &quot;Handling a Form Submission&quot;">​</a></h3><p>A common pattern when handling a form submisssion is to check for any constraint violations. If there are some, re-generate the HTML for the page containing the form, highlighting the violations. Otherwise, save the data and redirect to another page.</p><p>Here&#39;s how that looks:</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;"> NewWidgetHandler</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> AppHandler</span></span>
+import{_ as a,c as i,o as e,ag as t}from"./chunks/framework.C4nOkCZI.js";const c=JSON.parse('{"title":"Handlers & Actions","description":"","frontmatter":{},"headers":[],"relativePath":"handlers.md","filePath":"handlers.md"}'),n={name:"handlers.md"};function l(h,s,r,o,d,p){return e(),i("div",null,[...s[0]||(s[0]=[t(`<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="handler-structure" tabindex="-1">Handler Structure <a class="header-anchor" href="#handler-structure" aria-label="Permalink to &quot;Handler Structure&quot;">​</a></h3><p>A handler&#39;s initializer is subject to <a href="/keyword-injection.html">keyword injection</a>, with the addition of the <code>form:</code> keyword, which, if present, will be an instance of the associated form class, populated with the data in the form submission (not available for <code>path</code> or <code>action</code> routes).</p><p>You must implement <code>handle</code> to process the form. <strong>A handler&#39;s public API, as called by Brut and your tests, is <code>handle!</code></strong>, however you implement <code>handle</code>, which <code>handle!</code> calls.</p><p><code>handle</code>&#39;s return value dictates what will happen next:</p><table tabindex="0"><thead><tr><th>Return Value</th><th>Behavior</th></tr></thead><tbody><tr><td>Instance of a page or component</td><td>That page or component&#39;s HTML is generated and returned. This is not a redirect, but more like <code>render :new</code> in a Rails controller</td></tr><tr><td><a href="/api/Brut/FrontEnd/HttpStatus.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::HttpStatus</code></a></td><td>This HTTP status is returned with no body. Use <code>http_status</code> from <a href="/api/Brut/FrontEnd/HandlingResults.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::HandlingResults</code></a> (included in all handlers) to create an instance from a number</td></tr><tr><td><code>URI</code></td><td>Redirect to the URI. Use <code>redirect_to</code> from <a href="/api/Brut/FrontEnd/HandlingResults.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::HandlingResults</code></a> (included in all handlers) to generate a URI from a page class and parameters</td></tr><tr><td>Two element array with <em>element 0</em> being a <a href="/api/Brut/FrontEnd/HttpStatus.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::HttpStatus</code></a>, and <em>element 1</em> being a page or component instance</td><td>Generates the page or component&#39;s HTML, but sets the given status instead of 200. Useful for Ajax responses where the HTTP status affects client-side behavior</td></tr><tr><td><a href="/api/Brut/FrontEnd/Download.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Download</code></a></td><td>Download a file</td></tr><tr><td><a href="/api/Brut/FrontEnd/GenericResponse.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::GenericResponse</code></a></td><td>wrap any Rack response</td></tr></tbody></table><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><h3 id="handling-a-form-submission" tabindex="-1">Handling a Form Submission <a class="header-anchor" href="#handling-a-form-submission" aria-label="Permalink to &quot;Handling a Form Submission&quot;">​</a></h3><p>A common pattern when handling a form submisssion is to check for any constraint violations. If there are some, re-generate the HTML for the page containing the form, highlighting the violations. Otherwise, save the data and redirect to another page.</p><p>Here&#39;s how that looks:</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;"> NewWidgetHandler</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>
 <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:#D73A49;--shiki-dark:#F97583;">  end</span></span>
@@ -51,4 +51,4 @@ import{_ as a,c as i,o as e,ag as t}from"./chunks/framework.1L-BeKqY.js";const c
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      WidgetsPage</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:#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="hooks" tabindex="-1">Hooks <a class="header-anchor" href="#hooks" aria-label="Permalink to &quot;Hooks&quot;">​</a></h3><p>A handler&#39;s public API is <code>handle!</code>, because it first calls <code>before_handle</code>. This operates as a before hook, and has the same return values as <code>handle</code>, with the exception of also recognizing <code>nil</code>, which indicates processing should proceed to <code>handle</code>.</p><p>Generally, you don&#39;t need to implement hooksd on a per-handler basis, but may find it useful in a shared super class to implement cross-cutting behavior.</p><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h2><p>See <a href="/unit-tests.html">Unit Testing</a> for some basic assumptions and configuration available for all Brut unit tests.</p><p>Handler tests should be straightforward: you create your handler, call <code>handle!</code> (remember, <code>handle!</code> is the public API, and will call your hooks, which you want in a test), then examine the result returned and any ancillary behavior, such as updated database records.</p><p>Some matchers are available to make assertions about <code>handle!</code>&#39;s return value:</p><ul><li><code>have_redirected_to</code> will check that the handler redirected to a give URI. See <a href="/api/Brut/SpecSupport/Matchers/HaveRedirectedTo.html" target="_self" rel="noopener" data-no-router><code>Brut::SpecSupport::Matchers::HaveRedirectedTo</code></a>.</li><li><code>have_generated</code> will check that the handler generated a specific page or component&#39;s HTML. See <code>&lt;D-f&gt;Brut::SpecSupport::Matchers::HaveGenerated</code>.</li><li><code>have_returned_http_status</code> will check that the handler returned an HTTP status. See <a href="/api/Brut/SpecSupport/Matchers/HaveReturnedHttpStatus.html" target="_self" rel="noopener" data-no-router><code>Brut::SpecSupport::Matchers::HaveReturnedHttpStatus</code></a>.</li><li><code>have_constraint_violation</code> will check if a form had a particular constraint violation set on it. See <a href="/api/Brut/SpecSupport/Matchers/HaveConstraintViolation.html" target="_self" rel="noopener" data-no-router><code>Brut::SpecSupport::Matchers::HaveConstraintViolation</code></a>.</li></ul><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><h3 id="you-don-t-always-need-resourceful-or-restful-routes" tabindex="-1">You Don&#39;t Always Need Resourceful or RESTful Routes <a class="header-anchor" href="#you-don-t-always-need-resourceful-or-restful-routes" aria-label="Permalink to &quot;You Don&#39;t Always Need Resourceful or RESTful Routes&quot;">​</a></h3><p>For any code where the browser is performing a submission, use either <code>form</code> or <code>action</code> to declare your route. These will both use an HTTP <code>POST</code> to your server and handler. In the example above, we had a <code>POST</code> to <code>/delete_widget/:widget_id</code>, and not, say, a <code>DELETE</code> to it.</p><p>The main reason is that a browser can only submit to a server using <code>GET</code> or <code>POST</code>, so there&#39;s little value in &quot;tunneling&quot; another verb of POST. It doesn&#39;t really matter. And, even though you may use Ajax to submit such data, having it degrade to normal browser-based HTTP is a good practice.</p><p>For API-like calls where a browser will never directly interact with the route, and it would only be via a server-to-server call, RESTful routes makes sense. But they don&#39;t need to be the default.</p><h3 id="avoid-business-logic-in-handlers" tabindex="-1">Avoid Business Logic in Handlers <a class="header-anchor" href="#avoid-business-logic-in-handlers" aria-label="Permalink to &quot;Avoid Business Logic in Handlers&quot;">​</a></h3><p>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>`,38)]))}const g=a(n,[["render",l]]);export{c as __pageData,g as default};
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><h3 id="hooks" tabindex="-1">Hooks <a class="header-anchor" href="#hooks" aria-label="Permalink to &quot;Hooks&quot;">​</a></h3><p>A handler&#39;s public API is <code>handle!</code>, because it first calls <code>before_handle</code>. This operates as a before hook, and has the same return values as <code>handle</code>, with the exception of also recognizing <code>nil</code>, which indicates processing should proceed to <code>handle</code>.</p><p>Generally, you don&#39;t need to implement hooksd on a per-handler basis, but may find it useful in a shared super class to implement cross-cutting behavior.</p><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h2><p>See <a href="/unit-tests.html">Unit Testing</a> for some basic assumptions and configuration available for all Brut unit tests.</p><p>Handler tests should be straightforward: you create your handler, call <code>handle!</code> (remember, <code>handle!</code> is the public API, and will call your hooks, which you want in a test), then examine the result returned and any ancillary behavior, such as updated database records.</p><p>Some matchers are available to make assertions about <code>handle!</code>&#39;s return value:</p><ul><li><code>have_redirected_to</code> will check that the handler redirected to a give URI. See <a href="/api/Brut/SpecSupport/Matchers/HaveRedirectedTo.html" target="_self" rel="noopener" data-no-router><code>Brut::SpecSupport::Matchers::HaveRedirectedTo</code></a>.</li><li><code>have_generated</code> will check that the handler generated a specific page or component&#39;s HTML. See <code>&lt;D-f&gt;Brut::SpecSupport::Matchers::HaveGenerated</code>.</li><li><code>have_returned_http_status</code> will check that the handler returned an HTTP status. See <a href="/api/Brut/SpecSupport/Matchers/HaveReturnedHttpStatus.html" target="_self" rel="noopener" data-no-router><code>Brut::SpecSupport::Matchers::HaveReturnedHttpStatus</code></a>.</li><li><code>have_constraint_violation</code> will check if a form had a particular constraint violation set on it. See <a href="/api/Brut/SpecSupport/Matchers/HaveConstraintViolation.html" target="_self" rel="noopener" data-no-router><code>Brut::SpecSupport::Matchers::HaveConstraintViolation</code></a>.</li></ul><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><h3 id="you-don-t-always-need-resourceful-or-restful-routes" tabindex="-1">You Don&#39;t Always Need Resourceful or RESTful Routes <a class="header-anchor" href="#you-don-t-always-need-resourceful-or-restful-routes" aria-label="Permalink to &quot;You Don&#39;t Always Need Resourceful or RESTful Routes&quot;">​</a></h3><p>For any code where the browser is performing a submission, use either <code>form</code> or <code>action</code> to declare your route. These will both use an HTTP <code>POST</code> to your server and handler. In the example above, we had a <code>POST</code> to <code>/delete_widget/:widget_id</code>, and not, say, a <code>DELETE</code> to it.</p><p>The main reason is that a browser can only submit to a server using <code>GET</code> or <code>POST</code>, so there&#39;s little value in &quot;tunneling&quot; another verb of POST. It doesn&#39;t really matter. And, even though you may use Ajax to submit such data, having it degrade to normal browser-based HTTP is a good practice.</p><p>For API-like calls where a browser will never directly interact with the route, and it would only be via a server-to-server call, RESTful routes makes sense. But they don&#39;t need to be the default.</p><h3 id="avoid-business-logic-in-handlers" tabindex="-1">Avoid Business Logic in Handlers <a class="header-anchor" href="#avoid-business-logic-in-handlers" aria-label="Permalink to &quot;Avoid Business Logic in Handlers&quot;">​</a></h3><p>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>`,38)])])}const g=a(n,[["render",l]]);export{c as __pageData,g as default};

data/docs/assets/handlers.md.C5tUwmmo.lean.js

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

data/docs/assets/{hooks.md.Jmb5VOLA.js → hooks.md.CoiYCKRc.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as a,o as n,ag as e}from"./chunks/framework.1L-BeKqY.js";const E=JSON.parse('{"title":"Route Hooks","description":"","frontmatter":{},"headers":[],"relativePath":"hooks.md","filePath":"hooks.md"}'),h={name:"hooks.md"};function t(l,s,k,p,r,o){return n(),a("div",null,s[0]||(s[0]=[e(`<h1 id="route-hooks" tabindex="-1">Route Hooks <a class="header-anchor" href="#route-hooks" aria-label="Permalink to &quot;Route Hooks&quot;">​</a></h1><p>Route hooks are similar to <a href="/middleware.html">Middleware</a>, but have a richer API and aren&#39;t as low-level. Route hooks can happen before a page or handler is called, or after.</p><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to &quot;Overview&quot;">​</a></h2><p>We&#39;ve seen examples thusfar of using a route hook to place the authenticated user or account into the request context for later injection into pages or handlers. Brut uses route hooks for locale detection and for content security policies.</p><p>At its core, a <em>before</em> hook is a class that extends <a href="/api/Brut/FrontEnd/RouteHook.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::RouteHook</code></a> and implements <code>before</code> and an <em>after</em> hook implements <code>after</code>. Both <code>before</code> and <code>after</code> can be <a href="/keyword-injection.html">injected</a> with request-time information.</p><p>To register a hook, you&#39;d call <code>before</code> or <code>after</code> in your <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>
+import{_ as i,c as a,o as n,ag as e}from"./chunks/framework.C4nOkCZI.js";const E=JSON.parse('{"title":"Route Hooks","description":"","frontmatter":{},"headers":[],"relativePath":"hooks.md","filePath":"hooks.md"}'),h={name:"hooks.md"};function t(l,s,k,p,r,o){return n(),a("div",null,[...s[0]||(s[0]=[e(`<h1 id="route-hooks" tabindex="-1">Route Hooks <a class="header-anchor" href="#route-hooks" aria-label="Permalink to &quot;Route Hooks&quot;">​</a></h1><p>Route hooks are similar to <a href="/middleware.html">Middleware</a>, but have a richer API and aren&#39;t as low-level. Route hooks can happen before a page or handler is called, or after.</p><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to &quot;Overview&quot;">​</a></h2><p>We&#39;ve seen examples thusfar of using a route hook to place the authenticated user or account into the request context for later injection into pages or handlers. Brut uses route hooks for locale detection and for content security policies.</p><p>At its core, a <em>before</em> hook is a class that extends <a href="/api/Brut/FrontEnd/RouteHook.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::RouteHook</code></a> and implements <code>before</code> and an <em>after</em> hook implements <code>after</code>. Both <code>before</code> and <code>after</code> can be <a href="/keyword-injection.html">injected</a> with request-time information.</p><p>To register a hook, you&#39;d call <code>before</code> or <code>after</code> in your <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>
@@ -77,4 +77,4 @@ import{_ as i,c as a,o as n,ag as e}from"./chunks/framework.1L-BeKqY.js";const E
 <span class="line highlighted"><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;">  end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h2><p>Route hooks are normal classes, you could test them as you would a handler or other class. This may be advisable for complex hooks, however it may be more realistic to test their behavior through end-to-end tests as this will ensure they are configured correctly in the context of the 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>Route hooks and <a href="/pages.html#hooks">page hooks</a> serve similar purposes, so logic in one can be placed in other other at your discretion. We recommend you use route hooks for cross-cutting issues across the entire app, such as login checks or for adding context to a request.</p><p>For page- or use-case-specific behavior, it may be better to put the logic in a page hook.</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>Hooks are applied in <a href="/api/Brut/Framework/MCP.html" target="_self" rel="noopener" data-no-router><code>Brut::Framework::MCP</code></a> usiung Sinatra&#39;s hooks mechanism. While Brut may not always be based on Sinatra, it is now. You should not rely on it.</p><p>Lastly, there is some dissonance in how keyword injection works. Pages and Handlers have initializer injection, while hooks use method injection. This may change - Hooks may be re-designed to use initializer injection, and even changed so that before and after hooks have different base classes.</p>`,33)]))}const g=i(h,[["render",t]]);export{E as __pageData,g as default};
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h2><p>Route hooks are normal classes, you could test them as you would a handler or other class. This may be advisable for complex hooks, however it may be more realistic to test their behavior through end-to-end tests as this will ensure they are configured correctly in the context of the 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>Route hooks and <a href="/pages.html#hooks">page hooks</a> serve similar purposes, so logic in one can be placed in other other at your discretion. We recommend you use route hooks for cross-cutting issues across the entire app, such as login checks or for adding context to a request.</p><p>For page- or use-case-specific behavior, it may be better to put the logic in a page hook.</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>Hooks are applied in <a href="/api/Brut/Framework/MCP.html" target="_self" rel="noopener" data-no-router><code>Brut::Framework::MCP</code></a> usiung Sinatra&#39;s hooks mechanism. While Brut may not always be based on Sinatra, it is now. You should not rely on it.</p><p>Lastly, there is some dissonance in how keyword injection works. Pages and Handlers have initializer injection, while hooks use method injection. This may change - Hooks may be re-designed to use initializer injection, and even changed so that before and after hooks have different base classes.</p>`,33)])])}const g=i(h,[["render",t]]);export{E as __pageData,g as default};

data/docs/assets/hooks.md.CoiYCKRc.lean.js

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

data/docs/assets/{i18n.md.BAm9t9JJ.js → i18n.md.DxkCKhUw.js}

@@ -1,4 +1,4 @@
-import{_ as e,c as a,o as i,ag as t}from"./chunks/framework.1L-BeKqY.js";const k=JSON.parse('{"title":"Internationaliztion and Localization","description":"","frontmatter":{},"headers":[],"relativePath":"i18n.md","filePath":"i18n.md"}'),n={name:"i18n.md"};function o(l,s,d,h,p,r){return i(),a("div",null,s[0]||(s[0]=[t(`<h1 id="internationaliztion-and-localization" tabindex="-1">Internationaliztion and Localization <a class="header-anchor" href="#internationaliztion-and-localization" aria-label="Permalink to &quot;Internationaliztion and Localization&quot;">​</a></h1><p>Brut uses Ruby&#39;s i18n gem to provide support for localization and internationalization.</p><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to &quot;Overview&quot;">​</a></h2><p><a href="/api/Brut/I18n/BaseMethods.html" target="_self" rel="noopener" data-no-router><code>Brut::I18n::BaseMethods</code></a> provides the core implementation of Brut&#39;s i18n support, and it largely wraps the <code>t</code> and <code>l</code> methods of the i18n gem.</p><p>Consider this:</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:#6F42C1;--shiki-dark:#B392F0;">t</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;my.key&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">foo:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;Bar&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span></code></pre></div><p>This will locate the string with the key <code>my.key</code> and return it, replacing <code>%{foo}</code> with <code>&quot;Bar&quot;</code>, if <code>%{foo}</code> is present in the string.</p><p>The keys are located in files in <code>app/config/i18n</code>. The directories there correspond to the locales your app supports, e.g .<code>app/config/i18n/en</code> would hold translations for English.</p><p>The translation files themselves are 🎉<strong>NOT YAML</strong>🎊. They are Ruby files. By default, there are two files: <code>app/config/i18n/en/1_defaults.rb</code> and <code>app/config/i18n/en/2_app.rb</code> (noting that <code>/en/</code> is for English and other langauges are obviously supported).</p><p><code>1_defaults.rb</code> provides values for keys Brut may require or use, such as for front-end constraint violations. <code>2_app.rb</code> provides your app&#39;s keys. If this file contains the same keys as <code>1_defaults.rb</code>, your file&#39;s values will be used.</p><p>The file is a giant Hash, so the key above 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:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
+import{_ as e,c as a,o as i,ag as t}from"./chunks/framework.C4nOkCZI.js";const k=JSON.parse('{"title":"Internationaliztion and Localization","description":"","frontmatter":{},"headers":[],"relativePath":"i18n.md","filePath":"i18n.md"}'),n={name:"i18n.md"};function o(l,s,d,h,p,r){return i(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="internationaliztion-and-localization" tabindex="-1">Internationaliztion and Localization <a class="header-anchor" href="#internationaliztion-and-localization" aria-label="Permalink to &quot;Internationaliztion and Localization&quot;">​</a></h1><p>Brut uses Ruby&#39;s i18n gem to provide support for localization and internationalization.</p><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to &quot;Overview&quot;">​</a></h2><p><a href="/api/Brut/I18n/BaseMethods.html" target="_self" rel="noopener" data-no-router><code>Brut::I18n::BaseMethods</code></a> provides the core implementation of Brut&#39;s i18n support, and it largely wraps the <code>t</code> and <code>l</code> methods of the i18n gem.</p><p>Consider this:</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:#6F42C1;--shiki-dark:#B392F0;">t</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;my.key&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">foo:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;Bar&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span></code></pre></div><p>This will locate the string with the key <code>my.key</code> and return it, replacing <code>%{foo}</code> with <code>&quot;Bar&quot;</code>, if <code>%{foo}</code> is present in the string.</p><p>The keys are located in files in <code>app/config/i18n</code>. The directories there correspond to the locales your app supports, e.g .<code>app/config/i18n/en</code> would hold translations for English.</p><p>The translation files themselves are 🎉<strong>NOT YAML</strong>🎊. They are Ruby files. By default, there are two files: <code>app/config/i18n/en/1_defaults.rb</code> and <code>app/config/i18n/en/2_app.rb</code> (noting that <code>/en/</code> is for English and other langauges are obviously supported).</p><p><code>1_defaults.rb</code> provides values for keys Brut may require or use, such as for front-end constraint violations. <code>2_app.rb</code> provides your app&#39;s keys. If this file contains the same keys as <code>1_defaults.rb</code>, your file&#39;s values will be used.</p><p>The file is a giant Hash, so the key above 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:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  my:</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:#032F62;--shiki-dark:#9ECBFF;"> &quot;Hello there %{foo}&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>
@@ -20,4 +20,4 @@ import{_ as e,c as a,o as i,ag as t}from"./chunks/framework.1L-BeKqY.js";const k
 <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;">    )</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>The result of <code>t</code> is safe HTML, so you must use <code>raw</code> to avoid escaping it.</p><p>In a CLI or back-end context, HTML escaping is not relevant and can actually create problems, so <code>ForCLI</code> and <code>ForBackend</code> no-op <code>safe</code> and <code>capture</code>.</p><p>When using <code>ForHTML</code>, all interpolated values are HTML-escaped. <code>ForCLI</code> and <code>ForBackend</code> are not.</p><h3 id="localizing-dates-and-times" tabindex="-1">Localizing Dates and Times <a class="header-anchor" href="#localizing-dates-and-times" aria-label="Permalink to &quot;Localizing Dates and Times&quot;">​</a></h3><p><code>l</code> can be called and this defers to the Ruby I18n library.</p><p>Date and time formats can be configured in the translation files. <code>l</code> does not accept a full key for the format. It is created dynamically by the library, so you must take care in which one you use. If you pass a <code>Date</code> into <code>l</code>, <code>date.formats.«format»</code> is used. If you pass a <code>Time</code> in, <code>time.formats.«format»</code> is used.</p><p>The values of the formats are strings suitable for <a href="https://www.man7.org/linux/man-pages/man3/strftime.3.html" target="_blank" rel="noreferrer"><code>strftime</code></a>. The site <a href="https://www.strfti.me/" target="_blank" rel="noreferrer">strif.me</a> can be helpful in conjuring the right value.</p><p>Brut includes translations for various formats that you can inspect in <code>app/config/i18n/«lang»/1_defaults.rb</code>.</p><h3 id="displaying-dates-and-times-in-html" tabindex="-1">Displaying Dates and Times in HTML <a class="header-anchor" href="#displaying-dates-and-times-in-html" aria-label="Permalink to &quot;Displaying Dates and Times in HTML&quot;">​</a></h3><p>While <code>l</code> will return a string you can use anywhere, you are most likely going to show dates and times in HTML. For that, you should use a <code>&lt;time&gt;</code> element. Brut provides <a href="/api/Brut/FrontEnd/Components/TimeTag.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Components::TimeTag</code></a> (remember that if you <code>include Brut::FrontEnd::Components</code>, it&#39;s a Phlex <em>kit</em> and thus you can use <code>TimeTag(...)</code> directly) to do this. It contains additional behavior to make friendly dates and times.</p><ul><li>You can give it a <code>timestamp:</code> or <code>date:</code> to control which formatting style is used.</li><li><code>skip_year_if_same</code>, if true, will omit the year from any format if the current year is the same as the year being displayed. This is true by default</li><li><code>skip_dow_if_not_this_week</code>, if true, will omit the day of week if the date or time is more than 7 days in the past. This is true by default.</li></ul><p>The way <code>skip_year_if_same</code> and <code>skip_dow_if_not_this_week</code> work is to append <code>no_year</code> and/or <code>no_dow</code> to existing format strings which are assumed to omit this elements.</p><p>If you wish to create your own formats, you can add them as well.</p><h3 id="constraint-violations-and-field-names" tabindex="-1">Constraint Violations and Field Names <a class="header-anchor" href="#constraint-violations-and-field-names" aria-label="Permalink to &quot;Constraint Violations and Field Names&quot;">​</a></h3><p>The interpolated value <code>{field}</code> is special. It is assumed to be the name of a field in a constraint violation message, e.g. <code>&quot;%{field} is required&quot;</code>. It is the only interpolated value that can be omitted without causing an error.</p><p>If included, it will work as normal:</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:#6F42C1;--shiki-dark:#B392F0;">t</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;cv.ss.required&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">field:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;Email&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># =&gt; Email is required</span></span></code></pre></div><p>If omitted, the value of <code>&quot;cv.this_field&quot;</code> is used. This is included in <code>1_default.rb</code>, but if it&#39;s missing, Brut will raise. Assuming the value is <code>&quot;This field&quot;</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:#6F42C1;--shiki-dark:#B392F0;">t</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;cv.ss.required&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># =&gt; This field is required</span></span></code></pre></div><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h2><p>In tests, you can call <code>t</code> and <code>l</code> to examine values as needed. You may find the <code>have_i18n_string</code> matcher usefult to check generated HTML for I18n values (see <a href="/api/Brut/SpecSupport/Matchers/HaveI18nString.html" target="_self" rel="noopener" data-no-router><code>Brut::SpecSupport::Matchers::HaveI18nString</code></a>).</p><div class="warning custom-block github-alert"><p class="custom-block-title">WARNING</p><p>Brut hardcodes English for tests, which you may not want. This will be addressed in the future.</p></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>None at this time, however Brut&#39;s I18n has not been battle-tested.</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 7, 2025</em></p><p>None at this time.</p>`,61)]))}const u=e(n,[["render",o]]);export{k as __pageData,u as default};
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><p>The result of <code>t</code> is safe HTML, so you must use <code>raw</code> to avoid escaping it.</p><p>In a CLI or back-end context, HTML escaping is not relevant and can actually create problems, so <code>ForCLI</code> and <code>ForBackend</code> no-op <code>safe</code> and <code>capture</code>.</p><p>When using <code>ForHTML</code>, all interpolated values are HTML-escaped. <code>ForCLI</code> and <code>ForBackend</code> are not.</p><h3 id="localizing-dates-and-times" tabindex="-1">Localizing Dates and Times <a class="header-anchor" href="#localizing-dates-and-times" aria-label="Permalink to &quot;Localizing Dates and Times&quot;">​</a></h3><p><code>l</code> can be called and this defers to the Ruby I18n library.</p><p>Date and time formats can be configured in the translation files. <code>l</code> does not accept a full key for the format. It is created dynamically by the library, so you must take care in which one you use. If you pass a <code>Date</code> into <code>l</code>, <code>date.formats.«format»</code> is used. If you pass a <code>Time</code> in, <code>time.formats.«format»</code> is used.</p><p>The values of the formats are strings suitable for <a href="https://www.man7.org/linux/man-pages/man3/strftime.3.html" target="_blank" rel="noreferrer"><code>strftime</code></a>. The site <a href="https://www.strfti.me/" target="_blank" rel="noreferrer">strif.me</a> can be helpful in conjuring the right value.</p><p>Brut includes translations for various formats that you can inspect in <code>app/config/i18n/«lang»/1_defaults.rb</code>.</p><h3 id="displaying-dates-and-times-in-html" tabindex="-1">Displaying Dates and Times in HTML <a class="header-anchor" href="#displaying-dates-and-times-in-html" aria-label="Permalink to &quot;Displaying Dates and Times in HTML&quot;">​</a></h3><p>While <code>l</code> will return a string you can use anywhere, you are most likely going to show dates and times in HTML. For that, you should use a <code>&lt;time&gt;</code> element. Brut provides <a href="/api/Brut/FrontEnd/Components/TimeTag.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Components::TimeTag</code></a> (remember that if you <code>include Brut::FrontEnd::Components</code>, it&#39;s a Phlex <em>kit</em> and thus you can use <code>TimeTag(...)</code> directly) to do this. It contains additional behavior to make friendly dates and times.</p><ul><li>You can give it a <code>timestamp:</code> or <code>date:</code> to control which formatting style is used.</li><li><code>skip_year_if_same</code>, if true, will omit the year from any format if the current year is the same as the year being displayed. This is true by default</li><li><code>skip_dow_if_not_this_week</code>, if true, will omit the day of week if the date or time is more than 7 days in the past. This is true by default.</li></ul><p>The way <code>skip_year_if_same</code> and <code>skip_dow_if_not_this_week</code> work is to append <code>no_year</code> and/or <code>no_dow</code> to existing format strings which are assumed to omit this elements.</p><p>If you wish to create your own formats, you can add them as well.</p><h3 id="constraint-violations-and-field-names" tabindex="-1">Constraint Violations and Field Names <a class="header-anchor" href="#constraint-violations-and-field-names" aria-label="Permalink to &quot;Constraint Violations and Field Names&quot;">​</a></h3><p>The interpolated value <code>{field}</code> is special. It is assumed to be the name of a field in a constraint violation message, e.g. <code>&quot;%{field} is required&quot;</code>. It is the only interpolated value that can be omitted without causing an error.</p><p>If included, it will work as normal:</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:#6F42C1;--shiki-dark:#B392F0;">t</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;cv.ss.required&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">field:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;Email&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># =&gt; Email is required</span></span></code></pre></div><p>If omitted, the value of <code>&quot;cv.this_field&quot;</code> is used. This is included in <code>1_default.rb</code>, but if it&#39;s missing, Brut will raise. Assuming the value is <code>&quot;This field&quot;</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:#6F42C1;--shiki-dark:#B392F0;">t</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;cv.ss.required&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># =&gt; This field is required</span></span></code></pre></div><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h2><p>In tests, you can call <code>t</code> and <code>l</code> to examine values as needed. You may find the <code>have_i18n_string</code> matcher usefult to check generated HTML for I18n values (see <a href="/api/Brut/SpecSupport/Matchers/HaveI18nString.html" target="_self" rel="noopener" data-no-router><code>Brut::SpecSupport::Matchers::HaveI18nString</code></a>).</p><div class="warning custom-block github-alert"><p class="custom-block-title">WARNING</p><p>Brut hardcodes English for tests, which you may not want. This will be addressed in the future.</p></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>None at this time, however Brut&#39;s I18n has not been battle-tested.</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 7, 2025</em></p><p>None at this time.</p>`,61)])])}const u=e(n,[["render",o]]);export{k as __pageData,u as default};

data/docs/assets/i18n.md.DxkCKhUw.lean.js

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

data/docs/assets/{index.md.Bn9e0sRJ.js → index.md.DnphWyQd.js}

@@ -1 +1 @@
-import{_ as a,c as o,o as n,j as t}from"./chunks/framework.1L-BeKqY.js";const s="/assets/LogoStop.Gb3tDhL1.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":"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};
+import{_ as a,c as o,o as n,j as t}from"./chunks/framework.C4nOkCZI.js";const s="/assets/LogoStop.Gb3tDhL1.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":"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.Bn9e0sRJ.lean.js → index.md.DnphWyQd.lean.js}

@@ -1 +1 @@
-import{_ as a,c as o,o as n,j as t}from"./chunks/framework.1L-BeKqY.js";const s="/assets/LogoStop.Gb3tDhL1.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":"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};
+import{_ as a,c as o,o as n,j as t}from"./chunks/framework.C4nOkCZI.js";const s="/assets/LogoStop.Gb3tDhL1.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":"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/{instrumentation.md._lNSriEZ.js → instrumentation.md.BcxjC4jd.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as e,o as a,ag as t}from"./chunks/framework.1L-BeKqY.js";const c=JSON.parse('{"title":"Instrumentation and Observability","description":"","frontmatter":{},"headers":[],"relativePath":"instrumentation.md","filePath":"instrumentation.md"}'),n={name:"instrumentation.md"};function l(h,s,o,r,p,d){return a(),e("div",null,s[0]||(s[0]=[t(`<h1 id="instrumentation-and-observability" tabindex="-1">Instrumentation and Observability <a class="header-anchor" href="#instrumentation-and-observability" aria-label="Permalink to &quot;Instrumentation and Observability&quot;">​</a></h1><p>Brut has built-in support for OpenTelemetry, which is an open standard used by many observability vendors to allow you to understand the behavior of your app in production. Brut also includes a configuration for the <a href="https://github.com/CtrlSpice/otel-desktop-viewer/" target="_blank" rel="noreferrer">otel-desktop-viewer</a>, which allows you to see instrumentation in development.</p><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to &quot;Overview&quot;">​</a></h2><h3 id="why-instrument" tabindex="-1">Why Instrument? <a class="header-anchor" href="#why-instrument" aria-label="Permalink to &quot;Why Instrument?&quot;">​</a></h3><p>In production, you&#39;ll need to know what your app is doing and how well it&#39;s working. Historically, logs can provide this information in a roundabout way. Over the last many years, Application Performance Monitoring (APM) vendors like New Relic and Data Dog allowed developers to see much richer detail about how an app is working.</p><p>You could see, for example, the 95th percentil of your dashboard controller&#39;s performance, or the top 10 slowest SQL statements your app is executing. OpenTelemetry attempts to unify the API used to communicate this information from your app to your chosen vendor, and most vendors support it.</p><p>Instrumentation, then, is a way to record what your app is doing, how long its taking, and perhaps even why it&#39;s doing what it&#39;s doing, down to a very specific level. If properly configured, you could examine the performance of the app for a particular user on a particular day.</p><h3 id="setting-up-instrumentation" tabindex="-1">Setting up Instrumentation <a class="header-anchor" href="#setting-up-instrumentation" aria-label="Permalink to &quot;Setting up Instrumentation&quot;">​</a></h3><p>Brut automatically sets up OpenTelemetry (OTel) tracing. The primary interface you will use is <a href="/api/Brut/Instrumentation/OpenTelemetry.html" target="_self" rel="noopener" data-no-router><code>Brut::Instrumentation::OpenTelemetry</code></a>, which is available via <code>Brut.container.instrumentation</code>. We&#39;ll discuss that in a moment.</p><p>To configure the specifics of where the traces will go, the OTel gem uses environment variables:</p><table tabindex="0"><thead><tr><th>Variable</th><th>Value</th><th>Purpose</th></tr></thead><tbody><tr><td><code>OTEL_EXPORTER_OTLP_ENDPOINT</code></td><td>Depends on environment</td><td>Where to send the tracers. This is provided by your vendor, but is <code>http://otel-desktop-viewer:4318</code> in development</td></tr><tr><td><code>OTEL_EXPORTER_OTLP_HEADERS</code></td><td>Depends on vendor</td><td>Your vendor may ask you to set this. It often contains identifying information or API keys</td></tr><tr><td><code>OTEL_EXPORTER_OTLP_PROTOCOL</code></td><td>http/protobuf</td><td>Your vendor may request a different protocol, but protobuf is common and supported by otel-desktop-viewer</td></tr><tr><td><code>OTEL_LOG_LEVEL</code></td><td>debug</td><td>Useful when setting everything up to understand why things aren&#39;t working if they aren&#39;t working</td></tr><tr><td><code>OTEL_RUBY_BSP_START_THREAD_ON_BOOT</code></td><td>false</td><td>Deals with esoteric issues with Puma. See <a href="https://github.com/open-telemetry/opentelemetry-ruby/issues/462" target="_blank" rel="noreferrer">this GitHub issue</a> for the details.</td></tr><tr><td><code>OTEL_SERVICE_NAME</code></td><td>Your app&#39;s <code>id</code> from <code>App</code></td><td>Identifiers your app&#39;s name to the vendor</td></tr><tr><td><code>OTEL_TRACES_EXPORTER</code></td><td>otlp</td><td>Configures the class inside the OTel gem that will export the instrumentation to the vendor. If you omit this, Brut will log the instrumentation to the console</td></tr></tbody></table><p>When you created your Brut app, your <code>.env.development</code> and <code>.env.test</code> should have values for all these environment variables that will send instrumentation to the otel-desktop-viewer that was also configured.</p><p>If you run your app using <code>bin/dev</code> and use the app for a bit, then go to <code>http://localhost:8000</code>, you will see the otel-desktop-viewer UI and can browse the spans and traces sent by Brut.</p><h3 id="what-is-instrumented-by-default" tabindex="-1">What is Instrumented By Default <a class="header-anchor" href="#what-is-instrumented-by-default" aria-label="Permalink to &quot;What is Instrumented By Default&quot;">​</a></h3><p>Brut attempts to automatically instrument useful things so you don&#39;t have to do anything to start getting data. Brut will attempt to conform to standard semantics for HTTP requests and SQL statements.</p><p>Here is a non-exhaustive list of what Brut automatically instruments:</p><ul><li>How long each page or handler request takes, broken down by components.</li><li>CLI execution time</li><li>Time to rebuild the schema for tests</li><li>Time to run tests</li><li>Time to apply migrations</li><li>Time spent inside a route hook</li><li>The locale detected from the browser</li><li>The layout class used when rendering a page</li><li>If a requested path is owned by Brut or not</li><li>Ignored parameters on all form submissions</li><li>How long reloading takes in development</li><li>CSP reporting results</li><li>SQL Statements</li></ul><div class="warning custom-block github-alert"><p class="custom-block-title">WARNING</p><p><code>Sequel::Extensions::BrutInstrumentation</code> sets up telemetry for Sequel, and it does it in a relatively simplistic way. The result is that <em>all</em> SQL statements are part of the telemetry, including the actual values inserted or used in <code>WHERE</code> clauses. While you should not be putting sensitive data into your database, be warned that this is happening. There are plans to improve this to be more flexible and reduce the chance of sensitive data being sent in traces.</p></div><h3 id="adding-your-own-instrumentation" tabindex="-1">Adding Your Own Instrumentation <a class="header-anchor" href="#adding-your-own-instrumentation" aria-label="Permalink to &quot;Adding Your Own Instrumentation&quot;">​</a></h3><p>You can add instrumentation in two main ways, both of which can be used together.</p><h4 id="instrumenting-existing-methods" tabindex="-1">Instrumenting Existing Methods <a class="header-anchor" href="#instrumenting-existing-methods" aria-label="Permalink to &quot;Instrumenting Existing Methods&quot;">​</a></h4><p>Although Brut instruments the entrypoints to pages, handlers, and components, you will likely have your own set of back-end business logic that needs to be instrumented. If you aren&#39;t trying to diagnose a specific problem and just want to see your back-end class&#39; methods show up in your instrumentation vendor&#39;s dashboard, <a href="/api/Brut/Instrumentation/Methods.html" target="_self" rel="noopener" data-no-router><code>Brut::Instrumentation::Methods</code></a> will be the easiest way to do that.</p><p><a href="/api/Brut/Instrumentation/Methods.html" target="_self" rel="noopener" data-no-router><code>Brut::Instrumentation::Methods</code></a> can be included in any class, and provides three class methods, which are <em>mutually exclusive</em>:</p><ul><li><code>instrument_all</code> instruments all methods, public and private.</li><li><code>instrument_public</code> instruments only public methods.</li><li><code>instrument</code> instruments one or more named methods.</li></ul><p><code>initialize</code> is never instrumented.</p><p>Consider this 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;"> Widget</span></span>
+import{_ as i,c as e,o as a,ag as t}from"./chunks/framework.C4nOkCZI.js";const c=JSON.parse('{"title":"Instrumentation and Observability","description":"","frontmatter":{},"headers":[],"relativePath":"instrumentation.md","filePath":"instrumentation.md"}'),n={name:"instrumentation.md"};function l(h,s,o,r,p,d){return a(),e("div",null,[...s[0]||(s[0]=[t(`<h1 id="instrumentation-and-observability" tabindex="-1">Instrumentation and Observability <a class="header-anchor" href="#instrumentation-and-observability" aria-label="Permalink to &quot;Instrumentation and Observability&quot;">​</a></h1><p>Brut has built-in support for OpenTelemetry, which is an open standard used by many observability vendors to allow you to understand the behavior of your app in production. Brut also includes a configuration for the <a href="https://github.com/CtrlSpice/otel-desktop-viewer/" target="_blank" rel="noreferrer">otel-desktop-viewer</a>, which allows you to see instrumentation in development.</p><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to &quot;Overview&quot;">​</a></h2><h3 id="why-instrument" tabindex="-1">Why Instrument? <a class="header-anchor" href="#why-instrument" aria-label="Permalink to &quot;Why Instrument?&quot;">​</a></h3><p>In production, you&#39;ll need to know what your app is doing and how well it&#39;s working. Historically, logs can provide this information in a roundabout way. Over the last many years, Application Performance Monitoring (APM) vendors like New Relic and Data Dog allowed developers to see much richer detail about how an app is working.</p><p>You could see, for example, the 95th percentil of your dashboard controller&#39;s performance, or the top 10 slowest SQL statements your app is executing. OpenTelemetry attempts to unify the API used to communicate this information from your app to your chosen vendor, and most vendors support it.</p><p>Instrumentation, then, is a way to record what your app is doing, how long its taking, and perhaps even why it&#39;s doing what it&#39;s doing, down to a very specific level. If properly configured, you could examine the performance of the app for a particular user on a particular day.</p><h3 id="setting-up-instrumentation" tabindex="-1">Setting up Instrumentation <a class="header-anchor" href="#setting-up-instrumentation" aria-label="Permalink to &quot;Setting up Instrumentation&quot;">​</a></h3><p>Brut automatically sets up OpenTelemetry (OTel) tracing. The primary interface you will use is <a href="/api/Brut/Instrumentation/OpenTelemetry.html" target="_self" rel="noopener" data-no-router><code>Brut::Instrumentation::OpenTelemetry</code></a>, which is available via <code>Brut.container.instrumentation</code>. We&#39;ll discuss that in a moment.</p><p>To configure the specifics of where the traces will go, the OTel gem uses environment variables:</p><table tabindex="0"><thead><tr><th>Variable</th><th>Value</th><th>Purpose</th></tr></thead><tbody><tr><td><code>OTEL_EXPORTER_OTLP_ENDPOINT</code></td><td>Depends on environment</td><td>Where to send the tracers. This is provided by your vendor, but is <code>http://otel-desktop-viewer:4318</code> in development</td></tr><tr><td><code>OTEL_EXPORTER_OTLP_HEADERS</code></td><td>Depends on vendor</td><td>Your vendor may ask you to set this. It often contains identifying information or API keys</td></tr><tr><td><code>OTEL_EXPORTER_OTLP_PROTOCOL</code></td><td>http/protobuf</td><td>Your vendor may request a different protocol, but protobuf is common and supported by otel-desktop-viewer</td></tr><tr><td><code>OTEL_LOG_LEVEL</code></td><td>debug</td><td>Useful when setting everything up to understand why things aren&#39;t working if they aren&#39;t working</td></tr><tr><td><code>OTEL_RUBY_BSP_START_THREAD_ON_BOOT</code></td><td>false</td><td>Deals with esoteric issues with Puma. See <a href="https://github.com/open-telemetry/opentelemetry-ruby/issues/462" target="_blank" rel="noreferrer">this GitHub issue</a> for the details.</td></tr><tr><td><code>OTEL_SERVICE_NAME</code></td><td>Your app&#39;s <code>id</code> from <code>App</code></td><td>Identifiers your app&#39;s name to the vendor</td></tr><tr><td><code>OTEL_TRACES_EXPORTER</code></td><td>otlp</td><td>Configures the class inside the OTel gem that will export the instrumentation to the vendor. If you omit this, Brut will log the instrumentation to the console</td></tr></tbody></table><p>When you created your Brut app, your <code>.env.development</code> and <code>.env.test</code> should have values for all these environment variables that will send instrumentation to the otel-desktop-viewer that was also configured.</p><p>If you run your app using <code>bin/dev</code> and use the app for a bit, then go to <code>http://localhost:8000</code>, you will see the otel-desktop-viewer UI and can browse the spans and traces sent by Brut.</p><h3 id="what-is-instrumented-by-default" tabindex="-1">What is Instrumented By Default <a class="header-anchor" href="#what-is-instrumented-by-default" aria-label="Permalink to &quot;What is Instrumented By Default&quot;">​</a></h3><p>Brut attempts to automatically instrument useful things so you don&#39;t have to do anything to start getting data. Brut will attempt to conform to standard semantics for HTTP requests and SQL statements.</p><p>Here is a non-exhaustive list of what Brut automatically instruments:</p><ul><li>How long each page or handler request takes, broken down by components.</li><li>CLI execution time</li><li>Time to rebuild the schema for tests</li><li>Time to run tests</li><li>Time to apply migrations</li><li>Time spent inside a route hook</li><li>The locale detected from the browser</li><li>The layout class used when rendering a page</li><li>If a requested path is owned by Brut or not</li><li>Ignored parameters on all form submissions</li><li>How long reloading takes in development</li><li>CSP reporting results</li><li>SQL Statements</li></ul><div class="warning custom-block github-alert"><p class="custom-block-title">WARNING</p><p><code>Sequel::Extensions::BrutInstrumentation</code> sets up telemetry for Sequel, and it does it in a relatively simplistic way. The result is that <em>all</em> SQL statements are part of the telemetry, including the actual values inserted or used in <code>WHERE</code> clauses. While you should not be putting sensitive data into your database, be warned that this is happening. There are plans to improve this to be more flexible and reduce the chance of sensitive data being sent in traces.</p></div><h3 id="adding-your-own-instrumentation" tabindex="-1">Adding Your Own Instrumentation <a class="header-anchor" href="#adding-your-own-instrumentation" aria-label="Permalink to &quot;Adding Your Own Instrumentation&quot;">​</a></h3><p>You can add instrumentation in two main ways, both of which can be used together.</p><h4 id="instrumenting-existing-methods" tabindex="-1">Instrumenting Existing Methods <a class="header-anchor" href="#instrumenting-existing-methods" aria-label="Permalink to &quot;Instrumenting Existing Methods&quot;">​</a></h4><p>Although Brut instruments the entrypoints to pages, handlers, and components, you will likely have your own set of back-end business logic that needs to be instrumented. If you aren&#39;t trying to diagnose a specific problem and just want to see your back-end class&#39; methods show up in your instrumentation vendor&#39;s dashboard, <a href="/api/Brut/Instrumentation/Methods.html" target="_self" rel="noopener" data-no-router><code>Brut::Instrumentation::Methods</code></a> will be the easiest way to do that.</p><p><a href="/api/Brut/Instrumentation/Methods.html" target="_self" rel="noopener" data-no-router><code>Brut::Instrumentation::Methods</code></a> can be included in any class, and provides three class methods, which are <em>mutually exclusive</em>:</p><ul><li><code>instrument_all</code> instruments all methods, public and private.</li><li><code>instrument_public</code> instruments only public methods.</li><li><code>instrument</code> instruments one or more named methods.</li></ul><p><code>initialize</code> is never instrumented.</p><p>Consider this 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;"> Widget</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>
 <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>
@@ -87,4 +87,4 @@ import{_ as i,c as e,o as a,ag as t}from"./chunks/framework.1L-BeKqY.js";const c
 <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>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><p>The logging system is currently not very configurable, and works as follows:</p><ul><li>In development, log messages are written to the standard output and to <code>logs/development.log</code></li><li>In test, log messages are written to <code>logs/test.log</code></li><li>In production, log messages are written to the standard output</li></ul><p>The default log level is &quot;debug&quot; for the web app at &quot;fatal&quot; for CLI apps. You can set <code>LOG_LEVEL</code> in the environment to change this:</p><ul><li><code>&quot;debug&quot;</code> - Show all messages</li><li><code>&quot;info&quot;</code> - Show info and above (not debug messages)</li><li><code>&quot;warn&quot;</code> - Show warnings and above (not info, not debug)</li><li><code>&quot;error&quot;</code> - Show errors and fatals only</li><li><code>&quot;fatal&quot;</code> - Show fatals only</li></ul><p>Most CLIs also allow <code>--log-level</code> to accept one of these strings as wel ass <code>--verbose</code> to set the log level to debug.</p><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h2><p>Generally you don&#39;t want to test instrumentation unless it&#39;s highly complex and critical to the app&#39;s ability to be maintained. Ideally, your end-to-end tests will cover all the instrumentation code you write so you can be sure that none of that causes a problem.</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>Entire books and conferences exist on how to properly instrument your app. Our suggestion is to take what you have by default and add additional instrumentation only to solve specific problems or identify specific issues.</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 Aug 27, 2025</em></p><p>OpenTelemetry is notoriously opaque and, ironically, unobservable in its own behavior. Thus, the implementation is subject to change as I figure out what actually does what.</p><h3 id="web-requests" tabindex="-1">Web Requests <a class="header-anchor" href="#web-requests" aria-label="Permalink to &quot;Web Requests&quot;">​</a></h3><p><a href="/api/Brut/FrontEnd/Middlewares/OpenTelemetrySpan.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Middlewares::OpenTelemetrySpan</code></a> is configured in <a href="/api/Brut/Framework/MCP.html" target="_self" rel="noopener" data-no-router><code>Brut::Framework::MCP</code></a> as the first middleware. It sets up the outer span for all web requests. Inside each request block (the code internal to Brut that calls handlers or pages), this span&#39;s name is modified with the HTTP method and path via the <code>brut.otel.root_span</code> in the Rack environment.</p><h3 id="client-side" tabindex="-1">Client-Side <a class="header-anchor" href="#client-side" aria-label="Permalink to &quot;Client-Side&quot;">​</a></h3><p>The client-side portion of this is highly customized. The Otel open source code for the client side is massive and hugely complex, so Brut decided to try to produce something simple and straightforward as a start. This can and will evolve over time.</p><h3 id="cli-commands" tabindex="-1">CLI Commands <a class="header-anchor" href="#cli-commands" aria-label="Permalink to &quot;CLI Commands&quot;">​</a></h3><p>Brut CLI commands are instrumented as well, in <a href="/api/Brut/CLI/App.html" target="_self" rel="noopener" data-no-router><code>Brut::CLI::App</code></a> in <code>execute!</code>, however the trace only begins if the underlying command is going to be executed. This may change.</p><h3 id="sidekiq-jobs" tabindex="-1">Sidekiq Jobs <a class="header-anchor" href="#sidekiq-jobs" aria-label="Permalink to &quot;Sidekiq Jobs&quot;">​</a></h3><p>Although Brut currently does not provide a default Sidekiq configuration, if you set up Sidekiq and include the <code>opentelemetry-instrumentation-sidekiq</code> gem in your app&#39;s <code>Gemfile</code>, you should see instrumentation of your Sidekiq jobs. In practice, this default set up doesn&#39;t seem to work very well, so expect this to change for the better.</p>`,74)]))}const u=i(n,[["render",l]]);export{c as __pageData,u as default};
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><p>The logging system is currently not very configurable, and works as follows:</p><ul><li>In development, log messages are written to the standard output and to <code>logs/development.log</code></li><li>In test, log messages are written to <code>logs/test.log</code></li><li>In production, log messages are written to the standard output</li></ul><p>The default log level is &quot;debug&quot; for the web app at &quot;fatal&quot; for CLI apps. You can set <code>LOG_LEVEL</code> in the environment to change this:</p><ul><li><code>&quot;debug&quot;</code> - Show all messages</li><li><code>&quot;info&quot;</code> - Show info and above (not debug messages)</li><li><code>&quot;warn&quot;</code> - Show warnings and above (not info, not debug)</li><li><code>&quot;error&quot;</code> - Show errors and fatals only</li><li><code>&quot;fatal&quot;</code> - Show fatals only</li></ul><p>Most CLIs also allow <code>--log-level</code> to accept one of these strings as wel ass <code>--verbose</code> to set the log level to debug.</p><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h2><p>Generally you don&#39;t want to test instrumentation unless it&#39;s highly complex and critical to the app&#39;s ability to be maintained. Ideally, your end-to-end tests will cover all the instrumentation code you write so you can be sure that none of that causes a problem.</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>Entire books and conferences exist on how to properly instrument your app. Our suggestion is to take what you have by default and add additional instrumentation only to solve specific problems or identify specific issues.</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 Aug 27, 2025</em></p><p>OpenTelemetry is notoriously opaque and, ironically, unobservable in its own behavior. Thus, the implementation is subject to change as I figure out what actually does what.</p><h3 id="web-requests" tabindex="-1">Web Requests <a class="header-anchor" href="#web-requests" aria-label="Permalink to &quot;Web Requests&quot;">​</a></h3><p><a href="/api/Brut/FrontEnd/Middlewares/OpenTelemetrySpan.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Middlewares::OpenTelemetrySpan</code></a> is configured in <a href="/api/Brut/Framework/MCP.html" target="_self" rel="noopener" data-no-router><code>Brut::Framework::MCP</code></a> as the first middleware. It sets up the outer span for all web requests. Inside each request block (the code internal to Brut that calls handlers or pages), this span&#39;s name is modified with the HTTP method and path via the <code>brut.otel.root_span</code> in the Rack environment.</p><h3 id="client-side" tabindex="-1">Client-Side <a class="header-anchor" href="#client-side" aria-label="Permalink to &quot;Client-Side&quot;">​</a></h3><p>The client-side portion of this is highly customized. The Otel open source code for the client side is massive and hugely complex, so Brut decided to try to produce something simple and straightforward as a start. This can and will evolve over time.</p><h3 id="cli-commands" tabindex="-1">CLI Commands <a class="header-anchor" href="#cli-commands" aria-label="Permalink to &quot;CLI Commands&quot;">​</a></h3><p>Brut CLI commands are instrumented as well, in <a href="/api/Brut/CLI/App.html" target="_self" rel="noopener" data-no-router><code>Brut::CLI::App</code></a> in <code>execute!</code>, however the trace only begins if the underlying command is going to be executed. This may change.</p><h3 id="sidekiq-jobs" tabindex="-1">Sidekiq Jobs <a class="header-anchor" href="#sidekiq-jobs" aria-label="Permalink to &quot;Sidekiq Jobs&quot;">​</a></h3><p>Although Brut currently does not provide a default Sidekiq configuration, if you set up Sidekiq and include the <code>opentelemetry-instrumentation-sidekiq</code> gem in your app&#39;s <code>Gemfile</code>, you should see instrumentation of your Sidekiq jobs. In practice, this default set up doesn&#39;t seem to work very well, so expect this to change for the better.</p>`,74)])])}const u=i(n,[["render",l]]);export{c as __pageData,u as default};

data/docs/assets/instrumentation.md.BcxjC4jd.lean.js

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

data/docs/assets/{javascript.md.DzrMxUmI.js → javascript.md.D6fxhaQb.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as a,o as e,ag as t}from"./chunks/framework.1L-BeKqY.js";const c=JSON.parse('{"title":"JavaScript","description":"","frontmatter":{},"headers":[],"relativePath":"javascript.md","filePath":"javascript.md"}'),n={name:"javascript.md"};function l(p,s,h,o,r,d){return e(),a("div",null,s[0]||(s[0]=[t(`<h1 id="javascript" tabindex="-1">JavaScript <a class="header-anchor" href="#javascript" aria-label="Permalink to &quot;JavaScript&quot;">​</a></h1><p>Brut provides basic bundling using <a href="https://esbuild.github.io/" target="_blank" rel="noreferrer">esbuild</a>. You can use any front-end framework with Brut, but you don&#39;t have to use one.</p><p>Brut provides <a href="/brut-js.html">BrutJS</a>, which is a lightweight library of HTML custom elements and utility code. These elements can provide a fair bit of front-end functionality using progressive enhancement without the need for a framework.</p><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to &quot;Overview&quot;">​</a></h2><p>All your app&#39;s JavaScript lives in <code>app/src/front_end/js</code>, or in modules you bring in via <code>package.json</code>. Brut will <em>bundle</em> all of that up into a single <code>.js</code> file that is served up with your app. Brut does this by using esbuild, a stable and standardized tool for bundling JavaScript.</p><p>The way esbuild works is to be given an <em>entry point</em> that requires, or transitively requires, all of your JavaScript by using ES6 modules. <code>app/src/front_end/js/index.js</code> is the entry point for your app.</p><p>For example, if you have a <code>Widget</code> class that uses a <code>Status</code> class, and you also use the third party library &quot;foobar&quot;, here is how all the files would look.</p><p>First, <code>package.json</code> (in your app&#39;s root) would include <code>&quot;foobar&quot;</code> (and it must set <code>&quot;type&quot;</code> to <code>&quot;module&quot;</code>):</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</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;">{</span></span>
+import{_ as i,c as a,o as e,ag as t}from"./chunks/framework.C4nOkCZI.js";const c=JSON.parse('{"title":"JavaScript","description":"","frontmatter":{},"headers":[],"relativePath":"javascript.md","filePath":"javascript.md"}'),n={name:"javascript.md"};function l(p,s,h,o,r,d){return e(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="javascript" tabindex="-1">JavaScript <a class="header-anchor" href="#javascript" aria-label="Permalink to &quot;JavaScript&quot;">​</a></h1><p>Brut provides basic bundling using <a href="https://esbuild.github.io/" target="_blank" rel="noreferrer">esbuild</a>. You can use any front-end framework with Brut, but you don&#39;t have to use one.</p><p>Brut provides <a href="/brut-js.html">BrutJS</a>, which is a lightweight library of HTML custom elements and utility code. These elements can provide a fair bit of front-end functionality using progressive enhancement without the need for a framework.</p><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to &quot;Overview&quot;">​</a></h2><p>All your app&#39;s JavaScript lives in <code>app/src/front_end/js</code>, or in modules you bring in via <code>package.json</code>. Brut will <em>bundle</em> all of that up into a single <code>.js</code> file that is served up with your app. Brut does this by using esbuild, a stable and standardized tool for bundling JavaScript.</p><p>The way esbuild works is to be given an <em>entry point</em> that requires, or transitively requires, all of your JavaScript by using ES6 modules. <code>app/src/front_end/js/index.js</code> is the entry point for your app.</p><p>For example, if you have a <code>Widget</code> class that uses a <code>Status</code> class, and you also use the third party library &quot;foobar&quot;, here is how all the files would look.</p><p>First, <code>package.json</code> (in your app&#39;s root) would include <code>&quot;foobar&quot;</code> (and it must set <code>&quot;type&quot;</code> to <code>&quot;module&quot;</code>):</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</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;">{</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;name&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;your-app&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line highlighted"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;type&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;module&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;license&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;UNLICENSED&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
@@ -28,4 +28,4 @@ import{_ as i,c as a,o as e,ag as t}from"./chunks/framework.1L-BeKqY.js";const c
 <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 highlighted"><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:#6A737D;--shiki-dark:#6A737D;">      # ...</span></span></code></pre></div><p>The <code>asset_path</code> helper takes a logical path—<code>/js/app.js</code>—and returns the actual path the browser can use. More details on this can be found in <a href="/assets.html">assets</a>.</p><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h2><p>Client-side behavior is best tested with end-to-end tests, however you can simplify your end-to-end tests by creating unit tests of your custom elements. <a href="/brut-js/api/module-testing.html">BrutJS provides limited support for this</a></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>Brut encourages you to use HTML custom elements as progressive enhancements over server-generated views. This sort of client-side code will age well. The toolchain and dependencies are minimal, so you will not have to worry too much about code written this way.</p><p>It <em>will</em> be lower level and more verbose than existing frameworks. We would argue that it is not significantly more difficult and the sustainability is worth it.</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 7, 2025</em></p><p>Currently, Brut only supports a single entry point and bundle. This could be easily made more flexible if there is a desire to finely tweak the JavaScript loaded on specific pages.</p><p>Brut also does not expose any esbuild configuration. This could be provided in the future, but for now, it is hard-coded.</p><p>Brut may provide more direct support for import maps, but as of now, import maps are not widely used outside of Rails, and tend to cause a lot of problems, especially if you aren&#39;t able to field an HTTP/2 web server (or even know what that is).</p>`,32)]))}const u=i(n,[["render",l]]);export{c as __pageData,u as default};
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">      # ...</span></span></code></pre></div><p>The <code>asset_path</code> helper takes a logical path—<code>/js/app.js</code>—and returns the actual path the browser can use. More details on this can be found in <a href="/assets.html">assets</a>.</p><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h2><p>Client-side behavior is best tested with end-to-end tests, however you can simplify your end-to-end tests by creating unit tests of your custom elements. <a href="/brut-js/api/module-testing.html">BrutJS provides limited support for this</a></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>Brut encourages you to use HTML custom elements as progressive enhancements over server-generated views. This sort of client-side code will age well. The toolchain and dependencies are minimal, so you will not have to worry too much about code written this way.</p><p>It <em>will</em> be lower level and more verbose than existing frameworks. We would argue that it is not significantly more difficult and the sustainability is worth it.</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 7, 2025</em></p><p>Currently, Brut only supports a single entry point and bundle. This could be easily made more flexible if there is a desire to finely tweak the JavaScript loaded on specific pages.</p><p>Brut also does not expose any esbuild configuration. This could be provided in the future, but for now, it is hard-coded.</p><p>Brut may provide more direct support for import maps, but as of now, import maps are not widely used outside of Rails, and tend to cause a lot of problems, especially if you aren&#39;t able to field an HTTP/2 web server (or even know what that is).</p>`,32)])])}const u=i(n,[["render",l]]);export{c as __pageData,u as default};

data/docs/assets/javascript.md.D6fxhaQb.lean.js

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

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

@@ -0,0 +1 @@
+import{_ as a,c as r,o as s,j as e,a as t}from"./chunks/framework.C4nOkCZI.js";const m=JSON.parse('{"title":"Background Jobs","description":"","frontmatter":{},"headers":[],"relativePath":"jobs.md","filePath":"jobs.md"}'),n={name:"jobs.md"};function i(l,o,c,d,u,p){return s(),r("div",null,[...o[0]||(o[0]=[e("h1",{id:"background-jobs",tabindex:"-1"},[t("Background Jobs "),e("a",{class:"header-anchor",href:"#background-jobs","aria-label":'Permalink to "Background Jobs"'},"​")],-1),e("p",null,"Brut provides little direct support for background jobs. Currently, Brut recommends Sidekiq, since it is battle-tested, well-supported, and open source.",-1),e("p",null,"When you set up your Brut app, it should ask if you want Sidekiq support and add the necessary configuraiton.",-1),e("p",null,[t("It will expect jobs in "),e("code",null,"app/src/back_end/jobs"),t(".")],-1),e("div",{class:"warning custom-block github-alert"},[e("p",{class:"custom-block-title"},"WARNING"),e("p",null,"The way Sidekiq is configured with Brut is effective and reliable, but it is complex. It currently involves several moving parts to make it work properly. This will be an area for improvement.")],-1)])])}const k=a(n,[["render",i]]);export{m as __pageData,k as default};

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

@@ -0,0 +1 @@
+import{_ as a,c as r,o as s,j as e,a as t}from"./chunks/framework.C4nOkCZI.js";const m=JSON.parse('{"title":"Background Jobs","description":"","frontmatter":{},"headers":[],"relativePath":"jobs.md","filePath":"jobs.md"}'),n={name:"jobs.md"};function i(l,o,c,d,u,p){return s(),r("div",null,[...o[0]||(o[0]=[e("h1",{id:"background-jobs",tabindex:"-1"},[t("Background Jobs "),e("a",{class:"header-anchor",href:"#background-jobs","aria-label":'Permalink to "Background Jobs"'},"​")],-1),e("p",null,"Brut provides little direct support for background jobs. Currently, Brut recommends Sidekiq, since it is battle-tested, well-supported, and open source.",-1),e("p",null,"When you set up your Brut app, it should ask if you want Sidekiq support and add the necessary configuraiton.",-1),e("p",null,[t("It will expect jobs in "),e("code",null,"app/src/back_end/jobs"),t(".")],-1),e("div",{class:"warning custom-block github-alert"},[e("p",{class:"custom-block-title"},"WARNING"),e("p",null,"The way Sidekiq is configured with Brut is effective and reliable, but it is complex. It currently involves several moving parts to make it work properly. This will be an area for improvement.")],-1)])])}const k=a(n,[["render",i]]);export{m as __pageData,k as default};