rectify 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4347cd2896dcb19ca5f47ac3934c433d81668ac3
-  data.tar.gz: 377299eed0a96ce220b70e0967ba77fbcbe4512b
+  metadata.gz: d7db41f0a655c68a1cc60f253b0bca46e049be1e
+  data.tar.gz: 18cff71a5e52be32ec14c25df243b3aa1bdb4338
 SHA512:
-  metadata.gz: 0f7a0a7f6d15d47b15283bd123118af5c3d1a4ea6a996eb1e7bd206bbb10bf761b7a3cdfb5fa91df5bc50cab9593b57fa9ea4e7acdfc819a142f0ddff6e9bd54
-  data.tar.gz: 25af13f81a98dea2be0918b1a1710e5ef8e3df87650ce5cf3811275fe1e75e91e6af07fe5db2da293b21f5ef41a198c3fc52c78703499f82f082d00250afb7ec
+  metadata.gz: c014786d12349c161f38d17d5249156fc206e21fa43da1061d4237f72778a17ca2190353eb99d6a004ae39a2a5abbe9a9bbede7c0aaff187aa8fd62c2f3f3f4d
+  data.tar.gz: 16590d5c8313f1570612c1fc7d0308a0e3b848ed8cc8bb20c5afcb9ce073434abec5a68383c70f2e5896b51c77d5d242e62dcbfc583157655b23e79d03dfb1d5

data/lib/rectify/{controller.rb → controller_helpers.rb}

@@ -1,5 +1,5 @@
 module Rectify
-  module Controller
+  module ControllerHelpers
     def self.included(base_class)
       base_class.helper_method(:presenter)
     end

data/lib/rectify/form.rb

@@ -7,7 +7,9 @@ module Rectify
 
     def self.from_params(params, additional_params = {})
       params     = params.with_indifferent_access
-      attributes = params.fetch(mimicked_model_name, {}).merge(additional_params)
+      attributes = params
+        .fetch(mimicked_model_name, {})
+        .merge(additional_params)
 
       new(attributes).tap do |f|
         f.id = params[:id]

data/lib/rectify/presenter.rb

@@ -23,7 +23,9 @@ module Rectify
     attr_reader :controller
 
     def view_context
-      controller && controller.view_context
+      @view_context ||= begin
+        controller && controller.view_context
+      end
     end
   end
 end

data/lib/rectify/version.rb

@@ -1,3 +1,3 @@
 module Rectify
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/rectify.rb

@@ -9,4 +9,4 @@ require "rectify/form"
 require "rectify/command"
 require "rectify/save_command"
 require "rectify/presenter"
-require "rectify/controller"
+require "rectify/controller_helpers"

data/readme.md

@@ -25,15 +25,17 @@ bundle install
 
 Currently, Rectify consists of the following concepts:
 
-* Form Objects
-* Commands
-* Presenters
+* [Form Objects](#form-objects)
+* [Commands](#commands)
+* [Presenters](#presenters)
 
 You can use these separately or together to improve the structure of your Rails
 applications.
 
-The main problem that Rectify tries to solve is where your logic should go. Commonly,
-business logic is either placed in the controller or the model and the views are filled with too much logic. The opinion of Rectify is that these places are incorrect and that your models in particular are doing too much.
+The main problem that Rectify tries to solve is where your logic should go.
+Commonly, business logic is either placed in the controller or the model and the
+views are filled with too much logic. The opinion of Rectify is that these
+places are incorrect and that your models in particular are doing too much.
 
 Rectify's opinion is that controllers should just be concerned with HTTP related
 things and models should just be concerned with data access. The problem then
@@ -42,14 +44,16 @@ becomes, how and where do you place validations and other business logic.
 Using Rectify, the Form Objects contain validations and represent the data input
 of your system. Commands then take a Form Object (as well as other data) and
 perform a single action which is invoked by a controller. Presenters contain the
-presentation logic in a way that is easily testable and keeps your views as clean
-as possible.
+presentation logic in a way that is easily testable and keeps your views as
+clean as possible.
 
-Here's an example controller that shows details about a user and also allows a user to register an account. This creates a user, sends some emails, does some special auditing and integrates with a third party system:
+Here's an example controller that shows details about a user and also allows a
+user to register an account. This creates a user, sends some emails, does some
+special auditing and integrates with a third party system:
 
 ```ruby
 class UserController < ApplicationController
-  include Rectify::Controller
+  include Rectify::ControllerHelpers
 
   def show
     present UserDetailsPresenter.new(:user => current_user)
@@ -71,9 +75,10 @@ class UserController < ApplicationController
 end
 ```
 
-The `RegistrationForm` Form Object encapsulates the relevant data that is required for the
-action and the `RegisterAccount` Command encapsulates the business logic of registering
-a new account. The controller is clean and business logic now has a natural home:
+The `RegistrationForm` Form Object encapsulates the relevant data that is
+required for the action and the `RegisterAccount` Command encapsulates the
+business logic of registering a new account. The controller is clean and
+business logic now has a natural home:
 
 ```
 HTTP           => Controller  (redirecting, rendering, etc)
@@ -88,6 +93,21 @@ and Presenters.
 
 ## Form Objects
 
+The role of the Form Object is to mange the input data for a given action. It
+validates data and only allows whitelisted attributes (replacing the need for
+Strong Parameters). This is a departure from "The Rails Way" where the model
+contains the validations. Form Objects help to reduce the weight of your models
+for one, but also, in an app of reasonable complexity even simple things like
+validations become harder because context is important.
+
+For example, you can add validation for a `User` model but there are different
+context where the validations change. When a user registers themselves you might
+have one set of validations, when an admin edits that user you might have
+another set, maybe even when a user edits themselves you may have a third. In
+"The Rails Way" you would have to have conditional validation in your model.
+With Rectify you can have a different Form Object per context and keep things
+easier to manage.
+
 Form objects in Rectify are based on [Virtus](https://github.com/solnic/virtus)
 and make them compatible with Rails form builders, add ActiveModel validations
 and all allow you to specify a model to mimic.
@@ -103,7 +123,8 @@ class UserForm < Rectify::Form
 end
 ```
 
-You can then set that up in your controller instead of a normal ActiveRecord model:
+You can then set that up in your controller instead of a normal ActiveRecord
+model:
 
 ```ruby
 class UsersController < ApplicationController
@@ -133,13 +154,14 @@ You can use the form object with form builders such as
 
 ### Mimicking models
 
-When the form is generated it uses the name of the form class to infer what "model"
-it should mimic. In the example above, it will mimic the `User` model as it removes
-the `Form` suffix from the form class name by default.
+When the form is generated it uses the name of the form class to infer what
+"model" it should mimic. In the example above, it will mimic the `User` model
+as it removes the `Form` suffix from the form class name by default.
 
 The model being mimicked affects two things about the form:
 
-1. The route path helpers to use as the url to post to, for example: `users_path`.
+1. The route path helpers to use as the url to post to, for example:
+`users_path`.
 2. The parent key in the params hash that the controller receives, for example
 `user` in this case:
 
@@ -178,15 +200,15 @@ You define your attributes for your form object just like you do in
 [Virtus](https://github.com/solnic/virtus).
 
 By default, Rectify forms include an `id` attribute for you so you don't need to
-add that. We use this `id` attribute to fulfil some of the requirements of ActiveModel
-so your forms will work with form builders. For example, your form object has a
-`#persisted?` method. Your form object is never persisted so technically this
-should always return `false`.
+add that. We use this `id` attribute to fulfill some of the requirements of
+ActiveModel so your forms will work with form builders. For example, your form
+object has a `#persisted?` method. Your form object is never persisted so
+technically this should always return `false`.
 
 However, you are normally representing something that is persistable. So we use
 the value of `id` to workout if what this should return. If `id` is a number
-greater than zero then we assume it is persisted otherwise we assume it isn't. This
-is important as it affects where your form is posted (to the `#create` or
+greater than zero then we assume it is persisted otherwise we assume it isn't.
+This is important as it affects where your form is posted (to the `#create` or
 `#update` action in your controller).
 
 #### Populating attributes
@@ -210,9 +232,9 @@ the data in the request:
 form = UserForm.from_params(params)
 ```
 
-When populating from params we will populate the built in `id` attribute from the
-root of the params hash and populate the rest of the form attributes from within
-the parent key. For example:
+When populating from params we will populate the built in `id` attribute from
+the root of the params hash and populate the rest of the form attributes from
+within the parent key. For example:
 
 ```ruby
 params = {
@@ -232,7 +254,8 @@ form.last_name  # => "Pike"
 
 The other thing to notice is that (thanks to Virtus), attribute values are cast
 to the correct type. The params hash is actually all string based but when you
-get values from the form, they are returned as the correct type (see `id` above).
+get values from the form, they are returned as the correct type (see `id`
+above).
 
 In addition to the params hash, you may want to add additional contextual data.
 This can be done by supplying a second hash to the `.from_params` method.
@@ -265,10 +288,12 @@ form.last_name  # => "Pike"
 
 One important thing that is different about Rectify forms is that they are not
 bound by a model. You can use a model to populate the forms attributes but that
-is all it will do. It does not keep a reference to the model or interact with it.
-Rectify forms are designed to be lightweight representations of the data you want
-to collect or show in your forms, not something that is linked to a model. This
-allows you to create any form that you like which doesn't need to match the
+is all it will do. It does not keep a reference to the model or interact with
+it.
+
+Rectify forms are designed to be lightweight representations of the data you
+want to collect or show in your forms, not something that is linked to a model.
+This allows you to create any form that you like which doesn't need to match the
 representation of the data in the database.
 
 ### Validations
@@ -276,14 +301,15 @@ representation of the data in the database.
 Rectify includes `ActiveModel::Validations` for you so you can use all of the
 Rails validations that you are used to within your models.
 
-Your Form Object has a `#valid?` method that will validate the attributes of your
-form as well as any (deeply) nested form objects and array attributes that contain
-form objects.
+Your Form Object has a `#valid?` method that will validate the attributes of
+your form as well as any (deeply) nested form objects and array attributes that
+contain form objects. There is also an `#invalid?` method that returns the
+opposite of `#valid?`.
 
 ### Strong Parameters
 
-Did you notice in the example above that there was no mention of strong
-parameters. That's because with Form Objects you do not need strong parameters.
+Did you notice in the example above that there was no mention of Strong
+Parameters. That's because with Form Objects you do not need strong parameters.
 You only specify attributes in your form that are allowed to be accepted. All
 other data in your params hash is ignored.
 
@@ -292,19 +318,27 @@ about how to build a form object.
 
 ## Commands
 
+Commands (also known as Service Objects) are the home of your business logic.
+They allow you to simplify your models and controllers and allow them to focus
+on what they are responsible for. A Command should encapsulate a single user
+task such as registering for a new account or placing an order. You of course
+don't need to put all code for this task within the Command, you can (and
+should) create other classes that your Command uses to perform it's work.
+
+With regard to naming, Rectify suggests using verbs rather than nouns for
+Command class names, for example `RegisterAccount`, `PlaceOrder` or
+`GenerateEndOfYearReport`. Notice that we don't suffix commands with `Command`
+or `Service` or similar.
+
 Commands in Rectify are based on [Wisper](https://github.com/krisleech/wisper)
 which allows classes to broadcast events for publish/subscribe capabilities.
-`Rectify::Command` is a lightweight class that gives an alternate API and adds some
-helper methods to improve Command logic.
+`Rectify::Command` is a lightweight class that gives an alternate API and adds
+some helper methods to improve Command logic.
 
 The reason for using the pub/sub model rather than returning a result means that
 we can reduce the number of conditionals in our code as the outcome of a Command
 might be more complex than just success or failure.
 
-With regard to naming, Rectify suggests using verbs rather than nouns for Command
-class names, for example `RegisterAccount`, `PlaceOrder` or `GenerateEndOfYearReport`.
-Notice that we don't suffix commands with `Command` or `Service` or similar.
-
 Here is an example Command with the structure Rectify suggests (as seen in the
 overview above):
 
@@ -367,9 +401,9 @@ end
 
 When you call the `.call` class method, Rectify will instantiate a new instance
 of the command and will pass the parameters to it's constructor, it will then
-call the instance method `#call` on the newly created command object. The `.call`
-method also allows you to supply a block where you can handle the events that may
-have been broadcast from the command.
+call the instance method `#call` on the newly created command object. The
+`.call` method also allows you to supply a block where you can handle the events
+that may have been broadcast from the command.
 
 The events that your Command broadcasts can be anything, Rectify suggests `:ok`
 for success and `:invalid` if the form data is not valid, but it's totally up to
@@ -381,13 +415,13 @@ From here you can choose to implement your Command how you see fit. A
 ### Writing Commands
 
 As your application grows and Commands get more complex we recommend using the
-structure above. Within the `#call` method you first check that the input data is
-valid. If it is you then perform the various tasks that need to be completed.
+structure above. Within the `#call` method you first check that the input data
+is valid. If it is you then perform the various tasks that need to be completed.
 We recommend using private methods for each step that are well named which makes
 it very easy for anyone reading the code to workout what it does.
 
 Feel free to use other classes and objects where appropriate to keep your code
-well organised and maintainable.
+well organized and maintainable.
 
 ### Events
 
@@ -420,17 +454,18 @@ controller.
 
 You may occasionally want to expose a value within a handler block to the view.
 You do this via the `expose` method within the handler block. If you want to
-use `expose` then you must include the `Rectify::Controller` module in your
-controller. You pass a hash of the variables you wish to expose to the view and
-they will then be available. If you have set a Presenter for the view then
-`expose` will try to set an attribute on that presenter. If there is no Presenter
-or the Presenter doesn't have a matching attribute then `expose` will set an
-instance variable of the same name. See below for more details about Presenters.
+use `expose` then you must include the `Rectify::ControllerHelpers` module in
+your controller. You pass a hash of the variables you wish to expose to the view
+and they will then be available. If you have set a Presenter for the view then
+`expose` will try to set an attribute on that presenter. If there is no
+Presenter or the Presenter doesn't have a matching attribute then `expose` will
+set an instance variable of the same name. See below for more details about
+Presenters.
 
 ```ruby
 # within the controller:
 
-include Rectify::Controller
+include Rectify::ControllerHelpers
 
 def create
   present HomePresenter.new(:name => "Guest")
@@ -448,27 +483,27 @@ end
 # => <p>Hello Andy</p>
 ```
 
-Take a look at [Wisper](https://github.com/krisleech/wisper) for more information
-around how to do publish/subscribe.
+Take a look at [Wisper](https://github.com/krisleech/wisper) for more
+information around how to do publish/subscribe.
 
 ## Presenters
 
-A Presenter is a class that contains the presentational logic for your views. These
-are also known as an "exhibit", "view model", "view object" or just a "view" (Rails
-views are actually templates, but anyway). To avoid confusion Rectify calls these
-classes Presenters.
+A Presenter is a class that contains the presentational logic for your views.
+These are also known as an "exhibit", "view model", "view object" or just a
+"view" (Rails views are actually templates, but anyway). To avoid confusion
+Rectify calls these classes Presenters.
 
 It's often the case that you need some logic that is just for the UI. The same
 question comes up, where should this logic go? You could put it directly in the
 view, add it to the model or create a helper. Rectify's opinion is that all of
 these are incorrect. Instead, create a Presenter for the view (or component of
-the view) and place your logic here. These classes are easily testable and provide
-a more object oriented approach to the problem.
+the view) and place your logic here. These classes are easily testable and
+provide a more object oriented approach to the problem.
 
 To create a Presenter just derive off of `Rectify::Presenter`, add attributes as
-you do for Form Objects using [Virtus](https://github.com/solnic/virtus) `attribute`
-declaration. Inside a Presenter you have access to all view helper methods so
-it's easy to move the presetation logic here:
+you do for Form Objects using [Virtus](https://github.com/solnic/virtus)
+`attribute` declaration. Inside a Presenter you have access to all view helper
+methods so it's easy to move the presetation logic here:
 
 ```ruby
 class UserDetailsPresenter < Rectify::Presenter
@@ -482,9 +517,9 @@ class UserDetailsPresenter < Rectify::Presenter
 end
 ```
 
-Once you have a Presenter, you typically create it in your controller and make it
-accessible to your views. There are two ways to do that. The first way is to just
-treat it as a normal class:
+Once you have a Presenter, you typically create it in your controller and make
+it accessible to your views. There are two ways to do that. The first way is to
+just treat it as a normal class:
 
 ```ruby
 class UsersController < ApplicationController
@@ -497,20 +532,20 @@ end
 ```
 
 You need to call `#for_controller` and pass it a controller instance which will
-allow it access to the view helpers. You can then use the Presenter in your views
-as you would expect:
+allow it access to the view helpers. You can then use the Presenter in your
+views as you would expect:
 
 ```html
 <p><%= @presenter.edit_link %></p>
 ```
 
 The second way is a little cleaner as we have supplied a few helper methods to
-clean up remove some of the boilerplate. You need to include the `Rectify::Controller`
-module and then use the `present` helper:
+clean up remove some of the boilerplate. You need to include the
+`Rectify::ControllerHelpers` module and then use the `present` helper:
 
 ```ruby
 class UsersController < ApplicationController
-  include Rectify::Controller
+  include Rectify::ControllerHelpers
 
   def show
     user = User.find(params[:id])
@@ -533,14 +568,14 @@ method above or use the `present` method and add a `for` option with any key:
 
 ```ruby
 class ApplicationController < ActionController::Base
-  include Rectify::Controller
+  include Rectify::ControllerHelpers
 
   before_action { present LayoutPresenter.new(:user => user), :for => :layout }
 end
 ```
 
-To access this Presenter in the view, just pass the Presenter key to the `presenter`
-method like so:
+To access this Presenter in the view, just pass the Presenter key to the
+`presenter` method like so:
 
 ```html
 <p><%= presenter(:layout).login_link %></p>
@@ -548,12 +583,12 @@ method like so:
 
 ### Updating values of a Presenter
 
-After a presenter has been instantiated you can update it's values but just setting
-their attributes:
+After a presenter has been instantiated you can update it's values by just
+setting their attributes:
 
 ```ruby
 class UsersController < ApplicationController
-  include Rectify::Controller
+  include Rectify::ControllerHelpers
 
   def show
     user = User.find(params[:id])
@@ -574,15 +609,15 @@ end
 ```
 
 As mentioned above in the Commands section, you can use the `expose` method (if
-you include `Rectify::Controller`). You can use this anywhere in the controller
-action including the Command handler block. If you have set a Presenter for the
-view then `expose` will try to set an attribute on that presenter. If there is
-no Presenter or the Presenter doesn't have a matching attribute then `expose`
-will set an instance variable of the same name:
+you include `Rectify::ControllerHelpers`). You can use this anywhere in the
+controller action including the Command handler block. If you have set a
+Presenter for the view then `expose` will try to set an attribute on that
+presenter. If there is no Presenter or the Presenter doesn't have a matching
+attribute then `expose` will set an instance variable of the same name:
 
 ```ruby
 class UsersController < ApplicationController
-  include Rectify::Controller
+  include Rectify::ControllerHelpers
 
   def show
     user = User.find(params[:id])
@@ -599,10 +634,10 @@ end
 
 ### Decorators
 
-Another option for containing your UI logic is to use a Decorator. Rectify doesn't
-ship with a built in way to create a decorator but we recommend either using
-[Draper](https://github.com/drapergem/draper) or you can roll your own using
-`SimpleDelegator`:
+Another option for containing your UI logic is to use a Decorator. Rectify
+doesn't ship with a built in way to create a decorator but we recommend either
+using [Draper](https://github.com/drapergem/draper) or you can roll your own
+using `SimpleDelegator`:
 
 ```ruby
 class UserDecorator < SimpleDelegator
@@ -636,11 +671,12 @@ end
 
 ## Where do I put my files?
 
-The next inevitable question is "Where do I put my Forms, Commands and Presenters?".
-You could create `forms`, `commands` and `presenters` folders and follow the Rails Way.
-Rectify suggests grouping your classes by feature rather than by pattern. For example,
-create a folder called `core` (this can be anything) and within that, create a
-folder for each broad feature of your application. Something like the following:
+The next inevitable question is "Where do I put my Forms, Commands and
+Presenters?". You could create `forms`, `commands` and `presenters` folders and
+follow the Rails Way. Rectify suggests grouping your classes by feature rather
+than by pattern. For example, create a folder called `core` (this can be
+anything) and within that, create a folder for each broad feature of your
+application. Something like the following:
 
 ```
 .
@@ -648,7 +684,7 @@ folder for each broad feature of your application. Something like the following:
     ├── controllers
     ├── core
     │   ├── billing
-    │   ├── fulfilment
+    │   ├── fulfillment
     │   ├── ordering
     │   ├── reporting
     │   └── security
@@ -656,8 +692,8 @@ folder for each broad feature of your application. Something like the following:
     └── views
 ```
 
-Then you would place your classes in the appropriate feature folder. If you follow
-this pattern remember to namespace your classes with a matching module:
+Then you would place your classes in the appropriate feature folder. If you
+follow this pattern remember to namespace your classes with a matching module:
 
 ```ruby
 # in app/core/billing/send_invoice.rb
@@ -674,23 +710,23 @@ loaded automatically.
 
 ## Trade offs
 
-This style of Rails architecture is not a silver bullet for all projects. If your
-app is pretty much just basic CRUD then you are unlikely to get much benefit from
-this. However, if your app is more than just CRUD then you should see an
-improvement in code structure and maintainability.
+This style of Rails architecture is not a silver bullet for all projects. If
+your app is pretty much just basic CRUD then you are unlikely to get much
+benefit from this. However, if your app is more than just CRUD then you should
+see an improvement in code structure and maintainability.
 
 The downside to this approach is that there will be many more classes and files
-to deal with. This can be tricky as the application gets bigger to hold the whole
-system in your head. Personally I would prefer that as maintaining it will be
-easier as all code around a specific user task is on one place.
+to deal with. This can be tricky as the application gets bigger to hold the
+whole system in your head. Personally I would prefer that as maintaining it will
+be easier as all code around a specific user task is on one place.
 
-Before you use these methods in your project, consider the trade off and use these
-strategies where they make sense for you and your project.
+Before you use these methods in your project, consider the trade off and use
+these strategies where they make sense for you and your project.
 
 ## What's next?
 
 We stated above that the models should be responsible for data access. We
 may introduce a nice way to keep using the power of ActiveRecord but in a way
 where your models don't end up as a big ball of queries. We're thinking about
-Query Objects and a nice way to do this and we're also thinking about a nicer way
-to use raw SQL.
+Query Objects and a nice way to do this and we're also thinking about a nicer
+way to use raw SQL.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rectify
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Andy Pike
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-02-16 00:00:00.000000000 Z
+date: 2016-02-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: virtus
@@ -215,7 +215,7 @@ files:
 - LICENSE.txt
 - lib/rectify.rb
 - lib/rectify/command.rb
-- lib/rectify/controller.rb
+- lib/rectify/controller_helpers.rb
 - lib/rectify/form.rb
 - lib/rectify/presenter.rb
 - lib/rectify/save_command.rb