hanami/guides

Hanami Guides

Hanami 🌸

The web, with simplicity.

Version

This branch contains the code for hanami: 2.2

Frameworks

Hanami is a full-stack Ruby web framework. It's made up of smaller, single-purpose libraries.

This repository is for the full-stack framework, which provides the glue that ties all the parts together:

• Hanami::Router - Rack compatible HTTP router for Ruby
• Hanami::Controller - Full featured, fast and testable actions for Rack
• Hanami::Validations - Parameter validations & coercion for actions
• Hanami::View - Presentation with a separation between views and templates
• Hanami::Assets - Assets management for Ruby

These components are designed to be used independently or together in a Hanami application.

Status

Installation

Hanami supports Ruby (MRI) 3.1+.

gem install hanami

Usage

hanami new bookshelf
cd bookshelf && bundle
bundle exec hanami server # visit http://localhost:2300

Please follow along with the Getting Started guide.

Donations

You can give back to Open Source, by supporting Hanami development via GitHub Sponsors.

Supporters

• Trung Lê
• James Carlson
• Creditas

Contact

• Home page: http://hanamirb.org
• Community: http://hanamirb.org/community
• Guides: https://guides.hanamirb.org
• Snippets: https://snippets.hanamirb.org
• Mailing List: http://hanamirb.org/mailing-list
• API Doc: https://gemdocs.org/gems/hanami/latest
• Bugs/Issues: https://github.com/hanami/hanami/issues
• Stack Overflow: http://stackoverflow.com/questions/tagged/hanami
• Forum: https://discourse.hanamirb.org
• Chat: http://chat.hanamirb.org

Community

We strive for an inclusive and helpful community. We have a Code of Conduct to handle controversial cases. In general, we expect you to be nice with other people. Our hope is for a great software and a great Community.

Contributing

1. Fork it ( https://github.com/hanami/hanami/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

In addition to contributing code, you can help to triage issues. This can include reproducing bug reports, or asking for vital information such as version numbers or reproduction instructions. If you would like to start triaging issues, one easy way to get started is to subscribe to hanami on CodeTriage.

Tests

To run all test suite:

$ bundle exec rake

To run all the unit tests:

$ bundle exec rspec spec/unit

To run all the integration tests:

$ bundle exec rspec spec/integration

To run a single test:

$ bundle exec rspec path/to/spec.rb

Development Requirements

• Ruby >= 3.1
• Bundler
• Node.js (MacOS)

Versioning

Hanami uses Semantic Versioning 2.0.0

Copyright

Copyright © 2014–2024 Hanami Team – Released under MIT License.

guides's Issues

Validation example incomplete

When following the getting started guide to the letter, I am seeing the following error:

Failures:

  1) Add a book displays list of errors when params contains errors
     Failure/Error: expect(page).to have_content('There was a problem with your submission')
       expected to find text "There was a problem with your submission" in "Bookshelf"
     # ./spec/web/features/add_book_spec.rb:16:in `block (2 levels) in <top (required)>'

Finished in 0.12875 seconds (files took 1.55 seconds to load)
18 examples, 1 failure

Failed examples:

rspec ./spec/web/features/add_book_spec.rb:7 # Add a book displays list of errors when params contains errors

Adding the validation code below not only to apps/web/templates/books/new.html.erb but also to apps/web/templates/books/create.html.erb allows the tests to pass.

<% unless params.valid? %>
    <div class="errors">
        <h3>There was a problem with your submission</h3>
        <ul>
            <% params.error_messages.each do |message| %>
                <li><%= message %></li>
            <% end %>
        </ul>
    </div>
<% end %>

I imagine that there isn't meant to be this kind of duplication in the guide, or in

I'd be happy to contribute a pull request, but I don't know if this is a defect of the tests or the instructions for the templates.

Wrong number of aarguments issue

Hi All, am using hanami 1.3.1 and ruby version is 2.3.0. when i am trying to create new application it shows "wrong number of arguments (given 0, expected 2..3)" error.

Helpers: form helpers

Views: actions integration

Assets: customization

Views: parts

NET::ERR_CERT_COMMON_NAME_INVALID on guides.hanamirb.org

Helpers: custom helpers

Left-aligned content looks better then justified

`rhtml` highlighting is broken

It appears that the rhtml language is broken or missing for the code formatter. erb is also missing, and while html gives some odd highlighting on ERB tags it does still render a code box:

link_to helpers and concat

The guide indicates that link_to helpers do not need to be concated:

html.div do
  link_to 'Users', routes.users_path, class: 'btn'
  hr
  link_to 'Books', routes.books_path, class: 'btn'
end

However, in practice, only the last link renders. Upon some digging, apparently they need to be concated:

https://github.com/hanami/helpers/blob/9acd2bf17bc2e5579cdd91f8d0f88129367cb420/spec/support/fixtures.rb#L715

I'm going to assume that the code is correct and the guide needs updating?

Helpers: overview

• Use in templates
• Use in custom scopes
• Use in custom parts

2.0.0 Upgrade Notes not found

First, thank you for all of the hard work getting 2.0 out the door, I appreciate it!

From https://guides.hanamirb.org/ the link to the 2.0.0 upgrade notes is not found: https://guides.hanamirb.org/upgrade-notes/v200

We'll likely look to upgrade at some point in the future, and an upgrade guide would be immensely helpful.

Documentation Sidebar/Visibility of Links

1. Visibility of Links: It's really hard to read documentation links due to their light color (at least for me). Can you please review attached suggestion and change accordingly? I think it will help everyone.
2. Sidebar: When clicking on the sidebar section headings, they don't seem to close if you re-click on them. See attached GIF.

Issue 1

Issue 2

Helpers: assets helpers

Section for Headless browser testing

Headless browser testing requires a few changes to ensure that the real server that the browser will connect do is booted in the correct Hanami environment.

Referenced from hanami/hanami#1062

Views: scopes

Views: configuration

Views: context

Views: overview

Strange navbar behaviour in mobile view

What?

It's imposible to close navbar in mobile guides.

Why important?

It's really strange behaviour. I think it can be bad and off-puttingly for our users.

How to reproduce?

1. Open guides on mobile.
2. Click hamburger for getting all links
3. Try to click x for closing it
4. Profit

Add guidance on how to test when cookies and sessions are enabled

While reading through the Actions: Sessions section, I miss guidance on how to properly test this. I did find an article that describes using rack.session as a param, but it'd be great to have an official way to test in controllers when optional functionality like sessions and cookies are enabled.

Helpers: testing

Understanding code examples in 'custom predicates'

i'm trying to understand the meaning of the last three code blocks at this location:
https://github.com/hanami/guides/blob/master/content/validations/custom-predicates.md#internationalization-i18n

how do they fit into the context of 'custom predicates'?

Helpers: tag helpers

Expand Getting Started guide

Here's some feedback collected from @aeden

I think the getting started doc could be expanded to include the rest of the CRUD operations. I had to dig around a bit to figure out how to properly build the delete and update operations. The update operation could include a demonstration of moving form generation into the view classes (which, btw, is pretty awesome). It would also demonstrate how to override the default form method (using PATCH instead of the default POST). Finally, the delete would show how a form could be used for the delete button (unless there's a better way) and reinforce how to override the default form method
it would also help demonstrate the need to continue updating the route that was refactored into a resource. because by default the new route will be appended to the routes file, and it will not work automatically.

Views: input and exposures

Text a little hard to read in certain classes with background colors

The new Guides are beautiful. I do have a problem reading text in notice and convention classes. It's more readable if the font-weight is higher and/or the background color is darker.

DatabaseCleaner setup doesn't work with SQLite

When following persistence setup with ROM in the getting started guide, the database cleaner setup shown doesn't automatically work with SQLite. I know the guides are showing instructions for Postgres, but for simplicity I wanted to use SQLite, and it would be great if everything still worked 👌🏻

Concretely, I have the database URL set to sqlite://db/test.sqlite3 in tests, and I'm getting the following error:

DatabaseCleaner::Safeguard::Error::RemoteDatabaseUrl:
  ENV['DATABASE_URL'] is set to a remote URL. Please refer to https://github.com/DatabaseCleaner/database_cleaner#safeguards

It appears that DatabaseCleaner is falsely detecting the SQLite database URL as "remote", because it doesn't see any localhost or 127.0.0.1, even though it's in fact local.

Views: templates and partials

Mention `routes` helper for actions

I noticed in an action I can write:

routes.url(:account, id: account.address)

The Routing guide seems to only show the Hanami.app["routes"] way of doing things instead.

`SSL_ERROR_BAD_CERT_DOMAIN` when trying to access

Overview

When trying to access https://guides.hanamirb.org/ as of 2023-07-02 11:06am PST, I currently run into an SSL_ERROR_BAD_CERT_DOMAIN error in Firefox.

Screenshot

Helpers: escape helpers

Create a section "how to use hanami in production"

After 1to1 with @jodosha I learn that hanami s command is only for development and for production is better to use puma .... I think we have more than one tip for hanami in production that's why I suggest to create a separate area in guides and call it Hanami in production or something like this.

Update getting started guide for views

Assets: using your own bundler

• Bundler should match the format and location of our manifest.json
• Update "assets" script in package.json to call that bundler. It needs to respect the flags we currently send to ours, which is --sri and --watch (and it should compile and exit when --watch is not given).

Side navigation not accessible on mobile

Overview

When browsing hanami guides on mobile, the side navigation is not accessible in any way.

Helpers: number helpers

Actions: rendering views

Views: helpers

Assets: overview

Views: HTML escaping

Force Hugo version for Netlify

Hugo seems to move fairly quickly and occasionally breaks backwards compatibility.

The version of Hugo we're using to build the site on Netlify and locally is ambiguous. If you're using Homebrew locally it's likely the most recent release of Hugo, but Netlify uses the first version the site was ever built with.

We should define the version in the README and in a Netlify configuration file to be consistent.

Fix incorrect guidance for optional parameters

Consistently throughout the Guides, e.g., in the Usage section of the Actions : Parameters docs, the examples for defining an optional param actually require it. This is due to the use of filled in the parameter-validation definition.

Consider this example extracted from my own code that exercises the same problem. The intent of the optional(:profile) rule is to define an optional param that, if filled, must be a string and must have a maximum size of 8K:

      class CreateParams < Hanami::Action::Params
        predicates ConversagencePredicates # defines `:email?`

        validations do
          required(:user).schema do
            required(:name).filled(:str?, size?: 3..64)
            required(:email).filled(:email?)
            optional(:profile).filled(:str?, max_size?: 8192)
          end
        end
      end

Attempting to validate parameters that include an empty string for profile produce the errors "Profile must be filled" and "Profile size cannot be greater than 8192".

Digging into the Hanami::Validations GitHub README docs provided the answer. When I change my CreateParams class to

      class CreateParams < Hanami::Action::Params
        predicates ConversagencePredicates

        validations do
          required(:user).schema do
            required(:name).filled(:str?, size?: 3..64)
            required(:email).filled(:email?)
            optional(:profile).maybe(:str?, max_size?: 8192)
          end
        end
      end

the empty profile parameter is properly not flagged as invalid. The change, for those bleary-eyed after too many hours staring at the screen, is changing the filled to maybe. With that change, supplying nil is accepted (and coerced to an empty string), but supplying a non-nil, non-String parameter for profile, such as a Symbol, produces error messages and a failed validation.

As I said at the beginning, this appears to be fairly consistent mis-guidance throughout the Guides.

Broken link on learning how to write ROMRb queries.

I found a broken link at https://guides.hanamirb.org/repositories/overview/
in "Learn more on how to craft queries with ROM and Sequel."
It lead to http://rom-rb.org/current/learn/sql/queries/ which returns 404.
It seems like /current doesn't have a link to that section or at least it doesn't have that shape.

https://rom-rb.org/5.0/learn/sql/queries/ works but it's a specific version (the latest at the moment)

If you agree, I can submit a pull request changing it to that url for the 5.0 version.

Hope it helps.

Algolia search returns results for version 1.3

When I'm viewing guides for version 2.0 and I type into the search bar, Algolia returns search results from version 1.3. I would expect search results to be constrained to the currently specified Hanami version.

Concept for Guides 2.0

Overview

The guides for Hanami 1.3 become obsolete, so we should design the new version of the guides. However, we should also keep existing documentation working.

Here is the issue to track this update, with a list of what can be done.

When deciding on this, we can asynchronously work on smaller chapters, adapting existing guides when it makes sense, and rewriting it completely when that approach applies.

Todo

• Move the existing guides to content/1.0 folder
• Redirect all exisitng routes to 1.0
• Create a content/2.0 folder
• Update the sidebar to work with multiple nesting levels.
• Come with a raw structure of chapters for new guides (to be tweaked later)

The concept of documents structure

2.0
|_ GETTING STARTED
   |_ Guide assumptions. # What needs to be learnt before getting to this
   |_ What is Hanami?      # General concept, Philosophy, why it's special? (refer architecture overview)
   |_ Hello, Hanami           # Creating and running minimal working application
   |_ Quick Blog application # Listing and showing blog posts
   |_ Security                    # Basic authentication mechanisms.

|_ ARCHITECTURE
   |_ Overview     # List all the building blocks, show a diagram with data flow, link to more detailed sections.

|_ ROUTER
  |_ Overview
  |_ Basic Usage
  |_ ...
  |_ Testing
|_ ACTIONS
  |_ Overview
  |_ Basic Usage
  |_ ....
  |_ Testing
|_ VIEWS
  |_ Overview
  |_ Basic Usage
  |_ Layouts
  |_ Templates
  |_ Parts
  |_ ....
  |_ Testing
|_ Validations
  |_ Overview
  |_ Basic Usage
  |_ ....
  |_ Testing
|_ Persistance
  |_ Overview
  |_ Relations
  |_ Repositories
  |_ Structs
  |_ ...
  |_ Testing
|_ Slices
  |_ Overview
  |_ Basic Usage
  |_ ....
  |_ Testing
|_ Assets
  |_ Overview
  |_ Basic Usage
  |_ ....
  |_ Testing
|_ Utils
  |_ Overview
  |_ Basic Usage
  |_ ....
  |_ Testing
|_ Helpers
  |_ Overview
  |_ Basic Usage
  |_ ....
  |_ Testing
|_ Mailers
  |_ Overview
  |_ Basic Usage
  |_ ....
  |_ Testing
|_ Command Line
  |_ Overview
  |_ Basic Usage
  |_ ....
  |_ Testing
|_ Scaling UP
  |_ Manageable monolith
  |_ Splitting application into microservices
|_ Upgrade Notes

Views: testing

Assets: using a CDN

Views: alternative engines