rafters 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ff71963c4638eaf225b8ec0cd997188ea1591a17
-  data.tar.gz: 041941674c5c90f078d0d0ffb40a42f3cf1d1527
+  metadata.gz: 06d271740c2834640701158193c17c1054228825
+  data.tar.gz: c4cc3af9945fc8e0ece7e787f7ebbfd1fe5539ad
 SHA512:
-  metadata.gz: 843512e43b3ef5da3a9ad3312e972f69270c5df1d4de8c45169bb9d99d74bb218ec0a106ef3a713cafefbd378a490fc85d072343bea8ce94d861aa718ebf5161
-  data.tar.gz: 166c0648085d5e25a70e34c086dae9f21db86748091f21a371583783ff974bc5f8c96dcb24266d5e5914530cf5902d28b2c66fbe1cc150b36dcd248ae13e857f
+  metadata.gz: 89c94d519911b237cf4ed2d29fc5247a0cfd74d4dbd3339d0ea7dcf2a420920a117d161e053debe0e6dda6e192855e6643f3b14920126a137fd252caa4e54e4b
+  data.tar.gz: c86a9ab53bce55b978eea3134a08e7192a28fcec2bcfbcc8676a133bb977963944c499a6f5936d8fa933e7d9fbf1f202db85e0a23b29e83622d6b60fa31b5846

data/README.md

@@ -45,17 +45,17 @@ When you build out a page using Rafters you're effectively breaking it down into
 To begin creating a new component, run the following generator:
 
 ```sh
-$ rails generate rafters:component [name]
+$ rails generate rafters:component {name}
 ```
   
 This generator will create the following files:
 
 ```
-app/rafters/[name]
-app/rafters/[name]/[name]_component.rb
-app/rafters/[name]/assets/stylesheets/[name]_component.scss
-app/rafters/[name]/assets/javascripts/[name]_component.js.coffee
-app/rafters/[name]/views/[name]_component.html.erb
+app/rafters/{name}
+app/rafters/{name}/{name}_component.rb
+app/rafters/{name}/assets/stylesheets/{name}_component.scss
+app/rafters/{name}/assets/javascripts/{name}_component.js.coffee
+app/rafters/{name}/views/{name}_component.html.erb
 ```
   
 The two most important files generated above are `app/rafters/[name]/[name]_component.rb` and `app/rafters/[name]/views/[name]_component.html.erb`, which are (respectively) our component controller and view.
@@ -184,6 +184,94 @@ defaults type: "comment", filter: "none"
 default :published, false
 ```
 
+## Creating a source option for a component
+
+There are often times when a single, general component can be powered by multiple complex data sources. In order to do this Rafters includes to option to create "source" classes that belong to individual components. Each source should expose an interface that can be consumed by the component's template, and options that are set on the component level are accessible at the source level as well.
+
+To create a source, run the following generator:
+
+```ruby
+$ rails g rafters:source {component name} {source name}
+```
+
+This generator will create a file named `{component name}_{source name}_source.rb` in the specified component's sources directory.
+
+A source class is a simple Ruby class that includes the `Rafters::Source` module. You can do pretty much anything you want with source classes (including subclassing), as long as they all expose the same public interface methods. When a component is configured to use a specific source, the `#source` method in that component will return an instance of the specified source class.
+
+Here's a basic example - a list-view component with one source:
+
+The component itself:
+
+```ruby
+class ListViewComponent
+  include Rafters::Component
+  
+  attribute :items
+  
+  private
+  
+  def items
+    source.items
+  end
+end
+```
+
+A source for the component:
+
+```ruby
+class ListViewCommentSource
+  include Rafters::Source
+  
+  def items
+    @items ||= Comment.all
+  end
+end
+```
+
+The component's view template:
+
+```erb
+<ul>
+  <% items.each do |item| %>
+    <li><%= item.body %></li>
+  <% end %>
+</ul>
+```
+
+To render the above component with the `ListViewCommentSource`:
+
+```erb
+<div class="main">
+  <%= render_component :list_view, as: "comments-list", source: "ListViewCommentSource"
+</div>
+```
+
+If you want to add another source option for this component, simply create a new source class with the same interface:
+
+```ruby
+class ListViewPostSource
+  include Rafters::Source
+  
+  def items
+    @items ||= Post.where({
+      category_id: settings.category_id
+    }).all
+  end
+end
+```
+
+And render the component with the new source (and any settings that it may require):
+
+```erb
+<div class="main">
+  <%= render_component :list_view, as: "posts-list", source: "ListViewPostSource", {
+    category_id: @category.id
+  } %>
+</div>
+```
+
+The `Rafters::Component#controller` and `Rafters::Component#settings` methods are both available within your source classes, and will return the same information that they would in the related component.
+
 ## Contributing
 
 1. Fork it

data/lib/generators/rafters/component/component_generator.rb

@@ -7,6 +7,7 @@ class Rafters::ComponentGenerator < Rails::Generators::NamedBase
     empty_directory "#{base_directory}/assets/javascripts"
     empty_directory "#{base_directory}/assets/stylesheets"
     empty_directory "#{base_directory}/assets/images"
+    empty_directory "#{base_directory}/sources"
     empty_directory "#{base_directory}/views"
   end
 
@@ -23,10 +24,6 @@ class Rafters::ComponentGenerator < Rails::Generators::NamedBase
 
   private
 
-  def app_root
-    Rails.root
-  end
-
   def base_directory
     "app/components/#{file_name}"
   end

data/lib/generators/rafters/source/source_generator.rb

@@ -0,0 +1,26 @@
+class Rafters::SourceGenerator < Rails::Generators::NamedBase
+  source_root File.expand_path("../templates", __FILE__)
+  argument :source_name, type: :string
+
+  def create_directory
+    empty_directory "#{base_directory}"
+  end
+
+  def create_files
+    template "source.rb.erb", "#{base_directory}/#{source_file_name}_source.rb"
+  end
+
+  private
+
+  def base_directory
+    "app/components/#{file_name}/sources"
+  end
+
+  def source_file_name
+    source_name.underscore
+  end
+
+  def source_class_name
+    source_name.classify
+  end
+end

data/lib/generators/rafters/source/templates/source.rb.erb

@@ -0,0 +1,4 @@
+class <%= source_class_name %>Source
+  include Rafters::Source
+
+end

data/lib/rafters/version.rb

@@ -1,3 +1,3 @@
 module Rafters
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rafters
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Andrew Hite
@@ -173,6 +173,8 @@ files:
 - lib/generators/rafters/component/templates/views/component.html.erb
 - lib/generators/rafters/install/install_generator.rb
 - lib/generators/rafters/install/templates/initializer.rb
+- lib/generators/rafters/source/source_generator.rb
+- lib/generators/rafters/source/templates/source.rb.erb
 - lib/rafters.rb
 - lib/rafters/component.rb
 - lib/rafters/component_context.rb