platforms-core 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 63ca19d9929e26203496937d12e14635c4581e55c4f46df446f64c09c7236729
-  data.tar.gz: ddab12ef1680d7ec7ff8df9099f05f662a9a0ee483719aa13b58a89920147a5a
+  metadata.gz: 635a8202983e8824756c06d3d17d240c0f5b7de960da2d962fb566511a8ed517
+  data.tar.gz: 24b2cbf4024362c01ecb502ea933279740ed30f8b758cd0c9d1199f09f4e7685
 SHA512:
-  metadata.gz: d8043793edf1f427b4db0f4e96cf335f01803eeec53fd9cda8fde45992ad2da9d63b6bcebd35303c4e014ea7e7e5528a55ed4948d33e45369be7a92d02e9aba4
-  data.tar.gz: 6505d451a04186dc268e80f0b7048ed1667eaba1323ecb78b530c69a166f0a12f7ea159207dec332bc43c23eef4f1ad831e896e879ab5ea14d7970be48189424
+  metadata.gz: 3051fc09751fc8f5e0d61fe38f8ed6ff08cca2c87b328416c3f62cab6cdfdde4acb58cfc48b9ddc3bf8df78fc2027dffafbfaac83ea520ac84145132e158829f
+  data.tar.gz: f7294f4060c51e25fffbccaba08010c0baef619f10796b8c621770ca5314a50ea7569c4a3d90c1497e2fe6e25453b33545f77a52e2e5d60f9720bb414374571e

data/README.md

@@ -32,55 +32,88 @@ Or install it yourself as:
 $ gem install platforms-core
 ```
 
-Once the gem is installed, from your Rails directory you will need to install the gem's migrations:
+Once the gem is installed, from your Rails directory you will can run the following generator to complete the installation:
 
 ```bash
-$ rake platforms_core:install:migrations
+$ rails generate platforms:core:install
 ```
 
+This will:
+
+* Copy a basic initializer to `config/initializers/platforms_core.rb`; and
+* Install the gem's migrations into your application.
+
 ## Configuration
 
 REST-based APIs require authentication to get started. Please refer to
 your platform for instructions on how to do this.
 
-The gem assumes that you have a class called `User` and a class called `Network` which might look something like the following:
+### Starting a New App
+
+Your application needs to have at least `Network` and `User` models. These can be created by calling the generator:
+
+```bash
+$ rails generate platform:core:network foo some_info:string
+$ rails generate platform:core:user bar user more_info:string
+```
+
+Most of the options for the regular ActiveRecord model generator are available, including namespacing and indexing.
+
+This is roughly equivalent to calling the standard Rails model generators (`rails g model foo some_info:string`), however by using the above version the resulting models are configured by Platforms::Core as the `Network` or `User` models.
+
+Typically these would be called "Network" and "User", but here we have called them "Foo" and "Bar".
+
+### Adding to an Existing App
+
+If you already have `Network` and `User` models (which let's assume are called "Foo" and "Bar" respectively), you can add the relevant configuration by using the generator with the `--existing-model` flag:
+
+```bash
+$ rails generate platform:core:network foo --existing-model
+$ rails generate platform:core:user bar --existing-model
+```
+
+This will add the relevant concerns to the models, and update the initializer, without needing to create models from scratch.
+
+### Manual Configuration
+
+Finally, if you don't want to use the built-in generators then you can always create the models and configuration manually. The models should look something like this for a `Network`:
 
 ```ruby
-class User < ApplicationRecord
+# app/models/network.rb
 
-  # A User belongs to a Platforms::User
-  belongs_to :platforms_user,
-    class_name: "Platforms::User",
-    inverse_of: :app_user
+class Network < ApplicationRecord
+  include Platforms::Core::AppNetwork
+
+  # This requires an integer database column called
+  # 'platforms_network_id'
 
-  # Ensure a User only maps to one Platforms::User
-  validates :platforms_user_id, uniqueness: true
+  # ...
 end
 ```
-and Network:
+
+and for a `User`:
 
 ```ruby
-class Network < ApplicationRecord
+# app/models/user.rb
+
+class User < ApplicationRecord
+  include Platforms::Core::AppUser
 
-  # A Network belongs to a Platforms::Network
-  belongs_to :platforms_network,
-    class_name: "Platforms::Network",
-    inverse_of: :app_network
+  # This requires an integer database column called
+  # 'platforms_user_id'
 
-  # Ensure a Network only maps to one Platforms::Network
-  validates :platforms_network_id, uniqueness: true
+  # ...
 end
 ```
 
-If you need the User and Network classes to be named differently,
-use configurations:
+Additionally, you will need to create an initializer which configures the `Network` and `User` classes for the gem:
 
 ```ruby
 # config/initializers/platforms.rb
 
 Platforms::Core.configure do |config|
-  config.network_class = "SampleNetwork"
-  config.user_class    = "SampleUser"
+  config.network_class = "Foo"
+  config.user_class    = "Bar"
 end
 ```
 

data/lib/generators/platforms/core/base.rb

@@ -0,0 +1,96 @@
+require "rails/generators/active_record"
+
+module Platforms
+  module Core
+    # Generators to simpify installing Platforms::Core
+    module Generators
+
+      # These are common functions that apply to both User and Network model types.
+      # The setup for both is really quite similar:
+      # * Generating a model, or creating a migration to add an association column
+      # * Add the relevant Concern to the Model
+      # * Update the initializer to reference the new class
+      class Base < Rails::Generators::NamedBase
+        include ActiveRecord::Generators::Migration
+
+        source_root File.join(__dir__, "templates")
+
+        argument :attributes, type: :array, default: [], banner: "field[:type][:index] field[:type][:index]"
+
+        # Don't do check_class_collision here. It can be done within
+        # create_model instead, if required.
+
+        class_option :migration, type: :boolean
+        class_option :timestamps, type: :boolean
+        class_option :parent, type: :string, desc: "The parent class for the generated model"
+        class_option :indexes, type: :boolean, default: true, desc: "Add indexes for references and belongs_to columns"
+        class_option :primary_key_type, type: :string, desc: "The type for primary key"
+        class_option :database, type: :string, aliases: %i(--db), desc: "The database for your model's migration. By default, the current environment's primary database is used."
+
+        # Platforms-specific class option
+        class_option :existing_model, type: :boolean, default: false, desc: "Use existing model. Do not generate a new model definition"
+
+        # Create the model, unless --existing_model is specified.
+        # Calls the standard rails model generator, so should accept similar arguments
+        # to 'rails g model Foo'.
+        def create_model
+          return if options[:existing_model]
+          args = [name]
+          args << "platforms_#{concern_type}_id:integer"
+
+          # Recreate arguments
+          attributes.each do |a|
+            args << "#{a.name}:#{a.type}#{a.has_index? ? ":index" : "" }"
+          end
+
+          # Recreate options
+          options.each do |k, v|
+            unless k == "existing_model"
+              args << "--#{k}=#{v}"
+            end
+          end
+
+          # Use the standard model generator
+          generate "model", args.join(" ")
+        end
+
+        # Create a migration, when a model already exists.
+        # This could be for platforms_network_id or platforms_user_id.
+        def create_migration
+          return unless options[:existing_model]
+          migration_name = table_name.classify.pluralize
+          args = "AddPlatformsNetworkIdTo#{migration_name} platforms_#{concern_type}_id:integer"
+          generate "migration", args
+        end
+
+        # Adds the relevant concern to the network or user model.
+        # This is either Platforms::Core:AppNetwork or Platforms::Core::AppUser
+        # #file_name is inherited from Rails::Generators::NamedBase, according
+        # to https://guides.rubyonrails.org/generators.html
+        def add_concern_to_model
+
+          # Add the concern line
+          model_file_path = File.join("app", "models", class_path, "#{file_name}.rb")
+          inject_into_class model_file_path, class_name do
+            "  include Platforms::Core::App#{concern_type.capitalize}\n\n"
+          end
+        end
+
+        # Set a line in the initializer to 'config.network_class = "Network"'
+        # or similar. This could also be 'config.user_class = "MyUser"'
+        #
+        # Rather than gsub, matching config lines are removed and then added again.
+        def edit_initializer
+          init = "config/initializers/platforms_core.rb"
+          gsub_file init, /\s*config.#{concern_type}_class\s+= .*\n/, "\n"
+
+          inject_into_file init, after: "Platforms::Core.configure do |config|\n" do
+            "  config.#{concern_type}_class = \"#{class_name}\"\n"
+          end
+
+        end
+
+      end
+    end
+  end
+end

data/lib/generators/platforms/core/install/USAGE

@@ -0,0 +1,11 @@
+Description:
+    This will install the required migrations, and set up the initializer
+
+Example:
+    rails generate platforms:core:install
+
+    This will create:
+      The initializer in config/initializers/platforms_core.rb
+      Run $ rake patforms_core:install:migrations
+
+      Note that it will not run the migrations

data/lib/generators/platforms/core/install/install_generator.rb

@@ -0,0 +1,26 @@
+require 'rails/generators'
+
+module Platforms
+  module Core
+
+    # Simplify the installation of Platforms::Core by creating an
+    # initializer file and installing the migrations.
+    # This does not run the migrations.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      # Create config/initializers/platforms_core.rb according to the template.
+      def copy_initializer_file
+        copy_file "platforms_core.rb", "config/initializers/platforms_core.rb"
+      end
+
+      # Install the gem's migrations.
+      # This is equivalent to the built-in rake task
+      # "platforms_core:install:migrations"
+      def install_migrations
+        rake "platforms_core:install:migrations"
+      end
+
+    end
+  end
+end

data/lib/generators/platforms/core/install/templates/platforms_core.rb

@@ -0,0 +1,13 @@
+# This file has been generated by the installer
+# $ rails generate platforms:core:install
+#
+# To change the Network and User class, edit this file.
+# It will also be automatically updated when either of the
+# following generators are run:
+# $ rails generate platforms:core:network [args]
+# $ rails generate platforms:core:user [args]
+
+Platforms::Core.configure do |config|
+  config.network_class = "Network"
+  config.user_class = "User"
+end

data/lib/generators/platforms/core/network/USAGE

@@ -0,0 +1,14 @@
+Description:
+    Create a Network model, and include the relevant Platforms::Core Concern.
+    This will also set the relevant Network configuration in
+    config/initializers/plaforms_core.rb.
+
+Example:
+    rails generate platforms:core:network blah more_info:string
+
+    This will create the Blah model, including migration, and test suite.
+    It will have a string column called "more_info".
+    The concern is then included in app/models/blah.rb
+
+    Also works for namespaced models, and accepts similar arguments
+    as the ActiveRecord generator (database columns, associations).

data/lib/generators/platforms/core/network/network_generator.rb

@@ -0,0 +1,19 @@
+# require "platforms/core/generators/base"
+require "generators/platforms/core/base"
+
+module Platforms
+  module Core
+
+    # Create a model, with Platforms::Core specific additions for the
+    # 'Network' class that should be implemented by the parent
+    # application.
+    class NetworkGenerator < Platforms::Core::Generators::Base
+
+      # Set the concern_type to network
+      def concern_type
+        "network"
+      end
+
+    end
+  end
+end

data/lib/generators/platforms/core/user/USAGE

@@ -0,0 +1,14 @@
+Description:
+    Create a User model, and include the relevant Platforms::Core Concern.
+    This will also set the relevant User configuration in
+    config/initializers/plaforms_core.rb.
+
+Example:
+    rails generate platforms:core:user blah more_info:string
+
+    This will create the Blah model, including migration, and test suite.
+    It will have a string column called "more_info".
+    The concern is then included in app/models/blah.rb
+
+    Also works for namespaced models, and accepts similar arguments
+    as the ActiveRecord generator (database columns, associations).

data/lib/generators/platforms/core/user/user_generator.rb

@@ -0,0 +1,19 @@
+#require "platforms/core/generators/base"
+require "generators/platforms/core/base"
+
+module Platforms
+  module Core
+
+    # Create a model, with Platforms::Core specific additions for the
+    # 'User' class that should be implemented by the parent
+    # application.
+    class UserGenerator < Platforms::Core::Generators::Base
+
+      # Set the concern_type to user.
+      def concern_type
+        "user"
+      end
+
+    end
+  end
+end

data/lib/platforms/core.rb

@@ -1,8 +1,12 @@
+require "platforms/core/app_network"
+require "platforms/core/app_user"
 require "platforms/core/configuration"
 require "platforms/core/engine"
 require "platforms/core/omni_auth_setup"
 require "platforms/core/o_auth_2"
 
+require "generators/platforms/core/install/install_generator"
+
 # The top level namespace for Platforms, which includes Core and
 # other vendor-specific implementations.
 module Platforms

data/lib/platforms/core/app_network.rb

@@ -0,0 +1,19 @@
+module Platforms
+  module Core
+    # Add the relevant associations to a Network-type class.
+    module AppNetwork
+      extend ActiveSupport::Concern
+
+      included do
+        # A valid association object is required from Rails 5 onwards,
+        # unless otherwise specified.
+        belongs_to :platforms_network,
+          class_name: "Platforms::Network",
+          inverse_of: :app_network
+
+        # Ensure AppNetwork only maps to one Platforms::Network
+        validates :platforms_network_id, uniqueness: true
+      end
+    end
+  end
+end

data/lib/platforms/core/app_user.rb

@@ -0,0 +1,19 @@
+module Platforms
+  module Core
+    # Add the relevant associations to a User-type class.
+    module AppUser
+      extend ActiveSupport::Concern
+
+      included do
+        # A valid association object is required from Rails 5 onwards,
+        # unless otherwise specified.
+        belongs_to :platforms_user,
+          class_name: "Platforms::User",
+          inverse_of: :app_user
+
+        # Ensure AppUser only maps to one Platforms::User
+        validates :platforms_user_id, uniqueness: true
+      end
+    end
+  end
+end

data/lib/platforms/core/o_auth_2.rb

@@ -3,7 +3,6 @@ module Platforms
 
     # This is a module for common authentication methods, across multiple
     # platforms.
-    # @todo extract out the common functionality.
     module OAuth2
       extend ActiveSupport::Concern
 

data/lib/platforms/core/version.rb

@@ -2,6 +2,6 @@ module Platforms
   module Core
 
     # Version for display. Update as required.
-    VERSION = '0.1.2'
+    VERSION = '0.1.3'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: platforms-core
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Benjamin Elias
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-04-10 00:00:00.000000000 Z
+date: 2020-04-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -100,6 +100,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: generator_spec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: hashie
   requirement: !ruby/object:Gem::Requirement
@@ -208,7 +222,17 @@ files:
 - db/migrate/20200308091132_create_platforms_groups.rb
 - db/migrate/20200308091141_create_platforms_group_members.rb
 - db/migrate/20200313102128_create_platforms_certificates.rb
+- lib/generators/platforms/core/base.rb
+- lib/generators/platforms/core/install/USAGE
+- lib/generators/platforms/core/install/install_generator.rb
+- lib/generators/platforms/core/install/templates/platforms_core.rb
+- lib/generators/platforms/core/network/USAGE
+- lib/generators/platforms/core/network/network_generator.rb
+- lib/generators/platforms/core/user/USAGE
+- lib/generators/platforms/core/user/user_generator.rb
 - lib/platforms/core.rb
+- lib/platforms/core/app_network.rb
+- lib/platforms/core/app_user.rb
 - lib/platforms/core/configuration.rb
 - lib/platforms/core/engine.rb
 - lib/platforms/core/o_auth_2.rb