trailblazer 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 64d96dc88ee097d82859f27a353220b80c738e3e
-  data.tar.gz: 2b94910cfaa58c8b8c1d6ade98d7d1c2d9280c61
+  metadata.gz: 06e8559ba04b20c80f460c00d2fe76e94a7dceae
+  data.tar.gz: d16ed4ac3f269404152c316e2abcad2053c9f29c
 SHA512:
-  metadata.gz: 7ca6fc8e1715d0c98e07630c900daa3294bc6ac0387b32605efc2dc36d623cd61b43eed532c43255354ed210d564ef8ae58d2639d6bdfb8a826a6a4d9690cf3a
-  data.tar.gz: becc502617a59760160be2b64d53e3025be033e4c404ee76d557cdd3c0e780da963ed6e1305cc54d06f14739ef47ce8a9450c4753bc6d97a12db97a4c115e96d
+  metadata.gz: 2818fb4a0c7cfdc66b700df7feed6ac8a60dca747922ac901c311c92dffaf44dd0b3881ddfb46bf3eceebbc122d558bbd5c1acfc463a4ff2246824f519e475ee
+  data.tar.gz: 39daeb303ccadc8dd261cfa44576bf046d94174568abecceed193de66c902cd3fc1a5ce27d99814644f26585b800d7f7568b094f5c5ff044eb8fbbaf29ea1fa6

data/CHANGES.md

@@ -1,3 +1,7 @@
+# 0.3.1
+
+* Autoload `Dispatch`.
+
 # 0.3.0
 
 ## Changes

data/Gemfile

@@ -7,5 +7,5 @@ gemspec
 # gem "reform", path: "../reform"
 # gem "disposable", path: "../disposable"
 gem "virtus"
-gem "reform", github: "apotonick/reform"
-
+# gem "reform", github: "apotonick/reform"
+gem "reform", ">= 2.0.0.rc1"

data/README.md

@@ -141,11 +141,58 @@ class Create < Trailblazer::Operation
   self.contract_class = MyCommentForm
 ```
 
+## Callbacks
+
+Post-processing logic (also known as _callbacks_) is configured in operations.
+
+Following the schema of your contract, you can define callbacks for events tracked by the form's twin.
+
+```ruby
+class Create < Trailblazer::Operation
+  callback(:after_save) do
+    on_change :upload_file, property: :file
+
+    property :user do
+      on_create :notify_user!
+    end
+  end
+```
+
+The _Imperative Callback_ pattern then allows you to call this _callback group_ whereever you need it.
+
+```ruby
+class Create < Trailblazer::Operation
+
+  def process(params)
+    validate(params) do
+      contract.save
+      dispatch!(:after_save)
+    end
+  end
+end
+```
+
+No magical triggering of unwanted logic anymore, but explicit invocations where you want it.
+
+
 ## 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.
+In Trailblazer, models are completely empty. They solely contain associations and finders. No business logic is allowed in models.
+
+```ruby
+class Thing < ActiveRecord::Base
+  has_many :comments, -> { order(created_at: :desc) }
+  has_many :users, through: :authorships
+  has_many :authorships
+
+  scope :latest, lambda { all.limit(9).order("id DESC") }
+end
+```
+
+Only operations and views/cells can access models directly.
+
 
 ## Views
 
@@ -153,9 +200,31 @@ View rendering can happen using the controller as known from Rails. This is abso
 
 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.
+## Representers
+
+Operations can use representers from [Roar](https://github.com/apotonick/roar) to serialize and parse JSON and XML documents for APIs.
+
+Representers can be inferred automatically from your contract, then may be refined, e.g. with hypermedia or a format like `JSON-API`.
+
+```ruby
+class Create < Trailblazer::Operation
+
+  representer do
+    # inherited :body
+    include Roar::JSON::HAL
+
+    link(:self) { comment_path(represented.id) }
+  end
+```
+
+The operation can then parse incoming JSON documents in `validate` and render a document via `to_json`. The full [documentation is here](http://trailblazerb.org/gems/operation/representer.html) or in the [Trailblazer book](https://leanpub.com/trailblazer), chapter _Hypermedia APIs_.
+
+## Tests
+
+Subject to tests are mainly _Operation_s and _View Model_s, as they encapsulate endpoint behaviour of your app. As a nice side effect, factories are replaced by simple _Operation_ calls.
+
+
 
 ## Overview
 
@@ -165,6 +234,8 @@ Using the different layers is completely optional and up to you: Both Cells and
 
 ## Controller API
 
+[Learn more](http://trailblazerb.org/gems/operation/controller.html)
+
 Trailblazer provides four methods to present and invoke operations. But before that, you need to include the `Controller` module.
 
 ```ruby
@@ -294,24 +365,6 @@ In all three cases the following instance variables are assigned: `@operation`,
 Named instance variables can be included, too. This is documented [here](#named-controller-instance-variables).
 
 
-### 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 CommentsController < ApplicationController
-  # ..
-
-private
-  def process_params!(params)
-    params.merge!(current_user: current_user)
-  end
-end
-```
-
-This centralizes params normalization and doesn't require you to do that in every action manually.
-
-
 ### Different Request Formats
 
 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.
@@ -344,22 +397,22 @@ end
 The simplest way of running an operation is the _call style_.
 
 ```ruby
-op = Comment::Create[params]
+op = Comment::Create.(params)
 ```
 
-Using `Operation#[]` will return the operation instance. In case of an invalid operation, this will raise an exception.
+The call style runs the operation and return the operation instance, only.
 
-Note how this can easily be used for test factories.
+In case of an invalid operation, this will raise an exception.
 
-```ruby
-let(:comment) { Comment::Create[valid_comment_params].model }
-```
+### Run style
 
-Using operations as test factories is a fundamental concept of Trailblazer to remove buggy redundancy in tests and manual factories.
+The _run style_ will do the same as call, but won't raise an exception in case of an invalid result. Instead, it returns result _and_ the operation instance.
 
-### Run style
+```ruby
+result, op = Comment::Create.run(params)
+```
 
-You can run an operation manually and use the same block semantics as found in the controller.
+Additionally, it accepts a block that's only run for a valid state.
 
 ```ruby
 Comment::Create.run(params) do |op|
@@ -367,7 +420,27 @@ Comment::Create.run(params) do |op|
 end
 ```
 
-Of course, this does _not_ throw an exception but simply skips the block when the operation is invalid.
+## Form API
+
+Usually, an operation has a form object.
+
+```ruby
+class Create < Trailblazer::Operation
+  contract do
+    property :body
+    validates :body: presence: true, length: {max: 160}
+  end
+```
+
+A `::contract` block simply opens a new Reform class for you.
+
+```ruby
+contract do #=> Class.new(Reform::Form) do
+```
+
+This allows using Reform's API in the block.
+
+When inheriting, the block is `class_eval`ed in the inherited class' context and allows adding, removing and customizing the sub contract.
 
 ### CRUD Semantics
 

data/lib/trailblazer/autoloading.rb

@@ -3,4 +3,5 @@ Trailblazer::Operation.class_eval do
   autoload :Responder,  "trailblazer/operation/responder"
   autoload :CRUD,       "trailblazer/operation/crud"
   autoload :Collection, "trailblazer/operation/collection"
+  autoload :Dispatch,   "trailblazer/operation/dispatch"
 end

data/lib/trailblazer/operation.rb

@@ -143,7 +143,6 @@ module Trailblazer
 end
 
 require 'trailblazer/operation/crud'
-require "trailblazer/operation/dispatch"
 
 # run
 #   setup

data/lib/trailblazer/version.rb

@@ -1,3 +1,3 @@
 module Trailblazer
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

data/test/dispatch_test.rb

@@ -1,11 +1,12 @@
 require 'test_helper'
+require "trailblazer/operation/dispatch"
 
 # callbacks are tested in Disposable::Callback::Group.
 class OperationCallbackTest < MiniTest::Spec
   Song = Struct.new(:name)
 
   class Create < Trailblazer::Operation
-    include Dispatch
+    include Trailblazer::Operation::Dispatch
 
     contract do
       property :name

data/trailblazer.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "actionpack", '>= 3.0.0' # this framework works on Rails.
+
   spec.add_dependency "uber", ">= 0.0.10" # no builder inheritance.
   # spec.add_dependency "representable", ">= 2.1.1", "<2.3.0" # Representable::apply.
   spec.add_dependency "reform", ">= 1.2.0"
@@ -28,6 +28,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "minitest"
   # spec.add_development_dependency "minitest-spec-rails" # TODO: can anyone make this work (test/rails).
   spec.add_development_dependency "sidekiq", "~> 3.1.0"
+  spec.add_development_dependency "actionpack", '>= 3.0.0' # Rails is optional.
   spec.add_development_dependency "rails"
   spec.add_development_dependency "sqlite3"
   spec.add_development_dependency "responders"

metadata

@@ -1,29 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: trailblazer
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Nick Sutterer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-06-30 00:00:00.000000000 Z
+date: 2015-07-03 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: actionpack
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 3.0.0
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 3.0.0
 - !ruby/object:Gem::Dependency
   name: uber
   requirement: !ruby/object:Gem::Requirement
@@ -108,6 +94,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 3.1.0
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.0.0
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement