https://github.com/hanami/helpers
View helpers for Ruby applications
https://github.com/hanami/helpers
Last synced: 10 months ago
JSON representation
View helpers for Ruby applications
- Host: GitHub
- URL: https://github.com/hanami/helpers
- Owner: hanami
- License: mit
- Created: 2014-05-13T16:26:00.000Z (almost 12 years ago)
- Default Branch: main
- Last Pushed: 2024-11-06T13:00:22.000Z (over 1 year ago)
- Last Synced: 2025-06-10T23:33:59.557Z (11 months ago)
- Language: Ruby
- Homepage: http://hanamirb.org
- Size: 667 KB
- Stars: 77
- Watchers: 19
- Forks: 50
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Hanami::Helpers
View helpers for Ruby applications
## Status
[](https://badge.fury.io/rb/hanami-helpers)
[](https://github.com/hanami/helpers/actions?query=workflow%3Aci+branch%3Amain)
[](https://codecov.io/gh/hanami/helpers)
[](https://depfu.com/github/hanami/helpers?project=Bundler)
[](http://inch-ci.org/github/hanami/helpers)
## Contact
* Home page: http://hanamirb.org
* Mailing List: http://hanamirb.org/mailing-list
* API Doc: http://rdoc.info/gems/hanami-helpers
* Bugs/Issues: https://github.com/hanami/helpers/issues
* Support: http://stackoverflow.com/questions/tagged/hanami
* Chat: https//chat.hanamirb.org
## Rubies
__Hanami::Helpers__ supports Ruby (MRI) 3.0+
## Installation
Add this line to your application's Gemfile:
```ruby
gem 'hanami-helpers'
```
And then execute:
```shell
$ bundle
```
Or install it yourself as:
```shell
$ gem install hanami-helpers
```
## Usage
`Hanami::Helpers` offers a set of utilities to enrich web views.
### HTML helper
HTML5 markup generator (`#html`).
View:
```ruby
module Users
class Show
include Hanami::Helpers
def sidebar
html.aside(id: 'sidebar') do
p "Languages", class: 'title'
ul do
li "Italian"
li "English"
end
end
end
end
end
```
Template:
```erb
<%= sidebar %>
```
Output:
```html
Languages
- Italian
- English
```
### Form Helper
Form generator for HTML5 (`#form_for`)
#### Template Usage
Template:
```erb
<%=
form_for :book, routes.books_path do
text_field :title
submit 'Create'
end
%>
```
Output:
```html
Create
```
#### View Usage
View:
```ruby
module Books
class New
include Hanami::Helpers
def form
form_for :book, routes.books_path do
text_field :title
submit 'Create'
end
end
end
end
```
Template:
```erb
<%= form %>
```
Output:
```html
Create
```
#### Reuse Code
Views:
```ruby
module Books
class New
include Hanami::Helpers
def form
Form.new(:book, routes.books_path)
end
def submit_label
'Create'
end
end
class Edit
include Hanami::Helpers
def form
Form.new(:book, routes.book_path(id: book.id), {book: book}, {method: :patch})
end
def submit_label
'Update'
end
end
end
```
Templates:
```erb
# books/new.html.erb
<%= render partial: 'books/form' %>
```
```erb
# books/edit.html.erb
<%= render partial: 'books/form' %>
```
```erb
# books/_form.html.erb
<%=
form_for form, class: 'form-horizontal' do
text_field :title
submit submit_label
end
%>
```
Output for new:
```html
Create
```
Output for edit:
```html
Update
```
### Escape helper
HTML (`#h`), HTML attribute (`#ha`) and URL (`#hu`) escape helpers.
View:
```ruby
module Users
class Show
include Hanami::Helpers
def home_page_link
%(#{ h(user.website_name) })
end
def code_snippet
raw user.code_snippet
end
end
end
```
Template:
```erb
<%= home_page_link %>
<%= code_snippet %>
```
Output:
```html
My Blog
puts "Hello, World!"
```
### Routing Helper
Hanami and Hanami::Router integration (`#routes`).
View:
```ruby
module Home
class Index
include Hanami::Helpers
def link_to_home
%(Home)
end
end
end
```
Template:
```erb
<%= link_to_home %>
```
Output:
```html
Home
```
### Number Formatting Helper
Format numbers (`#format_number`).
View:
```ruby
module Home
class Index
include Hanami::Helpers
def visitors_count
format_number '1000'
end
end
end
```
Template:
```erb
<%= visitors_count %>
```
Output:
```html
1,000
```
## Philosophy
All the Hanami helpers are modules to include.
Most of the time they inject **private** methods.
This restriction prevents helper methods to be used on the outside (eg. in a template).
We want to encourage developers to use **meaningful** and **simple APIs** in their templates.
### Bad style example
```ruby
module Users
class Show
include Hanami::Helpers
end
end
```
```erb
<%= format_number user.followers_count %>
```
This style increases the complexity of the template and it makes testing hard.
### Good style example
```ruby
module Users
class Show
include Hanami::Helpers
def followers_count
format_number user.followers_count
end
end
end
```
```erb
<%= followers_count %>
```
This simplifies the markup.
In order to test the value that will be printed becomes easier: `Users::Show#followers_count`.
## Versioning
__Hanami::Helpers__ uses [Semantic Versioning 2.0.0](http://semver.org)
## Contributing
1. Fork it ( https://github.com/hanami/helpers/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
## Copyright
Copyright © 2014-2021 Luca Guidi – Released under MIT License
This project was formerly known as Lotus (`lotus-helpers`).