updated install instructions and generators

Author: catmando

docs/installation/installation.md

@@ -1,26 +1,7 @@
-require 'rails/generators'
 module Hyper
-  class Component < Rails::Generators::Base
-    source_root File.expand_path('../templates', __FILE__)
-    argument :components, type: :array
-    class_option 'base-class', :default => 'HyperComponent'
-    class_option 'add-route', :default => nil
-
-    def create_component_file
-      clear_cache
-      insure_hyperstack_loader_installed
-      insure_base_component_class_exists unless options['base-class'] == 'skip'
-      self.components.each do |component|
-        component_array = component.split('::')
-        @modules = component_array[0..-2]
-        @file_name = component_array.last
-        @indent = 0
-        template 'component_template.rb',
-                 File.join('app', 'hyperstack', 'components',
-                           *@modules.map(&:downcase),
-                           "#{@file_name.underscore}.rb")
-      end
-      add_route
+  class Component < GeneratorBase
+    def add_component
+      create_component_file 'component_template.rb'
     end
   end
 end

docs/installation/man-installation.md

@@ -0,0 +1,18 @@
+require 'rails/generators'
+module Hyper
+  class GeneratorBase < Rails::Generators::Base
+    class << self
+      alias rails_inherited inherited
+      def inherited(child)
+        rails_inherited(child)
+        child.class_eval do
+          source_root File.expand_path('../templates', __FILE__)
+          argument :components, type: :array
+          class_option 'base-class', :default => nil # will pull in value from config setting
+          class_option 'add-route', :default => nil
+          class_option 'no-help', :default => nil
+        end
+      end
+    end
+  end
+end

ruby/rails-hyperstack/lib/generators/hyper/component_generator.rb

@@ -1,24 +1,7 @@
-require 'rails/generators'
 module Hyper
-  class Router < Rails::Generators::Base
-    source_root File.expand_path('../templates', __FILE__)
-
-    argument :component, type: :string
-    class_option :path, type: :string, default: '/(*other)'
-    def create_component_file
-      component_array = component.split('::')
-      @modules = component_array[0..-2]
-      @file_name = component_array.last
-      
-      @indent = 0
-      template 'router_template.rb',
-               File.join('app/hyperstack/components',
-                         @modules.map(&:downcase).join('/'),
-                         "#{@file_name.underscore}.rb")
-    end
-
-    def add_route
-      route "get '#{options['path']}', to: 'hyperstack##{@file_name.underscore}'"
+  class Router < GeneratorBase
+    def add_router_component
+      create_component_file 'router_template.rb'
     end
   end
 end

ruby/rails-hyperstack/lib/generators/hyper/generator_base.rb

@@ -1,6 +1,6 @@
 <%- @modules.each do |module_name| %><%= "  "* @indent %>module <%= module_name.camelize %><%- @indent += 1 %>
 <%- end %><%="  "* @indent %>class <%= @file_name %> < <%= @component_base_class %>
-
+<%- unless @no_help %>
 <%="  "* @indent %>  # param :my_param
 <%="  "* @indent %>  # param param_with_default: "default value"
 <%="  "* @indent %>  # param :param_with_default2, default: "default value" # alternative syntax
@@ -9,8 +9,16 @@
 <%="  "* @indent %>  # other :attributes  # collects all other params into a hash
 <%="  "* @indent %>  # fires :callback  # creates a callback param
 
-<%="  "* @indent %>  # The following are the most common lifecycle call backs,
-<%="  "* @indent %>  # the following are the most common lifecycle call backs# delete any that you are not using.
+<%="  "* @indent %>  # access params using the param name
+<%="  "* @indent %>  # fire a callback using the callback name followed by a !
+
+<%="  "* @indent %>  # state is kept and read as normal instance variables
+<%="  "* @indent %>  # but when changing state prefix the statement with `mutate`
+<%="  "* @indent %>  # i.e. mutate @my_state = 12
+<%="  "* @indent %>  #      mutate @my_other_state[:bar] = 17
+
+<%="  "* @indent %>  # the following are the most common lifecycle call backs,
+<%="  "* @indent %>  # delete any that you are not using.
 <%="  "* @indent %>  # call backs may also reference an instance method i.e. before_mount :my_method
 
 <%="  "* @indent %>  before_mount do
@@ -28,12 +36,14 @@
 <%="  "* @indent %>  end
 
 <%="  "* @indent %>  before_unmount do
-<%="  "* @indent %>    # cleanup any thing (i.e. timers) before component is destroyed
+<%="  "* @indent %>    # cleanup any thing before component is destroyed
+<%="  "* @indent %>    # note timers are broadcast receivers are cleaned up
+<%="  "* @indent %>    # automatically
 <%="  "* @indent %>  end
 
-<%="  "* @indent %>  render do
+<%- end %><%="  "* @indent %>  render do
 <%="  "* @indent %>    DIV do
-<%="  "* @indent %>      "<%= (@modules+[@file_name]).join('::') %>"
+<%="  "* @indent %>      '<%= (@modules+[@file_name]).join('::') %>'
 <%="  "* @indent %>    end
 <%="  "* @indent %>  end
 <%="  "* @indent %>end

ruby/rails-hyperstack/lib/generators/hyper/router_generator.rb

@@ -1,16 +1,16 @@
 <%- @modules.each do |module_name| %><%= "  "* @indent %>module <%= module_name.camelize %><%- @indent += 1 %>
-<%- end %><%="  "* @indent %>class <%= @file_name %> < HyperComponent
+<%- end %><%="  "* @indent %>class <%= @file_name %> < <%= @component_base_class %>
 <%="  "* @indent %>  include Hyperstack::Router
 <%="  "* @indent %>  render do
 <%="  "* @indent %>    DIV do
 <%="  "* @indent %>      '<%= (@modules+[@file_name]).join('::') %>'
-<%="  "* @indent %>      # define routes using the Route psuedo component.  Examples:
+<%- unless @no_help %><%="  "* @indent %>      # define routes using the Route psuedo component.  Examples:
 <%="  "* @indent %>      # Route('/foo', mounts: Foo)                : match the path beginning with /foo and mount component Foo here
 <%="  "* @indent %>      # Route('/foo') { Foo(...) }                : display the contents of the block
 <%="  "* @indent %>      # Route('/', exact: true, mounts: Home)     : match the exact path / and mount the Home component
 <%="  "* @indent %>      # Route('/user/:id/name', mounts: UserName) : path segments beginning with a colon will be captured in the match param
 <%="  "* @indent %>      # see the hyper-router gem documentation for more details
-<%="  "* @indent %>    end
+<%- end %><%="  "* @indent %>    end
 <%="  "* @indent %>  end
 <%="  "* @indent %>end
 <%- @modules.each do %><%- @indent -= 1 %><%="  "* @indent %>end

ruby/rails-hyperstack/lib/generators/hyper/templates/component_template.rb

@@ -10,7 +10,14 @@ class InstallGenerator < Rails::Generators::Base
     class_option 'hyper-model-only', type: :boolean
 
     def add_component
-      generate 'hyper:component App -add-router' unless skip_adding_component?
+      if skip_adding_component?
+        # normally this is handled by the hyper:component
+        # generator, but if we are skipping it we will check it
+        # now.
+        insure_hyperstack_loader_installed
+      else
+        generate 'hyper:router App --add-route'
+      end
     end
 
     def add_hotloader
@@ -149,27 +156,29 @@ def move_and_update_application_record
 
     def add_engine_route
       return if skip_hyper_model?
-      
+      route 'mount Hyperstack::Engine => \'/hyperstack\'  # this route should be first in the routes file so it always matches'
+    end
 
     def report
       say "\n\n"
       unless skip_adding_component?
         say "🎢 Top Level App Component successfully installed at app/hyperstack/components/app.rb 🎢", :green
       end
-      unless skip_hotloader?
-        say "🚒 Hyperstack Hotloader installed - use bundle exec foreman start and visit localhost:5000 🚒", :green
-      end
       unless skip_webpack?
-        say "🚀 Webpack integrated with Hyperstack.  "\
-            "Add javascript assets to app/javascript/packs/client_only.js and /client_and_server.js 🚀", :green
+        say "📦 Webpack integrated with Hyperstack.  "\
+            "Add javascript assets to app/javascript/packs/client_only.js and /client_and_server.js 📦", :green
       end
       unless skip_hyper_model?
         say "👩‍✈️ Basic development policy defined.  See app/policies/application_policy.rb 👨🏽‍✈️", :green
-        say "💽 Move any Active Record models to the app/hyperstack/models to access them from the client 📀", :green
+        say "💽 HyperModel installed. Move any Active Record models to the app/hyperstack/models to access them from the client 📀", :green
       end
       if File.exists?(init = File.join('config', 'initializers', 'hyperstack.rb'))
         say "☑️  Check #{init} for other configuration options. ☑️", :green
       end
+      unless skip_hotloader?
+        say "🚒 Hyperstack Hotloader installed - use bundle exec foreman start and visit localhost:5000 🚒", :green
+      end
+
       say "\n\n"
     end
 
@@ -198,9 +207,27 @@ def inject_into_initializer(s)
       else
         create_file file_name, <<-RUBY
 #{s}
+# set the component base class
+
+Hyperstack.component_base_class = 'HyperComponent' # i.e. 'ApplicationComponent'
+
+# prerendering is default :off, you should wait until your
+# application is relatively well debugged before turning on.
+
 Hyperstack.prerendering = :off # or :on
+
+# transport controls how push (websocket) communications are
+# implemented.  The default is :action_cable.
+# Other possibilities are :pusher (see www.pusher.com) or
+# :simple_poller which is sometimes handy during system debug.
+
+Hyperstack.transport = :action_cable # or :none, :pusher,  :simple_poller
+
 # add this line if you need jQuery AND ARE NOT USING WEBPACK
 # Hyperstack.import 'hyperstack/component/jquery', client_only: true
+
+# change definition of on_error to control how errors such as validation
+# exceptions are reported on the server
 module Hyperstack
   def self.on_error(operation, err, params, formatted_error_message)
     ::Rails.logger.debug(

ruby/rails-hyperstack/lib/generators/hyper/templates/router_template.rb

@@ -6,6 +6,25 @@ class Base < Thor::Group
 
       protected
 
+      def create_component_file(template)
+        clear_cache
+        insure_hyperstack_loader_installed
+        insure_base_component_class_exists
+        @no_help = options.key?('no-help')
+        self.components.each do |component|
+          component_array = component.split('::')
+          @modules = component_array[0..-2]
+          @file_name = component_array.last
+          @indent = 0
+          template template,
+                   File.join('app', 'hyperstack', 'components',
+                             *@modules.map(&:downcase),
+                             "#{@file_name.underscore}.rb")
+        end
+        add_route
+      end
+
+
       def clear_cache
         run 'rm -rf tmp/cache' unless Dir.exists?(File.join('app', 'hyperstack'))
       end
@@ -37,7 +56,7 @@ def insure_hyperstack_loader_installed
 
 
       def insure_base_component_class_exists
-        @component_base_class = options['base-class']
+        @component_base_class = options['base-class'] || Hyperstack.component_base_class
         file_name = File.join(
           'app', 'hyperstack', 'components', "#{@component_base_class.underscore}.rb"
         )
@@ -63,10 +82,15 @@ def add_route
         end
         action_name = (@modules+[@file_name.underscore]).join('__')
         path = options['add-route'] == 'add-route' ? '/(*others)' : options['add-route']
-        route "get '#{path}', to: 'hyperstack##{action_name}'"
+        routing_code = "get '#{path}', to: 'hyperstack##{action_name}'"
+        log :route, routing_code
+        [/mount\s+Hyperstack::Engine[^\n]+\n/m, /\.routes\.draw do\s*\n/m].each do |sentinel|
+          in_root do
+            x = inject_into_file "config/routes.rb", optimize_indentation(routing_code, 2), after: sentinel, verbose: false, force: false
+          end
+        end
       end
 
-
       def yarn(package, version = nil)
         return if system("yarn add #{package}#{'@' + version if version}")
         raise Thor::Error.new("yarn failed to install #{package} with version #{version}")

ruby/rails-hyperstack/lib/generators/hyperstack/install_generator.rb

@@ -14,6 +14,7 @@
 Hyperstack.import 'hyper-state'
 
 require 'generators/hyperstack/install_generator'
+require 'generators/hyper/generator_base'
 require 'generators/hyper/component_generator'
 require 'generators/hyper/router_generator'
 begin
@@ -32,3 +33,5 @@ class RailsHyperstack < Rails::Railtie
     Dir[File.join(File.dirname(__FILE__),'tasks/hyperstack/*.rake')].each { |f| puts "loading #{f}"; load f }
   end
 end
+
+Hyperstack.define_setting :component_base_class, 'HyperComponent'