tramway 0.2.2 → 0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12b9bb73f91f5c694ee64efaa36d66a5ee68c6b41066a5e775b42e4ba81678d4
-  data.tar.gz: 79c240ff539d4762fb8a2c4b3fe29ff05805c2699e12225d53038fafb53c5a1d
+  metadata.gz: 5e8751e6e662061508bb687b258c13f3dcb40460344959595a66c998608e38af
+  data.tar.gz: 66076bba6be9af35c2e787bf43e8e6cb00877bd5f5b53cf4b70ce37a09f78c2b
 SHA512:
-  metadata.gz: 5ccd8cdeb8bb8b9df08d4885ff473e68ef7a29f5980460050e52db4d7b7b758da170cabece248f78589dbc102d47f1ae4c3ee1410d50d8103cbb4ffc549d0a2e
-  data.tar.gz: 58c752011aa51d3c0afd9e074380411657a390b0a09568226de9d4c38b033d1b9b23f172b27af2a3ae137bc342185fad3736085412025d66cac4dab68e4ff994
+  metadata.gz: aec595653662af5dfe38f8d402dd799d8da2ad77ba8c3e032aba22c56020467f9b4ee1f701a07e7477ecbd34ff7725c32fac18a6a359513e064dbbdc567d703c
+  data.tar.gz: 5e1799a4d4290ac7bf5e9bd8c1fe524119eb4449ffe0ddeccb3ecf934343160672572c22e834f76a7bebe522d4ca226aa08ce8336ba1f56f88dc53fe692eba72

data/README.md

@@ -1,6 +1,13 @@
 # Tramway
 Unite Ruby on Rails brilliance. Streamline development with Tramway.
 
+* [Installation](https://github.com/Purple-Magic/tramway#installation)
+* [Usage](https://github.com/Purple-Magic/tramway#usage)
+  * [Tramway Entities](https://github.com/Purple-Magic/tramway#tramway-entities)
+  * [Tramway Decorators](https://github.com/Purple-Magic/tramway#tramway-decorators)
+  * [Tramway Form](https://github.com/Purple-Magic/tramway#tramway-form)
+  * [Tramway Navbar](https://github.com/Purple-Magic/tramway#tramway-navbar)
+
 ## Installation
 Add this line to your application's Gemfile:
 
@@ -26,9 +33,22 @@ end
 
 By default, links to the Tramway Entities index page are rendered in [Tramway Navbar](https://github.com/Purple-Magic/tramway#tramway-navbar).
 
-### Tailwind components
+#### Define entities with options
 
-Tramway uses [Tailwind](https://tailwindcss.com/) by default. All UI helpers are implemented with [ViewComponent](https://github.com/viewcomponent/view_component).
+Tramway Entity supports several options that are used in different features.
+
+**route**
+
+*config/initializers/tramway.rb*
+```ruby
+Tramway.configure do |config|
+  config.entities = [
+    { name: :user, route: { namespace: :admin } },                                 # `admin_users_path` link in the Tramway Navbar
+    { name: :podcast, route: { route_method: :shows } },                           # `shows_path` link in the Tramway Navbar
+    { name: :episodes, route: { namespace: :podcasts, route_method: :episodes } }, # `podcasts_episodes_path` link in the Tramway Navbar
+  ]
+end
+```
 
 ### Tramway Decorators
 
@@ -80,6 +100,152 @@ def show
 end
 ```
 
+### Tramway Form
+
+Tramway provides **convenient** form objects for Rails applications. List properties you want to change and the rules in Form classes. No controllers overloading.
+
+*app/forms/user_form.rb
+```ruby
+class UserForm < Tramway::BaseForm
+  properties :email, :password, :first_name, :last_name, :phone
+
+  def password=(value)
+    object.password = value if value.present?
+  end
+end
+```
+
+**Controllers without Tramway Form**
+
+*app/controllers/users_controller.rb*
+```ruby
+class UsersController < ApplicationController
+  def create
+    @user = User.new
+    if @user.save user_params
+      render :show
+    else
+      render :new
+    end
+  end
+
+  def update
+    @user = User.find params[:id]
+    if @user.save user_params
+      render :show
+    else
+      render :edit
+    end
+  end
+  
+  private
+
+  def user_params
+    params[:user].permit(:email, :password, :first_name, :last_name, :phone)
+  end
+end
+```
+
+**Controllers with Tramway Form**
+
+*app/controllers/users_controller.rb*
+```ruby
+class UsersController < ApplicationController
+  def create
+    @user = tramway_form User.new
+    if @user.submit params[:user]
+      render :show
+    else
+      render :new
+    end
+  end
+
+  def update
+    @user = tramway_form User.find params[:id]
+    if @user.submit params[:user]
+      render :show
+    else
+      render :edit
+    end
+  end
+end
+```
+
+#### Implement Form objects for any case
+
+*app/forms/user_updating_email_form.rb*
+```ruby
+class UserUpdatingEmailForm < Tramway::BaseForm
+  properties :email
+end
+```
+
+*app/controllers/updating_emails_controller.rb*
+```ruby
+def update
+  @user = UserUpdatingEmailForm.new User.find params[:id]
+  if @user.submit params[:user]
+    # success
+  else
+    # failure
+  end
+end
+```
+
+#### Create form namespaces
+
+*app/forms/admin/user_form.rb*
+```ruby
+class Admin::UserForm < Tramway::BaseForm
+  properties :email, :password, :first_name, :last_name, :etc
+end
+```
+
+*app/controllers/admin/users_controller.rb*
+```ruby
+class Admin::UsersController < Admin::ApplicationController
+  def create
+    @user = tramway_form User.new, namespace: :admin
+    if @user.submit params[:user]
+      render :show
+    else
+      render :new
+    end
+  end
+
+  def update
+    @user = tramway_form User.find(params[:id]), namespace: :admin
+    if @user.submit params[:user]
+      render :show
+    else
+      render :edit
+    end
+  end
+end
+```
+
+### Make flexible and extendable forms
+
+Tramway Form properties are not mapped to a model. You're able to make extended forms.
+
+*app/forms/user_form.rb*
+```ruby
+class UserForm < Tramway::BaseForm
+  properties :email, :password, :full_name
+
+  # RULE: in case password is empty, don't save
+  def password=(value)
+    object.password = value if value.present?
+  end
+
+  # EXTENDED FIELD: full name
+  def full_name=(value)
+    object.first_name = value.split(' ').first
+    object.last_name = value.split(' ').last
+  end
+end
+```
+
 ### Tramway Navbar
 
 Tramway provides DSL for rendering Tailwind Navgiation bar.
@@ -146,6 +312,10 @@ tramway_navbar title: 'Purple Magic' do |nav|
 end
 ```
 
+### Tailwind components
+
+Tramway uses [Tailwind](https://tailwindcss.com/) by default. All UI helpers are implemented with [ViewComponent](https://github.com/viewcomponent/view_component).
+
 ## Contributing
 
 Install [lefthook](https://github.com/evilmartians/lefthook)

data/lib/tramway/base_form.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Tramway
+  # Provides form object for Tramway
+  #
+  class BaseForm
+    attr_reader :object
+
+    %i[model_name to_key to_model errors attributes].each do |method_name|
+      delegate method_name, to: :object
+    end
+
+    def initialize(object)
+      @object = object
+    end
+
+    class << self
+      def property(attribute, _proc_obj = nil)
+        @properties ||= []
+        @properties << attribute
+
+        delegate attribute, to: :object
+      end
+
+      def properties(*attributes)
+        if attributes.any?
+          attributes.each do |attribute|
+            property(attribute)
+          end
+        else
+          @properties || []
+        end
+      end
+    end
+
+    def submit(params)
+      __submit params
+
+      object.save.tap do
+        __object
+      end
+    end
+
+    def submit!(params)
+      __submit params
+
+      object.save!.tap do
+        __object
+      end
+    end
+
+    def method_missing(method_name, *args)
+      if method_name.to_s.end_with?('=') && args.count == 1
+        object.public_send(method_name, args.first)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      method_name.to_s.end_with?('=') || super
+    end
+
+    private
+
+    def __submit(params)
+      self.class.properties.each do |attribute|
+        public_send("#{attribute}=", params[attribute])
+      end
+    end
+
+    def __object
+      object.persisted? ? object.reload : object
+    end
+  end
+end

data/lib/tramway/config.rb

@@ -15,7 +15,9 @@ module Tramway
 
     def entities=(collection)
       @entities = collection.map do |entity|
-        Tramway::Configs::Entity.new(name: entity)
+        entity_options = entity.is_a?(Hash) ? entity : { name: entity }
+
+        Tramway::Configs::Entity.new(**entity_options)
       end
     end
 

data/lib/tramway/configs/entities/route.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Tramway
+  module Configs
+    module Entities
+      # Route struct describes rules for route management
+      #
+      class Route < Dry::Struct
+        attribute? :namespace, Types::Coercible::String
+        attribute? :route_method, Types::Coercible::String
+
+        def helper_method_by(underscored_name)
+          "#{[namespace, route_method || underscored_name].compact.join('_')}_path"
+        end
+      end
+    end
+  end
+end

data/lib/tramway/configs/entity.rb

@@ -1,24 +1,44 @@
 # frozen_string_literal: true
 
+require 'tramway/configs/entities/route'
+
 module Tramway
   module Configs
-    # Tramway is entity based framework
-    #
-    class Entity
-      attr_reader :name
+    # Tramway is an entity-based framework
+    class Entity < Dry::Struct
+      attribute :name, Types::Coercible::String
+      attribute? :route, Tramway::Configs::Entities::Route
 
-      def initialize(name:)
-        @name = name.to_s
+      def routes
+        OpenStruct.new index: Rails.application.routes.url_helpers.public_send(route_helper_method)
       end
 
-      def routes
-        underscored_name = name.parameterize.pluralize.underscore
+      def human_name
+        options = if model_class.present?
+                    model_name = model_class.model_name.human
+                    { single: model_name, plural: model_name.pluralize }
+                  else
+                    { single: name.capitalize, plural: name.pluralize.capitalize }
+                  end
+        OpenStruct.new(**options)
+      end
+
+      private
 
-        OpenStruct.new index: Rails.application.routes.url_helpers.public_send("#{underscored_name}_path")
+      def model_class
+        name.camelize.constantize
+      rescue StandardError
+        nil
       end
 
-      def human_name
-        OpenStruct.new single: name.capitalize, plural: name.pluralize.capitalize
+      def route_helper_method
+        underscored_name = name.parameterize.pluralize.underscore
+
+        if route.present?
+          route.helper_method_by(underscored_name)
+        else
+          "#{underscored_name}_path"
+        end
       end
     end
   end

data/lib/tramway/engine.rb

@@ -18,6 +18,12 @@ module Tramway
 
         loaded_class.include Tramway::Helpers::DecorateHelper
       end
+
+      ActiveSupport.on_load(:action_controller) do |loaded_class|
+        require 'tramway/helpers/form_helper'
+
+        loaded_class.include Tramway::Helpers::FormHelper
+      end
     end
   end
 end

data/lib/tramway/forms/class_helper.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Tramway
+  module Forms
+    # Provides method to determine decorators classes
+    module ClassHelper
+      module_function
+
+      def form_class(object, form, namespace)
+        object_class = object.class
+
+        if form.present?
+          form
+        elsif namespace.present?
+          "#{namespace.to_s.camelize}::#{object_class}Form".constantize
+        else
+          "#{object_class}Form".constantize
+        end
+      end
+    end
+  end
+end

data/lib/tramway/helpers/form_helper.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'tramway/forms/class_helper'
+
+module Tramway
+  module Helpers
+    # Provides methods into Rails ActionController
+    #
+    module FormHelper
+      def tramway_form(object, form: nil, namespace: nil)
+        Tramway::Forms::ClassHelper.form_class(object, form, namespace).new object
+      end
+    end
+  end
+end

data/lib/tramway/navbar.rb

@@ -51,8 +51,6 @@ module Tramway
       filling_side :left
 
       entities.each do |entity|
-        entity.to_s.pluralize
-
         item entity.human_name.plural, entity.routes.index
       end
 

data/lib/tramway/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Tramway
-  VERSION = '0.2.2'
+  VERSION = '0.3'
 end

data/lib/tramway.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
+require 'types'
 require 'tramway/version'
 require 'tramway/engine'
 require 'tramway/base_decorator'
+require 'tramway/base_form'
 require 'tramway/config'
 require 'view_component/compiler'
 require 'view_component/engine'

data/lib/types.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'dry-struct'
+
+# We need because of this https://dry-rb.org/gems/dry-struct/1.6/recipes/
+module Types
+  include Dry.Types()
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tramway
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: '0.3'
 platform: ruby
 authors:
 - kalashnikovisme
@@ -9,8 +9,22 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-07-26 00:00:00.000000000 Z
+date: 2023-09-04 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: dry-struct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: haml-rails
   requirement: !ruby/object:Gem::Requirement
@@ -88,16 +102,21 @@ files:
 - lib/tasks/tramway_tasks.rake
 - lib/tramway.rb
 - lib/tramway/base_decorator.rb
+- lib/tramway/base_form.rb
 - lib/tramway/config.rb
+- lib/tramway/configs/entities/route.rb
 - lib/tramway/configs/entity.rb
 - lib/tramway/decorators/class_helper.rb
 - lib/tramway/decorators/collection_decorator.rb
 - lib/tramway/engine.rb
+- lib/tramway/forms/class_helper.rb
 - lib/tramway/helpers/decorate_helper.rb
+- lib/tramway/helpers/form_helper.rb
 - lib/tramway/helpers/navbar_helper.rb
 - lib/tramway/navbar.rb
 - lib/tramway/utils/render.rb
 - lib/tramway/version.rb
+- lib/types.rb
 homepage: https://github.com/purple-magic/tramway
 licenses:
 - MIT