= Alki::Rails

Rails integration for Alki! Allows easily using Alki in your Rails project. Alki is a dependency injection and program organization framework.

== Why use Alki with Rails?

While Rails is a fantastic web framework, it doesn't offer a lot of tools to manage your
core business logic. Common idioms like "Fat Model" or "Fat Controller" work ok for a while,
but most large Rails projects get to a point where their business logic grows beyond
Rails' basic MVC paradigm.

Using Alki to manage your business logic allows your Rails code to focus on what it does best:
serve web pages. With Alki::Rails, Alki integrates seamlessly with Rails, while also keeping
your core code encapsulated.

=== What about Rails Services?

Recent versions of Rails have added an `app/services` directory as a place to put
dedicated service classes containing your business logic.

The key difference between these Rails services and Alki services is that Rails services are
classes or modules,
while Alki services can be any type of object.

By using objects, Alki allows services to be configured and dependency injected before
being used, allowing classes to be simpler, more focused, and easily tested.

== Installation

Add this line to your Rails application's Gemfile:

[source,ruby]
----
gem 'alki-rails'
----

And then execute:

[source]
----
$ bundle
----

Finally, run the generator to create an empty `config/assembly.rb` and to make your
assembly elements accessible in your controllers and in the console.

[source]
----
$ bin/rails generate alki
----

== Usage

Elements like services and application settings are defined in your Assembly definition
(`config/assembly.rb`). These elements are accessible by name directly within controllers
and the rails console.

See http://alki.io[alki.io] for more documentation on how to use Alki.

.config/assembly.rb
```ruby
Alki do
  group :orders do
    service :manager do
      require 'order_manager'
      OrderManager.new model, payment_processor
    end

    service :model do
      Order
    end

    service :payment_processor do
      require 'stripe_processor'
      StripeProcessor.new
    end
  end
end
```

.app/controllers/orders_controller.rb
```ruby
class OrdersController < ApplicationController
  def post
    # Can reference Assembly elements directly in controllers
    @order = orders.manager.place_order params[:order]
  end
end
```

.lib/order_manager.rb
```ruby
class OrderManager
  def initialize(model,payment_processor)
    @model = model
    @payment_processor = payment_processor
  end

  ...
end
```

.lib/stripe_processor.rb
```ruby
class StripeProcessor
  ...
end
```

Elements can also be accessed directly in the rails console,
or anywhere in your Rails application, via `Alki::Rails`:

.config/assembly.rb
```ruby
Alki do
  group :settings do
    set :msg, 'Hello World'
  end
end
```

.Rails Console
```
2.3.2 :001 > settings.msg
 => 'Hello World'
2.3.2 :001 > Alki::Rails.settings.msg
 => 'Hello World'
```

=== Code Reloading

Alki::Rails automatically will set up http://alki.io/projects/alki-reload[Alki::Reload] and enable it whenever
Rails itself has code reloading enabled. It will handle reloading all Alki configuration files and files in `lib/`.

Generally the Rails and Alki code reloading systems should work together without any issues.
One place however where they do work differently is in the console.
Alki does not require the `reload!` method to be called and will automatically reload code as soon as it changes.

== Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/alki-project/alki-rails[https://github.com/alki-project/alki-rails]. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the http://contributor-covenant.org[Contributor Covenant] code of conduct.

== License

The gem is available as open source under the terms of the http://opensource.org/licenses/MIT[MIT License].