trailblazer 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 501c866e1640a0a821e4bbeaa38fbab80ef8c03d
-  data.tar.gz: b76816095a34ad206dbf1d74fbefd070957f73f4
+  metadata.gz: 64d96dc88ee097d82859f27a353220b80c738e3e
+  data.tar.gz: 2b94910cfaa58c8b8c1d6ade98d7d1c2d9280c61
 SHA512:
-  metadata.gz: 69aed732717c006c7a32f09fabbaa2ff886cb9fd4d6be4fccdf6dd0f81959415c440470705a008570f5e0ccf9bcc9dadfff4cb19e50babb04c0d2dcf77a75cc3
-  data.tar.gz: 769c47a8a86e3777c7bd6f13a4893b3fe969712be3e1eecfdaadd4f013c082d61abe9fbe2ca4a6cdf47bd69fe2e774a3b7cc4927352fe2601fb1a349007f6eff
+  metadata.gz: 7ca6fc8e1715d0c98e07630c900daa3294bc6ac0387b32605efc2dc36d623cd61b43eed532c43255354ed210d564ef8ae58d2639d6bdfb8a826a6a4d9690cf3a
+  data.tar.gz: becc502617a59760160be2b64d53e3025be033e4c404ee76d557cdd3c0e780da963ed6e1305cc54d06f14739ef47ce8a9450c4753bc6d97a12db97a4c115e96d

data/.travis.yml

@@ -1,8 +1,6 @@
 language: ruby
 rvm:
+  - 2.2.0
   - 2.1.2
   - 2.0.0
   - 1.9.3
-script:
-  - bundle exec rake test
-  - bundle exec rake rails

data/CHANGES.md

@@ -1,3 +1,36 @@
+# 0.3.0
+
+## Changes
+
+* In Railtie, use `ActionDispatch::Reloader.to_prepare` for autoloading, nothing else. This should fix spring reloading.
+* Allow `Op#validate(params, model, Contract)` with CRUD.
+* Allows prefixed table names, e.g. `admin.users` in `Controller`. The instance variables will be `@user`. Thanks to @fernandes and especially @HuckyDucky.
+* Added `Operation::Collection` which will allow additional behavior like pagination and scoping. Thanks to @fernandes for his work on this.
+* Added `Operation::collection` to run `setup!` without instantiating a contract. This is called in the new `Controller#collection` method.
+* Added `Operation#model` as this is a fundamental concept now.
+* Improved the undocumented `Representer` module which allows inferring representers from contract, using them to deserialize documents for the form, and rendering documents.
+* Changed `Operation::Dispatch` which now provides imperative callbacks.
+
+## API change
+
+1. The return value of #process is no longer returned from ::run and ::call. They always return the operation instance.
+2. The return value of #validate is `true` or `false`. This allows a more intuitive operation body.
+
+    ```ruby
+    def process(params)
+      if validate(params)
+        .. do valid
+      else
+        .. handle invalid
+      end
+    end
+    ```
+
+* `Worker` only works with Reform >= 2.0.0.
+
+# 0.2.3
+
+
 # 0.2.2
 
 # Added Operation#errors as every operation maintains a contract.

data/Gemfile

@@ -5,4 +5,7 @@ gemspec
 
 # gem "representable", path: "../representable"
 # gem "reform", path: "../reform"
-# gem "reform", git: "https://github.com/apotonick/reform.git"
+# gem "disposable", path: "../disposable"
+gem "virtus"
+gem "reform", github: "apotonick/reform"
+

data/README.md

@@ -2,13 +2,7 @@
 
 _Trailblazer is a thin layer on top of Rails. It gently enforces encapsulation, an intuitive code structure and gives you an object-oriented architecture._
 
-In a nutshell: Trailblazer makes you write **logicless models** that purely act as data objects, don't contain callbacks, nested attributes, validations or domain logic. It **removes bulky controllers** and strong_parameters by supplying additional layers to hold that code and **completely replaces helpers**.
-
-![](https://raw.githubusercontent.com/apotonick/trailblazer/master/doc/trb.jpg)
-
-Please buy my book [Trailblazer - A new architecture for Rails](https://leanpub.com/trailblazer) and [let me know](http://twitter.com/apotonick) what you think! I am still working on the book but keep adding new chapters every other week. It will be about 300 pages and we're developing a real, full-blown Rails/Trb application.
-
-The [demo application](https://github.com/apotonick/gemgem-trbrb) implements what we discuss in the book.
+In a nutshell: Trailblazer makes you write **logicless models** that purely act as data objects, don't contain callbacks, nested attributes, validations or domain logic. **Controllers** become lean HTTP endpoints. Your **business logic** (including validation) is decoupled from the actual Rails framework and modeled in _operations_.
 
 ## Mission
 
@@ -55,14 +49,127 @@ Trailblazer uses Rails routing to map URLs to controllers (we will add simplific
 
 ## Controllers
 
-Controllers are lean endpoints for HTTP. They differentiate between request formats like HTML or JSON and immediately dispatch to an operation. Controllers do not contain any business logic.
+Controllers are lean endpoints for HTTP. They differentiate between request formats like HTML or JSON and do not contain any business logic. Actions immediately dispatch to an operation.
+
+```ruby
+class CommentsController < ApplicationController
+  def create
+    Comment::Create.(params)
+  end
+```
+
+This can be simplified using the `run` method and allows you a simple conditional to handle failing operations.
+
+```ruby
+class CommentsController < ApplicationController
+  def create
+    run Comment::Create do |op|
+      return redirect_to(comment_path op.model) # success.
+    end
+
+    render :new # re-render form.
+  end
+```
+
+Again, the controller only knows how to dispatch to the operation and what to do for success and invalid processing. While business affairs (e.g. logging or rollbacks) are to be handled in the operation, the controller invokes rendering or redirecting.
+
+## Operation
+
+The [API is documented here](http://trailblazerb.org/gems/operation/api.html).
+
+Operations encapsulate business logic and are the heart of a Trailblazer architecture. One operation per high-level domain _function_ is used. Different formats or environments are handled in subclasses. Operations don't know about HTTP or the environment.
+
+An operation is not just a monolithic replacement for your business code. An operation is a simple orchestrator between the form object, models and your business code.
+
+You don't have to use the form/contract if you don't want it, BTW.
+
+```ruby
+class Comment < ActiveRecord::Base
+  class Create < Trailblazer::Operation
+    def process(params)
+      # do whatever you feel like.
+    end
+  end
+end
+```
+
+Operations only need to implement `#process` which receives the params from the caller.
+
+## Validations
+
+Operations usually have a form object which is simply a `Reform::Form` class. All the [API documented in Reform](https://github.com/apotonick/reform) can be applied and used.
+
+The operation makes use of the form object using the `#validate` method.
+
+```ruby
+class Comment < ActiveRecord::Base
+  class Create < Trailblazer::Operation
+    contract do
+      property :body, validates: {presence: true}
+    end
+
+    def process(params)
+      @model = Comment.new
+
+      validate(params[:comment], @model) do |f|
+        f.save
+      end
+    end
+  end
+end
+```
+
+The contract (aka _form_) is defined in the `::contract` block. You can implement nested forms, default values, validations, and everything else Reform provides.
+
+In case of a valid form the block for `#validate` is invoked. It receives the populated form object. You can use the form to save data or write your own logic. This is where your business logic is implemented, and in turn could be an invocation of service objects or organizers.
+
+Technically speaking, what really happens in `Operation#validate` is the following.
+
+```ruby
+contract_class.new(@model).validate(params[:comment])
+```
+
+This is a familiar work-flow from Reform. Validation does _not_ touch the model.
+
+
+
+
+If you prefer keeping your forms in separate classes or even files, you're free to do so.
+
+```ruby
+class Create < Trailblazer::Operation
+  self.contract_class = MyCommentForm
+```
+
+## Models
+
+Models for persistence can be implemented using any ORM you fancy, for instance [ActiveRecord](https://github.com/rails/rails/tree/master/activerecord#active-record--object-relational-mapping-in-rails) or [Datamapper](http://datamapper.org/).
+
+In Trailblazer, models are completely empty and solely configure database-relevant directives and associations. No business logic is allowed in models. Only operations, views and cells can access models directly.
+
+## Views
+
+View rendering can happen using the controller as known from Rails. This is absolutely fine for simple views.
+
+More complex UI logic happens in _View Models_ as found in [Cells](https://github.com/apotonick/cells). View models also replace helpers.
+
+8. **HTTP API** Consuming and rendering API documents (e.g. JSON or XML) is done via [roar](https://github.com/apotonick/roar) and [representable](https://github.com/apotonick/representable). They usually inherit the schema from <em>Contract</em>s .
+
+10. **Tests** Subject to tests are mainly <em>Operation</em>s and <em>View Model</em>s, as they encapsulate endpoint behaviour of your app. As a nice side effect, factories are replaced by simple _Operation_ calls.
+
+## Overview
+
+Trailblazer is basically a mash-up of mature gems that have been developed over the past 10 years and are used in hundreds and thousands of production apps.
+
+Using the different layers is completely optional and up to you: Both Cells and Reform can be excluded from your stack if you wish so.
+
+## Controller API
 
 Trailblazer provides four methods to present and invoke operations. But before that, you need to include the `Controller` module.
 
 ```ruby
 class CommentsController < ApplicationController
   include Trailblazer::Operation::Controller
-
 ```
 
 ### Rendering the form object
@@ -115,7 +222,7 @@ def create
 end
 ```
 
-Note that the operation instance is yield to the block.
+Note that the operation instance is yielded to the block.
 
 The case of an invalid response can be handled after the block.
 
@@ -144,6 +251,12 @@ end
 
 This will simply run the operation and chuck the instance into the responder letting the latter sort out what to render or where to redirect. The operation delegates respective calls to its internal `model`.
 
+`#respond` will accept options to be passed on to `respond_with`, too
+
+```ruby
+respond Comment::Create, params, location: brandnew_comments_path
+```
+
 You can also handle different formats in that block. It is totally fine to do that in the controller as this is _endpoint_ logic that is HTTP-specific and not business.
 
 ```ruby
@@ -175,154 +288,86 @@ For document-based APIs and request types that are not HTTP the operation will b
 
 Note that `#present` will leave rendering up to you - `respond_to` is _not_ called.
 
-### Controller API
 
 In all three cases the following instance variables are assigned: `@operation`, `@form`, `@model`.
 
 Named instance variables can be included, too. This is documented [here](#named-controller-instance-variables).
 
-## Operation
 
-Operations encapsulate business logic. One operation per high-level domain _function_ is used. Different formats or environments are handled in subclasses. Operations don't know about HTTP.
+### Normalizing params
+
+Override `#process_params!` to add or remove values to `params` before the operation is run. This is called in `#run`, `#respond` and `#present`.
 
 ```ruby
-class Comment < ActiveRecord::Base
-  class Create < Trailblazer::Operation
-    def process(params)
-      # do whatever you feel like.
-      self
-    end
+class CommentsController < ApplicationController
+  # ..
+
+private
+  def process_params!(params)
+    params.merge!(current_user: current_user)
   end
 end
- ```
-
-Operations only need to implement `#process` which receives the params from the caller.
-
-### Call style
-
-The simplest way of running an operation is the _call style_.
-
-```ruby
-op = Comment::Create[params]
 ```
 
-Using `Operation#[]` will return the operation instance. In case of an invalid operation, this will raise an exception.
-
-Note how this can easily be used for test factories.
+This centralizes params normalization and doesn't require you to do that in every action manually.
 
-```ruby
-let(:comment) { Comment::Create[valid_comment_params].model }
-```
 
-Using operations as test factories is a fundamental concept of Trailblazer to remove buggy redundancy in tests and manual factories.
+### Different Request Formats
 
-### Run style
+In case you have document-API operations that use representers to deserialize the incoming JSON or XML: You can configure the controller to pass the original request body into the operation via `params["comment"]` - instead of the pre-parsed hash from Rails.
 
-You can run an operation manually and use the same block semantics as found in the controller.
+You need to configure this in the controller.
 
 ```ruby
-Comment::Create.run(params) do |op|
-  # only run when valid.
-end
+class CommentsController < ApplicationController
+  operation document_formats: :json
 ```
 
-Of course, this does _not_ throw an exception but simply skips the block when the operation is invalid.
-
-## Validations
-
-Operations usually have a form object which is simply a `Reform::Form` class. All the [API documented in Reform](https://github.com/apotonick/reform) can be applied and used.
 
-The operation makes use of the form object using the `#validate` method.
+It's up to the operation's builder to decide which class to instantiate.
 
 ```ruby
-class Comment < ActiveRecord::Base
-  class Create < Trailblazer::Operation
-    contract do
-      property :body, validates: {presence: true}
-    end
-
-    def process(params)
-      @model = Comment.new
-
-      validate(params[:comment], @model) do |f|
-        f.save
-      end
-    end
+class Create < Trailblazer::Operation
+  builds do |params|
+    JSON if params[:format] == "json"
   end
 end
- ```
-
-The contract (aka _form_) is defined in the `::contract` block. You can implement nested forms, default values, validations, and everything else Reform provides.
-
-In case of a valid form the block for `#validate` is invoked. It receives the populated form object. You can use the form to save data or write your own logic.
-
-Technically speaking, what really happens in `Operation#validate` is the following.
-
-```ruby
-contract_class.new(@model).validate(params[:comment])
 ```
 
-This is a familiar work-flow from Reform. Validation does _not_ touch the model.
-
-
-## Models
-
-Models for persistence can be implemented using any ORM you fancy, for instance [ActiveRecord](https://github.com/rails/rails/tree/master/activerecord#active-record--object-relational-mapping-in-rails) or [Datamapper](http://datamapper.org/).
-
-In Trailblazer, models are completely empty and solely configure database-relevant directives and associations. No business logic is allowed in models. Only operations, views and cells can access models directly.
-
-## Views
-
-View rendering can happen using the controller as known from Rails. This is absolutely fine for simple views.
-
-More complex UI logic happens in _View Models_ as found in [Cells](https://github.com/apotonick/cells). View models also replace helpers.
-
-
+[Note that this will soon be provided with a module.]
 
 
-8. **HTTP API** Consuming and rendering API documents (e.g. JSON or XML) is done via [roar](https://github.com/apotonick/roar) and [representable](https://github.com/apotonick/representable). They usually inherit the schema from <em>Contract</em>s .
-
-10. **Tests** Subject to tests are mainly <em>Operation</em>s and <em>View Model</em>s, as they encapsulate endpoint behaviour of your app. As a nice side effect, factories are replaced by simple _Operation_ calls.
+## Operation API
 
-Trailblazer is basically a mash-up of mature gems that have been developed over the past 10 years and are used in hundreds and thousands of production apps.
+### Call style
 
+The simplest way of running an operation is the _call style_.
 
-## Controller API
+```ruby
+op = Comment::Create[params]
+```
 
-### Normalizing params
+Using `Operation#[]` will return the operation instance. In case of an invalid operation, this will raise an exception.
 
-Override `#process_params!` to add or remove values to `params` before the operation is run. This is called in `#run`, `#respond` and `#present`.
+Note how this can easily be used for test factories.
 
 ```ruby
-class CommentsController < ApplicationController
-  # ..
-
-private
-  def process_params!(params)
-    params.merge!(current_user: current_user)
-  end
-end
+let(:comment) { Comment::Create[valid_comment_params].model }
 ```
 
-This centralizes params normalization and doesn't require you to do that in every action manually.
-
+Using operations as test factories is a fundamental concept of Trailblazer to remove buggy redundancy in tests and manual factories.
 
-### Different Request Formats
+### Run style
 
-The controller helpers `#present` and `#respond` automatically pass the request body into the operation via the `params` hash. It's up to the operation's builder to decide which class to instantiate.
+You can run an operation manually and use the same block semantics as found in the controller.
 
 ```ruby
-class Create < Trailblazer::Operation
-  builds do |params|
-    JSON if params[:format] == "json"
-  end
+Comment::Create.run(params) do |op|
+  # only run when valid.
 end
 ```
 
-[Note that this will soon be provided with a module.]
-
-
-## Operation API
+Of course, this does _not_ throw an exception but simply skips the block when the operation is invalid.
 
 ### CRUD Semantics
 
@@ -366,7 +411,7 @@ Another action is `:find` (which is currently doing the same as `:update`) to fi
 
 ### Normalizing params
 
-Override #setup_params! to add or remove values to params before the operation is run.
+Override `#setup_params!` to add or remove values to params before the operation is run.
 
 ```ruby
 class Create < Trailblazer::Operation
@@ -375,7 +420,7 @@ class Create < Trailblazer::Operation
   end
 
   private
-    def process_params!(params)
+    def setup_params!(params)
       params.merge!(show_all: true) if params[:admin]
     end
   end
@@ -384,6 +429,9 @@ end
 
 This centralizes params normalization and doesn't require you to do that manually in `#process`.
 
+### Collections
+
+Operations can also be used to present (and soon to process) collections of objects, e.g. for an `Index` operation. This is [documented here](http://trailblazerb.org/gems/operation/collection.html).
 
 ### Background Processing
 
@@ -401,31 +449,6 @@ class Comment::Image::Crop < Trailblazer::Operation
 end
 ```
 
-### Rendering Operation's Form
-
-You have access to an operation's form using `::present`.
-
-```ruby
-Comment::Create.present(params)
-```
-
-This will run the operation's `#process` method _without_ the validate block and return the contract.
-
-### Marking Operation as Invalid
-
-Sometimes you don't need a form object but still want the validity behavior of an operation.
-
-```ruby
-def process(params)
-  return invalid! unless params[:id]
-
-  Comment.find(params[:id]).destroy
-  self
-end
-```
-
-`#invalid!` returns `self` per default but accepts any result.
-
 
 ### Worker::FileMarshaller: needs representable 2.1.1 (.schema)
 
@@ -461,33 +484,7 @@ This will go through `app/concepts/`, find all the `crud.rb` files, autoload the
 
 (Please don't read this section!)
 
-### Additional Model Setup
-
-Override `Operation#setup_model(params)` to add nested objects that can be infered from `params` or are static.
-
-This is called right after `#model!`.
-
-### Validation Errors
-
-You can access the contracts `Errors` object via `Operation#errors`.
 
-### ActiveModel Semantics
-
-When using `Reform::Form::ActiveModel` (which is used automatically in a Rails environment to make form builders work) you need to invoke `model Comment` in the contract. This can be inferred automatically from the operation by including `CRUD::ActiveModel`.
-
-```ruby
-class Create < Trailblazer::Operation
-  include CRUD
-  include CRUD::ActiveModel
-
-  model Comment
-
-  contract do # no need to call ::model, here.
-    property :text
-  end
-```
-
-If you want that in all CRUD operations, check out [how you can include](https://github.com/apotonick/gemgem-trbrb/blob/chapter-5/config/initializers/trailblazer.rb#L26) it automatically.
 
 ### Named Controller Instance Variables
 
@@ -504,6 +501,14 @@ end
 
 This will setup a named instance variable of your operation's model, for example `@song`.
 
+## The Book
+
+![](https://raw.githubusercontent.com/apotonick/trailblazer/master/doc/trb.jpg)
+
+Please buy my book [Trailblazer - A new architecture for Rails](https://leanpub.com/trailblazer) and [let me know](http://twitter.com/apotonick) what you think! I am still working on the book but keep adding new chapters every other week. It will be about 300 pages and we're developing a real, full-blown Rails/Trb application.
+
+The [demo application](https://github.com/apotonick/gemgem-trbrb) implements what we discuss in the book.
+
 ## Why?
 
 * Grouping code, views and assets by concepts increases the **maintainability** of your apps. Developers will find their way faster into your structure as the file layout is more intuitive.