Merge pull request #72 from basemate/introduce_scaffolder

Introduce scaffolder (documented & tested)

Author: jonasjabari

Gemfile

@@ -32,3 +32,7 @@ group :development, :test do
   gem 'byebug'
   gem 'webmock'
 end
+
+group :test do
+  gem "generator_spec"
+end

Gemfile.lock

@@ -99,6 +99,9 @@ GEM
     docile (1.3.1)
     erubi (1.7.1)
     ffi (1.9.25)
+    generator_spec (0.9.4)
+      activesupport (>= 3.0.0)
+      railties (>= 3.0.0)
     globalid (0.4.2)
       activesupport (>= 4.2.0)
     haml (5.0.4)
@@ -250,6 +253,7 @@ DEPENDENCIES
   capybara
   cells-haml
   cells-rails
+  generator_spec
   matestack-ui-core!
   poltergeist
   puma

docs/README.md

@@ -6,9 +6,10 @@
 2. [Concepts](./concepts)
 3. [Core Components](./components)
 4. [Integrations](./integrations)
+5. [Tooling](./tooling_and_ecosystem)
 
 ## Diving deeper
 
-5. [Extend](./extend)
-6. [Architecture](./architecture)
-7. [Contribute](./contribute)
+6. [Extend](./extend)
+7. [Architecture](./architecture)
+8. [Contribute](./contribute)

docs/contribute/README.md

@@ -29,12 +29,9 @@ Tests follow quite the same rules as the documentation: Make sure to either add
 
 ## Release
 
-Webpacker is used for managing all JS assets. In order to deploy a packed JS, we
-use a "builder" app found in repo_root/builder
-This builder app uses a symlink in order to reference the actual core found in
-builder/vendor.
+Webpacker is used for managing all JS assets. In order to deploy a packed JS, we use a "builder" app found in `repo_root/builder`. This builder app uses a symlink in order to reference the actual core found in `builder/vendor`.
 
-You can run webpacker inside this builder app in order to pack JS assets:
+You can run webpacker inside this builder app to pack JS assets:
 
 ```shell
 cd builder

docs/extend/README.md

@@ -0,0 +1 @@
+# tbd

docs/tooling_and_ecosystem/generators/README.md

@@ -0,0 +1,19 @@
+# Create Matestack concepts using generators
+
+Those are extensions of the `Rails::Generators` and follow the same system as the classic Rails scaffolders. Reach out to us with feedback or if things don't behave the way you'd expect them to do!
+
+## General usage
+
+Create matestack apps, pages and components (and some corresponding parts, like routes and controllers) automatically from the command line!
+
+Each generator takes mandatory arguments and optional flags. Check their detailed description to see default parameters and the full list of options.
+
+Tests can be found [here](../../spec/lib/generators).
+
+**Note:** We recommend commiting or stashing your current changes so you see created/modified files within your application!
+
+Matestack App Generator is documented [here](./matestack_app_generator.md).
+
+Matestack Page Generator is documented [here](./matestack_page_generator.md).
+
+Matestack Component Generator is documented [here](./matestack_component_generator.md).

docs/tooling_and_ecosystem/generators/matestack_app_generator.md

@@ -0,0 +1,36 @@
+# Matestack App Generator
+
+## Usage
+
+Generates matestack apps to `app/matestack/apps`.
+
+## Parameters
+
+**NAME** - Mandatory. Creates an empty matestack page in `app/matestack/apps/NAME.rb`.
+
+**--all_inclusive** - Optional. Also creates a corresponding matestack page, a controller with an action for the matestack page and a route to it.
+
+## Example 1
+
+```bash
+rails generate matestack_app example_app
+```
+
+Creates an ExampleApp in `app/matestack/apps/example_app.rb`.
+
+## Example 2
+
+```bash
+rails generate matestack_app simple_app --all_inclusive
+```
+
+Creates:
+- a SimpleApp in `app/matestack/apps/simple_app.rb`
+- an ExamplePage in `app/matestack/pages/simple_app/example_page.rb`
+- a SimpleAppController in `app/controllers/simple_app_controller.rb`
+- a route to `http://localhost:3000/simple_app/example_page`
+
+To see all options, run
+```bash
+rails generate matestack_app -h
+```

docs/tooling_and_ecosystem/generators/matestack_component_generator.md

@@ -0,0 +1,28 @@
+# Matestack Component Generator
+
+## Usage
+
+Generates matestack components to `app/matestack/components`.
+
+## Parameters
+
+**NAME** - Mandatory. Creates an empty matestack component in `app/matestack/components/NAME.rb`.
+
+**--dynamic** - Optional. Makes the created component dynamic and also creates a corresponding `app/matestack/components/NAME.js` file.
+
+**--haml** - Optional. Creates a `app/matestack/components/NAME.haml` file to use 'normal' HTML tags.
+
+**--scss** - Optional. Creates an `app/matestack/components/NAME.scss` for custom component styling.
+
+## Example
+
+```bash
+rails generate matestack_component simple_component
+```
+
+Creates a SimpleComponent in `app/matestack/components/simple_component.rb`.
+
+To see all options, run
+```bash
+rails generate matestack_component -h
+```

docs/tooling_and_ecosystem/generators/matestack_page_generator.md

@@ -0,0 +1,52 @@
+# Matestack Page Generator
+
+## Usage
+
+Generates matestack pages to `app/matestack/pages`.
+
+## Parameters
+
+**NAME** - Mandatory. Creates an empty matestack page in `app/matestack/pages/NAME.rb`.
+
+**--app_name** - Mandatory. Adds a `/app_name` folder to `app/matestack/pages` to indicate to which matestack app the pages belongs. Pages _do not necessarily need to belong to an app_, but for now the page scaffolder can only provide this functionality.
+
+**--namespace** - Optional. Adds a `/namespace` folder within the `/app_name` and a namespace to the `page.rb`. You can also scope the namespace using additional `/`'s like so: `namespace_1/namespace_2`
+
+**--controller_action** - Optional. Takes a `controller#action` to use in the created route for the page. If not provided, a `controller#action` is created from **NAME** and **--app_name**.
+
+## Example 1
+
+```bash
+rails generate matestack_page simple_page --app_name example_app
+```
+
+Creates a SimplePage in `app/matestack/pages/example_app/simple_page.rb`.
+
+It also adds `get '#example_app/simple_page', to: 'example_app#simple_page'` to the `config/routes.rb` and proposes a
+```ruby
+def simple_page
+  responder_for(Pages::ExampleApp::SimplePage)
+end
+```
+in the terminal to use in your controller.
+
+## Example 2
+
+```bash
+rails generate matestack_page second_page --app_name example_app --namespace sample_namespace
+```
+
+Creates a SimplePage in `app/matestack/pages/example_app/sample_namespace/second_page.rb`.
+
+It also adds `get '#example_app/sample_namespace/second_page', to: 'example_app#second_page'` to the `config/routes.rb` and proposes a
+```ruby
+def simple_page
+  responder_for(Pages::ExampleApp::SampleNamespace::SecondPage)
+end
+```
+in the terminal to use in your, e.g., `example_app_controller.rb`.
+
+To see all options, run
+```bash
+rails generate matestack_page -h
+```

lib/generators/matestack_app/USAGE

@@ -0,0 +1,21 @@
+Description:
+    Stubs out a new matestack app. Pass the app name under_scored.
+
+    If you want so, pass the option '--all_inclusive' to also create
+    a corresponding matestack example_page, a controller, its action
+    and the route in 'config/routes.rb'.
+
+Example 1:
+    `rails generate matestack_app example_app`
+
+    This will create:
+        app/matestack/apps/example_app.rb
+
+Example 2:
+`rails generate matestack_app example_app --all_inclusive`
+
+    This will create:
+        app/matestack/apps/example_app.rb
+        app/matestack/pages/example_app/example_page.rb
+        app/controllers/example_app_controller.rb
+        route  get 'example_app/example_page', to: 'example_app#example_page'

lib/generators/matestack_app/matestack_app_generator.rb

@@ -0,0 +1,26 @@
+class MatestackAppGenerator < Rails::Generators::NamedBase
+  source_root File.expand_path('templates', __dir__)
+
+  class_option :all_inclusive, type: :boolean, default: false
+
+  def create_matestack_app
+
+    generator_path = "app/matestack/apps/#{file_name}.rb"
+
+    template 'matestack_app.erb', generator_path
+
+    if options[:all_inclusive] == true
+      controller_path = "app/controllers/#{file_name}_controller.rb"
+      template 'matestack_app_controller.erb', controller_path
+
+      route %{get '#{file_name}/example_page', to: '#{file_name}\#example_page'}
+
+      generate "matestack_page example_page --app_name #{file_name} --called_by_app_generator=true"
+
+      puts "You can visit your new matestack apps' example page under http://localhost:3000/#{file_name}/example_page"
+
+    end
+
+  end
+
+end

lib/generators/matestack_app/templates/matestack_app.erb

@@ -0,0 +1,26 @@
+class Apps::<%= class_name %> < Matestack::Ui::App
+
+# OPTIONAL: Prepare data that gets used on every page of this app
+# def prepare
+#   API calls and db queries go here
+# end
+
+# MANDATORY: This is where your matestack pages get yielded
+def response
+  components {
+    page_content
+  }
+end
+
+# OPTIONAL: Use partials to render stuff like layout components
+# def partial_one
+#   partial {
+#     # your components go here
+#   }
+# end
+
+# OPTIONAL: Slots come after partials
+# def slots
+# end
+
+end

lib/generators/matestack_app/templates/matestack_app_controller.erb

@@ -0,0 +1,7 @@
+class <%= class_name %>Controller < ApplicationController
+
+  def example_page
+    responder_for(Pages::<%= class_name %>::ExamplePage)
+  end
+
+end

lib/generators/matestack_component/USAGE

@@ -0,0 +1,20 @@
+Description:
+    Stubs out a new matestack component. Pass the component name, under_scored.
+
+    To create a dynamic component, specify it using the --dynamic option.
+
+    To place this component within a namespace, specify the namespace name under_scored and it
+    will get generated into 'app/matestack/components/namespace/*'.
+
+Example 1:
+    `rails generate matestack_component NAME`
+
+    This will create:
+        app/matestack/components/NAME.rb
+
+Example 2:
+    `rails generate matestack_component NAME --dynamic --namespace sample_namespace`
+
+    This will create:
+        app/matestack/components/sample_namespace/NAME.rb
+        app/matestack/components/sample_namespace/NAME.js

lib/generators/matestack_component/matestack_component_generator.rb

@@ -0,0 +1,30 @@
+class MatestackComponentGenerator < Rails::Generators::NamedBase
+  source_root File.expand_path('templates', __dir__)
+
+  class_option :dynamic, type: :boolean, default: false
+  class_option :scss, type: :boolean, default: false
+  class_option :haml, type: :boolean, default: false
+  class_option :namespace, type: :string
+
+  def create_matestack_component
+    @dynamic = options[:dynamic]
+    @namespace = options[:namespace]
+
+    # Future: Check for matestack-compatible namespacing!
+
+    to_be_created_files = ['.rb']
+    to_be_created_files << '.js' if options[:dynamic]
+    to_be_created_files << '.scss' if options[:scss]
+    to_be_created_files << '.haml' if options[:haml]
+
+    matestack_component_dir_path = "app/matestack/components/"
+    matestack_component_dir_path << "#{@namespace}/" unless @namespace.nil?
+
+    to_be_created_files.each do |file|
+      generator_path = matestack_component_dir_path + "/#{file_name}#{file}"
+      template "matestack_component#{file}.erb", generator_path
+    end
+
+  end
+
+end

lib/generators/matestack_component/templates/matestack_component.haml.erb

@@ -0,0 +1,5 @@
+.<%= file_name %>{@tag_attributes}
+  %div
+    This is your custom <%= class_name %> component
+  - if block_given?
+    = yield

lib/generators/matestack_component/templates/matestack_component.js.erb

@@ -0,0 +1,17 @@
+// Require your custom component in your application.js before usage
+// Place it below "//= require matestack-ui-core" using the following line:
+//= require <% unless @namespace.nil? %><%= @namespace %>/<% end %><%= file_name %>
+
+MatestackUiCore.Vue.component('custom<% unless @namespace.nil? %>-<%= @namespace %><% end %>-<%= file_name %>', {
+  mixins: [MatestackUiCore.componentMixin],
+  data: function() {
+    return {
+      foo: 'bar'
+    };
+  },
+  methods: {},
+  mounted: function(){
+    // this is your completeness check and should be deleted before deployment
+    console.log('Custom Dynamic Component <%= class_name %> mounted!')
+  }
+});

lib/generators/matestack_component/templates/matestack_component.rb.erb

@@ -0,0 +1,13 @@
+class Components::<% unless @namespace.nil? %><%= @namespace.camelize %>::<% end %><%= class_name %> < Matestack::Ui::<% if @dynamic == true %>DynamicComponent<% else %>StaticComponent<% end %>
+
+  def prepare
+    # DB queries and API calls go here
+  end
+
+  def response
+    components {
+      # orchestrate existing matestack components here
+    }
+  end
+
+end

lib/generators/matestack_component/templates/matestack_component.scss.erb

@@ -0,0 +1 @@
+// your styles for the component <%= class_name %> go here