rails_components 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6f8e93ccb73397896fa9905a032a2134c1c0de2c
-  data.tar.gz: af568ee8b46b7e64aec5c6c1491d0984239a3ac8
+  metadata.gz: 2a9892e6e453a2e8871728debfebfe8fa39bdc7c
+  data.tar.gz: 862da46086c74bec8e0f25f36df89d07eb4dfb8c
 SHA512:
-  metadata.gz: 4a407dcd0bd60b1a211966988fbf454eb44ec3fa97e4d435c2ca6b43f3331bc624b6cce1dec52ca43d867cbb7e9a6d69f98e3e0be4f23f5bdeb1acbec80595fb
-  data.tar.gz: a34cbac6e4c88caebcbf49f46defcba19ba7a97ee57a7858d7e5b6ac4c97f9e443b9eed7484f692afbbee2e8d6a3d25ed90c7ba59bedfabb59235ba15d710975
+  metadata.gz: 904185c83aa85ffc5557522e408ed079d1e0dbcbfdf9f94ffd0cfc3db9eaf4dd28b3813c7012ce19dd3ffba497fad19d5099cfcbb1ed075d217380746c54b345
+  data.tar.gz: 2aeed2b147ba742e5109163bc553d347624b520b21b121b1b32472fcde58b4e60f868ab412d7cbbb75b5d4b5cc30a801aa9b77047a4dcb904ded275469cd5011

data/README.md

@@ -1,7 +1,7 @@
 # Rails Components
 
 write reusable components in your rails views. a thin wrapper around `render`
-that makes passing blocks, and html attributes to templates simple as pie.
+that makes passing blocks and html attributes to partials simple as pie.
 
 ## Installation
 
@@ -104,10 +104,34 @@ if you're using haml, it already does this for you, and you can use props direct
   = yield
 ```
 
+by default `html` combines the classes and html attributes, but you can pass
+it a special key: `html_merge_strategy`, with one of these values:
+- `:combine` - (default) values on duplicated keys are combined in an array
+- `:merge` - normal ruby merge, duplicate keys are overriden by props' values
+- `:replace` - only the attributes passed in by props are used
+
+```
+<!-- component -->
+<%= content_tag :div, props.html(class: "box") do %>
+  <%= yield %>
+<% end %>
+
+<!-- in a view -->
+<%= component 'box', class: "big rectangle", html_merge_strategy: :merge do %>
+  <p>not a box!</p>
+<% end %>
+```
+
+```html
+<!-- output -->
+<div class="big rectangle">
+  <p>not a box!</p>
+</div>
+```
 
 ## Bigger Examples
 
-[Bootstrap modal][bsmodal]:
+### [Bootstrap modal](http://v4-alpha.getbootstrap.com/components/modal/)
 
 ```erb
 <!-- in a view -->
@@ -120,10 +144,8 @@ if you're using haml, it already does this for you, and you can use props direct
   <% end %>
   <%= component 'modal/footer' %>
 <% end %>
-```
 
-```erb
-<!-- components -->
+<!-- the components -->
 
 <!-- app/views/components/_modal.html.erb -->
 <%= content_tag :div, props.html(class: 'modal fade', tabindex: '-1', role: 'dialog') do %>
@@ -197,11 +219,110 @@ if you're using haml, it already does this for you, and you can use props direct
 ```
 
 
-[Basscss navigation]
+### A navbar, based off of the [basscss guide](http://www.basscss.com/v7/docs/guides/ui/#navbars)
+
+```
+<!-- in a view -->
+<%= component 'navbar', class: "white bg-green" do %>
+  <div class="left">
+    <%= component 'navbar/item', "Burgers", href: "#!" %>
+    <%= component 'navbar/item', "An example", href: "#!", class: "btn-narrow" %>
+  </div>
+  <div class="right">
+    <%= component 'navbar/item', "My Account", href: "#!" %>
+  </div>
+  <div class="overflow-hidden px2 py1">
+    <%= component 'input', name: "whatever", class: "right m0 fit bg-darken-1", placeholder: "Search" %>
+  </div>
+<% end %>
+```
+
+```erb
+<!-- app/views/components/_navbar.html.erb -->
+<%= content_tag :div, props.html(class: "clearfix mb2") do %>
+  <%= yield %>
+<% end %>
+
+<!-- app/views/components/navbar/_item.html.erb -->
+<%= link_to href, props.html(class: "btn m0 py2") do %>
+  <%= yield %>
+<% end %>
+
+<!-- app/views/components/_input.html.erb -->
+<%= text_field_tag local_assigns[:name], local_assigns[:value], props.html(class: "input border-box").except(:name, :value) %>
+```
+
+### Tachyons [image with title and subtitle](http://tachyons.io/components/collections/square-title-subtitle/index.html)
+
+```
+<%= component "square", 'Title of piece',
+    subtitle: "Subtitle of piece", image_url: "http://mrmrs.io/images/0008.jpg" %>
+```
+
+```erb
+<!-- component -->
+<article class="fl w-100 w-50-m  w-25-ns pa2-ns">
+  <div class="aspect-ratio aspect-ratio--1x1">
+    <img style="background-image:url(<%= j image_url %>);"
+         class="db bg-center cover aspect-ratio--object" />
+  </div>
+  <%= link_to url, class: "ph2 ph0-ns pb3 link db" do %>
+    <h3 class="f5 f4-ns mb0 black-90"><%= yield %></h3>
+    <h3 class="f6 f5 fw4 mt2 black-60"><%= subtitle %></h3>
+  <% end %>
+</article>
+```
+
+You might find later that you need to reuse and change specific parts of this
+component, or use it with it's contents in a different order.
+You can split it up into many small components as needed, without having to
+change the original way your component is used:
+
+```erb
+<!-- component -->
+<%= component 'square/container' do %>
+  <%= component 'square/image_container' do %>
+    <%= component 'square/image', props.slice(:image_url) %>
+  <% end %>
+  <%= component 'square/link', props.slice(:url) do %>
+    <%= component 'square/title' do %><%= yield %><% end %>
+    <%= component 'square/subtitle', subtitle %>
+  <% end %>
+<% end %>
+
+<!-- app/views/components/square/_container.html.erb -->
+<%= content_tag :article, props.html(class: "fl w-100 w-50-m w-25-ns pa2-ns") do %>
+  <%= yield %>
+<% end %>
+
+<!-- app/views/components/square/_image.html.erb -->
+<%= image_tag '', props.html(style: "background-image:url(#{j image_url});",
+                             class: "db bg-center cover aspect-ratio--object") %>
+
+<!-- app/views/components/square/_image_container.html.erb -->
+<%= content_tag :div, props.html(class: "aspect-ratio aspect-ratio--1x1") do %>
+  <%= yield %>
+<% end %>
+
+<!-- app/views/components/square/_link.html.erb -->
+<%= link_to props[:url], props.html(class: "ph2 ph0-ns pb3 link db").except(:url) do %>
+  <%= yield %>
+<% end %>
+
+<!-- app/views/components/square/_subtitle.html.erb -->
+<%= content_tag props.fetch(:tag_name, :h3), props.html(class: "f6 f5 fw4 mt2 black-60").except(:tag_name) do %>
+  <%= yield %>
+<% end %>
+
+<!-- app/views/components/square/_title.html.erb -->
+<%= content_tag props.fetch(:tag_name, :h3), props.html(class: "f5 f4-ns mb0 black-90").except(:tag_name) do %>
+  <%= yield %>
+<% end %>
+```
 
 ## How this compares to `render`
 
-`component` is a wrapper around `render` [under the hood](./lib/rails_components.rb):
+`component` [is a wrapper](./lib/rails_components.rb) around `render`
 
 ```erb
 <%= component 'modal', title: "Example" do %>
@@ -209,48 +330,68 @@ if you're using haml, it already does this for you, and you can use props direct
 <% end %>
 ```
 
+is equivalent to:
+
 ```erb
 <%= render layout: 'component/modal', locals: { title: "Example" } do %>
   Modal content!
 <% end %>
 ```
 
-Where it shines is taking arguments instead of blocks
+where it shines is taking arguments instead of blocks
 
 ```erb
 <%= component 'modal', 'Modal content!', title: "Example" do %>
 ```
 
-And allowing you to use reserved words, which doesn't work with render
+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 -->
+<!-- won't work! rails tries to 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
+## Motivation
 
-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.
+Working on rails apps where the same css class declarations were repeated
+many times over, making changing common components very difficult. This
+abstraction is particularily helpful when using functional/atomic/utility css
+classes.
+
+From the [basscss docs](http://www.basscss.com/v7/docs/guides/tips/#handle-complexity-in-markup):
+
+> Large projects will inevitably become more complex. Handling and
+> maintaining that complexity in markup templates is much easier than
+> adding complexity to your stylesheet. Before abstracting combinations
+> of styles out in to new styles, make sure to look for patterns and
+> think about reusability, and consider ways in which your templating
+> engine can DRY up your code. If you’re constantly duplicating the
+> same markup to create UI elements like media player controls or
+> modals, make use of things like partials, helpers, or __components__
+> to keep things maintainable.
+
+(emphasis added)
 
-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
+## 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. render's api is probably not getting any big changes, so hopefully
+it creates a minimal amount of headaches.
+
+This project's goal is to act as documentation and examples of how to write
+components in a rails app. adhoc files in `app/views/shared` doesn't make
+anyone happy.
 
-- make it as easy to write reusable components
-- feel familiar to existing rails helpers, like `link_to` or `content_tag`
 
 ## TODO
 
@@ -259,5 +400,3 @@ TODO
 - 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.rb

@@ -5,7 +5,7 @@ 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?
+    if RailsComponents.configuration.template_directory
       component_template = [RailsComponents.configuration.template_directory, component_template].join('/')
     end
 

data/lib/rails_components/html_helpers.rb

@@ -2,7 +2,18 @@
 module RailsComponents
   module HtmlHelpers
     def html(html_attributes_to_merge = {})
-      merge(html_attributes_to_merge) { |key, v1, v2| [v1, v2].flatten(1) }
+      strategy = delete(:html_merge_strategy) || :combine
+
+      case strategy.to_sym
+      when :combine
+        merge(html_attributes_to_merge) { |key, v1, v2| [v1, v2].flatten(1) }
+      when :merge
+        html_attributes_to_merge.merge(self)
+      when :replace
+        self
+      else
+        raise "unknown html_merge_stragey: #{strategy}"
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_components
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Peter Schilling
@@ -45,5 +45,6 @@ rubyforge_project:
 rubygems_version: 2.6.1
 signing_key: 
 specification_version: 4
-summary: Rails view components
+summary: a thin wrapper around render that makes passing blocks and html attributes
+  to partials simple as pie.
 test_files: []