komponent 1.0.0.pre.1 → 1.0.0.pre.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 49bd1e590f8faf9b5eb6a2ca87b556144bf0333d
-  data.tar.gz: aff68306564d0e94d963e1de3fb28f13d33f714e
+  metadata.gz: 40e0a4ef6174624542dbc86dd1c6e4013458f5c5
+  data.tar.gz: 6107b8a0dce15687071b2acc798fb88e4a704a46
 SHA512:
-  metadata.gz: e37992a8d7e267a8d056db03e77dd3a23f8e8e6b7e2a3b96a32d950e2370e646e889ba5e982f736938b7ed481fba4d34aa299eb262b507033f2f8792b9b7ec52
-  data.tar.gz: 753ce8aba84b0410f406ac691a7294b7f0e4badad58b67907ac31811ab40329ffd3212506546cc84a4fb16c760e1ad944e6f141c7a457d023fb95e0205b8071f
+  metadata.gz: 287bfee2642a337f11bec08f8b9c30c1dddcab28679eef865bd4411653a57d4f3d8235a2f720b46ae210f0344fbdc6bf896dd91859fff35d9ce95fefa6f6195c
+  data.tar.gz: 5ecb567ec3c60cca672aaddc42a5bfe23c9051fc74e76ac1ff8c08618e75448baaf467fed9d49ed264d38f632430847ab2273a0ff968a1bcdb693afaaf7dbb27

data/README.md

@@ -1,59 +1,128 @@
 # Komponent
 
-## Installation
+**Komponent** implements an opinionated way of organizing front-end code in Ruby on Rails, based on _components_.
+
+Each component has its own folder, containing a Ruby module, a slim partial, a PostCSS stylesheet and a JavaScript file.
+
+Komponent relies heavily on webpacker to manage dependencies and generate the production JS and CSS files.
+
+This gem has been inspired by our Rails development practices at [Ouvrages](https://ouvrages-web.fr) and [Etamin Studio](https://etaminstudio.com), and the (excellent) [_Modern Front-end in Rails_](https://evilmartians.com/chronicles/evil-front-part-1) article from Evil Martians.
+
+
+## Getting started
 
 ```ruby
-gem 'komponent'
+# Gemfile
+
+gem "komponent"
 ```
 
-Modify your webpacker config to:
+Run the following command to set up your project instantly:
 
+```sh
+rails generate komponent:install
 ```
-# config/webpacker.yml
-source_path: frontend
-```
+
+This command will:
+
+* check that the dependencies (currently, webpacker) are installed
+* rename the `app/javascript` folder to `frontend` and modify webpacker config accordingly
+* create the `frontend/components` folder where you will put your component
+* create the `frontend/components/index.js` file that will list your components and `import` it in `frontend/packs/application.js`
 
 ## Usage
 
-Generate new component with `component` generator:
+Generate a new component with the `component` generator:
 
-`rails generate component button`
+```sh
+rails generate component button
+```
+
+Then, render it in your views with the `component` helper (or its alias `c`).
 
-And use it in your views with helper. You can pass `locals`, or `block` to component helper.
+```slim
+/ app/views/pages/home.html.slim
 
-`= component('button')`
+= component "button"
+= c "button"
+```
 
-Locals passed in to component are accessible as instance variables.
+You can pass `locals` to the helper. They are accessible within the component partial, as instance variables.
 
+```slim
+/ app/views/pages/home.html.slim
+
+= component "button", text: "My button"
 ```
-= component('button', color: :red)
+
+```slim
+/ frontend/components/button/_button.html.slim
 
 .button
-  = @color
+  = @text
 ```
 
-You can define custom helpers in `ButtonComponent`:
+The component also accepts a `block`. To render the block, just use the standard `yield`.
 
+```slim
+/ app/views/pages/home.html.slim
+
+= component "button"
+  span= "My button"
 ```
-class ButtonComponent
-  def bar
-    "foo"
-  end
-end
+
+```slim
+/ frontend/components/button/_button.html.slim
 
 .button
-  = bar
+  = yield
 ```
 
-You can set properties in `ButtonComponent` too:
+Each component comes with a Ruby `module`. You can use it to set properties:
 
+```ruby
+# frontend/components/button/button_component.rb
+
+module ButtonComponent
+  property :href, required: true
+  property :text, default: "My button"
+end
 ```
-class ButtonComponent
-  property :foo, default: "bar", required: true
+
+```slim
+/ frontend/components/button/_button.html.slim
+
+a.button(href=@href)
+  = @text
+```
+
+If your partial becomes a too complex and you want to remove logic from it, you may want to define custom helpers in the `ButtonComponent` module:
+
+```ruby
+# frontend/components/button/button_component.rb
+
+module ButtonComponent
+  property :href, required: true
+  property :text, default: "My button"
+
+  def external_link?
+    @href.starts_with? "http"
+  end
 end
+```
 
-.button
-  = @foo
+```slim
+/ frontend/components/button/_button.html.slim
+
+a.button(href=@href)
+  = @text
+  = " (external link)" if external_link?
+```
+
+```slim
+/ app/views/pages/home.html.slim
+
+= component "button", text: "My button", href: "http://github.com"
 ```
 
 ## Contributing

data/komponent.gemspec

@@ -9,9 +9,9 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Ouvrages"]
   spec.email         = ["contact@ouvrages-web.fr"]
 
-  spec.summary       = ""
-  spec.description   = ""
-  spec.homepage      = ""
+  spec.summary       = "An opinionated way of organizing front-end code in Ruby on Rails, based on components"
+  spec.description   = "An opinionated way of organizing front-end code in Ruby on Rails, based on components"
+  spec.homepage      = "http://komponent.io"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files -z`.split("\x0").reject do |f|

data/lib/generators/component/component_generator.rb

@@ -2,36 +2,58 @@ class ComponentGenerator < Rails::Generators::Base
   source_root File.expand_path('../templates', __FILE__)
 
   argument :component, required: true, desc: "Component name, e.g: button"
+  class_option :locale, type: :boolean, default: false
 
   def create_view_file
-    template "view.html.slim.erb", component_path + "_#{component}.html.slim"
+    template "view.html.#{template_engine}.erb", component_path + "_#{component_name}.html.#{template_engine}"
   end
 
   def create_css_file
-    template "css.erb", component_path + "#{component}.css"
+    template "css.erb", component_path + "#{component_name}.css"
   end
 
   def create_js_file
-    template "js.erb", component_path + "#{component}.js"
+    template "js.erb", component_path + "#{component_name}.js"
   end
 
   def create_rb_file
-    template "rb.erb", component_path + "#{component}_component.rb"
+    template "rb.erb", component_path + "#{component_name}_component.rb"
+  end
+
+  def create_locale_files
+    return unless locale?
+
+    I18n.available_locales.each do |locale|
+      @locale = locale
+      template "locale.erb", component_path + "#{component_name}.#{locale}.yml"
+    end
   end
 
   def append_frontend_packs
     append_to_file "frontend/components/index.js" do
-      "import \"components/#{component}/#{component}\";"
+      "import \"components/#{component_name}/#{component_name}\";"
     end
   end
 
   protected
 
   def component_path
-    "frontend/components/#{component}/"
+    "frontend/components/#{component_name}/"
   end
 
   def module_name
-    "#{component}_component".camelize
+    "#{component_name}_component".camelize
+  end
+  
+  def component_name
+    component.underscore
+  end
+
+  def template_engine
+    Rails.application.config.app_generators.rails[:template_engine] || :erb
+  end
+
+  def locale?
+    options[:locale]
   end
 end

data/lib/generators/component/templates/css.erb

@@ -1 +1 @@
-.<%= component %> {}
+.<%= component_name.dasherize %> {}

data/lib/generators/component/templates/js.erb

@@ -1 +1 @@
-import "./<%= component %>.css";
+import "./<%= component_name %>.css";

data/lib/generators/component/templates/locale.erb

@@ -0,0 +1,3 @@
+<%= @locale %>:
+  <%= component_name %>:
+    component_name: <%= component_name %>

data/lib/generators/component/templates/view.html.erb.erb

@@ -0,0 +1,3 @@
+<div class="<%= component_name.dasherize %>">
+  <%= component_name %>
+</div>

data/lib/generators/component/templates/view.html.haml.erb

@@ -0,0 +1 @@
+.<%= component_name.dasherize %> <%= component_name %>

data/lib/generators/component/templates/view.html.slim.erb

@@ -1 +1 @@
-.<%= component %> <%= component %>
+.<%= component_name.dasherize %> <%= component_name %>

data/lib/generators/komponent/install_generator.rb

@@ -0,0 +1,58 @@
+module Komponent
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      def check_webpacker_dependency
+        unless File.exists?(webpacker_configuration_file) and File.directory?(webpacker_default_structure)
+          raise Thor::Error, dependencies_not_met_error_message
+        end
+      end
+
+      def create_root_directory
+        empty_directory(komponent_root_directory)
+      end
+
+      def modify_webpacker_configuration
+        gsub_file(webpacker_configuration_file, /source_path: app\/javascript$/, "source_path: frontend")
+      end
+
+      def move_webpacker_default_structure
+        run("mv #{webpacker_default_structure}/* #{komponent_root_directory}")
+      end
+
+      def create_komponent_default_structure
+        empty_directory(components_directory)
+        create_file(components_directory.join("index.js"))
+      end
+
+      def append_to_application_pack
+        append_to_file(application_pack_path, "import 'components';")
+      end
+
+      private
+
+      def application_pack_path
+        komponent_root_directory.join("packs", "application.js")
+      end
+
+      def komponent_root_directory
+        Rails.root.join("frontend")
+      end
+
+      def components_directory
+        Rails.root.join(komponent_root_directory, "components")
+      end
+
+      def webpacker_configuration_file
+        Rails.root.join("config", "webpacker.yml")
+      end
+
+      def webpacker_default_structure
+        Rails.root.join("app", "javascript")
+      end
+
+      def dependencies_not_met_error_message
+        "Seems you don't have webpacker installed in your project. Please install webpacker, and follow instructions at https://github.com/rails/webpacker"
+      end
+    end
+  end
+end

data/lib/komponent/railtie.rb

@@ -1,14 +1,24 @@
-require 'komponent/komponent_helper'
 require 'komponent/core/component_helper'
 
 module Komponent
   class Railtie < Rails::Railtie
-    initializer "komponent.helper" do |app|
-      ActionView::Base.send :include, KomponentHelper
+    initializer "komponent.action_view" do |app|
+      ActiveSupport.on_load :action_view do
+        require 'komponent/komponent_helper'
+        include KomponentHelper
+      end
     end
 
-    initializer "komponent.controller" do |app|
-      ActionController::Base.prepend_view_path "#{app.config.root}/frontend"
+    initializer "komponent.action_dispatch" do |app|
+      ActiveSupport.on_load :action_controller do
+        ActionController::Base.prepend_view_path "#{app.config.root}/frontend"
+      end
+    end
+
+    initializer "komponent.i18n" do |app|
+      ActiveSupport.on_load :i18n do
+        I18n.load_path.concat(Dir["#{app.config.root}/frontend/components/*/*.yml"])
+      end
     end
 
     initializer 'komponent.autoload', before: :set_autoload_paths do |app|

data/lib/komponent/version.rb

@@ -1,3 +1,3 @@
 module Komponent
-  VERSION = "1.0.0.pre.1"
+  VERSION = "1.0.0.pre.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: komponent
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.1
+  version: 1.0.0.pre.2
 platform: ruby
 authors:
 - Ouvrages
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-12-07 00:00:00.000000000 Z
+date: 2017-12-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -38,7 +38,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '10.0'
-description: ''
+description: An opinionated way of organizing front-end code in Ruby on Rails, based
+  on components
 email:
 - contact@ouvrages-web.fr
 executables: []
@@ -57,14 +58,18 @@ files:
 - lib/generators/component/component_generator.rb
 - lib/generators/component/templates/css.erb
 - lib/generators/component/templates/js.erb
+- lib/generators/component/templates/locale.erb
 - lib/generators/component/templates/rb.erb
+- lib/generators/component/templates/view.html.erb.erb
+- lib/generators/component/templates/view.html.haml.erb
 - lib/generators/component/templates/view.html.slim.erb
+- lib/generators/komponent/install_generator.rb
 - lib/komponent.rb
 - lib/komponent/core/component_helper.rb
 - lib/komponent/komponent_helper.rb
 - lib/komponent/railtie.rb
 - lib/komponent/version.rb
-homepage: ''
+homepage: http://komponent.io
 licenses:
 - MIT
 metadata: {}
@@ -87,5 +92,6 @@ rubyforge_project:
 rubygems_version: 2.6.13
 signing_key: 
 specification_version: 4
-summary: ''
+summary: An opinionated way of organizing front-end code in Ruby on Rails, based on
+  components
 test_files: []