brut 0.14.0 → 0.15.0

data/docs/assets/{recipes_form-errors.md.Bv5RCKqH.js → recipes_form-errors.md.B5ptSzMO.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":"Styling Form Errors","description":"","frontmatter":{},"headers":[],"relativePath":"recipes/form-errors.md","filePath":"recipes/form-errors.md"}'),t={name:"recipes/form-errors.md"};function h(l,s,p,k,r,d){return n(),a("div",null,s[0]||(s[0]=[e(`<h1 id="styling-form-errors" tabindex="-1">Styling Form Errors <a class="header-anchor" href="#styling-form-errors" aria-label="Permalink to &quot;Styling Form Errors&quot;">​</a></h1><p>Brut makes it as easy as possible to unify client-side and server-side constraint violation handling, including how you style those messages.</p><h2 id="requirements" tabindex="-1">Requirements <a class="header-anchor" href="#requirements" aria-label="Permalink to &quot;Requirements&quot;">​</a></h2><p>What you want:</p><ul><li>When a form is rendered for the first time, there should be errors shown.</li><li>When a visitor interacts with a form before submissions, no errors are shown.</li><li>When the form is submitted, client-side constraint violations should be shown.</li><li>When JavaScript is circumvented and the form is submitted with client-side constraint violations, the form should be re-generated, showing those violations the same is if JavaScripts was <em>not</em> circumvented</li><li>When there are no client-side constraint violations, but there <em>are</em> server-side violations, the form should be re-generated, showing those violations the same is if JavaScripts was <em>not</em> circumvented</li></ul><p>This can be achieved through CSS.</p><h2 id="recipe" tabindex="-1">Recipe <a class="header-anchor" href="#recipe" aria-label="Permalink to &quot;Recipe&quot;">​</a></h2><h3 id="create-pages-and-html" tabindex="-1">Create Pages and HTML <a class="header-anchor" href="#create-pages-and-html" aria-label="Permalink to &quot;Create Pages and HTML&quot;">​</a></h3><p>First, create a form and handler:</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>bin/scaffold form /new_widget</span></span></code></pre></div><p>Edit <code>app/src/front_end/forms/new_widget_form.rb</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;"> NewWidgetForm</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> AppForm</span></span>
+import{_ as i,c as a,o as n,ag as e}from"./chunks/framework.C4nOkCZI.js";const E=JSON.parse('{"title":"Styling Form Errors","description":"","frontmatter":{},"headers":[],"relativePath":"recipes/form-errors.md","filePath":"recipes/form-errors.md"}'),t={name:"recipes/form-errors.md"};function h(l,s,p,k,r,d){return n(),a("div",null,[...s[0]||(s[0]=[e(`<h1 id="styling-form-errors" tabindex="-1">Styling Form Errors <a class="header-anchor" href="#styling-form-errors" aria-label="Permalink to &quot;Styling Form Errors&quot;">​</a></h1><p>Brut makes it as easy as possible to unify client-side and server-side constraint violation handling, including how you style those messages.</p><h2 id="requirements" tabindex="-1">Requirements <a class="header-anchor" href="#requirements" aria-label="Permalink to &quot;Requirements&quot;">​</a></h2><p>What you want:</p><ul><li>When a form is rendered for the first time, there should be errors shown.</li><li>When a visitor interacts with a form before submissions, no errors are shown.</li><li>When the form is submitted, client-side constraint violations should be shown.</li><li>When JavaScript is circumvented and the form is submitted with client-side constraint violations, the form should be re-generated, showing those violations the same is if JavaScripts was <em>not</em> circumvented</li><li>When there are no client-side constraint violations, but there <em>are</em> server-side violations, the form should be re-generated, showing those violations the same is if JavaScripts was <em>not</em> circumvented</li></ul><p>This can be achieved through CSS.</p><h2 id="recipe" tabindex="-1">Recipe <a class="header-anchor" href="#recipe" aria-label="Permalink to &quot;Recipe&quot;">​</a></h2><h3 id="create-pages-and-html" tabindex="-1">Create Pages and HTML <a class="header-anchor" href="#create-pages-and-html" aria-label="Permalink to &quot;Create Pages and HTML&quot;">​</a></h3><p>First, create a form and handler:</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>bin/scaffold form /new_widget</span></span></code></pre></div><p>Edit <code>app/src/front_end/forms/new_widget_form.rb</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;"> NewWidgetForm</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> AppForm</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  input </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">minlength:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 3</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  input </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:description</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><p>Now, implement the handler in <code>app/src/front_end/handlers/new_widget_handler.rb</code> to check for client-side violations <em>and</em> require that the description have at least 5 words in it.</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">class</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> NewWidgetHandler</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> AppHandler</span></span>
@@ -63,4 +63,4 @@ import{_ as i,c as a,o as n,ag as e}from"./chunks/framework.1L-BeKqY.js";const E
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  background-color</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">pink</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  border</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">solid</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> thin</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> red</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  border-radius</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">rem</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div>`,29)]))}const g=i(t,[["render",h]]);export{E as __pageData,g as default};
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div>`,29)])])}const g=i(t,[["render",h]]);export{E as __pageData,g as default};

data/docs/assets/recipes_form-errors.md.B5ptSzMO.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":"Styling Form Errors","description":"","frontmatter":{},"headers":[],"relativePath":"recipes/form-errors.md","filePath":"recipes/form-errors.md"}'),t={name:"recipes/form-errors.md"};function h(l,s,p,k,r,d){return n(),a("div",null,[...s[0]||(s[0]=[e("",29)])])}const g=i(t,[["render",h]]);export{E as __pageData,g as default};

data/docs/assets/{recipes_indexed-forms.md.CstYyOSo.js → recipes_indexed-forms.md.BYYQGW2C.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as a,o as n,ag as e}from"./chunks/framework.1L-BeKqY.js";const g=JSON.parse('{"title":"Indexed Forms","description":"","frontmatter":{},"headers":[],"relativePath":"recipes/indexed-forms.md","filePath":"recipes/indexed-forms.md"}'),h={name:"recipes/indexed-forms.md"};function t(l,s,p,k,r,d){return n(),a("div",null,s[0]||(s[0]=[e(`<h1 id="indexed-forms" tabindex="-1">Indexed Forms <a class="header-anchor" href="#indexed-forms" aria-label="Permalink to &quot;Indexed Forms&quot;">​</a></h1><p>HTTP allows a form to have any number of elements with the same name. HTTP will make all values available to you. Rack supports this, too, but not in a standard way.</p><p>This recipe will show a form that has more than one set of text fields for the same conceptual field.</p><h2 id="feature" tabindex="-1">Feature <a class="header-anchor" href="#feature" aria-label="Permalink to &quot;Feature&quot;">​</a></h2><p>Allow editing a single form that has 10 sets of name/quantity fields, in order to bulk create up to 10 widgets at a time.</p><h2 id="recipe" tabindex="-1">Recipe <a class="header-anchor" href="#recipe" aria-label="Permalink to &quot;Recipe&quot;">​</a></h2><p>We&#39;ll create a form, a handler, and a page to do this.</p><h3 id="creating-a-form-with-indexes" tabindex="-1">Creating a Form with Indexes <a class="header-anchor" href="#creating-a-form-with-indexes" aria-label="Permalink to &quot;Creating a Form with Indexes&quot;">​</a></h3><p>First, we&#39;ll scaffold the form and handler:</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>bin/scaffold form /bulk_create_widgets</span></span></code></pre></div><p>Next, we&#39;ll create the form in <code>app/src/front_end/forms/bulk_create_widgets_form.rb</code> This will look like a normal form except each field will have <code>array: true</code>, to indicate there will be an arbitrary number of these fields. Since they are not all going to be required, we&#39;ll set <code>required: false</code>.</p><p>When you specify <code>array:true</code>, the method created by <code>input</code> accepts an index as an argument. For example, <code>form.name(3)</code> would retrieve the fourth name submitted.</p><p>We&#39;ll also implement the method <code>each_widget</code> that will yield each name/quantity pair. The reason Brut doesn&#39;t provide this is that your form could have non-array values as well, so there is no obvious implementation.</p><p>Brut <em>does</em> provide an <code>_each</code> method for every array field. We can use that to iterate over however many values were submitted.</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;"> BulkCreateWidgetsForm</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> AppForm</span></span>
+import{_ as i,c as a,o as n,ag as e}from"./chunks/framework.C4nOkCZI.js";const g=JSON.parse('{"title":"Indexed Forms","description":"","frontmatter":{},"headers":[],"relativePath":"recipes/indexed-forms.md","filePath":"recipes/indexed-forms.md"}'),h={name:"recipes/indexed-forms.md"};function t(l,s,p,k,r,d){return n(),a("div",null,[...s[0]||(s[0]=[e(`<h1 id="indexed-forms" tabindex="-1">Indexed Forms <a class="header-anchor" href="#indexed-forms" aria-label="Permalink to &quot;Indexed Forms&quot;">​</a></h1><p>HTTP allows a form to have any number of elements with the same name. HTTP will make all values available to you. Rack supports this, too, but not in a standard way.</p><p>This recipe will show a form that has more than one set of text fields for the same conceptual field.</p><h2 id="feature" tabindex="-1">Feature <a class="header-anchor" href="#feature" aria-label="Permalink to &quot;Feature&quot;">​</a></h2><p>Allow editing a single form that has 10 sets of name/quantity fields, in order to bulk create up to 10 widgets at a time.</p><h2 id="recipe" tabindex="-1">Recipe <a class="header-anchor" href="#recipe" aria-label="Permalink to &quot;Recipe&quot;">​</a></h2><p>We&#39;ll create a form, a handler, and a page to do this.</p><h3 id="creating-a-form-with-indexes" tabindex="-1">Creating a Form with Indexes <a class="header-anchor" href="#creating-a-form-with-indexes" aria-label="Permalink to &quot;Creating a Form with Indexes&quot;">​</a></h3><p>First, we&#39;ll scaffold the form and handler:</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>bin/scaffold form /bulk_create_widgets</span></span></code></pre></div><p>Next, we&#39;ll create the form in <code>app/src/front_end/forms/bulk_create_widgets_form.rb</code> This will look like a normal form except each field will have <code>array: true</code>, to indicate there will be an arbitrary number of these fields. Since they are not all going to be required, we&#39;ll set <code>required: false</code>.</p><p>When you specify <code>array:true</code>, the method created by <code>input</code> accepts an index as an argument. For example, <code>form.name(3)</code> would retrieve the fourth name submitted.</p><p>We&#39;ll also implement the method <code>each_widget</code> that will yield each name/quantity pair. The reason Brut doesn&#39;t provide this is that your form could have non-array values as well, so there is no obvious implementation.</p><p>Brut <em>does</em> provide an <code>_each</code> method for every array field. We can use that to iterate over however many values were submitted.</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;"> BulkCreateWidgetsForm</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> AppForm</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  input </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,                    </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">array:</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;">required:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> false</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  input </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:quantity</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">type:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> :number</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">array:</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;">required:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">                                               min:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 1</span></span>
@@ -71,4 +71,4 @@ import{_ as i,c as a,o as n,ag as e}from"./chunks/framework.1L-BeKqY.js";const g
 <span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">      end</span></span>
 <span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">    end</span></span>
 <span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  end</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">end</span></span></code></pre></div><p>Even if the form doesn&#39;t have 10 entries, the code above will create 10 pairs of fields. If there are server-side constraint violations, they will be shown for the appropriate index. Lastly, Brut&#39;s components (like <code>TextField</code>) will use the Rack non-standard HTML for arrays of values. Instead of <code>name=&quot;quantity&quot;</code>, Brut will render <code>name=&quot;quantity[]&quot;</code>.</p>`,23)]))}const o=i(h,[["render",t]]);export{g as __pageData,o as default};
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">end</span></span></code></pre></div><p>Even if the form doesn&#39;t have 10 entries, the code above will create 10 pairs of fields. If there are server-side constraint violations, they will be shown for the appropriate index. Lastly, Brut&#39;s components (like <code>TextField</code>) will use the Rack non-standard HTML for arrays of values. Instead of <code>name=&quot;quantity&quot;</code>, Brut will render <code>name=&quot;quantity[]&quot;</code>.</p>`,23)])])}const o=i(h,[["render",t]]);export{g as __pageData,o as default};

data/docs/assets/recipes_indexed-forms.md.BYYQGW2C.lean.js

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

data/docs/assets/{recipes_migrations.md.CTcnWDJF.js → recipes_migrations.md.Cid7-3cu.js}

@@ -1,4 +1,4 @@
-import{_ as a,c as i,o as n,ag as e}from"./chunks/framework.1L-BeKqY.js";const c=JSON.parse('{"title":"Migration Example","description":"","frontmatter":{},"headers":[],"relativePath":"recipes/migrations.md","filePath":"recipes/migrations.md"}'),t={name:"recipes/migrations.md"};function l(p,s,h,k,d,o){return n(),i("div",null,s[0]||(s[0]=[e(`<h1 id="migration-example" tabindex="-1">Migration Example <a class="header-anchor" href="#migration-example" aria-label="Permalink to &quot;Migration Example&quot;">​</a></h1><p>If you&#39;ve not used <a href="https://sequel.jeremyevans.net/" target="_blank" rel="noreferrer">Sequel</a> before, this recipe will show you the basics of creating <a href="https://sequel.jeremyevans.net/rdoc/files/doc/migration_rdoc.html" target="_blank" rel="noreferrer">migrations</a>, which are how the database schema is managed in Brut.</p><h2 id="feature" tabindex="-1">Feature <a class="header-anchor" href="#feature" aria-label="Permalink to &quot;Feature&quot;">​</a></h2><ul><li>An accounts table will store an email and a deactivated date</li><li>A blog posts table will store a title and content, and be attributed to an account.</li></ul><h2 id="recipe" tabindex="-1">Recipe <a class="header-anchor" href="#recipe" aria-label="Permalink to &quot;Recipe&quot;">​</a></h2><p>We&#39;ll create the migration, create data models, create and lint factories, then create seed data.</p><h3 id="create-the-migration" tabindex="-1">Create the Migration <a class="header-anchor" href="#create-the-migration" aria-label="Permalink to &quot;Create the Migration&quot;">​</a></h3><p>Create the migration file with <code>bin/db new_migration</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>&gt; bin/db new_migration Accounts and Blog Posts</span></span>
+import{_ as a,c as i,o as n,ag as e}from"./chunks/framework.C4nOkCZI.js";const c=JSON.parse('{"title":"Migration Example","description":"","frontmatter":{},"headers":[],"relativePath":"recipes/migrations.md","filePath":"recipes/migrations.md"}'),t={name:"recipes/migrations.md"};function l(p,s,h,k,d,o){return n(),i("div",null,[...s[0]||(s[0]=[e(`<h1 id="migration-example" tabindex="-1">Migration Example <a class="header-anchor" href="#migration-example" aria-label="Permalink to &quot;Migration Example&quot;">​</a></h1><p>If you&#39;ve not used <a href="https://sequel.jeremyevans.net/" target="_blank" rel="noreferrer">Sequel</a> before, this recipe will show you the basics of creating <a href="https://sequel.jeremyevans.net/rdoc/files/doc/migration_rdoc.html" target="_blank" rel="noreferrer">migrations</a>, which are how the database schema is managed in Brut.</p><h2 id="feature" tabindex="-1">Feature <a class="header-anchor" href="#feature" aria-label="Permalink to &quot;Feature&quot;">​</a></h2><ul><li>An accounts table will store an email and a deactivated date</li><li>A blog posts table will store a title and content, and be attributed to an account.</li></ul><h2 id="recipe" tabindex="-1">Recipe <a class="header-anchor" href="#recipe" aria-label="Permalink to &quot;Recipe&quot;">​</a></h2><p>We&#39;ll create the migration, create data models, create and lint factories, then create seed data.</p><h3 id="create-the-migration" tabindex="-1">Create the Migration <a class="header-anchor" href="#create-the-migration" aria-label="Permalink to &quot;Create the Migration&quot;">​</a></h3><p>Create the migration file with <code>bin/db new_migration</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>&gt; bin/db new_migration Accounts and Blog Posts</span></span>
 <span class="line"><span>[ bin/db ] Migration created:</span></span>
 <span class="line"><span>   app/src/back_end/data_models/migrations/20250711215310_Accounts-and-Blog-Posts.rb</span></span></code></pre></div><div class="note custom-block github-alert"><p class="custom-block-title">NOTE</p><p>Your filename will be different, since it embeds a timestamp for when <code>bin/db new_migration</code> was run.</p></div><p>Now, use Sequel&#39;s migrations API, keeping in mind <a href="/database-schema.html">Brut&#39;s augmentations</a>, to create our tables.</p><p>Our tables will use <a href="/database-schema.html#external-ids">an external ids</a>. Note that Brut will ensure both tables have primary keys and have <code>created_at</code> fields.</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/back_end/data_models/migrations/20250711215310_Accounts-and-Blog-Posts.rb</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">Sequel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">migration</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> do</span></span>
@@ -94,4 +94,4 @@ import{_ as a,c as i,o as n,ag as e}from"./chunks/framework.1L-BeKqY.js";const c
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">      create</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">:blog_post</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">account:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> chris)</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    end</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><p>We can apply this with <code>bin/db seed</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>bin/db seed</span></span></code></pre></div><div class="important custom-block github-alert"><p class="custom-block-title">IMPORTANT</p><p><code>bin/db rebuild</code> will <em>not</em> apply seed data, however <code>bin/setup</code> should. For now, if you want to totally reset your database, you will need to do <code>bin/db rebuild &amp;&amp; bin/db seed &amp;&amp; bin/db rebuild -e test</code></p></div>`,37)]))}const g=a(t,[["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><p>We can apply this with <code>bin/db seed</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>bin/db seed</span></span></code></pre></div><div class="important custom-block github-alert"><p class="custom-block-title">IMPORTANT</p><p><code>bin/db rebuild</code> will <em>not</em> apply seed data, however <code>bin/setup</code> should. For now, if you want to totally reset your database, you will need to do <code>bin/db rebuild &amp;&amp; bin/db seed &amp;&amp; bin/db rebuild -e test</code></p></div>`,37)])])}const g=a(t,[["render",l]]);export{c as __pageData,g as default};

data/docs/assets/recipes_migrations.md.Cid7-3cu.lean.js

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

data/docs/assets/{recipes_text-field-component.md.H4wLAK0Z.js → recipes_text-field-component.md.VhOsCtKI.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as a,o as n,ag as l}from"./chunks/framework.1L-BeKqY.js";const g=JSON.parse('{"title":"Creating your Own Text Field Component","description":"","frontmatter":{},"headers":[],"relativePath":"recipes/text-field-component.md","filePath":"recipes/text-field-component.md"}'),h={name:"recipes/text-field-component.md"};function t(p,s,k,e,E,r){return n(),a("div",null,s[0]||(s[0]=[l(`<h1 id="creating-your-own-text-field-component" tabindex="-1">Creating your Own Text Field Component <a class="header-anchor" href="#creating-your-own-text-field-component" aria-label="Permalink to &quot;Creating your Own Text Field Component&quot;">​</a></h1><p>Brut&#39;s <a href="/api/Brut/FrontEnd/Components/Input/InputTag.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Components::Input::InputTag</code></a> creates only the <code>&lt;input&gt;</code> HTML element. You will likely want something more sophsticated. You can achieve this by creating your own component.</p><h2 id="feature" tabindex="-1">Feature <a class="header-anchor" href="#feature" aria-label="Permalink to &quot;Feature&quot;">​</a></h2><p>We&#39;ll make a text field that has a label, error messages, and styling. It will support three sizes: small, normal, and large.</p><p>It will require a form and an input name, and optional index as well.</p><h2 id="recipe" tabindex="-1">Recipe <a class="header-anchor" href="#recipe" aria-label="Permalink to &quot;Recipe&quot;">​</a></h2><h3 id="create-the-initializer" tabindex="-1">Create the Initializer <a class="header-anchor" href="#create-the-initializer" aria-label="Permalink to &quot;Create the Initializer&quot;">​</a></h3><p>First, we&#39;ll create the component:</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>bin/scaffold component text_field</span></span></code></pre></div><p>Now, edit the initializer to accept the parameters we need:</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># app/src/front_end/components/text_field_component.rb</span></span>
+import{_ as i,c as a,o as n,ag as l}from"./chunks/framework.C4nOkCZI.js";const g=JSON.parse('{"title":"Creating your Own Text Field Component","description":"","frontmatter":{},"headers":[],"relativePath":"recipes/text-field-component.md","filePath":"recipes/text-field-component.md"}'),h={name:"recipes/text-field-component.md"};function t(p,s,k,e,E,r){return n(),a("div",null,[...s[0]||(s[0]=[l(`<h1 id="creating-your-own-text-field-component" tabindex="-1">Creating your Own Text Field Component <a class="header-anchor" href="#creating-your-own-text-field-component" aria-label="Permalink to &quot;Creating your Own Text Field Component&quot;">​</a></h1><p>Brut&#39;s <a href="/api/Brut/FrontEnd/Components/Input/InputTag.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Components::Input::InputTag</code></a> creates only the <code>&lt;input&gt;</code> HTML element. You will likely want something more sophsticated. You can achieve this by creating your own component.</p><h2 id="feature" tabindex="-1">Feature <a class="header-anchor" href="#feature" aria-label="Permalink to &quot;Feature&quot;">​</a></h2><p>We&#39;ll make a text field that has a label, error messages, and styling. It will support three sizes: small, normal, and large.</p><p>It will require a form and an input name, and optional index as well.</p><h2 id="recipe" tabindex="-1">Recipe <a class="header-anchor" href="#recipe" aria-label="Permalink to &quot;Recipe&quot;">​</a></h2><h3 id="create-the-initializer" tabindex="-1">Create the Initializer <a class="header-anchor" href="#create-the-initializer" aria-label="Permalink to &quot;Create the Initializer&quot;">​</a></h3><p>First, we&#39;ll create the component:</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>bin/scaffold component text_field</span></span></code></pre></div><p>Now, edit the initializer to accept the parameters we need:</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># app/src/front_end/components/text_field_component.rb</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">class</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> TextFieldComponent</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> AppComponent</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> initialize</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">form:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">                 input_name:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
@@ -98,4 +98,4 @@ import{_ as i,c as a,o as n,ag as l}from"./chunks/framework.1L-BeKqY.js";const g
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      button { </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Save&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    end</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div>`,27)]))}const y=i(h,[["render",t]]);export{g as __pageData,y as default};
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div>`,27)])])}const y=i(h,[["render",t]]);export{g as __pageData,y as default};

data/docs/assets/recipes_text-field-component.md.VhOsCtKI.lean.js

@@ -0,0 +1 @@
+import{_ as i,c as a,o as n,ag as l}from"./chunks/framework.C4nOkCZI.js";const g=JSON.parse('{"title":"Creating your Own Text Field Component","description":"","frontmatter":{},"headers":[],"relativePath":"recipes/text-field-component.md","filePath":"recipes/text-field-component.md"}'),h={name:"recipes/text-field-component.md"};function t(p,s,k,e,E,r){return n(),a("div",null,[...s[0]||(s[0]=[l("",27)])])}const y=i(h,[["render",t]]);export{g as __pageData,y as default};

data/docs/assets/roadmap.md.CJsbUmK_.js

@@ -0,0 +1 @@
+import{_ as t,c as o,o as a,ag as i}from"./chunks/framework.C4nOkCZI.js";const h=JSON.parse('{"title":"Roadmap to 1.0","description":"","frontmatter":{},"headers":[],"relativePath":"roadmap.md","filePath":"roadmap.md"}'),l={name:"roadmap.md"};function r(s,e,n,d,c,m){return a(),o("div",null,[...e[0]||(e[0]=[i('<h1 id="roadmap-to-1-0" tabindex="-1">Roadmap to 1.0 <a class="header-anchor" href="#roadmap-to-1-0" aria-label="Permalink to &quot;Roadmap to 1.0&quot;">​</a></h1><p>A lot of Brut is solid, but there&#39;s several things missing from what I would call a 1.0 release. Here are some ideas of what I think is needed:</p><h2 id="better-dev-experience" tabindex="-1">Better Dev Experience <a class="header-anchor" href="#better-dev-experience" aria-label="Permalink to &quot;Better Dev Experience&quot;">​</a></h2><ul><li>The output of <code>bin/dev</code> isn&#39;t great.</li><li>otel-desktop-viewer is cool, but not the easiest to figure out issues as compred to good &#39;ole logging.</li><li>Error pages in the app are <em>really</em> bad.</li><li>CLI apps are OK, but could be fancier.</li></ul><h2 id="more-tests" tabindex="-1">More Tests <a class="header-anchor" href="#more-tests" aria-label="Permalink to &quot;More Tests&quot;">​</a></h2><ul><li>Unit tests for all/most classes are needed. There&#39;s only a few now.</li><li>Integration test of <code>mkbrut</code>, all automated.</li><li>Web component/custom element tests need to be re-thought.</li><li>Test output is a wall of text stack trace and this sucks.</li><li>Improvements in access to Playwright features.</li><li>Playright is the worst E2E testing tool except all the rest. Would love a better option here.</li></ul><h2 id="more-complete-web-features" tabindex="-1">More Complete Web Features <a class="header-anchor" href="#more-complete-web-features" aria-label="Permalink to &quot;More Complete Web Features&quot;">​</a></h2><ul><li>Content security policy doens&#39;t allow for hashes, which can be limiting in some situations. I want everyone to be running with a CSP, so it has to be configurable to some degree.</li><li>Websockets, server-push, etc. should be possible or at least have a recipe.</li><li>Learn more about importmaps.</li></ul><h2 id="client-side-improvements" tabindex="-1">Client-Side Improvements <a class="header-anchor" href="#client-side-improvements" aria-label="Permalink to &quot;Client-Side Improvements&quot;">​</a></h2><p>BrutJS is woefully incomplete. I&#39;d like developers to be able to accomplishe certain tasks without needing a framework:</p><ul><li>Hooks into asset building to e.g. enable TailwindCSS or other tools.</li><li>Better use of <code>fetch</code> in more situations</li><li>Server-generated HTML replacement</li><li>Better support for &quot;API&quot; style back-end when a framework <em>is</em> going to be used.</li></ul><h2 id="deployment" tabindex="-1">Deployment <a class="header-anchor" href="#deployment" aria-label="Permalink to &quot;Deployment&quot;">​</a></h2><p>Out of the box support for more deployment mechanism, at least:</p><ul><li>Normal Heroku/<code>Procfile</code>-based deploy</li><li>Digital Ocean-style hosting</li><li>VPS?</li></ul><h2 id="documentation" tabindex="-1">Documentation <a class="header-anchor" href="#documentation" aria-label="Permalink to &quot;Documentation&quot;">​</a></h2><ul><li>More recipes for how to do things</li><li>More complete API docs with examples</li><li>A unified look and feel across the board</li><li>Get rid of VitePress for something less client-heavy, but still great</li><li>Dash-accessible API docs</li></ul><h2 id="misc" tabindex="-1">Misc <a class="header-anchor" href="#misc" aria-label="Permalink to &quot;Misc&quot;">​</a></h2><ul><li>More direct Sidekiq support</li></ul>',18)])])}const p=t(l,[["render",r]]);export{h as __pageData,p as default};

data/docs/assets/roadmap.md.CJsbUmK_.lean.js

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

data/docs/assets/{routes.md.BD6y2i-f.js → routes.md.C1dgIBtD.js}

@@ -1,4 +1,4 @@
-import{_ as a,c as t,o as s,ag as i}from"./chunks/framework.1L-BeKqY.js";const u=JSON.parse('{"title":"Routes","description":"","frontmatter":{},"headers":[],"relativePath":"routes.md","filePath":"routes.md"}'),o={name:"routes.md"};function n(r,e,l,h,d,p){return s(),t("div",null,e[0]||(e[0]=[i(`<h1 id="routes" tabindex="-1">Routes <a class="header-anchor" href="#routes" aria-label="Permalink to &quot;Routes&quot;">​</a></h1><p>The primary function of a web framework like Brut is to map URLs requested by the browser or an HTTP client and invoke code based on them.</p><p>Brut has a fairly simple routing system that&#39;s not designed for flexibility.</p><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to &quot;Overview&quot;">​</a></h2><p>Your app has a subclass of <a href="/api/Brut/Framework/App.html" target="_self" rel="noopener" data-no-router><code>Brut::Framework::App</code></a>, called <code>App</code>. It includes a call to the <code>routes</code> class method. In there, you declare your routes by using one of four methods:</p><table tabindex="0"><thead><tr><th>Method</th><th>HTTP Method</th><th>Purpose</th></tr></thead><tbody><tr><td><code>page «route»</code></td><td>GET</td><td>Declare a page</td></tr><tr><td><code>form «route»</code></td><td>POST</td><td>Declare a form to be submitted to a handler</td></tr><tr><td><code>action «route»</code></td><td>POST</td><td>Declare an element-less form to be submitted to a handler (akin to Rails&#39; <code>button_to</code> helper)</td></tr><tr><td><code>path «route», method: «method»</code></td><td><code>«method»</code></td><td>Declare an arbitrary path to a handler</td></tr></tbody></table><p>The value for <code>«route»</code>, along with the method called, is used to determine what class(es) will be used to handle the route.</p><h3 id="«route»-syntax" tabindex="-1">«route» Syntax <a class="header-anchor" href="#«route»-syntax" aria-label="Permalink to &quot;«route» Syntax&quot;">​</a></h3><p>A route is a string that contains the <em>path part</em> of a <a href="https://developer.mozilla.org/en-US/docs/Web/API/URL" target="_blank" rel="noreferrer">URL</a>. <em>Segments</em> of the path (i.e. the stuff between each forward slash <code>/</code>) can be either <em>static</em> or a <em>placeholder</em>.</p><p>As such:</p><ul><li>Only the <a href="https://developer.mozilla.org/en-US/docs/Web/API/URL/pathname" target="_blank" rel="noreferrer">pathname</a> of a request may be specified.</li><li>All routes must start with a slash</li><li>A placeholder segment must be a valid Ruby identifier preceded by a colon, e.g. <code>:company_id</code> is allowed, but <code>:company-id</code> is not.</li><li>Routes may not start with a placeholder.</li></ul><p>Some examples:</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>&quot;/dash_board&quot;</span></span>
+import{_ as a,c as t,o as s,ag as i}from"./chunks/framework.C4nOkCZI.js";const u=JSON.parse('{"title":"Routes","description":"","frontmatter":{},"headers":[],"relativePath":"routes.md","filePath":"routes.md"}'),o={name:"routes.md"};function n(r,e,l,h,d,p){return s(),t("div",null,[...e[0]||(e[0]=[i(`<h1 id="routes" tabindex="-1">Routes <a class="header-anchor" href="#routes" aria-label="Permalink to &quot;Routes&quot;">​</a></h1><p>The primary function of a web framework like Brut is to map URLs requested by the browser or an HTTP client and invoke code based on them.</p><p>Brut has a fairly simple routing system that&#39;s not designed for flexibility.</p><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to &quot;Overview&quot;">​</a></h2><p>Your app has a subclass of <a href="/api/Brut/Framework/App.html" target="_self" rel="noopener" data-no-router><code>Brut::Framework::App</code></a>, called <code>App</code>. It includes a call to the <code>routes</code> class method. In there, you declare your routes by using one of four methods:</p><table tabindex="0"><thead><tr><th>Method</th><th>HTTP Method</th><th>Purpose</th></tr></thead><tbody><tr><td><code>page «route»</code></td><td>GET</td><td>Declare a page</td></tr><tr><td><code>form «route»</code></td><td>POST</td><td>Declare a form to be submitted to a handler</td></tr><tr><td><code>action «route»</code></td><td>POST</td><td>Declare an element-less form to be submitted to a handler (akin to Rails&#39; <code>button_to</code> helper)</td></tr><tr><td><code>path «route», method: «method»</code></td><td><code>«method»</code></td><td>Declare an arbitrary path to a handler</td></tr></tbody></table><p>The value for <code>«route»</code>, along with the method called, is used to determine what class(es) will be used to handle the route.</p><h3 id="«route»-syntax" tabindex="-1">«route» Syntax <a class="header-anchor" href="#«route»-syntax" aria-label="Permalink to &quot;«route» Syntax&quot;">​</a></h3><p>A route is a string that contains the <em>path part</em> of a <a href="https://developer.mozilla.org/en-US/docs/Web/API/URL" target="_blank" rel="noreferrer">URL</a>. <em>Segments</em> of the path (i.e. the stuff between each forward slash <code>/</code>) can be either <em>static</em> or a <em>placeholder</em>.</p><p>As such:</p><ul><li>Only the <a href="https://developer.mozilla.org/en-US/docs/Web/API/URL/pathname" target="_blank" rel="noreferrer">pathname</a> of a request may be specified.</li><li>All routes must start with a slash</li><li>A placeholder segment must be a valid Ruby identifier preceded by a colon, e.g. <code>:company_id</code> is allowed, but <code>:company-id</code> is not.</li><li>Routes may not start with a placeholder.</li></ul><p>Some examples:</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>&quot;/dash_board&quot;</span></span>
 <span class="line"><span>&quot;/widgets/:id&quot;</span></span>
 <span class="line"><span>&quot;/company/:company_id/locations/:location_id&quot;</span></span>
 <span class="line"><span>&quot;/&quot;</span></span></code></pre></div><h3 id="class-naming-conventions" tabindex="-1">Class Naming Conventions <a class="header-anchor" href="#class-naming-conventions" aria-label="Permalink to &quot;Class Naming Conventions&quot;">​</a></h3><p>Brut is convention-based, so you are not able to specify the name of the classes used to handle routes. Brut will use the method you called (e.g. <code>page</code>) and the route your provided to determine the class name.</p><p>Some examples:</p><table tabindex="0"><thead><tr><th>Route invocation</th><th>Expected Class Name(s)</th></tr></thead><tbody><tr><td><code>page &quot;/dashboard&quot;</code></td><td><code>DashboardPage</code></td></tr><tr><td><code>page &quot;/widgets/:id&quot;</code></td><td><code>WidgetsByIdPage</code></td></tr><tr><td><code>form &quot;/login&quot;</code></td><td><code>LoginForm</code> and <code>LoginHandler</code></td></tr><tr><td><code>action &quot;/delete_widget/:id&quot;</code></td><td><code>DeleteWidgetWithIdHandler</code></td></tr><tr><td><code>path &quot;/tokens/personal/:token, method :put&quot;</code></td><td><code>Tokens::PersonalWithTokenHandler</code></td></tr></tbody></table><p>Specifically, the name of the class(es) is/are determined as follows:</p><ul><li>Static segments of the pathname are mapped to namespaces or a class based on converting the path segment to camel-case. For example <code>new_widget</code> becomes <code>NewWidget</code>.</li><li>The final static segment in the path represents a class name. All other static segments represent modules in which the final class is namespaced <ul><li>If the route is for a page, <code>Page</code> is appended to the class name.</li><li>If the route is for a form, there are two classes in play, one appended with <code>Form</code> and one with <code>Handler</code>.</li><li>If the route has no form and is just a handler, <code>Handler</code> is appended to the class name.</li></ul></li><li>Placeholder segments are attached to the previous static segment, augmenting its name: <ul><li>The placeholder is camel-cased</li><li>The placeholder is prefixed with <code>By</code> for <code>page</code> routes and <code>With</code> for all other routes</li><li>the prefixed-placeholder is appended to the previous module or class name, e.g. <code>WidgetsById</code></li></ul></li><li>These are now connected to form a valid Ruby class name.</li><li>The route <code>/</code> is special and always maps to <code>HomePage</code>.</li></ul><p>Note that deeply nested routes that contain several placeholders will work, and create complicated classnames.</p><div class="language-ruby vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ruby</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">page </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;/company/:company_id/location/:location_id&quot;</span></span>
@@ -18,4 +18,4 @@ import{_ as a,c as t,o as s,ag as i}from"./chunks/framework.1L-BeKqY.js";const u
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">#    :id was used as a path parameter for</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">#    WidgetsByIdPage (path &#39;/widgets/:id&#39;)</span></span></code></pre></div><p><code>routing</code> is how you create links to other pages:</p><div class="language-erb vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">erb</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">a</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> href</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&lt;%= </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">DashBoardPage</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">routing</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> %&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  Go to Dashboard</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;/</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">a</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span></code></pre></div><div class="note custom-block github-alert"><p class="custom-block-title">NOTE</p><p>You can use <code>routing</code> to create <code>&lt;form&gt;</code> actions, but <a href="/api/Brut/FrontEnd/Components/FormTag.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Components::FormTag</code></a>, which we&#39;ll discuss in <a href="/forms.html">Forms</a>, can do this for you.</p></div><p>The <code>routing</code> method isn&#39;t an abstraction around routes. It&#39;s more of a strongly-typed translation. This means when you change something, your app won&#39;t route to non-existent routes—it&#39;ll blow up with a helpful error.</p><p>For example, if you decided that <code>/dash_board/</code> should&#39;ve been called <code>/account_home</code>, you would change the value in <code>app.rb</code>, then rename the class. At this point, any code that routes to <code>DashboardPage.routing</code> will raise a <code>NameError</code>. With sufficient test coverage, you can address everywhere you see the <code>NameError</code> and be confident you have changed the name and route successfully.</p><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h2><p>Routes are configuration, so you do not need to test them. In fact, you can&#39;t test them directly. Your end-to-end tests should adequately cover the correct usage of your routes. If you always using <code>.routing</code> to generate routes, Ruby&#39;s runtime checks will also ensure you have not used a non-existent or invalid route.</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 does not provide flexibility with routes, nor is logic intended to exist where you are declaring them.</p><h3 id="routes-should-be-named-for-concepts-anyone-can-understand" tabindex="-1">Routes Should be Named for Concepts Anyone Can Understand <a class="header-anchor" href="#routes-should-be-named-for-concepts-anyone-can-understand" aria-label="Permalink to &quot;Routes Should be Named for Concepts Anyone Can Understand&quot;">​</a></h3><p>If you have an account management page that allows modifying data in a table called <code>user_preferences</code>, but everyone just calls it &quot;the account management page&quot;, the route should be <code>/account_management</code>.</p><p>Although routes are primarily for programmers, there&#39;s no reason not to name them using the terms everyone involved in your app uses. This is part of the reason Brut inserts <code>By</code> or <code>With</code> when there is a placeholder. It allows you to have a page for all widgets—the &quot;widgets page&quot;—and a page for a specific widget by id—the &quot;widgets by id page&quot;.</p><h3 id="prefer-shallow-routes-with-a-single-placeholder" tabindex="-1">Prefer Shallow Routes with a Single Placeholder <a class="header-anchor" href="#prefer-shallow-routes-with-a-single-placeholder" aria-label="Permalink to &quot;Prefer Shallow Routes with a Single Placeholder&quot;">​</a></h3><p>The more path segments your route has, and the more placeholders it is, the longer your class name will be and the more you lose the connection to reality. The &quot;company by company id location by location id page&quot; doesn&#39;t exactly roll off the tongue.</p><p>Life will be easier if you can choose names and routes that have a single placeholder. Multiple path segments can be useful for namespacing.</p><h3 id="placeholders-identify-things-query-strings-search-for-things" tabindex="-1">Placeholders Identify Things, Query Strings Search for Things <a class="header-anchor" href="#placeholders-identify-things-query-strings-search-for-things" aria-label="Permalink to &quot;Placeholders Identify Things, Query Strings Search for Things&quot;">​</a></h3><p>A query string is for just that: querying. The query string is not for identifying things. That&#39;s what URIs are for.</p><p>As such, for routes where a specific <em>thing</em> is being identified, use route placeholders like <code>/widgets/:id</code>. When a route is used for searching or locating <em>things</em>, a query string is better: <code>/widgets?type=«type»</code>.</p><p>Remember that the query string is <em>not</em> part of the class name. The values for the query string will be made available to your page or handler.</p><h3 id="pluralization-is-up-to-you" tabindex="-1">Pluralization Is Up to You <a class="header-anchor" href="#pluralization-is-up-to-you" aria-label="Permalink to &quot;Pluralization Is Up to You&quot;">​</a></h3><p>The rules Brut uses to determine the class names to handle routes do not rely on pluralization. You can have a <code>/widget</code> route and a <code>/widgets</code> route, if that makes sense to your domain and team. They are both handled by the same set of underlying rules.</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 Feb 23, 2025</em></p><p>Brut stores all configured routes in a <a href="/api/Brut/FrontEnd/Routing.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Routing</code></a> object. This means that all metadata about a route is available. You are not intended to interact with this class, but you will note that in certain circumstances, the <a href="/api/Brut/FrontEnd/Routing/Route.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Routing::Route</code></a> can be injected into your class.</p><p>Brut uses this metadata to create route handlers with Sinatra. While Brut may not always use Sinatra under the covers, it does as of the writing, so when you call <code>page &quot;/widgets&quot;</code>, Brut will call <code>get &quot;/widgets&quot; do</code> and pass a block to Sinatra to find the class to handle the reqest, create an instance of it, call a method on it, and return the response.</p>`,54)]))}const g=a(o,[["render",n]]);export{u as __pageData,g as default};
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;/</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">a</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span></code></pre></div><div class="note custom-block github-alert"><p class="custom-block-title">NOTE</p><p>You can use <code>routing</code> to create <code>&lt;form&gt;</code> actions, but <a href="/api/Brut/FrontEnd/Components/FormTag.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Components::FormTag</code></a>, which we&#39;ll discuss in <a href="/forms.html">Forms</a>, can do this for you.</p></div><p>The <code>routing</code> method isn&#39;t an abstraction around routes. It&#39;s more of a strongly-typed translation. This means when you change something, your app won&#39;t route to non-existent routes—it&#39;ll blow up with a helpful error.</p><p>For example, if you decided that <code>/dash_board/</code> should&#39;ve been called <code>/account_home</code>, you would change the value in <code>app.rb</code>, then rename the class. At this point, any code that routes to <code>DashboardPage.routing</code> will raise a <code>NameError</code>. With sufficient test coverage, you can address everywhere you see the <code>NameError</code> and be confident you have changed the name and route successfully.</p><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h2><p>Routes are configuration, so you do not need to test them. In fact, you can&#39;t test them directly. Your end-to-end tests should adequately cover the correct usage of your routes. If you always using <code>.routing</code> to generate routes, Ruby&#39;s runtime checks will also ensure you have not used a non-existent or invalid route.</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 does not provide flexibility with routes, nor is logic intended to exist where you are declaring them.</p><h3 id="routes-should-be-named-for-concepts-anyone-can-understand" tabindex="-1">Routes Should be Named for Concepts Anyone Can Understand <a class="header-anchor" href="#routes-should-be-named-for-concepts-anyone-can-understand" aria-label="Permalink to &quot;Routes Should be Named for Concepts Anyone Can Understand&quot;">​</a></h3><p>If you have an account management page that allows modifying data in a table called <code>user_preferences</code>, but everyone just calls it &quot;the account management page&quot;, the route should be <code>/account_management</code>.</p><p>Although routes are primarily for programmers, there&#39;s no reason not to name them using the terms everyone involved in your app uses. This is part of the reason Brut inserts <code>By</code> or <code>With</code> when there is a placeholder. It allows you to have a page for all widgets—the &quot;widgets page&quot;—and a page for a specific widget by id—the &quot;widgets by id page&quot;.</p><h3 id="prefer-shallow-routes-with-a-single-placeholder" tabindex="-1">Prefer Shallow Routes with a Single Placeholder <a class="header-anchor" href="#prefer-shallow-routes-with-a-single-placeholder" aria-label="Permalink to &quot;Prefer Shallow Routes with a Single Placeholder&quot;">​</a></h3><p>The more path segments your route has, and the more placeholders it is, the longer your class name will be and the more you lose the connection to reality. The &quot;company by company id location by location id page&quot; doesn&#39;t exactly roll off the tongue.</p><p>Life will be easier if you can choose names and routes that have a single placeholder. Multiple path segments can be useful for namespacing.</p><h3 id="placeholders-identify-things-query-strings-search-for-things" tabindex="-1">Placeholders Identify Things, Query Strings Search for Things <a class="header-anchor" href="#placeholders-identify-things-query-strings-search-for-things" aria-label="Permalink to &quot;Placeholders Identify Things, Query Strings Search for Things&quot;">​</a></h3><p>A query string is for just that: querying. The query string is not for identifying things. That&#39;s what URIs are for.</p><p>As such, for routes where a specific <em>thing</em> is being identified, use route placeholders like <code>/widgets/:id</code>. When a route is used for searching or locating <em>things</em>, a query string is better: <code>/widgets?type=«type»</code>.</p><p>Remember that the query string is <em>not</em> part of the class name. The values for the query string will be made available to your page or handler.</p><h3 id="pluralization-is-up-to-you" tabindex="-1">Pluralization Is Up to You <a class="header-anchor" href="#pluralization-is-up-to-you" aria-label="Permalink to &quot;Pluralization Is Up to You&quot;">​</a></h3><p>The rules Brut uses to determine the class names to handle routes do not rely on pluralization. You can have a <code>/widget</code> route and a <code>/widgets</code> route, if that makes sense to your domain and team. They are both handled by the same set of underlying rules.</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 Feb 23, 2025</em></p><p>Brut stores all configured routes in a <a href="/api/Brut/FrontEnd/Routing.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Routing</code></a> object. This means that all metadata about a route is available. You are not intended to interact with this class, but you will note that in certain circumstances, the <a href="/api/Brut/FrontEnd/Routing/Route.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Routing::Route</code></a> can be injected into your class.</p><p>Brut uses this metadata to create route handlers with Sinatra. While Brut may not always use Sinatra under the covers, it does as of the writing, so when you call <code>page &quot;/widgets&quot;</code>, Brut will call <code>get &quot;/widgets&quot; do</code> and pass a block to Sinatra to find the class to handle the reqest, create an instance of it, call a method on it, and return the response.</p>`,54)])])}const g=a(o,[["render",n]]);export{u as __pageData,g as default};

data/docs/assets/routes.md.C1dgIBtD.lean.js

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

data/docs/assets/security.md.Jn4SY1uK.js

@@ -0,0 +1 @@
+import{_ as t,c as o,o as a,ag as r}from"./chunks/framework.C4nOkCZI.js";const p=JSON.parse('{"title":"Security","description":"","frontmatter":{},"headers":[],"relativePath":"security.md","filePath":"security.md"}'),i={name:"security.md"};function s(n,e,c,l,d,u){return a(),o("div",null,[...e[0]||(e[0]=[r('<h1 id="security" tabindex="-1">Security <a class="header-anchor" href="#security" aria-label="Permalink to &quot;Security&quot;">​</a></h1><p>As a new framework, Brut has not been battle-tested against potential securitiy exploits. That said, Brut does configure several features to help manage security issues.</p><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to &quot;Overview&quot;">​</a></h2><p>Web application security is a large topic. Brut provides a few features out of the box to manage security of your app:</p><ul><li>Encrypted sessions</li><li>Cross-Site Request Forgery (CSRF) protection</li><li>Content Security Policy headers and tools</li><li><code>bundle audit</code></li></ul><h3 id="encrypted-sessions" tabindex="-1">Encrypted Sessions <a class="header-anchor" href="#encrypted-sessions" aria-label="Permalink to &quot;Encrypted Sessions&quot;">​</a></h3><p>Brut uses the <code>Rack::Session::Cookie</code> middleware to manage cookies. They are encrypted with the value of the environment variable <code>SESSION_SECRET</code>. This prevents both the website visitor and other websites from examining the contents of the cookie.</p><p>This means that if Brut places data in there, it can rely on it being safe when fetched later.</p><p>Cookie behavior and configuration is currently not configurable.</p><h3 id="csrf-protection" tabindex="-1">CSRF Protection <a class="header-anchor" href="#csrf-protection" aria-label="Permalink to &quot;CSRF Protection&quot;">​</a></h3><p>A <a href="https://owasp.org/www-community/attacks/csrf" target="_blank" rel="noreferrer">cross-site request forgery</a> happens when a malicious site submits information from their site to a Brut-powered site, assuming it will allow and respect your credentials, potentially initiating an action on the Brut-powered site that you did not intend.</p><p>The common way to mitigate this is to require a CSRF token to be included with each form submission. This value is generated by the server and included int he user&#39;s secure session. If the form submission&#39;s CSRF token matches, the request is assumed to be valid.</p><p>Brut configures <a href="https://sinatrarb.com/rack-protection/" target="_blank" rel="noreferrer">Rack::Protection::AuthenticityToken</a> as a middleware. Its configuration requires that <em>all</em> form submissions include a valid CSRF token, with a few exceptions noted in the <a href="#technical-notes">Technical Notes</a> section below.</p><p>To include a valid CSRF token in your <a href="/forms.html">form</a>, use <a href="/api/Brut/FrontEnd/Components/FormTag.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Components::FormTag</code></a> to generate your <code>&lt;form&gt;</code>. That&#39;s it.</p><p>Brut&#39;s approach to Ajax requests is to model them as form submissions, so by creating a form using <code>FormTag</code> and using its <a href="https://developer.mozilla.org/en-US/docs/Web/API/FormData" target="_blank" rel="noreferrer"><code>FormData</code></a> to submit that form with e.g. <code>fetch</code>, the CSRF token will be supplied.</p><div class="note custom-block github-alert"><p class="custom-block-title">NOTE</p><p>AJax and CSRF is currently somewhat immature in Brut, so there may be areas where things don&#39;t work as you&#39;d expect.</p></div><h3 id="content-security-policy-headers-and-tools" tabindex="-1">Content Security Policy headers and tools <a class="header-anchor" href="#content-security-policy-headers-and-tools" aria-label="Permalink to &quot;Content Security Policy headers and tools&quot;">​</a></h3><p><a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP" target="_blank" rel="noreferrer">Content Security Policy (CSP)</a> is a way for a website to tell the browser what CSS and JavaScript is allowed to execute on the page. Most web frameworks default to a lax or no policy, which makes applying one later difficult.</p><p>Brut takes the opposite approach. By default, Brut configures <a href="/api/Brut/FrontEnd/RouteHooks/CSPNoInlineStylesOrScripts.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::RouteHooks::CSPNoInlineStylesOrScripts</code></a> as an after route hook. This sets the content security poilcy header to disallow all inline stylings (the <code>style=</code> attribute) and all inline script tags (e.g. <code>onclick=</code>). In development, inline styles are allowed, since they are convienient when prototyping.</p><p>Brut also configures CSP reporting, which is sent into the <a href="/instrumentation.html">instrumentation</a> system.</p><p>You can control this behavior by changing the <code>csp_class</code> and/or <code>csp_reporting_class</code> using <code>Brut.container.override</code> in your <code>App</code>. You can either create your own route hook and use that, or set either to <code>nil</code> to disable CSP entirely.</p><h3 id="bundle-audit" tabindex="-1"><code>bundle audit</code> <a class="header-anchor" href="#bundle-audit" aria-label="Permalink to &quot;`bundle audit`&quot;">​</a></h3><p>The <code>bin/ci</code> script provided when you created your Burt app includes a call to <code>bundle exec bundle audit check --update</code>, which will audit your RubyGems for versions that have known vulnerabilities. If any are found, <code>bin/ci</code> exits nonzero, thus failing your build.</p><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h2><p>In general, you don&#39;t want to test any of this unless you&#39;ve set up something custom or complex. Testing security is done more effectively by a third party evaluating your app as a so-called &quot;black box&quot; or &quot;opaque box&quot; where its probed for issues without knowing how the app is implemented.</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><ul><li>Do not disable CSRF protection.</li><li>Do not disable your content security policy. Use Brut&#39;s built-in and design your app to not require inline styles or scripts. It&#39;s much easier to not do this in the first place than to try to unwind it later.</li><li>Do not ship your app if <code>bundle audit</code> finds vulnerabilities.</li></ul><h2 id="technical-notes" tabindex="-1">Technical Notes <a class="header-anchor" href="#technical-notes" aria-label="Permalink to &quot;Technical Notes&quot;">​</a></h2><div class="important custom-block github-alert"><p class="custom-block-title">IMPORTANT</p><p>Technical Notes are for deeper understanding and debugging. While we will try to keep them up-to-date with changes to Brut&#39;s internals, the source code is always more correct.</p></div><p><em>Last Updated June 13, 2025</em></p><h3 id="csrf-protection-1" tabindex="-1">CSRF Protection <a class="header-anchor" href="#csrf-protection-1" aria-label="Permalink to &quot;CSRF Protection&quot;">​</a></h3><p>CSRF protection is not required for <em>Brut-owned paths</em>, as defined by <a href="/api/Brut/FrontEnd/Middlewares/AnnotateBrutOwnedPaths.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Middlewares::AnnotateBrutOwnedPaths</code></a>. The reason for this is that these paths semantically should not be HTTP GETs, but are also not form submissions. They are currently used for locale detection and instrumentation, which we believe are OK to allow without CSRF protection.</p><p>This may change in the future.</p><h3 id="encrypted-sessions-1" tabindex="-1">Encrypted Sessions <a class="header-anchor" href="#encrypted-sessions-1" aria-label="Permalink to &quot;Encrypted Sessions&quot;">​</a></h3><p>Session cookies are set to expire after 1 year and use the value <code>Lax</code> for <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cookies#controlling_third-party_cookies_with_samesite" target="_blank" rel="noreferrer"><code>SameSite</code></a>. &quot;Lax&quot; allows other sites to submit the Brut-powered site&#39;s cookies, but only if the user navigates to the site. They are not sent if another site submits an Ajax request. We feel this is the right tradeoff betweeen usability and security.</p>',35)])])}const m=t(i,[["render",s]]);export{p as __pageData,m as default};

data/docs/assets/security.md.Jn4SY1uK.lean.js

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

data/docs/assets/{seed-data.md.BvFZlqIk.js → seed-data.md.UZW0WxYN.js}

@@ -1,4 +1,4 @@
-import{_ as e,c as s,o as i,ag as t}from"./chunks/framework.1L-BeKqY.js";const k=JSON.parse('{"title":"See Data for Development","description":"","frontmatter":{},"headers":[],"relativePath":"seed-data.md","filePath":"seed-data.md"}'),n={name:"seed-data.md"};function l(o,a,h,d,r,p){return i(),s("div",null,a[0]||(a[0]=[t(`<h1 id="see-data-for-development" tabindex="-1">See Data for Development <a class="header-anchor" href="#see-data-for-development" aria-label="Permalink to &quot;See Data for Development&quot;">​</a></h1><p>In Brut, <em>seed data</em> is data you set up for the purposes of doing local development. It is <em>not</em> for managing production data and is not used for tests.</p><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to &quot;Overview&quot;">​</a></h2><p>Seed data lives in <code>app/src/back_end/data_models/seed</code>. You can create as many files in here as you like. Each should contain a class that extends <a href="/api/Brut/BackEnd/SeedData.html" target="_self" rel="noopener" data-no-router><code>Brut::BackEnd::SeedData</code></a> and implements <code>seed!</code>. By doing this, the class is regsitered with Brut and when you run <code>bin/db seed</code> all the classes are created and <code>seed!</code> is called.</p><p>FactoryBot will be set up for you, so you can call <code>FactoryBot.create</code> to create the data.</p><p>For example, here is how we might create two accounts, one deactivated, in the same organization:</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/back_end/data_models/seed/all_seed_data.rb</span></span>
+import{_ as e,c as s,o as i,ag as t}from"./chunks/framework.C4nOkCZI.js";const k=JSON.parse('{"title":"See Data for Development","description":"","frontmatter":{},"headers":[],"relativePath":"seed-data.md","filePath":"seed-data.md"}'),n={name:"seed-data.md"};function l(o,a,h,d,r,p){return i(),s("div",null,[...a[0]||(a[0]=[t(`<h1 id="see-data-for-development" tabindex="-1">See Data for Development <a class="header-anchor" href="#see-data-for-development" aria-label="Permalink to &quot;See Data for Development&quot;">​</a></h1><p>In Brut, <em>seed data</em> is data you set up for the purposes of doing local development. It is <em>not</em> for managing production data and is not used for tests.</p><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to &quot;Overview&quot;">​</a></h2><p>Seed data lives in <code>app/src/back_end/data_models/seed</code>. You can create as many files in here as you like. Each should contain a class that extends <a href="/api/Brut/BackEnd/SeedData.html" target="_self" rel="noopener" data-no-router><code>Brut::BackEnd::SeedData</code></a> and implements <code>seed!</code>. By doing this, the class is regsitered with Brut and when you run <code>bin/db seed</code> all the classes are created and <code>seed!</code> is called.</p><p>FactoryBot will be set up for you, so you can call <code>FactoryBot.create</code> to create the data.</p><p>For example, here is how we might create two accounts, one deactivated, in the same organization:</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/back_end/data_models/seed/all_seed_data.rb</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">class</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> AllSeedData</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;">BackEnd</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">SeedData</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  include</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> FactoryBot</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">Syntax</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">::</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">Methods</span></span>
 <span class="line"></span>
@@ -11,4 +11,4 @@ import{_ as e,c as s,o as i,ag as t}from"./chunks/framework.1L-BeKqY.js";const k
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">                              organization:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">                              email:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;chris@example.com&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><p>You can store other data here, such as a CSV, if you want to load data organized in another way. Seed data will only ever be loaded in development, so you can organize it however you like.</p><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h2><p>You do not need to test your seed data. Presumably, you will be using your app in development, and this will be sufficient to determine if your seed data is fit for purpose.</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><ul><li>Use FactoryBot as this is consistent with your tests</li><li>Use literal values for anything relevant to local development. In the example above, the two email addresses are important, presumably because you&#39;d be using those to login. The organization name, however, is irrelevant, so we allow Faker to come up with a name.</li><li>Use local variables as documentation. In the example above, there&#39;s no need to set <code>active_account</code> or <code>inactive_account</code>, but doing so makes it clear what those objects are for.</li><li>Ensure all seed data classes are independent from one another, as the order of their exeuction cannot be guaranteed.</li></ul><h2 id="technical-notes" tabindex="-1">Technical Notes <a class="header-anchor" href="#technical-notes" aria-label="Permalink to &quot;Technical Notes&quot;">​</a></h2><div class="important custom-block github-alert"><p class="custom-block-title">IMPORTANT</p><p>Technical Notes are for deeper understanding and debugging. While we will try to keep them up-to-date with changes to Brut&#39;s internals, the source code is always more correct.</p></div><p><em>Last Updated May 8, 2025</em></p><p>All seed data is loaded in one transaction. This means that if any class&#39; seed data fails, no data will be written.</p><p>Seed data also is not assumed to be idempotent. If you run it twice, you will likely get an error. Because <a href="/database-schema.html#ephemeral-dev-database">your dev database is ephemeral</a>, you can always recreate your dev database via <code>bin/db rebuild &amp;&amp; bin/db seed</code>.</p>`,17)]))}const u=e(n,[["render",l]]);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>You can store other data here, such as a CSV, if you want to load data organized in another way. Seed data will only ever be loaded in development, so you can organize it however you like.</p><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h2><p>You do not need to test your seed data. Presumably, you will be using your app in development, and this will be sufficient to determine if your seed data is fit for purpose.</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><ul><li>Use FactoryBot as this is consistent with your tests</li><li>Use literal values for anything relevant to local development. In the example above, the two email addresses are important, presumably because you&#39;d be using those to login. The organization name, however, is irrelevant, so we allow Faker to come up with a name.</li><li>Use local variables as documentation. In the example above, there&#39;s no need to set <code>active_account</code> or <code>inactive_account</code>, but doing so makes it clear what those objects are for.</li><li>Ensure all seed data classes are independent from one another, as the order of their exeuction cannot be guaranteed.</li></ul><h2 id="technical-notes" tabindex="-1">Technical Notes <a class="header-anchor" href="#technical-notes" aria-label="Permalink to &quot;Technical Notes&quot;">​</a></h2><div class="important custom-block github-alert"><p class="custom-block-title">IMPORTANT</p><p>Technical Notes are for deeper understanding and debugging. While we will try to keep them up-to-date with changes to Brut&#39;s internals, the source code is always more correct.</p></div><p><em>Last Updated May 8, 2025</em></p><p>All seed data is loaded in one transaction. This means that if any class&#39; seed data fails, no data will be written.</p><p>Seed data also is not assumed to be idempotent. If you run it twice, you will likely get an error. Because <a href="/database-schema.html#ephemeral-dev-database">your dev database is ephemeral</a>, you can always recreate your dev database via <code>bin/db rebuild &amp;&amp; bin/db seed</code>.</p>`,17)])])}const u=e(n,[["render",l]]);export{k as __pageData,u as default};

data/docs/assets/seed-data.md.UZW0WxYN.lean.js

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

data/docs/assets/space-time-continuum.md.D9rYGDFH.js

@@ -0,0 +1 @@
+import{_ as t,c as o,o as s,ag as i}from"./chunks/framework.C4nOkCZI.js";const l=JSON.parse('{"title":"Space/Time Continuum - Making Sense of Times and Time Zones","description":"","frontmatter":{},"headers":[],"relativePath":"space-time-continuum.md","filePath":"space-time-continuum.md"}'),a={name:"space-time-continuum.md"};function n(r,e,d,c,h,m){return s(),o("div",null,[...e[0]||(e[0]=[i('<h1 id="space-time-continuum-making-sense-of-times-and-time-zones" tabindex="-1">Space/Time Continuum - Making Sense of Times and Time Zones <a class="header-anchor" href="#space-time-continuum-making-sense-of-times-and-time-zones" aria-label="Permalink to &quot;Space/Time Continuum - Making Sense of Times and Time Zones&quot;">​</a></h1><p>Time zones are the worst. But they are fact of life. This means that answer a question like &quot;what is the date?&quot; or &quot;is it Monday?&quot; are not that easy to answer. Brut tries to help.</p><h2 id="timezones-outside-of-web-requests" tabindex="-1">Timezones Outside of Web Requests <a class="header-anchor" href="#timezones-outside-of-web-requests" aria-label="Permalink to &quot;Timezones Outside of Web Requests&quot;">​</a></h2><p>For back-end code, storing dates to the database, etc., Brut falls back to the normal Ruby app mechanisms for determining the &quot;current time zone&quot;, which is to say, it super-duper depends. The system, the database, and Ruby can all configure a time zone that is in effect when dates are parsed or stored.</p><p>The main way to deal with this is in how <a href="/database-schema.html">Brut manages your database schema</a>, which is to say that it defaults to using <code>timestamp with time zone</code> and encourages you to do the same.</p><p>What this data type means is if your system is set to UTC, stores a timestamp, then restarts with the time zone set to America/Los_Angeles, that timestamp will be read back without ambiguity. If you use <code>timestamp without time zone</code> (or SQL&#39;s standard <code>timestamp</code>), this will not be the case.</p><p>All this is to say, if you use <code>timestamp with time zone</code>, you should generally not have to worry about this. Just be careful when serializing these values.</p><h2 id="timezones-for-sessions" tabindex="-1">Timezones for Sessions <a class="header-anchor" href="#timezones-for-sessions" aria-label="Permalink to &quot;Timezones for Sessions&quot;">​</a></h2><p>Depending on what your app does, you may need to show dates or times to the site visitor. And you&#39;ll probably want to show those in their time zone. Brut can help with this.</p><p>As mentioned in <a href="/flash-and-session.html">Flash and Session</a>, the session provides access to timezone information. Brut also provides a <code>Clock</code> class that represents the current date and time in the current session&#39;s time zone.</p><p>There are two ways to determine a visitor&#39;s time zone: you can ask them, or you can ask their browser.</p><h3 id="getting-timezone-from-the-browser" tabindex="-1">Getting Timezone from the Browser <a class="header-anchor" href="#getting-timezone-from-the-browser" aria-label="Permalink to &quot;Getting Timezone from the Browser&quot;">​</a></h3><p>The default <code>&lt;head&gt;</code> section of your app&#39;s <code>DefaultLayout</code> will include the Brut-provided custom element <a href="/brut-js/api/LocaleDetection.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-locale-detection&gt;</code></a>. This HTML custom element is configured to communicate the browser&#39;s locale and timezone back to Brut at the URL <code>/__brut/local_detection</code>, which is handled by <a href="/api/Brut/FrontEnd/Handlers/LocaleDetectionHandler.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Handlers::LocaleDetectionHandler</code></a>.</p><p>The custom element uses <code>Intl.DateTimeFormat().resolvedOptions().timeZone</code> to determine the browser&#39;s timezone and sends this back to Brut. Whatever this value is, it will be set in the session as <code>timezone_from_browser</code>. When you ask the session for the <code>timezone_from_browser</code>, Brut will attempt to locate a <code>TZInfo::Timezone</code> with that name. If it finds one, that is returned. Otherwise, <code>nil</code> is returned.</p><p>This is only part of how Brut determines the session&#39;s time zone.</p><h3 id="getting-the-session-s-timezone" tabindex="-1">Getting the Session&#39;s Timezone <a class="header-anchor" href="#getting-the-session-s-timezone" aria-label="Permalink to &quot;Getting the Session&#39;s Timezone&quot;">​</a></h3><p>If you ask the session instead for <code>timezone</code>, and it has not been set explicitly, Brut will first check <code>timezone_from_browser</code>. If it&#39;s not <code>nil</code>, it&#39;s returned. If it <em>is</em> <code>nil</code>, the timezone whose name is in <code>ENV[&#39;TZ&#39;]</code> is returned, unless that is missing or invalid, in which case UTC is returned.</p><p>If you have a way to ask the user what their timezone is, you can set it via <code>session.timezone=</code>. If you have done this, <em>that</em> value is returned instead of the above logic.</p><p>Note that in all cases, the timezone that is serialized into the session is the name. This means it&#39;s technically possible for the name to be valid when stored and invalid when read, if you have updated the <code>tzinfo</code> gem and something changed (this should be exceedingly rare).</p><p>Therefore, it&#39;s recommended that if you have asked the visitor their preferred time zone, you store that somewhere in the database, so you can detect when the value from the session has drifted.</p><h3 id="using-the-timezone" tabindex="-1">Using the Timezone <a class="header-anchor" href="#using-the-timezone" aria-label="Permalink to &quot;Using the Timezone&quot;">​</a></h3><p>With a <code>TZInfo::Timezone</code> object, you can certainly create a Ruby <code>Time</code> object via <code>timezone.to_local(Time.new)</code>. However, you don&#39;t have to do this. By <a href="/keyword-injection.html">keyword injecting</a><code>clock:</code>, you will get an instance of <code>Clock</code>, primed with the value of <code>session.timezone</code> as its timezone.</p><p>The <code>Clock</code> responds to <code>now</code> and <code>today</code>, and will return the current timestamp and current date, respectively, in the visitor&#39;s time zone. This means that if your view code does something like <code>l(clock.now, format: :date)</code>, it will show the current time in the visitor&#39;s time zone.</p><p>This, coupled with the use of <code>timestamp with time zone</code>, means these values can be safely sent to the back-end to be stored in the database, and conversion is not necessary.</p><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h2><p>If your app makes heavy use of timezone-based timestamps or dates, you are encouraged to test this logic. <a href="/api/Brut/SpecSupport/ClockSupport.html" target="_self" rel="noopener" data-no-router><code>Brut::SpecSupport::ClockSupport</code></a> (included by default in page, component, and handler tests) provides helper methods to manipulate and use <code>Clock</code> instances. You should not need to mock time or use something like Timecop.</p><p>If your tests just need a clock, or a clock at a time, regardless of time zone, you can use <code>real_clock</code> or <code>clock_at(now:)</code> to pass into your pages, components, and handlers. These will be set at UTC.</p><p>If your tests require a particular timezone, you may use <code>clock_in_timezone_at(timezone_name:, now:)</code>. The timezone name is from <code>tzinfo</code>&#39;s database. <code>clock_in_timezone_at</code> will raise an error if given an invalid timezone. <code>now:</code> is a string that will be parsed as a <code>Time</code>.</p><p>If you are testing something that is sensitive to time, but you do not have access to the clock, <a href="/api/Brut/SpecSupport/SessionSupport.html" target="_self" rel="noopener" data-no-router><code>Brut::SpecSupport::SessionSupport</code></a> provides <code>empty_session</code>, which returns a session object on which you can call <code>timezone=</code>. Beyond this, you may need to provide hooks for setting the time, for example via a query string parameter.</p>',29)])])}const p=t(a,[["render",n]]);export{l as __pageData,p as default};

data/docs/assets/space-time-continuum.md.D9rYGDFH.lean.js

@@ -0,0 +1 @@
+import{_ as t,c as o,o as s,ag as i}from"./chunks/framework.C4nOkCZI.js";const l=JSON.parse('{"title":"Space/Time Continuum - Making Sense of Times and Time Zones","description":"","frontmatter":{},"headers":[],"relativePath":"space-time-continuum.md","filePath":"space-time-continuum.md"}'),a={name:"space-time-continuum.md"};function n(r,e,d,c,h,m){return s(),o("div",null,[...e[0]||(e[0]=[i("",29)])])}const p=t(a,[["render",n]]);export{l as __pageData,p as default};

data/docs/assets/{tutorial.md.BM40jnoq.js → tutorial.md.BX6f6l00.js}

@@ -1,4 +1,4 @@
-import{_ as a,c as t,o as i,ag as e}from"./chunks/framework.1L-BeKqY.js";const k=JSON.parse('{"title":"Tutorials","description":"","frontmatter":{},"headers":[],"relativePath":"tutorial.md","filePath":"tutorial.md"}'),n={name:"tutorial.md"};function l(o,s,h,p,d,r){return i(),t("div",null,s[0]||(s[0]=[e(`<h1 id="tutorials" tabindex="-1">Tutorials <a class="header-anchor" href="#tutorials" aria-label="Permalink to &quot;Tutorials&quot;">​</a></h1><p>Below are several tutorials, along with screencasts showing the tutorial steps as a video. The first one is to <a href="https://video.hardlimit.com/w/ae7EMhwjDq9kSH5dqQ9swV" target="_blank" rel="noreferrer">build a blog in 15 minutes</a>. The remainder of the tutorials assumey you are going in order, however code for each starting point is available, so you can skip around.</p><p>If you&#39;d just like to read source code, there are two apps you can check out:</p><ul><li><a href="https://github.com/thirdtank/blog-demo" target="_blank" rel="noreferrer">The blog we&#39;ll build here</a></li><li><a href="https://github.com/thirdtank/adrs.cloud" target="_blank" rel="noreferrer">ADRs.cloud</a>, which is a more realistic app that has mulitple database tables, progressively-enhanced UI, and background jobs.</li></ul><p>You can be running either of these locally in minutes as long as you have Docker installed.</p><h2 id="understanding-these-tutorials" tabindex="-1">Understanding These Tutorials <a class="header-anchor" href="#understanding-these-tutorials" aria-label="Permalink to &quot;Understanding These Tutorials&quot;">​</a></h2><p>These tutorials will show you command line invocations and code. You should be able to follow along and just type what we say and it should work.</p><p>That said, it&#39;s not always clear what we are talking about.</p><h3 id="understanding-command-line-invocations" tabindex="-1">Understanding Command Line Invocations <a class="header-anchor" href="#understanding-command-line-invocations" aria-label="Permalink to &quot;Understanding Command Line Invocations&quot;">​</a></h3><p>If you aren&#39;t comfortable on the command line, it can be hard to understand what parts of this tutorial represent stuff you should type/paste and what is output from those commands. Here is how that works.</p><p>When we want you to run a command, the preceding text will tell you something like &quot;run this command&quot;, and then you&#39;ll see a codeblock that has the label &quot;bash&quot; in the upper right corner, like so:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</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;">ls</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -l</span></span></code></pre></div><p>If you hover over it, an icon with the tooltip &quot;Copy Code&quot; will appear on the right, and you can click that to copy the command-line invocation. Or, you can select it and copy it, or you can type it in manually.</p><p>In any case, you are expected to type/paste/execute the entire thing. Other parts of this documentation site may precede command lines with <code>&gt;</code> to indicate it&#39;s a shell command. For this tutorial, we aren&#39;t doing that.</p><p>Sometimes, commands are long. They can be split up by entering a backslash (<code>\\</code>) as the last character of a line, hitting return, and continuing the command. For example this command:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</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;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> push</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> origin</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> main</span></span></code></pre></div><p>Could be executed like so:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</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;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> push</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
+import{_ as a,c as t,o as i,ag as e}from"./chunks/framework.C4nOkCZI.js";const k=JSON.parse('{"title":"Tutorials","description":"","frontmatter":{},"headers":[],"relativePath":"tutorial.md","filePath":"tutorial.md"}'),n={name:"tutorial.md"};function l(o,s,h,p,d,r){return i(),t("div",null,[...s[0]||(s[0]=[e(`<h1 id="tutorials" tabindex="-1">Tutorials <a class="header-anchor" href="#tutorials" aria-label="Permalink to &quot;Tutorials&quot;">​</a></h1><p>Below are several tutorials, along with screencasts showing the tutorial steps as a video. The first one is to <a href="https://video.hardlimit.com/w/ae7EMhwjDq9kSH5dqQ9swV" target="_blank" rel="noreferrer">build a blog in 15 minutes</a>. The remainder of the tutorials assumey you are going in order, however code for each starting point is available, so you can skip around.</p><p>If you&#39;d just like to read source code, there are two apps you can check out:</p><ul><li><a href="https://github.com/thirdtank/blog-demo" target="_blank" rel="noreferrer">The blog we&#39;ll build here</a></li><li><a href="https://github.com/thirdtank/adrs.cloud" target="_blank" rel="noreferrer">ADRs.cloud</a>, which is a more realistic app that has mulitple database tables, progressively-enhanced UI, and background jobs.</li></ul><p>You can be running either of these locally in minutes as long as you have Docker installed.</p><h2 id="understanding-these-tutorials" tabindex="-1">Understanding These Tutorials <a class="header-anchor" href="#understanding-these-tutorials" aria-label="Permalink to &quot;Understanding These Tutorials&quot;">​</a></h2><p>These tutorials will show you command line invocations and code. You should be able to follow along and just type what we say and it should work.</p><p>That said, it&#39;s not always clear what we are talking about.</p><h3 id="understanding-command-line-invocations" tabindex="-1">Understanding Command Line Invocations <a class="header-anchor" href="#understanding-command-line-invocations" aria-label="Permalink to &quot;Understanding Command Line Invocations&quot;">​</a></h3><p>If you aren&#39;t comfortable on the command line, it can be hard to understand what parts of this tutorial represent stuff you should type/paste and what is output from those commands. Here is how that works.</p><p>When we want you to run a command, the preceding text will tell you something like &quot;run this command&quot;, and then you&#39;ll see a codeblock that has the label &quot;bash&quot; in the upper right corner, like so:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</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;">ls</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -l</span></span></code></pre></div><p>If you hover over it, an icon with the tooltip &quot;Copy Code&quot; will appear on the right, and you can click that to copy the command-line invocation. Or, you can select it and copy it, or you can type it in manually.</p><p>In any case, you are expected to type/paste/execute the entire thing. Other parts of this documentation site may precede command lines with <code>&gt;</code> to indicate it&#39;s a shell command. For this tutorial, we aren&#39;t doing that.</p><p>Sometimes, commands are long. They can be split up by entering a backslash (<code>\\</code>) as the last character of a line, hitting return, and continuing the command. For example this command:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</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;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> push</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> origin</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> main</span></span></code></pre></div><p>Could be executed like so:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</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;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> push</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
 <span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">    origin</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
 <span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">    main</span></span></code></pre></div><p>In both cases, you can copy/type these as written and they will work.</p><p>To show output of a command, a separate code block will be used, and the first line of the output will be the string <code># OUTPUT:</code>, and there should <strong>not</strong> be a &quot;bash&quot; label in the upper right corner:</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># OUTPUT</span></span>
 <span class="line"><span>app                    dx                   puma.config.rb</span></span>
@@ -24,4 +24,4 @@ import{_ as a,c as t,o as i,ag as e}from"./chunks/framework.1L-BeKqY.js";const k
 <span class="line highlighted"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    span </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">do</span></span>
 <span class="line highlighted"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">      inline_svg</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;edit_icon&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
 <span class="line highlighted"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span></code></pre><div class="line-numbers-wrapper" aria-hidden="true"><span class="line-number">12</span><br><span class="line-number">13</span><br><span class="line-number">14</span><br><span class="line-number">15</span><br><span class="line-number">16</span><br><span class="line-number">17</span><br></div></div><p>This says to find the line that looks like the first one (preceded with a <code>-</code> and shown in red) and replace it with the second one (preceded with a <code>+</code> and shown in green). <strong>Do not use the <code>+</code> or <code>-</code> in your code</strong>, that is just to indicate which line is which.</p><p>Lastly, we&#39;ll try to mention the path to the file either in the preceding text or as a comment in the code.</p><h2 id="tutorials-1" tabindex="-1">Tutorials <a class="header-anchor" href="#tutorials-1" aria-label="Permalink to &quot;Tutorials&quot;">​</a></h2><p>These go mostly in order, each building on the last, but you can start anywhere by using the tutorial on GitHub. The only one that starts from nothing is the first one.</p><table tabindex="0"><thead><tr><th>Index</th><th>Title</th><th>Tutorial</th><th>Screencast</th></tr></thead><tbody><tr><td>1</td><td>Build a Blog in 15 Minutes</td><td><a href="./tutorials/01-intro.html">Tutorial</a></td><td><a href="https://video.hardlimit.com/w/ae7EMhwjDq9kSH5dqQ9swV" target="_blank" rel="noreferrer">Screencast</a></td></tr><tr><td>2</td><td>Adding a Styled Confirmation Dialog</td><td><a href="./tutorials/02-dialog.html">Tutorial</a></td><td><a href="https://video.hardlimit.com/w/4y8Pjd8VVPDK372mozCUdj" target="_blank" rel="noreferrer">Screencast</a></td></tr><tr><td>3</td><td>Leveraging Externalizable IDs (coming soon)</td><td></td><td></td></tr><tr><td>4</td><td>Form Basics (coming soon)</td><td></td><td></td></tr><tr><td>5</td><td>Advanced Forms (coming soon)</td><td></td><td></td></tr><tr><td>6</td><td>AJax Form Submissions (coming soon)</td><td></td><td></td></tr><tr><td>7</td><td>Authentication (coming soon)</td><td></td><td></td></tr><tr><td>8</td><td>Background Jobs with Sidekiq (coming soon)</td><td></td><td></td></tr><tr><td>9</td><td>How to Leverage BrutJS and Custom Elements (coming soon)</td><td></td><td></td></tr></tbody></table>`,40)]))}const u=a(n,[["render",l]]);export{k as __pageData,u as default};
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span></code></pre><div class="line-numbers-wrapper" aria-hidden="true"><span class="line-number">12</span><br><span class="line-number">13</span><br><span class="line-number">14</span><br><span class="line-number">15</span><br><span class="line-number">16</span><br><span class="line-number">17</span><br></div></div><p>This says to find the line that looks like the first one (preceded with a <code>-</code> and shown in red) and replace it with the second one (preceded with a <code>+</code> and shown in green). <strong>Do not use the <code>+</code> or <code>-</code> in your code</strong>, that is just to indicate which line is which.</p><p>Lastly, we&#39;ll try to mention the path to the file either in the preceding text or as a comment in the code.</p><h2 id="tutorials-1" tabindex="-1">Tutorials <a class="header-anchor" href="#tutorials-1" aria-label="Permalink to &quot;Tutorials&quot;">​</a></h2><p>These go mostly in order, each building on the last, but you can start anywhere by using the tutorial on GitHub. The only one that starts from nothing is the first one.</p><table tabindex="0"><thead><tr><th>Index</th><th>Title</th><th>Tutorial</th><th>Screencast</th></tr></thead><tbody><tr><td>1</td><td>Build a Blog in 15 Minutes</td><td><a href="./tutorials/01-intro.html">Tutorial</a></td><td><a href="https://video.hardlimit.com/w/ae7EMhwjDq9kSH5dqQ9swV" target="_blank" rel="noreferrer">Screencast</a></td></tr><tr><td>2</td><td>Adding a Styled Confirmation Dialog</td><td><a href="./tutorials/02-dialog.html">Tutorial</a></td><td><a href="https://video.hardlimit.com/w/4y8Pjd8VVPDK372mozCUdj" target="_blank" rel="noreferrer">Screencast</a></td></tr><tr><td>3</td><td>Leveraging Externalizable IDs (coming soon)</td><td></td><td></td></tr><tr><td>4</td><td>Form Basics (coming soon)</td><td></td><td></td></tr><tr><td>5</td><td>Advanced Forms (coming soon)</td><td></td><td></td></tr><tr><td>6</td><td>AJax Form Submissions (coming soon)</td><td></td><td></td></tr><tr><td>7</td><td>Authentication (coming soon)</td><td></td><td></td></tr><tr><td>8</td><td>Background Jobs with Sidekiq (coming soon)</td><td></td><td></td></tr><tr><td>9</td><td>How to Leverage BrutJS and Custom Elements (coming soon)</td><td></td><td></td></tr></tbody></table>`,40)])])}const u=a(n,[["render",l]]);export{k as __pageData,u as default};

data/docs/assets/tutorial.md.BX6f6l00.lean.js

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

data/docs/assets/{tutorials_01-intro.md.B4sUBY3X.js → tutorials_01-intro.md.CzZ3kpF_.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as a,o as n,ag as e}from"./chunks/framework.1L-BeKqY.js";const t="/assets/welcome-to-brut.VSWzl17-.png",p="/assets/initial-home-page.DNIaYmgP.png",l="/assets/styled-home-page.BzdI7dWz.png",h="/assets/basic-form.DbHnu0oW.png",o="/assets/basic-form-with-violations.Cv6Y9-Q_.png",k="/assets/styled-form-with-violations.Bv_sa9tg.png",d="/assets/styled-form-with-server-side-violations.Bjxd8Dpv.png",r="/assets/styled-home-page-with-posts.Dd4kG89D.png",c="/assets/new-post-editor.DrHr-5oh.png",g="/assets/new-post-home-page.Bm34lyMg.png",B=JSON.parse('{"title":"Build a Blog in 15 Minutes","description":"","frontmatter":{},"headers":[],"relativePath":"tutorials/01-intro.md","filePath":"tutorials/01-intro.md"}'),E={name:"tutorials/01-intro.md"};function u(y,s,F,b,m,C){return n(),a("div",null,s[0]||(s[0]=[e(`<h1 id="build-a-blog-in-15-minutes" tabindex="-1">Build a Blog in 15 Minutes <a class="header-anchor" href="#build-a-blog-in-15-minutes" aria-label="Permalink to &quot;Build a Blog in 15 Minutes&quot;">​</a></h1><p>This will start from nothing and show you the main features of Brut by building a very basic blog. You&#39;ll learn how to make a new Brut app, how to build pages, submit forms, validate data, and access data in a database. You&#39;ll also learn how to test it all.</p><h2 id="set-up" tabindex="-1">Set Up <a class="header-anchor" href="#set-up" aria-label="Permalink to &quot;Set Up&quot;">​</a></h2><p>The only two pieces of software you need are Docker and a code editor:</p><ol><li><p><a href="https://docker.com" target="_blank" rel="noreferrer">Install Docker</a></p><div class="tip custom-block github-alert"><p class="custom-block-title">TIP</p><p>If you are on Windows, we <em>highly</em> recommend you use the Windows Subystem for Linux (WSL2), as this makes Brut, web developement, and, honestly, your entire life as you know it, far easier than trying to get things working natively in Windows.</p></div></li><li><p>If you are new to programming or new to Ruby and don&#39;t know what editor to get, use VSCode. If you are a vim or emacs person, those will be far better, but if you are used to an IDE, VSCode will be the easiest to get set up and learn to use.</p></li></ol><p>To check that docker is installed, open up a terminal and run:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</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;">docker</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> info</span></span></code></pre></div><p>This should produce a ton of output:</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># OUTPUT</span></span>
+import{_ as i,c as a,o as n,ag as e}from"./chunks/framework.C4nOkCZI.js";const t="/assets/welcome-to-brut.VSWzl17-.png",p="/assets/initial-home-page.DNIaYmgP.png",l="/assets/styled-home-page.BzdI7dWz.png",h="/assets/basic-form.DbHnu0oW.png",o="/assets/basic-form-with-violations.Cv6Y9-Q_.png",k="/assets/styled-form-with-violations.Bv_sa9tg.png",d="/assets/styled-form-with-server-side-violations.Bjxd8Dpv.png",r="/assets/styled-home-page-with-posts.Dd4kG89D.png",c="/assets/new-post-editor.DrHr-5oh.png",g="/assets/new-post-home-page.Bm34lyMg.png",B=JSON.parse('{"title":"Build a Blog in 15 Minutes","description":"","frontmatter":{},"headers":[],"relativePath":"tutorials/01-intro.md","filePath":"tutorials/01-intro.md"}'),E={name:"tutorials/01-intro.md"};function u(y,s,F,b,m,C){return n(),a("div",null,[...s[0]||(s[0]=[e(`<h1 id="build-a-blog-in-15-minutes" tabindex="-1">Build a Blog in 15 Minutes <a class="header-anchor" href="#build-a-blog-in-15-minutes" aria-label="Permalink to &quot;Build a Blog in 15 Minutes&quot;">​</a></h1><p>This will start from nothing and show you the main features of Brut by building a very basic blog. You&#39;ll learn how to make a new Brut app, how to build pages, submit forms, validate data, and access data in a database. You&#39;ll also learn how to test it all.</p><h2 id="set-up" tabindex="-1">Set Up <a class="header-anchor" href="#set-up" aria-label="Permalink to &quot;Set Up&quot;">​</a></h2><p>The only two pieces of software you need are Docker and a code editor:</p><ol><li><p><a href="https://docker.com" target="_blank" rel="noreferrer">Install Docker</a></p><div class="tip custom-block github-alert"><p class="custom-block-title">TIP</p><p>If you are on Windows, we <em>highly</em> recommend you use the Windows Subystem for Linux (WSL2), as this makes Brut, web developement, and, honestly, your entire life as you know it, far easier than trying to get things working natively in Windows.</p></div></li><li><p>If you are new to programming or new to Ruby and don&#39;t know what editor to get, use VSCode. If you are a vim or emacs person, those will be far better, but if you are used to an IDE, VSCode will be the easiest to get set up and learn to use.</p></li></ol><p>To check that docker is installed, open up a terminal and run:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</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;">docker</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> info</span></span></code></pre></div><p>This should produce a ton of output:</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># OUTPUT</span></span>
 <span class="line"><span>Client:</span></span>
 <span class="line"><span> Version:    28.2.2</span></span>
 <span class="line"><span>«LOTS OF OUTPUT»</span></span></code></pre></div><p>To be extra sure, <strong>right after you ran <code>docker info</code></strong>, check <code>$?</code>, the exit code, to make sure it&#39;s a 0, which means the command ran successfully:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">echo</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> $?</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># OUTPUT</span></span>
@@ -705,4 +705,4 @@ import{_ as i,c as a,o as n,ag as e}from"./chunks/framework.1L-BeKqY.js";const t
 <span class="line"><span>No vulnerabilities found</span></span>
 <span class="line"><span>[ bin/ci ] Checking to see that all classes have tests</span></span>
 <span class="line"><span>[ bin/test ] All tests exists!</span></span>
-<span class="line"><span>[ bin/ci ] Done</span></span></code></pre></div><p>That&#39;s it!</p><h2 id="areas-for-self-exploration" tabindex="-1">Areas for Self-Exploration <a class="header-anchor" href="#areas-for-self-exploration" aria-label="Permalink to &quot;Areas for Self-Exploration&quot;">​</a></h2><p>Here are a few enhancement you can try to make:</p><ul><li>Create a client-side constraint requiring the title to match a certain regexp.</li><li>Add a server-side constraint requiring at least two paragraphs.</li><li>Allow editing the blog post creation date</li><li>Add an author field to allow entering the author&#39;s name</li><li>Add pagination to the home page</li></ul>`,330)]))}const f=i(E,[["render",u]]);export{B as __pageData,f as default};
+<span class="line"><span>[ bin/ci ] Done</span></span></code></pre></div><p>That&#39;s it!</p><h2 id="areas-for-self-exploration" tabindex="-1">Areas for Self-Exploration <a class="header-anchor" href="#areas-for-self-exploration" aria-label="Permalink to &quot;Areas for Self-Exploration&quot;">​</a></h2><p>Here are a few enhancement you can try to make:</p><ul><li>Create a client-side constraint requiring the title to match a certain regexp.</li><li>Add a server-side constraint requiring at least two paragraphs.</li><li>Allow editing the blog post creation date</li><li>Add an author field to allow entering the author&#39;s name</li><li>Add pagination to the home page</li></ul>`,330)])])}const f=i(E,[["render",u]]);export{B as __pageData,f as default};

data/docs/assets/{tutorials_01-intro.md.B4sUBY3X.lean.js → tutorials_01-intro.md.CzZ3kpF_.lean.js}

@@ -1 +1 @@
-import{_ as i,c as a,o as n,ag as e}from"./chunks/framework.1L-BeKqY.js";const t="/assets/welcome-to-brut.VSWzl17-.png",p="/assets/initial-home-page.DNIaYmgP.png",l="/assets/styled-home-page.BzdI7dWz.png",h="/assets/basic-form.DbHnu0oW.png",o="/assets/basic-form-with-violations.Cv6Y9-Q_.png",k="/assets/styled-form-with-violations.Bv_sa9tg.png",d="/assets/styled-form-with-server-side-violations.Bjxd8Dpv.png",r="/assets/styled-home-page-with-posts.Dd4kG89D.png",c="/assets/new-post-editor.DrHr-5oh.png",g="/assets/new-post-home-page.Bm34lyMg.png",B=JSON.parse('{"title":"Build a Blog in 15 Minutes","description":"","frontmatter":{},"headers":[],"relativePath":"tutorials/01-intro.md","filePath":"tutorials/01-intro.md"}'),E={name:"tutorials/01-intro.md"};function u(y,s,F,b,m,C){return n(),a("div",null,s[0]||(s[0]=[e("",330)]))}const f=i(E,[["render",u]]);export{B as __pageData,f as default};
+import{_ as i,c as a,o as n,ag as e}from"./chunks/framework.C4nOkCZI.js";const t="/assets/welcome-to-brut.VSWzl17-.png",p="/assets/initial-home-page.DNIaYmgP.png",l="/assets/styled-home-page.BzdI7dWz.png",h="/assets/basic-form.DbHnu0oW.png",o="/assets/basic-form-with-violations.Cv6Y9-Q_.png",k="/assets/styled-form-with-violations.Bv_sa9tg.png",d="/assets/styled-form-with-server-side-violations.Bjxd8Dpv.png",r="/assets/styled-home-page-with-posts.Dd4kG89D.png",c="/assets/new-post-editor.DrHr-5oh.png",g="/assets/new-post-home-page.Bm34lyMg.png",B=JSON.parse('{"title":"Build a Blog in 15 Minutes","description":"","frontmatter":{},"headers":[],"relativePath":"tutorials/01-intro.md","filePath":"tutorials/01-intro.md"}'),E={name:"tutorials/01-intro.md"};function u(y,s,F,b,m,C){return n(),a("div",null,[...s[0]||(s[0]=[e("",330)])])}const f=i(E,[["render",u]]);export{B as __pageData,f as default};

data/docs/assets/{tutorials_02-dialog.md.CPNK1SC_.js → tutorials_02-dialog.md.De6iTsWX.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as a,o as n,ag as e}from"./chunks/framework.1L-BeKqY.js";const t="/assets/02-confirmation-flow.D9gZ0S5U.png",l="/assets/02-confirmation-dialog-browser.DH8ALFO4.png",p="/assets/02-confirmation-dialog-browser-element.DPsf0xUW.png",h="/assets/02-confirmation-dialog-browser-element-styled.3NEGM20-.png",b=JSON.parse('{"title":"Tutorial: Styled Confirmation Dialog","description":"","frontmatter":{},"headers":[],"relativePath":"tutorials/02-dialog.md","filePath":"tutorials/02-dialog.md"}'),r={name:"tutorials/02-dialog.md"};function o(k,s,d,c,g,E){return n(),a("div",null,s[0]||(s[0]=[e(`<h1 id="tutorial-styled-confirmation-dialog" tabindex="-1">Tutorial: Styled Confirmation Dialog <a class="header-anchor" href="#tutorial-styled-confirmation-dialog" aria-label="Permalink to &quot;Tutorial: Styled Confirmation Dialog&quot;">​</a></h1><p>For actions that can&#39;t be undone, it&#39;s customary to confirm with the visitor that they are sure they want to take that action. Brut provides support for this. You can use <code>window.confirm</code> or create your own styled <code>&lt;dialog&gt;</code> that Brut will use. Both approaches don&#39;t require writing any JavaScript yourself.</p><p><a href="https://video.hardlimit.com/w/4y8Pjd8VVPDK372mozCUdj" target="_blank" rel="noreferrer">You can watching this as a screencast instead</a>.</p><h2 id="set-up" tabindex="-1">Set Up <a class="header-anchor" href="#set-up" aria-label="Permalink to &quot;Set Up&quot;">​</a></h2><p>If you haven&#39;t followed the <a href="/tutorials/01-intro.html">initial tutorial</a>, you&#39;ll need to pull down the blog app so you have a place to work.</p><ol><li><p><a href="https://docker.com" target="_blank" rel="noreferrer">Install Docker</a></p><div class="tip custom-block github-alert"><p class="custom-block-title">TIP</p><p>If you are on Windows, we <em>highly</em> recommend you use the Windows Subystem for Linux (WSL2), as this makes Brut, web developement, and, honestly, your entire life as you know it, far easier than trying to get things working natively in Windows.</p></div></li><li><p>Clone the <code>blog-demo</code> repo (<strong>don&#39;t use Codespaces as it is not supported</strong>):</p><div class="vp-code-group vp-adaptive-theme"><div class="tabs"><input type="radio" name="group-3hukd" id="tab-jTrnAT9" checked><label data-title="Terminal" for="tab-jTrnAT9">Terminal</label><input type="radio" name="group-3hukd" id="tab-CZvrEe1"><label data-title="GitHub CLI" for="tab-CZvrEe1">GitHub CLI</label></div><div class="blocks"><div class="language-bash vp-adaptive-theme active"><button title="Copy Code" class="copy"></button><span class="lang">bash</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;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> clone</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> git@github.com:thirdtank/blog-demo.git</span></span></code></pre></div><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</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;">gh</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> repo</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> clone</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> thirdtank/blog-demo</span></span></code></pre></div></div></div></li><li><p><code>cd</code> to what you just cloned.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">cd</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> blog-demo</span></span></code></pre></div></li><li><p>Create a branch named <code>confirmation-dialog</code> off of the <code>02-confirmation-dialog/start</code> branch:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</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;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> checkout</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -b</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> confirmation-dialog</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> 02-confirmation-dialog/start</span></span></code></pre></div></li><li><p>Build your development image.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</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;">dx/build</span></span></code></pre></div></li><li><p>Start the environment, which will pull down Postgres and otel-desktop-viewer</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</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;">dx/start</span></span></code></pre></div></li><li><p>In another terminal window, &quot;log in&quot; to your dev environment (note that you can use your editor on your computer to edit code)</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</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;">dx/exec</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> bash</span></span></code></pre></div></li><li><p>Set up and run tests to make sure things are working before you start making changes. Note, this is <strong>inside the container</strong>, not directly on your computer.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</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;">bin/setup</span></span>
+import{_ as i,c as a,o as n,ag as e}from"./chunks/framework.C4nOkCZI.js";const t="/assets/02-confirmation-flow.D9gZ0S5U.png",l="/assets/02-confirmation-dialog-browser.DH8ALFO4.png",p="/assets/02-confirmation-dialog-browser-element.DPsf0xUW.png",h="/assets/02-confirmation-dialog-browser-element-styled.3NEGM20-.png",u=JSON.parse('{"title":"Tutorial: Styled Confirmation Dialog","description":"","frontmatter":{},"headers":[],"relativePath":"tutorials/02-dialog.md","filePath":"tutorials/02-dialog.md"}'),r={name:"tutorials/02-dialog.md"};function o(k,s,d,c,g,E){return n(),a("div",null,[...s[0]||(s[0]=[e(`<h1 id="tutorial-styled-confirmation-dialog" tabindex="-1">Tutorial: Styled Confirmation Dialog <a class="header-anchor" href="#tutorial-styled-confirmation-dialog" aria-label="Permalink to &quot;Tutorial: Styled Confirmation Dialog&quot;">​</a></h1><p>For actions that can&#39;t be undone, it&#39;s customary to confirm with the visitor that they are sure they want to take that action. Brut provides support for this. You can use <code>window.confirm</code> or create your own styled <code>&lt;dialog&gt;</code> that Brut will use. Both approaches don&#39;t require writing any JavaScript yourself.</p><p><a href="https://video.hardlimit.com/w/4y8Pjd8VVPDK372mozCUdj" target="_blank" rel="noreferrer">You can watching this as a screencast instead</a>.</p><h2 id="set-up" tabindex="-1">Set Up <a class="header-anchor" href="#set-up" aria-label="Permalink to &quot;Set Up&quot;">​</a></h2><p>If you haven&#39;t followed the <a href="/tutorials/01-intro.html">initial tutorial</a>, you&#39;ll need to pull down the blog app so you have a place to work.</p><ol><li><p><a href="https://docker.com" target="_blank" rel="noreferrer">Install Docker</a></p><div class="tip custom-block github-alert"><p class="custom-block-title">TIP</p><p>If you are on Windows, we <em>highly</em> recommend you use the Windows Subystem for Linux (WSL2), as this makes Brut, web developement, and, honestly, your entire life as you know it, far easier than trying to get things working natively in Windows.</p></div></li><li><p>Clone the <code>blog-demo</code> repo (<strong>don&#39;t use Codespaces as it is not supported</strong>):</p><div class="vp-code-group vp-adaptive-theme"><div class="tabs"><input type="radio" name="group-Nc_py" id="tab-oGGQEg7" checked><label data-title="Terminal" for="tab-oGGQEg7">Terminal</label><input type="radio" name="group-Nc_py" id="tab-gs-HkeB"><label data-title="GitHub CLI" for="tab-gs-HkeB">GitHub CLI</label></div><div class="blocks"><div class="language-bash vp-adaptive-theme active"><button title="Copy Code" class="copy"></button><span class="lang">bash</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;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> clone</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> git@github.com:thirdtank/blog-demo.git</span></span></code></pre></div><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</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;">gh</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> repo</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> clone</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> thirdtank/blog-demo</span></span></code></pre></div></div></div></li><li><p><code>cd</code> to what you just cloned.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">cd</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> blog-demo</span></span></code></pre></div></li><li><p>Create a branch named <code>confirmation-dialog</code> off of the <code>02-confirmation-dialog/start</code> branch:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</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;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> checkout</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -b</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> confirmation-dialog</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> 02-confirmation-dialog/start</span></span></code></pre></div></li><li><p>Build your development image.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</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;">dx/build</span></span></code></pre></div></li><li><p>Start the environment, which will pull down Postgres and otel-desktop-viewer</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</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;">dx/start</span></span></code></pre></div></li><li><p>In another terminal window, &quot;log in&quot; to your dev environment (note that you can use your editor on your computer to edit code)</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</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;">dx/exec</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> bash</span></span></code></pre></div></li><li><p>Set up and run tests to make sure things are working before you start making changes. Note, this is <strong>inside the container</strong>, not directly on your computer.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</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;">bin/setup</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">bin/ci</span></span></code></pre></div></li></ol><h2 id="what-we-re-doing" tabindex="-1">What We&#39;re Doing <a class="header-anchor" href="#what-we-re-doing" aria-label="Permalink to &quot;What We&#39;re Doing&quot;">​</a></h2><p>When writing a blog post, if the title and content satisfy all constraints, the post is saved and shown on the home page. Because this can&#39;t currently be undone, we want the user to confirm the posting, just to avoid any accidents.</p><p>Initially, we will use <code>window.confirm</code> to do this. After that, we&#39;ll create a nicely styled dialog to do the confirmation. While this will require that the browser execute JavaScript, we won&#39;t be writing any. We&#39;ll use Brut-provided Web Components to do this.</p><p><img src="`+t+`" alt="Diagram showing the flow, with a screenshot of the blog post editor on the left, and a pink arrow from
 the &#39;Post it&#39; button going to the text &#39;Are You Sure?&#39;. From there, a pink line labeled &#39;No&#39; goes back
 to the editor, while a pink line labeled &#39;Yes&#39; goes to a screenshot of the home page showing the blog
@@ -271,4 +271,4 @@ post."></p><h2 id="initial-version-using-window-confirm" tabindex="-1">Initial V
 <span class="line"><span>[ bin/db ] Database exists. Dropping...</span></span>
 <span class="line"><span>[ bin/db ] blog_test does not exit. Creating...</span></span>
 <span class="line"><span>[ bin/db ] Migrations applied</span></span>
-<span class="line"><span>[ bin/test ] [&quot;bin/db rebuild --env=test&quot;] succeeded</span></span></code></pre></div><h2 id="areas-for-self-exploration" tabindex="-1">Areas for Self-Exploration <a class="header-anchor" href="#areas-for-self-exploration" aria-label="Permalink to &quot;Areas for Self-Exploration&quot;">​</a></h2><ul><li>Extract the dialog into its own component</li><li>Use Internationalization for all the dialog values</li></ul>`,79)]))}const y=i(r,[["render",o]]);export{b as __pageData,y as default};
+<span class="line"><span>[ bin/test ] [&quot;bin/db rebuild --env=test&quot;] succeeded</span></span></code></pre></div><h2 id="areas-for-self-exploration" tabindex="-1">Areas for Self-Exploration <a class="header-anchor" href="#areas-for-self-exploration" aria-label="Permalink to &quot;Areas for Self-Exploration&quot;">​</a></h2><ul><li>Extract the dialog into its own component</li><li>Use Internationalization for all the dialog values</li></ul>`,79)])])}const y=i(r,[["render",o]]);export{u as __pageData,y as default};

data/docs/assets/{tutorials_02-dialog.md.CPNK1SC_.lean.js → tutorials_02-dialog.md.De6iTsWX.lean.js}

@@ -1 +1 @@
-import{_ as i,c as a,o as n,ag as e}from"./chunks/framework.1L-BeKqY.js";const t="/assets/02-confirmation-flow.D9gZ0S5U.png",l="/assets/02-confirmation-dialog-browser.DH8ALFO4.png",p="/assets/02-confirmation-dialog-browser-element.DPsf0xUW.png",h="/assets/02-confirmation-dialog-browser-element-styled.3NEGM20-.png",b=JSON.parse('{"title":"Tutorial: Styled Confirmation Dialog","description":"","frontmatter":{},"headers":[],"relativePath":"tutorials/02-dialog.md","filePath":"tutorials/02-dialog.md"}'),r={name:"tutorials/02-dialog.md"};function o(k,s,d,c,g,E){return n(),a("div",null,s[0]||(s[0]=[e("",79)]))}const y=i(r,[["render",o]]);export{b as __pageData,y as default};
+import{_ as i,c as a,o as n,ag as e}from"./chunks/framework.C4nOkCZI.js";const t="/assets/02-confirmation-flow.D9gZ0S5U.png",l="/assets/02-confirmation-dialog-browser.DH8ALFO4.png",p="/assets/02-confirmation-dialog-browser-element.DPsf0xUW.png",h="/assets/02-confirmation-dialog-browser-element-styled.3NEGM20-.png",u=JSON.parse('{"title":"Tutorial: Styled Confirmation Dialog","description":"","frontmatter":{},"headers":[],"relativePath":"tutorials/02-dialog.md","filePath":"tutorials/02-dialog.md"}'),r={name:"tutorials/02-dialog.md"};function o(k,s,d,c,g,E){return n(),a("div",null,[...s[0]||(s[0]=[e("",79)])])}const y=i(r,[["render",o]]);export{u as __pageData,y as default};