brut 0.0.29 → 0.1.0

data/brutrb.com/recipes/authentication.md

@@ -7,15 +7,16 @@ this recipe will demonstrate all the moving parts:
 * How to design pages that require authentication
 * How to manage the signed-in user in code
 
-## Feature Description
+## Feature
 
-* Visitors can sign up for an account with an email and password
-* Visitors can log in with their email and password
-* Visitors cannot access the home page without logging in
-* Visitors can access the about page without logging in
+* Visitors can log in with an email, that is assumed to have been inserted previously (no passwords or signup, just to simplify the recipe)
+* Visitors can access the home page without logging in
+* Visitors cannot access the dashboard page without logging in
 
 ## Recipe
 
+### Set up Database and Seed Data
+
 First, we'll make a database table called `accounts` that will have an email field
 and a password hash field.
 
@@ -23,4 +24,312 @@ and a password hash field.
 bin/db new-migration accounts
 ```
 
-This will create a file in `app/src/back_end/data_models/migrations` 
+This will create a file in `app/src/back_end/data_models/migrations`.  We'll edit it
+to create a new table called `accounts`:
+
+```ruby
+Sequel.migration do
+  up do
+    create_table :accounts, comment: "People or systems who can access this system", external_id: true do
+      column :email, :text, unique: true
+      column :deactivated_at, :timestamptz, null: true
+    end
+  end
+end
+```
+
+We'll also create `app/src/back_end/data_models/db/account.rb`:
+
+```ruby
+class DB::Account < AppDataModel
+end
+```
+
+Next, we'll create a factory for it in `specs/factories/db/account.factory.rb`:
+
+```ruby
+require "bcrypt"
+FactoryBot.define do
+  factory :account, class: "DB::Account" do
+    email         { Faker::Internet.unique.email }
+    trait :inactive do
+      deactivated_at { Time.now }
+    end
+  end
+end
+```
+
+Next, we'll make seed data in `app/src/back_end/data_models/seed/app_seed_data.rb`
+
+```ruby
+require "brut/back_end/seed_data"
+class AppSeedData < Brut::BackEnd::SeedData
+  include FactoryBot::Syntax::Methods
+  def seed!
+    create(:account,            email: "pat@example.com")
+    create(:account, :inactive, email: "chris@example.com")
+  end
+end
+```
+
+Now, let's apply this to the database and load the seed data:
+
+```
+> bin/db migrate
+> bin/db migrate -e test
+> bin/db seed
+```
+
+### Create a Login Page
+
+To make this UI work, we'll need a login page and a dashboard page.
+
+```
+> bin/scaffold page /login
+> bin/scaffold page /dashboard
+```
+
+We'll also need a login form:
+
+```
+> bin/scaffold form /login
+```
+
+We'll add a link on the HomePage to log in:
+
+```ruby
+# app/src/front_end/pages/home_page.rb
+class HomePage < AppPage
+  def page_template
+    h1 { "Welcome!" }
+    a(href: LoginPage.routing) {
+      "Log in"
+    }
+  end
+end
+```
+
+Before building the login page, we'll need the form.  It'll just have one field:
+email:
+
+```ruby
+# app/src/front_end/forms/login_form.rb
+class LoginForm < AppForm
+  input :email # Brut will make this type=email and required
+end
+```
+
+Now, we can create the login page:
+
+```ruby
+# app/src/front_end/pages/login_page.rb
+class LoginPage < AppPage
+
+  include Brut::FrontEnd::Components
+
+  # An existing form can be passed in, so that this
+  # page can be shown with form errors from a previous
+  # login attempt
+  def initialize(form: nil)
+    @form = form || LoginForm.new
+  end
+
+  def page_template
+    h1 { "Login, please!" }
+    brut_form do
+      FormTag(for: @form) do
+        label do
+          Inputs::TextField(form: @form, input_name: :email)
+          div { "Email" }
+          ConstraintViolations(form: @form, input_name: :email)
+        end
+        button do
+          "Login"
+        end
+      end
+    end
+  end
+end
+```
+
+Let's style the constraint violations in `app/src/front_end/css/index.css`:
+
+```css
+/* app/src/front_end/css/index.css */
+brut-cv {
+  display: none;
+}
+
+brut-cv[server-side],
+brut-form[submitted-invalid] brut-cv {
+  display: block;
+  color var(--red-300);
+}
+```
+
+Now, you can click on "Login", and you should see a client-side error message.
+
+### Handle Logins
+
+Now, we'll build out the login handler.  An email must exist and be active to be
+allowed in.
+
+```ruby
+# app/src/front_end/handlers/login_handler.rb
+class LoginHandler < AppHandler
+  def initialize(form:, session:, flash:)
+    @form    = form
+    @session = session
+    @flash   = flash
+  end
+
+  def handle
+    if !form.constraint_violations? # no client-side issues
+      account = DB::Account.find(email: form.email, deactivated_at: nil)
+      if !account
+        form.server_side_constraint_violation(
+          input_name: :email,
+          key: :no_such_account
+        )
+      end
+    end
+    if form.constraint_violations?
+      LoginPage.new(form: @form)
+    else
+      session.login!(account:)
+      redirect_to(DashboardPage)
+    end
+  end
+end
+```
+
+Hopefully, this logic is straightforward.  We'll need to allow `AppSession` to
+implement `login!`.  We'll also need to have it fetch the `DB::Account` from the
+session, we'll add that, too.
+
+```ruby
+# app/src/front_end/support/app_session.rb
+class AppSession < Brut::FrontEnd::Session
+  def login!(account:)
+    self[:account_id] = account.id
+  end
+  def account
+    DB::Account.find(id: self[:account_id])
+  end
+end
+```
+
+Now, we can build the dashboard page to greet them.  Instead of injecting the
+session, however, we're going to inject the account as `current_account:`.  We'll
+set this up in a minute.
+
+```ruby
+# app/src/front_end/pages/dashboard_page.rb
+class DashboardPage < AppPage
+  def initialize(current_account:)
+    @current_account = current_account
+  end
+
+  def page_template
+    h1 { "Dashboard" }
+    h2 { "Hello #{@current_account.email}!" }
+  end
+end
+```
+
+### Injecting the Current Account
+
+We want the current account to be in the `Brut::FrontEnd::RequestContext` if the
+visitor is logged in.  We'll do that in a route hook.
+
+First, we'll declare it in `App`:
+
+```ruby
+# app/src/app.rb
+class App < Brut::Framework::App
+
+  # ...
+
+  before :SetupCurrentAccount
+
+  # ...
+end
+```
+
+Now, we can build the `SetupCurrentAccount` route hook.  Since it'll run after
+`Brut::FrontEnd::RouteHooks::SetupRequestContext`, we can assume a `RequestContext`
+will be available for injection. The session will be, too, of course:
+
+```ruby
+# app/src/front_end/hooks/setup_current_account.rb
+class SetupCurrentAccount < Brut::FrontEnd::RouteHook
+  def before(request_context:, session:)
+    logged_in = !!session.account
+    # NOTE: we do not insert nil. Either insert a value or don't insert.
+    if logged_in
+      request_context[:current_account] = session.account
+    end
+  end
+end
+```
+
+At this point, the code we've written should work.  The only problem is that anyone
+can access the Dashboard page. Granted, doing so without being logged in will cause
+an error, but we don't want that.
+
+### Requiring Login
+
+To require login, we'll add to the `SetupCurrentAccount` hook we created. We want to
+allow access to the login page as well as any Brut-owned paths.  If a logged-out
+user access a restricted page, we'll redirect them to the login page.
+
+```ruby
+# app/src/front_end/hooks/setup_current_account.rb
+class SetupCurrentAccount < Brut::FrontEnd::RouteHook
+  def before(request_context:, session:)
+    logged_in = !!session.account
+    if logged_in
+      request_context[:current_account] = session.account
+    end
+
+    is_login_page      = request.path_info.match(/#{Regexp.escape(LoginPage.routing)}/
+    is_brut_owned_path = env["brut.owned_path"]
+
+    path_requires_login = !is_login_page && 
+                          !is_brut_owned_path
+
+    if !logged_in && path_requires_login
+      redirect_to(LoginPage)
+    end
+  end
+end
+```
+
+And that's it!  The visitor should be redirected if they aren't logged in, but
+should be allowed to restricted pages like the dashboard page if they are.
+
+### You Don't Need Page Hooks for This
+
+Implementing something like this in Rails would usually involve similar code to what
+we just did, but pages requiring login would have some sort of `before_action`:
+
+```ruby{2}
+class WidgetsController < ApplicationController
+  before_action :require_login!
+
+  # ...
+end
+```
+
+This could be shared in a parent page, but you essentially have to remember to do this on every page that requires login (or do the opposite - allow specific pages to be accessed without logging in).
+
+In Rails, this is a good practice, because even though your views won't route a
+logged-out visitor to a logged-in page, URL hacking or bugs could result in an
+attempt to do so.  You need the failsafe.
+
+In Brut, the very definition of the page's class includes the requirement for the
+`current_account`. The page cannot be instantiated without it.
+
+Thus, there is no need for a failsafe.  `SetupCurrentAccount` handles checking the
+routes, and that's it.  If someone hacks a URL or a bug in the code sends a
+logged-out visitor to the dashboard page, Brut literally cannot handle the request, since the `current_account` will be missing.

data/brutrb.com/recipes/blank-layouts.md

@@ -0,0 +1,22 @@
+# Blank or No Layout
+
+If you don't want a layout, you are encouraged to create a blank layout, for example:
+
+```ruby
+class BlankLayout < Brut::FrontEnd::Layout
+  def view_template
+    yield
+  end
+end
+
+# use like so:
+
+class NakedPage < AppPage
+  def layout = "blank"
+
+  def page_template
+    # ...
+  end
+end
+```
+

data/brutrb.com/recipes/custom-flash.md

@@ -0,0 +1,51 @@
+# Custom Flash Class
+
+If you want to have a more sophisticated [Flash](/flash-and-session), you can do
+this by overriding Brut's [configuration](/configuration).
+
+## Recipe
+
+First, create your new class in `app/support/app_flash.rb`. You can implement your
+new methods using `[]` and `[]=`.
+
+```ruby
+class AppFlash < Brut::FrontEnd::Flash
+  def debug  =   self[:debug]
+  def debug? = !!self.debug
+
+  def debug=(debug_message)
+    self[:debug] = debug_message
+  end
+end
+```
+
+Now, in `app/src/app.rb`'s initializer, use `Brut.container.override`:
+
+```ruby {6}
+class App < Brut::Framework::App
+  def initialize
+
+    # ...
+
+    Brut.container.override("flash_class",AppFlash)
+  end
+end
+```
+
+Now, any time you inject `flash:` into a component, it'll be an instance of
+`AppFlash`:
+
+```ruby
+class HomePage < AppPage
+  def initialize(flash:)
+    @flash = flash
+  end
+
+  def page_template
+    h1 { "Welcome!" }
+    if @flash.debug?
+      aside { @flash.debug }
+    end
+  end
+end
+```

data/brutrb.com/recipes/indexed-forms.md

@@ -0,0 +1,149 @@
+# Indexed Forms
+
+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.
+
+This recipe will show a form that has more than one set of text fields for the same
+conceptual field.
+
+## Feature
+
+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.
+
+## Recipe
+
+We'll create a form, a handler, and a page to do this.
+
+### Creating a Form with Indexes
+
+First, we'll scaffold the form and handler:
+
+```
+bin/scaffold form /bulk_create_widgets
+```
+
+Next, we'll create the form in `app/src/front_end/forms/bulk_create_widgets_form.rb`
+This will look like a normal form except each field will have `array: true`, to
+indicate there will be an arbitrary number of these fields.  Since they are not all
+going to be required, we'll set `required: false`.
+
+When you specify `array:true`, the method created by `input` accepts an index as an
+argument. For example,  `form.name(3)` would retrieve the fourth name submitted.
+
+We'll also implement the method `each_widget` that will yield each name/quantity
+pair.  The reason Brut doesn't provide this is that your form could have non-array
+values as well, so there is no obvious implementation.
+
+Brut *does* provide an `_each` method for every array field. We can use that to
+iterate over however many values were submitted.
+
+```ruby
+class BulkCreateWidgetsForm < AppForm
+  input :name,                    array: true, required: false
+  input :quantity, type: :number, array: true, required: false,
+                                               min: 1
+
+  def each_widget(&block)
+    name_each do |name, index|
+      block.(name, self.quantity(index), index)
+    end
+  end
+end
+```
+
+### Processing a Form with Array Values
+
+When Brut sends this data to us, each field will be an array of values. We'll see
+how to generate the HTML for that in a moment.  Before that, let's implement the
+handler.
+
+We want to require a name and quantity if either is present.  If not, it's fine.
+When we detect a problem, we'll use the `index:` parameter on
+`server_side_constraint_violation` to indicate which index has the issue.
+
+```ruby
+# app/src/front_end/handlers/bulk_create_widgets_handledr.rb
+class BulkCreateWidgetsHandler < AppHandler
+  def initialize(form:)
+    @form = form
+  end
+
+  def handle
+    @form.each_widget(name, quantity, index)
+      name_blank     = name.to_s.strip == ""
+      quantity_blank = name.to_s.strip == ""
+      if name_blank && quantity_blank
+        # fine
+      elsif !name_blank && !quantity_blank
+        # fine
+      elsif name_blank
+        @form.server_side_constraint_violation(
+          input_name: :name,
+          key: :required_with_quantity,
+          index: index
+        )
+      else
+        @form.server_side_constraint_violation(
+          input_name: :quantity,
+          key: :required_with_name,
+          index: index
+        )
+      end
+    end
+    if @form.constraint_violations?
+      BulkCreateWidgetsPage.new(form: @form)
+    else
+      redirect_to(WidgetsPage)
+    end
+  end
+end
+```
+
+### Generating a Form with Array Values
+
+Whew!  Now, let's see our HTML for the form. Note the use
+of the `index:` parameter when creating the form elements.
+
+```ruby
+# app/src/front_end/pages/bulk_create_widgets_page.rb
+class BulkCreateWidgetsPage < AppPage
+
+  include Brut::FrontEnd::Components
+
+  def initialize(form:)
+    @form = form || BulkCreateWidgetsForm.new
+    @num_widgets = 10
+  end
+
+  def page_template
+    brut_form do
+      FormTag(for: @form) do
+        @num_widgets.each do |index|
+          label do
+            Inputs::TextField(form: @form, input_name: :name, index: index)
+            div { "Name #{index + 1}" }
+            ConstraintViolations(form: @form, input_name: :name, index: index)
+          end
+          label do
+            Inputs::TextField(form: @form, input_name: :quantity, index: index)
+            div { "Quantity for Widget #{index + 1}" }
+            ConstraintViolations(form: @form, input_name: :quantity, index: index)
+          end
+        end
+        button { "Save Widgets }
+      end
+    end
+  end
+end
+```
+
+ Even if the form doesn'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's components (like `TextField`) will use the Rack
+ non-standard HTML for arrays of values. Instead of `name="quantity"`, Brut will
+ render `name="quantity[]"`.
+
+
+