rails_components 0.0.0 → 0.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b85fde4793b42ad98c8b8e90318431f671f31f2a
-  data.tar.gz: 9c2b9254764b6ed2105973680a8259eacc7e1048
+  metadata.gz: 6f8e93ccb73397896fa9905a032a2134c1c0de2c
+  data.tar.gz: af568ee8b46b7e64aec5c6c1491d0984239a3ac8
 SHA512:
-  metadata.gz: 20bc74881d692dc5383758061c89d6cf6905e20f42e20ec9c16e52f057137bf467729be30c40d35e50c3a21d19409f426700de4ff262bcb1e886ae156117751b
-  data.tar.gz: 7aac8b7081ca95612535116dea76506a84d64dac865c94575fc40e8d111bcd443a52bc36624a3a0335237de7f881e938609872d37cf24f873667772d4931023d
+  metadata.gz: 4a407dcd0bd60b1a211966988fbf454eb44ec3fa97e4d435c2ca6b43f3331bc624b6cce1dec52ca43d867cbb7e9a6d69f98e3e0be4f23f5bdeb1acbec80595fb
+  data.tar.gz: a34cbac6e4c88caebcbf49f46defcba19ba7a97ee57a7858d7e5b6ac4c97f9e443b9eed7484f692afbbee2e8d6a3d25ed90c7ba59bedfabb59235ba15d710975

data/README.md

@@ -1,16 +1,17 @@
 # Rails Components
 
-It allows you to write reusable components in your rails views.
+write reusable components in your rails views. a thin wrapper around `render`
+that makes passing blocks, and html attributes to templates simple as pie.
 
 ## Installation
 
-Install the rails components gem by adding it to your Gemfile:
+get the gem
 
 ```rb
 gem 'rails_components'
 ```
 
-Include RailsComponents in your app/helpers/application_helper.rb:
+and make the `component` helper available in your views
 
 ```rb
 module ApplicationHelper
@@ -18,48 +19,245 @@ module ApplicationHelper
 end
 ```
 
+## Usage
 
-## Examples:
+a component is a template
 
-Bootstrap modal, with an ID, in erb:
+```erb
+<!-- app/views/components/_my_cool_component.html.erb -->
+<div class="my-cool-component">Hello!</div>
+```
+
+a component can yield, and you can pass a block to it
+
+```erb
+<!-- app/views/components/_my_cool_component.html.erb -->
+<div class="my-cool-component"><%= yield %></div>
+```
 
 ```erb
-<% content_tag :div, class: ['modal', props[:class]] do %>
-  <div class="modal fade" tabindex="-1" role="dialog">
-    <div class="modal-dialog" role="document">
-      <div class="modal-content">
-        <%= yield %>
-      </div><!-- /.modal-content -->
-    </div><!-- /.modal-dialog -->
-  </div><!-- /.modal -->
+<!-- in a view -->
+<h1>My website!</h1>
+<%= component 'my_cool_component' do %>
+  <p>It's great.</p>
 <% end %>
 ```
 
+or pass it an argument instead of a block, like `link_to` or `content_tag`
+
 ```erb
-<div class="modal-header">
-  <button type="button" class="close" data-dismiss="modal" aria-label="Close"><span aria-hidden="true">&times;</span></button>
-  <h4 class="modal-title"><%= yield %></h4>
+<!-- in a view -->
+<%= component 'my_cool_component', "It's great." %>
+```
+
+they live in `app/views/components` by default.
+
+components have a special method: `props`.  `props` is the same as the
+template's local variables, except it includes reserved words.
+This makes it useful for passing html attributes like `class`.
+
+```erb
+<!-- component -->
+<%= content_tag :div, props do %>
+  <%= yield %>
+<% end %>
+
+<!-- in a view -->
+<%= component 'box', class: "box", data: { foo: 'bar' } do %>
+  <p>my box!</p>
+<% end %>
+```
+
+```html
+<!-- output -->
+<div class="box" data-foo="bar">
+  <p>my box!</p>
 </div>
 ```
 
+`props` has a method called `html` which combines it with additional html attributes:
+
 ```erb
-<div class="modal-body">
+<!-- component -->
+<%= content_tag :div, props.html(class: "box") do %>
   <%= yield %>
+<% end %>
+
+<!-- in a view -->
+<%= component 'box', class: "big" do %>
+  <p>my big box!</p>
+<% end %>
+```
+
+```html
+<!-- output -->
+<div class="big box">
+  <p>my big box!</p>
 </div>
 ```
 
+if you're using haml, it already does this for you, and you can use props directly:
+
+```haml
+/ component
+.box{ props }
+  = yield
+```
+
+
+## Bigger Examples
+
+[Bootstrap modal][bsmodal]:
+
 ```erb
-<div class="modal-footer">
+<!-- in a view -->
+<%= component 'modal', id: "important-message", class: "my-fancy-modal" do %>
+  <%= component 'modal/header', "Cool" %>
+  <%= component 'modal/body' do %>
+    <p>
+      Some important stuff!
+    </p>
+  <% end %>
+  <%= component 'modal/footer' %>
+<% end %>
+```
+
+```erb
+<!-- components -->
+
+<!-- app/views/components/_modal.html.erb -->
+<%= content_tag :div, props.html(class: 'modal fade', tabindex: '-1', role: 'dialog') do %>
+  <div class="modal-dialog" role="document">
+    <div class="modal-content">
+      <%= yield %>
+    </div><!-- /.modal-content -->
+  </div><!-- /.modal-dialog -->
+<% end %>
+
+<!-- app/views/components/modal/_header.html.erb -->
+<%= component 'modal/header_container' do %>
+  <%= component 'close_button', data: { dismiss: "modal" } %>
+  <%= component 'modal/title' do %>
+    <%= yield %>
+  <% end %>
+<% end %>
+
+<!-- app/views/components/modal/_header_container.html.erb -->
+<%= content_tag :div, props.html(class: "modal-header") do %>
+  <%= yield %>
+<% end %>
+
+<!-- app/views/components/modal/_title.html.erb -->
+<%= content_tag props.fetch(:tag, "h4"), props.html(class: "modal-title").except(:tag) do %>
   <%= yield %>
+<% end %>
+
+<!-- app/views/components/_close_button.html.erb -->
+<%= content_tag :button, props.html(type: 'button', class: 'close', :"aria-label" => 'close' ) do %>
+  <span aria-hidden="true">&times;</span>
+<% end %>
+
+<!-- app/views/components/modal/_body.html.erb -->
+<%= content_tag :div, props.html(class: 'modal-body') do %>
+  <%= yield %>
+<% end %>
+
+<!-- app/views/components/modal/_footer.html.erb -->
+<%= component 'modal/footer_container', props do %>
+  <button type="button" class="btn btn-secondary" data-dismiss="modal">Close</button>
+  <%= yield %>
+<% end %>
+
+<!-- app/views/components/modal/_footer_container.html.erb -->
+<%= content_tag :div, props.html(class: "modal-footer") do %>
+  <%= yield %>
+<% end %>
+```
+
+```html
+<!-- output -->
+<div id="important-message" class="my-fancy-modal modal fade" tabindex="-1" role="dialog">
+  <div class="modal-dialog" role="document">
+    <div class="modal-content">
+      <div class="modal-header">
+        <button data-dismiss="modal" type="button" class="close" aria-label="close">
+          <span aria-hidden="true">&times;</span>
+        </button>
+        <h4 class="modal-title">Cool</h1>
+      </div>
+      <div class="modal-body">
+        <p>Some important stuff!</p>
+      </div>
+      <div class="modal-footer">
+        <button type="button" class="btn btn-secondary" data-dismiss="modal">Close</button>
+      </div>
+    </div><!-- /.modal-content -->
+  </div><!-- /.modal-dialog -->
 </div>
 ```
 
+
+[Basscss navigation]
+
+## How this compares to `render`
+
+`component` is a wrapper around `render` [under the hood](./lib/rails_components.rb):
+
+```erb
+<%= component 'modal', title: "Example" do %>
+  Modal content!
+<% end %>
+```
+
 ```erb
-<button type="button" class="btn btn-default" data-dismiss="modal">Close</button>
+<%= render layout: 'component/modal', locals: { title: "Example" } do %>
+  Modal content!
+<% end %>
 ```
 
+Where it shines is taking arguments instead of blocks
+
+```erb
+<%= component 'modal', 'Modal content!', title: "Example" do %>
+```
 
-# Goals
+And allowing you to use reserved words, which doesn't work with render
+
+```erb
+<!-- won't work! rails can't make `class` a local variable -->
+<%= render layout: 'component/modal', locals: { class: "fancy-modal" } do %>
+  Modal content!
+<% end %>
+```
+
+```erb
+<!-- works! -->
+<%= component 'modal', 'Modal content!', class: "fancy-modal" do %>
+```
+
+## What's the future of this project, will it be maintained, etc
+
+Hard to say. If you're worried about dependencies, copy it into your project
+as a helper. I would be surprised if `render` gets any big changes.
+
+This project serves more as documentation and examples of how to write
+components in a rails app (as opposed to adhoc files in `app/views/shared`.)
+
+## Configuration
+
+TODO
+
+## Goals
 
 - make it as easy to write reusable components
-- feel familiar to existing rails helpers, like `link_to` or `content_tag` 
+- feel familiar to existing rails helpers, like `link_to` or `content_tag`
+
+## TODO
+
+- tests
+- test configuration
+- figure out how to make vim-rails jump to files (gf) properly
+- point out that mixing erb and haml has issues
+
+[bsmodal]: http://v4-alpha.getbootstrap.com/components/modal/
+[bspanel]: http://v4-alpha.getbootstrap.com/components/card/

data/lib/rails_components/configuration.rb

@@ -0,0 +1,22 @@
+# https://robots.thoughtbot.com/mygem-configure-block
+module RailsComponents
+  class << self
+    attr_accessor :configuration
+  end
+
+  def self.configuration
+    @configuration ||=  Configuration.new
+  end
+
+  def self.configure
+    yield(configuration) if block_given?
+  end
+
+  class Configuration
+    attr_accessor :template_directory
+
+    def initialize
+      @template_directory = 'components'
+    end
+  end
+end

data/lib/rails_components/html_helpers.rb

@@ -0,0 +1,8 @@
+# meant to be mixed into a hash
+module RailsComponents
+  module HtmlHelpers
+    def html(html_attributes_to_merge = {})
+      merge(html_attributes_to_merge) { |key, v1, v2| [v1, v2].flatten(1) }
+    end
+  end
+end

data/lib/rails_components.rb

@@ -1,14 +1,35 @@
+require 'rails_components/html_helpers'
+require 'rails_components/configuration'
+
 module RailsComponents
   COMPONENT_RESERVED_WORDS = %i(class return super).freeze
 
   def component(component_template, text_or_locals_with_block = nil, locals = nil, &block)
+    unless RailsComponents.configuration.template_directory.nil?
+      component_template = [RailsComponents.configuration.template_directory, component_template].join('/')
+    end
+
     if block_given?
       render({ layout: component_template, locals: component_locals(text_or_locals_with_block) }, &block)
+    elsif text_or_locals_with_block.is_a?(Hash) && locals.nil?
+      render(layout: component_template, locals: component_locals(text_or_locals_with_block)) {}
     else
       render(layout: component_template, locals: component_locals(locals)) { text_or_locals_with_block }
     end
   end
 
+  # references:
+  # - https://github.com/rails/rails/blob/v5.0.0/actionview/lib/action_view/helpers/tag_helper.rb#L104
+  def component_content_tag(props, name, content_or_options_with_block = nil, options = nil, escape = true, &block)
+    if block_given?
+      content_or_options_with_block = props.merge_html(content_or_options_with_block) if content_or_options_with_block.is_a? Hash
+      content_tag(name, content_or_options_with_block, options, escape, &block)
+    else
+      options = props.merge_html(options)
+      content_tag(name, content_or_options_with_block, options, escape, &block)
+    end
+  end
+
   private
 
   # because rails does some weird stuff to make it easy to access the locals in
@@ -20,6 +41,7 @@ module RailsComponents
   # - https://github.com/rails/rails/blob/master/actionview/lib/action_view/template.rb
   def component_locals(locals)
     locals ||= {}
+    locals.extend(HtmlHelpers)
     locals.except(*COMPONENT_RESERVED_WORDS).merge(props: locals)
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_components
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.0.1
 platform: ruby
 authors:
 - Peter Schilling
@@ -20,6 +20,8 @@ files:
 - LICENSE
 - README.md
 - lib/rails_components.rb
+- lib/rails_components/configuration.rb
+- lib/rails_components/html_helpers.rb
 homepage: https://github.com/schpet/rails_components
 licenses:
 - MIT