README.md in active_job_channel-0.3.0 vs README.md in active_job_channel-0.4.0
- old
+ new
@@ -1,23 +1,34 @@
[](https://badge.fury.io/rb/active_job_channel)
+[](https://travis-ci.org/shanecav84/active_job_channel)
# ActiveJobChannel
Use ActionCable to alert front-end users of finished ActiveJobs
+* [Installation](#installation)
+* [Setup](#setup)
+ 1. [Create ActionCable Connection](#create-connection) (optional)
+ 2. [Enable ActiveJobChannel for a job](#enable-active_job_channel)
+ * [Configuration](#configuration)
+ * [`global_brodcast`](#global_broadcast)
+ 3. [Handle ActiveJobChannel broadcasts](#handle-broadcasts)
+* [Caveats](#caveats)
+* [Todo](#todo)
+* [Contributing](#contributing)
+ * [Dev setup](#dev-setup)
+* [License](#license)
+
## Installation
1. Install in your Gemfile
```ruby
gem 'active_job_channel'
```
## Setup
-1. [Create ActionCable Connection](#create-actioncable-connection-optional) (optional)
-2. [Enable ActiveJobChannel for a job](#enable-activejobchannel-for-a-job)
-3. [Handle ActiveJobChannel broadcasts](#handle-activejobchannel-broadcasts)
-### Create ActionCable Connection (optional)
+### <a name="create-connection"></a> 1. Create ActionCable Connection (optional)
You can skip this step if you're not concerned with authorizing or brodcasting
privately to ActionCable connections
1. Setup an [ActionCable subscription adapter](http://edgeguides.rubyonrails.org/action_cable_overview.html#subscription-adapter)
@@ -28,42 +39,57 @@
3. If you would like notifications broadcast privately to ActionCable
connections, set up a connection identifier for your connection using
`identified_by`. The identifier you use will also need to be passed to your
job.
-### Enable ActiveJobChannel for a job
-1. For each job you'd like to be notified about, call `active_job_channel` in
- its class
-2. To broadcast notifications privately, set the identifier you configured in
- your ActionCable Connection setup to either the instance variable
- `@ajc_identifier` or the method `ajc_identifier`
+### <a name="enable-active_job_channel"></a> 2. Enable ActiveJobChannel for a job
+1. For each job you'd like to be notified about, include `ActiveJobChannel` and
+ call `active_job_channel` in its class
+2. Private vs. Public broadcasts
+ 1. To broadcast notifications privately to a specific connection, set the
+ identifier you configured in your ActionCable Connection setup to either
+ the instance variable `@ajc_identifier` or the method `ajc_identifier`.
+
+ ```ruby
+ class MyJob < ActiveJob::Base
+ include ActiveJobChannel
+ active_job_channel
+
+ def perform(current_user)
+ @ajc_identifier = current_user
+ end
+
+ private
+
+ # def ajc_identifier
+ # User.find_by(key: value)
+ # end
+ end
+ ```
+
+ 2. To broadcast publicly to all ActionCable connections, pass
+ `{ global_broadcast: true }` to `active_job_channel` and do not set `ajc_identifier`
+
+ ```ruby
+ class MyJob < ActiveJob::Base
+ include ActiveJobChannel
+ active_job_channel global_broadcast: true
+
+ def perform; end
+ end
+ ```
-```ruby
-class MyJob < ActiveJob::Base
- active_job_channel
- def perform(current_user)
- @ajc_identifier = current_user
- end
-
- private
-
- # def ajc_identifier
- # User.find_by(key: value)
- # end
-end
-```
-
#### Configuration
##### global_broadcast
Notifications will be broadcast to `ajc_identifier` by default. To broadcast
all notifications for a job to all ActionCable connections, pass
`{ global_broadcast: true }` to `active_job_channel`.
-### Handle ActiveJobChannel broadcasts
+### <a name="handle-broadcasts"></a> 3. Handle ActiveJobChannel broadcasts
1. Include `active_job_channel.js` in your layouts
```ruby
javascript_include_tag 'active_job_channel'
@@ -78,18 +104,31 @@
2. Customize the callbacks for broadcasted notifications:
```javascript
//= require notifyjs
- ActiveJobChannel.onJobSuccess = function(job) { $.notify(job.name + ' succeeded!') };
- ActiveJobChannel.onJobFailure = function(job) { $.notify(job.name + ' failed!') };
+ ActiveJobChannel.onJobSuccess = function(job) { $.notify(job.data.job_class + ' succeeded!') };
+ ActiveJobChannel.onJobFailure = function(job) { $.notify(job.data.job_class + ' failed!') };
```
- `job` has the attributes `name` and `status`. A failed `job` includes an
- `error` attribute. `status` is one of `success` or `failure`.
+ `job` is a JSON object that has the attributes `status` and `data`. The value
+ of `status` can be one of `success` or `failure`. The value of `data` is a
+ JSON object of [job data serialized by ActiveJob](https://github.com/rails/rails/blob/649f19cab1d4dd805c915912ede29c86655084cd/activejob/lib/active_job/core.rb#L79).
+ It has the following keys:
+ - "job_class"
+ - "job_id" - Internal ActiveJob job identifier
+ - "provider_job_id" - ID optionally provided by ActiveJob queue adapter
+ - "queue_name"
+ - "priority"
+ - "arguments" - arguments passed to the job
+ - "executions" - how many times the job was attempted
+ - "locale"
+ A failed `job` includes an `error` attribute with the result of calling
+ `inspect` on the exception that precpitated the failure.
+
## Caveats
ActiveJobChannel depends on ActiveJob and ActionCable, and, as such, is
subject to their limitations:
* A persisted [subscription adapter](http://guides.rubyonrails.org/action_cable_overview.html#subscription-adapter)
@@ -98,8 +137,27 @@
* Because ActiveJob does not know when a job has permanently failed,
ActiveJobChannel sends notfications for each failure, retried or final
## Todo
- Better default front-end notification behavior
+
+## Contributing
+
+Issues and pull requests are welcome.
+
+### Dev setup
+
+1. Clone the project
+ ```bash
+ git clone https://github.com/shanecav84/active_job_channel
+ ```
+2. Install dependencies
+ ```bash
+ bundle install
+ ```
+3. Run the tests
+ ```bash
+ bundle exec rake
+ ```
## License
The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).