# Ecto.Observable
[![Build Status](https://travis-ci.org/nsweeting/ecto_observable.svg?branch=master)](https://travis-ci.org/nsweeting/ecto_observable)
[![Ecto.Observable Version](https://img.shields.io/hexpm/v/ecto_observable.svg)](https://hex.pm/packages/ecto_observable)
`Ecto.Observable` adds "observable" functionality to `Ecto.Repo`.
## Installation
The package can be installed by adding `ecto_observable` to your list of dependencies in `mix.exs`:
```elixir
def deps do
[
{:ecto_observable, "~> 0.1.0"}
]
end
```
## Documentation
See [HexDocs](https://hexdocs.pm/ecto_observable) for additional documentation.
## Getting Started
Lets say we have a `Post` schema. Each post can have many topics. Users can
subscribe to a given topic. Whenever a post is created for a given topic, we
are responsible for informing the subscribed users.
Given the above, lets setup our new "observable" repo.
```elixir
defmodule Repo do
use Ecto.Repo, otp_app: :my_app
use Ecto.Observable
@observers [SubscribersObserver]
def init(_args, config) do
init_observable(@observers)
{:ok, config}
end
end
```
We have defined our repo as normal - but with a few additions. First, we must
`use Ecto.Observable` to bring in the required observable functionality. Second,
from within our `Ecto.Repo.init/2` callback, we must invoke the `Ecto.Observable.init_observable/1`
function to setup our repo with the observers we want.
Lets create our new observer now.
```elixir
defmodule SubscribersObserver do
use Ecto.Observer
def observations do
[
{Post, :insert},
{Post, :update} # Defined for the sake of example. Ignore me!
]
end
# Lets ignore posts that dont have any topics.
def handle_insert(%Post{topics: []}) do
:ok
end
def handle_insert(%Post{topics: topics}) do
# Do work required to inform subscribed users.
end
# Defined for the sake of example. Ignore me!
def handle_update(old_post, new_post) do
:ok
end
end
```
Now that we are starting to use "observable" behaviour, we must modify the way
in which we insert posts with our repo.
```elixir
def create_post(params \\ %{}) do
%Post{}
|> Post.changeset(params)
|> Repo.insert_and_notify()
end
```
Our users will now be informed of any new posts with topics they are interested in!