hanami-helpers 0.0.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c7c166ba28d9d65bfa9fab4325f0cfd2529f6aa9
-  data.tar.gz: 37899e63412cc17a329506ef85606df67f80210a
+  metadata.gz: 00c50648c23a0d34befe080287206beb9e46aa34
+  data.tar.gz: 2be73f77dead23bc48142b567b0a2595d9ba6a00
 SHA512:
-  metadata.gz: d4536ae052bec8721bcdf14173ba55fe1967cd05a20edbaf5e43377feaa66eb3233840e93c665ea66caf9236c0a1039b811c9b5b3a87765379acdbab54769e9d
-  data.tar.gz: 02b9b40ba70a5eb29a5a0fca353ffc90f356bbcf815582a53abfd0be53f4154d52c9584c6e1256d15883b960339553c045d0c940dfcb43522cff386a700bec1c
+  metadata.gz: ce6e712b2a0e0aaf38e79a682112a51929ec62fb77cc2f2af17c0645fddc28d56654e0c0b8dd4acf4c707c502ea7cc6dc19870e1ed7ca027304755d90dde9826
+  data.tar.gz: 75c87873818c331507ce01574fbd5652a9be6f8e782805e4f731377f37e81429578384cc9dde5b7a1f521d6c0473ab4e6f4057ff9593fcee49bf68bdd9f6d419

data/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Hanami::Helpers
+View helpers for Ruby web applications
+
+## v0.3.0 - 2016-01-22
+### Changed
+- [Luca Guidi] Renamed the project
+
+## v0.2.6 - 2016-01-12
+### Added
+- [Cam Huynh] Added support for HTML helper (`#html`) block syntax (eg. `html { div('hello') }`)
+- [Shin-ichi Ueda] Added support for `<dd>` HTML tag
+
+### Fixed
+- [Rodrigo Panachi] Don't generate CSRF token hidden input for forms with `GET` method
+
+## v0.2.5 - 2015-09-30
+### Added
+- [Leonardo Saraiva] Improved support for HTML content in `#link_to` helper. It now accepts blocks to build markup inside an anchor tag.
+- [José Mota] Added `#text` to the form builder
+- [Alex Wochna] Added `#number_field` to the form builder
+- [Scott Le] Added `#text_area` to the form builder
+
+### Fixed
+- [Pascal Betz] Ensure boolean attributes in HTML forms to not be printed if their value is `nil` (eg. avoid to print `disabled=""`).
+
+### Changed
+- [Luca Guidi] Form `#label` helper outputs capitalized strings, instead of titleized (eg. `"Remember me"` instead of `"Remember Me"`).
+
+## v0.2.0 - 2015-06-23
+### Added
+- [Luca Guidi] Introduced `Lotus::Helpers::FormHelper`. HTML5 form generator (`#form_for`).
+- [Tom Kadwill & Luca Guidi] Introduced `Lotus::Helpers::NumberFormattingHelper`. Format numbers (`#format_number`).
+- [Tom Kadwill] Introduced `Lotus::Helpers::LinkToHelper`. Link helper (`#link_to`).
+
+## v0.1.0 - 2015-03-23
+### Added
+- [Luca Guidi] Introduced `Lotus::Helpers::RoutingHelper`. It exposes `#routes` in views for compatibility with Lotus (`hanamirb` gem)
+- [Alfonso Uceda Pompa] Introduced `Lotus::Helpers::EscapeHelper`. It implements OWASP/ESAPI suggestions for HTML, HTML attribute and URL escape helpers.
+- [Luca Guidi] Introduced `Lotus::Helpers::HtmlHelper`. It allows to generate complex HTML5 markup with Ruby.

data/LICENSE.md

@@ -0,0 +1,22 @@
+Copyright (c) 2014-2016 Luca Guidi
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,8 +1,28 @@
 # Hanami::Helpers
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/hanami/helpers`. To experiment with that code, run `bin/console` for an interactive prompt.
+View helpers for Ruby applications
 
-TODO: Delete this and the text above, and describe your gem
+## Status
+
+[![Gem Version](http://img.shields.io/gem/v/hanami-helpers.svg)](https://badge.fury.io/rb/hanami-helpers)
+[![Build Status](http://img.shields.io/travis/hanami/helpers/master.svg)](https://travis-ci.org/hanami/helpers?branch=master)
+[![Coverage](http://img.shields.io/coveralls/hanami/helpers/master.svg)](https://coveralls.io/r/hanami/helpers)
+[![Code Climate](http://img.shields.io/codeclimate/github/hanami/helpers.svg)](https://codeclimate.com/github/hanami/helpers)
+[![Dependencies](http://img.shields.io/gemnasium/hanami/helpers.svg)](https://gemnasium.com/hanami/helpers)
+[![Inline Docs](http://inch-ci.org/github/hanami/helpers.svg)](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) 2.2+
 
 ## Installation
 
@@ -14,23 +34,356 @@ gem 'hanami-helpers'
 
 And then execute:
 
-    $ bundle
+```shell
+$ bundle
+```
 
 Or install it yourself as:
 
-    $ gem install hanami-helpers
+```shell
+$ gem install hanami-helpers
+```
 
 ## Usage
 
-TODO: Write usage instructions here
+`Hanami::Helpers` offers a set of utilities to enrich web views.
+
+### HTML helper
+
+HTML5 markup generator (`#html`).
 
-## Development
+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 %>
+```
 
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+Output:
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+```html
+<aside id="sidebar">
+  <p class="title">Languages</p>
+
+  <ul>
+    <li>Italian</li>
+    <li>English</li>
+  </ul>
+</aside>
+```
+
+### 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
+<form action="/books" method="POST" accept-charset="utf-8" id="book-form">
+  <input type="text" name="book[title]" id="book-id" value="">
+  <button type="submit">Create</button>
+</form>
+```
+
+#### 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
+<form action="/books" method="POST" accept-charset="utf-8" id="book-form">
+  <input type="text" name="book[title]" id="book-id" value="">
+  <button type="submit">Create</button>
+</form>
+```
+
+#### 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
+<form action="/books" method="POST" accept-charset="utf-8" id="book-form">
+  <input type="text" name="book[title]" id="book-id" value="">
+  <button type="submit">Create</button>
+</form>
+```
+
+Output for edit:
+
+```html
+<form action="/books/23" method="POST" accept-charset="utf-8" id="book-form">
+  <input type="hidden" name="_method" value="PATCH">
+  <input type="text" name="book[title]" id="book-id" value="TDD">
+  <button type="submit">Update</button>
+</form>
+```
+
+### 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
+      %(<a href="#{ hu(user.home_page_url) }" title="#{ ha(user.name} }'s website">#{ h(user.website_name) }</a>)
+    end
+
+    def code_snippet
+      raw user.code_snippet
+    end
+  end
+end
+```
+
+Template:
+
+```erb
+<%= home_page_link %>
+<%= code_snippet %>
+```
+
+Output:
+
+```html
+<a href="https://example.org" title="Maria's website">My Blog</a>
+<code>puts "Hello, World!"</code>
+```
+
+### Routing Helper
+
+Hanami and Hanami::Router integration (`#routes`).
+
+View:
+
+```ruby
+module Home
+  class Index
+    include Hanami::Helpers
+
+    def link_to_home
+      %(<a href="#{ routes.home_path }">Home</a>)
+    end
+  end
+end
+```
+
+Template:
+
+```erb
+<%= link_to_home %>
+```
+
+Output:
+
+```html
+<a href="/">Home</a>
+```
+
+### 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
+<p><%= visitors_count %></p>
+```
+
+Output:
+
+```html
+<p>1,000</p>
+```
+
+## 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
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/hanami-helpers.
+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-2016 Luca Guidi – Released under MIT License
 
+This project was formerly known as Lotus (`lotus-helpers`).