lotus-helpers 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c456e9b7dddb756479d01c3884c5b05a7f110cad
-  data.tar.gz: 7c9135f6175e001b453b322537b963d6cd4b5c79
+  metadata.gz: 97a8fa23a2691afc98472ad1155025367148d2ca
+  data.tar.gz: 731d5dca8b9da7d4177ca6e8f51c260e88055f53
 SHA512:
-  metadata.gz: a70509dbdb1a17017afe2ba74be5e37408a9cc243bd7593f502f2ddc4e13f73add4502fb2cc86e41a639d65a1ab8f3db154d9536df8d79678e5aa87b60ced121
-  data.tar.gz: f67132c0dbeb0f476998deac8d4b567a1985ae5e3ae0a0bbf4c047957265343b4b5da7f8c55d73e9f8bddd2dd4755fbb96b27aca9d7a463757702a40d8a0b276
+  metadata.gz: 7298684737de0d27f28beaf7d1ba969ee37f0cc7de543c0e81d6063d2b915bf39a12e1794ad7d479956ba6c8854d49b439b4c4cab614ae1e1f959de5fca11c61
+  data.tar.gz: 142c218a581680c85c7d6f207988d787436d85467fdacfd9a0a7d54a29c74d3adb77960fabb5a1f0a18d030f25f26e4bbe2058dda57b184276a89877fc5dca48

data/README.md

@@ -1,29 +1,221 @@
 # Lotus::Helpers
 
-TODO: Write a gem description
+View helpers for Ruby applications
+
+## Status
+
+[![Gem Version](http://img.shields.io/gem/v/lotus-helpers.svg)](https://badge.fury.io/rb/lotus-helpers)
+[![Build Status](http://img.shields.io/travis/lotus/helpers/master.svg)](https://travis-ci.org/lotus/helpers?branch=master)
+[![Coverage](http://img.shields.io/coveralls/lotus/helpers/master.svg)](https://coveralls.io/r/lotus/helpers)
+[![Code Climate](http://img.shields.io/codeclimate/github/lotus/helpers.svg)](https://codeclimate.com/github/lotus/helpers)
+[![Dependencies](http://img.shields.io/gemnasium/lotus/helpers.svg)](https://gemnasium.com/lotus/helpers)
+[![Inline Docs](http://inch-ci.org/github/lotus/helpers.svg)](http://inch-ci.org/github/lotus/helpers)
+
+## Contact
+
+* Home page: http://lotusrb.org
+* Mailing List: http://lotusrb.org/mailing-list
+* API Doc: http://rdoc.info/gems/lotus-helpers
+* Bugs/Issues: https://github.com/lotus/helpers/issues
+* Support: http://stackoverflow.com/questions/tagged/lotus-ruby
+* Chat: https://gitter.im/lotus/chat
+
+## Rubies
+
+__Lotus::Helpers__ supports Ruby (MRI) 2+ and JRuby 1.7 (with 2.0 mode).
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'lotus-helpers'
+```ruby
+gem 'lotus-helpers'
+```
 
 And then execute:
 
-    $ bundle
+```shell
+$ bundle
+```
 
 Or install it yourself as:
 
-    $ gem install lotus-helpers
+```shell
+$ gem install lotus-helpers
+```
 
 ## Usage
 
-TODO: Write usage instructions here
+`Lotus::Helpers` offers a set of utilities to enrich web views.
+
+### HTML helper
+
+HTML5 markup generator (`#html`).
+
+View:
+
+```ruby
+module Users
+  class Show
+    include Lotus::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
+<aside id="sidebar">
+  <p class="title">Languages</p>
+
+  <ul>
+    <li>Italian</li>
+    <li>English</li>
+  </ul>
+</aside>
+```
+
+### Escape helper
+
+HTML (`#h`), HTML attribute (`#ha`) and URL (`#hu`) escape helpers.
+
+View:
+
+```ruby
+module Users
+  class Show
+    include Lotus::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
+
+Lotus and Lotus::Router integration (`#routes`).
+
+View:
+
+```ruby
+module Home
+  class Index
+    include Lotus::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>
+```
+
+## Philosophy
+
+All the Lotus 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 Lotus::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 Lotus::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
+
+__Lotus::Helpers__ uses [Semantic Versioning 2.0.0](http://semver.org)
 
 ## Contributing
 
-1. Fork it ( https://github.com/[my-github-username]/lotus-helpers/fork )
+1. Fork it ( https://github.com/lotus/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-2015 Luca Guidi – Released under MIT License

data/lib/lotus/helpers.rb

@@ -1,7 +1,27 @@
-require "lotus/helpers/version"
+require 'lotus/helpers/version'
+require 'lotus/helpers/html_helper'
+require 'lotus/helpers/escape_helper'
+require 'lotus/helpers/routing_helper'
 
 module Lotus
+  # View helpers for Ruby applications
+  #
+  # @since 0.1.0
   module Helpers
-    # Your code goes here...
+    # Override for Module.included
+    #
+    # It injects all the available helpers.
+    #
+    # @since 0.1.0
+    # @api private
+    #
+    # @see http://www.ruby-doc.org/core/Module.html#method-i-included
+    def self.included(base)
+      base.class_eval do
+        include Lotus::Helpers::HtmlHelper
+        include Lotus::Helpers::EscapeHelper
+        include Lotus::Helpers::RoutingHelper
+      end
+    end
   end
 end

data/lib/lotus/helpers/escape_helper.rb

@@ -0,0 +1,271 @@
+require 'lotus/utils/escape'
+
+module Lotus
+  module Helpers
+    # Escape helpers
+    #
+    # You can include this module inside your view and 
+    # the view will have access all methods.
+    #
+    # By including <tt>Lotus::Helpers::EscapeHelper</tt> it will inject private
+    # methods as markup escape utilities.
+    #
+    # @since 0.1.0
+    module EscapeHelper
+      private
+      # Escape the given HTML tag content.
+      #
+      # This should be used only for untrusted contents: user input.
+      #
+      # This should be used only for tag contents.
+      # To escape tag attributes please use <tt>Lotus::Helpers::EscapeHelper#escape_html_attribute</tt>.
+      #
+      # @param input [String] the input
+      #
+      # @return [String] the escaped string
+      #
+      # @since 0.1.0
+      #
+      # @see Lotus::Helpers::EscapeHelper#escape_html_attribute
+      #
+      # @example Basic usage
+      #   require 'lotus/helpers/escape_helper'
+      #
+      #   class MyView
+      #     include Lotus::Helpers::EscapeHelper
+      #
+      #     def good_content
+      #       h "hello"
+      #     end
+      #
+      #     def evil_content
+      #       h "<script>alert('xss')</script>"
+      #     end
+      #   end
+      #
+      #   view = MyView.new
+      #
+      #   view.good_content
+      #     # => "hello"
+      #
+      #   view.evil_content
+      #     # => "&lt;script&gt;alert(&apos;xss&apos;)&lt;&#x2F;script&gt;"
+      #
+      # @example With HTML builder
+      #   #
+      #   # CONTENTS ARE AUTOMATICALLY ESCAPED
+      #   #
+      #   require 'lotus/helpers'
+      #
+      #   class MyView
+      #     include Lotus::Helpers
+      #
+      #     def evil_content
+      #       html.div do
+      #         "<script>alert('xss')</script>"
+      #       end
+      #     end
+      #   end
+      #
+      #   view = MyView.new
+      #   view.evil_content
+      #     # => "<div>\n&lt;script&gt;alert(&apos;xss&apos;)&lt;&#x2F;script&gt;</div>"
+      def escape_html(input)
+        Utils::Escape.html(input)
+      end
+
+      # @since 0.1.0
+      alias_method :h, :escape_html
+
+      # Escape the given HTML tag attribute.
+      #
+      # This MUST be used for escaping HTML tag attributes.
+      #
+      # This should be used only for untrusted contents: user input.
+      #
+      # This can also be used to escape tag contents, but it's slower.
+      # For this purpose use <tt>Lotus::Helpers::EscapeHelper#escape_html</tt>.
+      #
+      # @param input [String] the input
+      #
+      # @return [String] the escaped string
+      #
+      # @since 0.1.0
+      #
+      # @see Lotus::Helpers::EscapeHelper#escape_html
+      #
+      # @example Basic usage
+      #   require 'lotus/helpers/escape_helper'
+      #
+      #   class MyView
+      #     include Lotus::Helpers::EscapeHelper
+      #
+      #     def good_attribute
+      #       attribute = "small"
+      #
+      #       %(<span class="#{ ha(attribute) }">hello</span>
+      #     end
+      #
+      #     def evil_attribute
+      #       attribute = %(" onclick="javascript:alert('xss')" id=")
+      #
+      #       %(<span class="#{ ha(attribute) }">hello</span>
+      #     end
+      #   end
+      #
+      #   view = MyView.new
+      #
+      #   view.good_attribute
+      #     # => %(<span class="small">hello</span>)
+      #
+      #   view.evil_attribute
+      #     # => %(<span class="&quot;&#x20;onclick&#x3d;&quot;javascript&#x3a;alert&#x28;&#x27;xss&#x27;&#x29;&quot;&#x20;id&#x3d;&quot;">hello</span>
+      #
+      # @example With HTML builder
+      #   #
+      #   # ATTRIBUTES AREN'T AUTOMATICALLY ESCAPED
+      #   #
+      #   require 'lotus/helpers'
+      #
+      #   class MyView
+      #     include Lotus::Helpers
+      #
+      #     def evil_attribute
+      #       user_input_attribute = %(" onclick="javascript:alert('xss')" id=")
+      #
+      #       html.span id: 'greet', class: ha(user_input_attribute) do
+      #         "hello"
+      #       end
+      #     end
+      #   end
+      #
+      #   view = MyView.new
+      #   view.evil_attribute
+      #     # => %(<span class="&quot;&#x20;onclick&#x3d;&quot;javascript&#x3a;alert&#x28;&#x27;xss&#x27;&#x29;&quot;&#x20;id&#x3d;&quot;">hello</span>
+      def escape_html_attribute(input)
+        Utils::Escape.html_attribute(input)
+      end
+
+      # @since 0.1.0
+      alias_method :ha, :escape_html_attribute
+
+      # Escape an URL to be used in HTML attributes
+      #
+      # This allows only URLs with whitelisted schemes to pass the filter.
+      # Everything else is stripped.
+      #
+      # Default schemes are:
+      #
+      #   * http
+      #   * https
+      #   * mailto
+      #
+      # If you want to allow a different set of schemes, you should pass it as
+      # second argument.
+      #
+      # This should be used only for untrusted contents: user input.
+      #
+      # @param input [String] the input
+      # @param schemes [Array<String>] an optional array of whitelisted schemes
+      #
+      # @return [String] the escaped string
+      #
+      # @since 0.1.0
+      #
+      # @see Lotus::Utils::Escape.url
+      # @see Lotus::Utils::Escape::DEFAULT_URL_SCHEMES
+      #
+      # @example Basic usage
+      #   require 'lotus/helpers/escape_helper'
+      #
+      #   class MyView
+      #     include Lotus::Helpers::EscapeHelper
+      #
+      #     def good_url
+      #       url = "http://lotusrb.org"
+      #
+      #       %(<a href="#{ hu(url) }">Lotus</a>
+      #     end
+      #
+      #     def evil_url
+      #       url = "javascript:alert('xss')"
+      #
+      #       %(<a href="#{ hu(url) }">Evil</a>
+      #     end
+      #   end
+      #
+      #   view = MyView.new
+      #
+      #   view.good_url
+      #     # => %(<a href="http://lotusrb.org">Lotus</a>)
+      #
+      #   view.evil_url
+      #     # => %(<a href="">Evil</a>)
+      #
+      # @example Custom schemes
+      #   require 'lotus/helpers/escape_helper'
+      #
+      #   class MyView
+      #     include Lotus::Helpers::EscapeHelper
+      #
+      #     def ftp_link
+      #       schemes = ['ftp', 'ftps']
+      #       url     = 'ftps://ftp.example.org'
+      #
+      #       %(<a href="#{ hu(url, schemes) }">FTP</a>
+      #     end
+      #   end
+      #
+      #   view = MyView.new
+      #
+      #   view.ftp_link
+      #     # => %(<a href="ftps://ftp.example.org">FTP</a>)
+      def escape_url(input, schemes = Utils::Escape::DEFAULT_URL_SCHEMES)
+        Utils::Escape.url(input, schemes)
+      end
+
+      # @since 0.1.0
+      alias_method :hu, :escape_url
+
+      # Bypass escape.
+      #
+      # Please notice that this can be really dangerous.
+      # Use at your own peril.
+      #
+      # @param input [String] the input
+      #
+      # @return [Lotus::Utils::Escape::SafeString] the string marked as safe string
+      #
+      # @since 0.1.0
+      #
+      # @example
+      #   require 'lotus/helpers/escape_helper'
+      #
+      #   class MyView
+      #     include Lotus::Helpers::EscapeHelper
+      #
+      #     def good_content
+      #       raw "<p>hello</p>"
+      #     end
+      #
+      #     def evil_content
+      #       raw "<script>alert('xss')</script>"
+      #     end
+      #   end
+      #
+      #   view = MyView.new
+      #
+      #   view.good_content
+      #     # => "<p>hello</p>"
+      #
+      #   #
+      #   # !!! WE HAVE OPENED OUR APPLICATION TO AN XSS ATTACK !!!
+      #   #
+      #   view.evil_content
+      #     # => "<script>alert('xss')</script>"
+      def raw(input)
+        Utils::Escape::SafeString.new(input)
+      end
+    end
+  end
+end