= Hexx

{<img src="http://img.shields.io/gem/v/hexx.svg?style=flat" alt="Gem Version" />}[https://rubygems.org/gems/hexx]
{<img src="http://img.shields.io/travis/nepalez/hexx.svg?style=flat" alt="Bild Status" />}[https://travis-ci.org/nepalez/hexx]
{<img src="http://img.shields.io/codeclimate/github/nepalez/hexx.svg?style=flat" alt="Code Metrics" />}[https://codeclimate.com/github/nepalez/hexx]
{<img src="http://img.shields.io/gemnasium/nepalez/hexx.svg?style=flat" alt="Dependency Status" />}[https://gemnasium.com/nepalez/hexx]
{<img src="http://img.shields.io/coveralls/nepalez/hexx.svg?style=flat" alt="Coverage Status" />}[https://coveralls.io/r/nepalez/hexx]
{<img src="http://img.shields.io/badge/license-MIT-blue.svg?style=flat" alt="License" />}[https://github.com/nepalez/hexx/blob/master/LICENSE.rdoc]

The module provides a base service objects class and some features for the
domain models (entities).

Provides:
* +Service+ base class for decoupling a domain business logics from a controller
* +Models+ module for extending domain models.

== Installation

Add this line to your application's Gemfile:

    gem "hexx", "~> 2.0"

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install hexx

== A pattern

Service objects decouple business logics from both:
* Domain _models_ (entities).
* Delivery mechanism _controllers_ (such as Rails framework).

Following object oriented architecture service objects exploit the
*Observer* (Listener) pattern, using the
{ Wisper }[https://github.com/krisleech/wisper] gem. A service doesn't
return their result to caller but notifies its subscribers instead.

Some examples of this pattern implementation are available at the
{ wisper gem wiki }[https://github.com/krisleech/wisper/wiki].

=== Service

A typical service object is shown below:

  require 'hexx'

  class GetItem < Hexx::Service

    # whitelists parameters and defines corresponding attributes.
    allow_params :name

    # defines some validation using ActiveModel::Validations helpers.
    validate :name, presence: true

    # runs a service
    def run

      # runs some 
      transaction
        MyModel.save! name: name # name is defined by allow_params helper.
        publish :success         # notifies its listeners.
      end
    end
  end

Usage of the service (in a Rails controller):

  class ItemsController < ActionController::Base

    # Creates an item with given name
    def show
      service = GetItem.new params.allow(:name)
      service.subscribe self, prefix: :on
      service.run
    end

    # Publishes a success message
    def success
      render "created"
    end

    # Publishes an error messages
    def error(messages)
      @messages = messages
      render "error"
    end

Note the controller knows nothing about the action itself. It responsible only
for selection of proper service and responding to its results.

Also note any controller action does one thing only. The +show+ action
are requested by a client. The +on_success+ and +on_error+ are called by
a service and reports to a client.

=== Models and Entities

The module also defines module <tt>Hexx::Models</tt> to extend domain models
(entities). This allows coercion of model attributes with +attr_coerced+ helper:

  class User
    extend Hexx::Models
    attr_coerced  :name, type: ActiveSupport::Multibyte::Chars
  end

  user = User.new name: "Ivan"
  
  user.name
  # => "Ivan"
  
  user.name.class
  # => ActiveSupport::Multibyte::Chars

The method defines (or redefines) both attribute getter and setter. You can use
it to transform values by default:

  class StrippedString < String
    def initialize(value)
      super value.strip
    end
  end

  class User
    extend Hexx::Models
    attr_coerced :name, type: StrippedString
  end

  user = User.name " Ivan  "
  user.name # => "Ivan"

== Relevant Links

1:: Matt Wynne's talk {Hexagonal Rails}[http://www.confreaks.com/videos/977-goruco2012-hexagonal-rails]

== License

The project is distributed under the {MIT LICENSE}[LICENSE.rdoc].