README.md in alephant-publisher-queue-1.0.0 vs README.md in alephant-publisher-queue-1.1.0
- old
+ new
@@ -4,223 +4,162 @@
[](https://travis-ci.org/BBC-News/alephant-publisher-queue) [](https://gemnasium.com/BBC-News/alephant-publisher-queue) [](http://badge.fury.io/rb/alephant-publisher-queue)
## Dependencies
-- JRuby 1.7.8
-- An AWS account (you'll need to create):
- - An S3 bucket
- - An SQS Queue (if no sequence id provided then `sequence_id` will be used)
- - A Dynamo DB table (optional, will attempt to create if can't be found)
+- JRuby 1.7.8+
+- An AWS account, with:
+ - S3 bucket.
+ - SQS Queue.
+ - Dynamo DB table.
## Migrating from [Alephant::Publisher](https://github.com/BBC-News/alephant-publisher)
-1. Add the new gem in your Gemfile (`gem 'alephant-publisher-queue'`).
-2. Run `bundle install`.
-3. Require the new gem in your app (`require 'alephant/publisher/queue'`).
-4. Note that the namespace has changed from `Alephant::Publisher` to `Alephant::Publisher::Queue`.
+Add the new gem in your Gemfile:
+```
+gem 'alephant-publisher-queue'
+```
+
+Run:
+
+```
+bundle install
+```
+
+Require the new gem in your app:
+
+```
+require 'alephant/publisher/queue'
+```
+
+**Important** - note that the namespace has changed from `Alephant::Publisher` to `Alephant::Publisher::Queue`.
+
## Installation
Add this line to your application's Gemfile:
- gem 'alephant-publisher-queue'
+```
+gem 'alephant-publisher-queue'
+```
And then execute:
- $ bundle
+```
+bundle
+```
Or install it yourself as:
- $ gem install alephant-publisher-queue
+```
+gem install alephant-publisher-queue
+```
## Setup
Ensure you have a `config/aws.yml` in the format:
```yaml
access_key_id: ACCESS_KEY_ID
secret_access_key: SECRET_ACCESS_KEY
```
-## Usage
+## Structure
-**In your application:**
+Provide a view and template:
-```rb
-require 'alephant'
+```
+└── views
+ ├── models
+ │ └── foo.rb
+ └── templates
+ └── foo.mustache
+```
-sequential_proc = Proc.new do |last_seen_id, data|
- last_seen_id < data['sequence_id'].to_i
-end
+**foo.rb**
-set_last_seen_proc = Proc.new do |data|
- data['sequence_id'].to_i
+```ruby
+class Foo < Alephant::Views::Base
+ def content
+ @data['content']
+ end
end
+```
-opts = {
- :s3_bucket_id => 'bucket-id',
- :s3_object_path => 'path/to/object',
- :s3_object_id => 'object_id',
- :sequencer_table_name => 'your_dynamo_db_table',
- :sqs_queue_url => 'https://your_amazon_sqs_queue_url',
- :sequential_proc => sequential_proc,
- :set_last_seen_proc => set_last_seen_proc,
- :lookup_table_name => 'your_lookup_table'
-}
+**foo.mustache**
-logger = Logger.new
-
-thread = Alephant::Alephant.new(opts, logger).run!
-thread.join
```
+{{ content }}
+```
-Publisher requires both queue options and writer options to be provided. To ensure a standard format you should use the `Options` class to generate your options before passing them onto the Publisher...
+## Usage
```ruby
-opts = Alephant::Publisher::Options.new
-# => #<Alephant::Publisher::Options:0x0602f958 @queue={}, @writer={}>
+require "alephant/logger"
+require "alephant/publisher/queue"
-opts.queue
-# => {}
-# empty to start with
+module MyApp
+ def self.run!
+ loop do
+ Alephant::Publisher::Queue.create(options).run!
+ rescue => e
+ Alephant::Logger.get_logger.warn "Error: #{e.message}"
+ end
+ end
-opts.writer
-# => {}
-# empty to start with
+ private
-opts.add_queue(:foo => "bar")
-# The key 'foo' is invalid
-# => nil
-
-opts.queue
-# => {}
-# still empty as the foo key was invalid
-
-opts.add_queue(:sqs_queue_url => "bar")
-# => {:sqs_queue_url=>"bar"}
-
-opts.queue
-# => {:sqs_queue_url=>"bar"}
-
-opts.add_writer(:sqs_queue_url => "bar")
-# The key 'sqs_queue_url' is invalid
-# => nil
-# the sqs_queue_url key was valid for the queue options,
-# but is invalid when trying to add it to the writer options
-
-opts.add_writer(:msg_vary_id_path => "bar")
-=> {:msg_vary_id_path=>"bar"}
-
-opts.writer
-=> {:msg_vary_id_path=>"bar"}
+ def self.options
+ Alephant::Publisher::Queue::Options.new.tap do |opts|
+ opts.add_queue(
+ :aws_account_id => 'example',
+ :sqs_queue_name => 'test_queue'
+ )
+ opts.add_writer(
+ :keep_all_messages => 'false',
+ :lookup_table_name => 'lookup-dynamo-table',
+ :renderer_id => 'renderer-id',
+ :s3_bucket_id => 'bucket-id',
+ :s3_object_path => 'example-s3-path',
+ :sequence_id_path => '$.sequential_id',
+ :sequencer_table_name => 'sequence-dynamo-table',
+ :view_path => 'path/to/views'
+ )
+ end
+ end
+end
```
-logger is optional, and must confirm to the Ruby standard logger interface
+Add a message to your SQS queue, with the following format:
-Provide a view in a folder (fixtures are optional):
-
-```
-└── views
- ├── models
- │ └── foo.rb
- ├── fixtures
- │ └── foo.json
- └── templates
- └── foo.mustache
-```
-
-**SQS Message Format**
-
```json
{
- "content": "hello world",
+ "content": "Hello World!",
"sequential_id": 1
}
```
-**foo.rb**
+Output:
-```rb
-module MyApp
- module Views
- class Foo < Alephant::Views::Base
- def content
- @data['content']
- end
- end
- end
-end
```
-
-**foo.mustache**
-
-```mustache
-{{content}}
+Hello World!
```
-**S3 Output**
+S3 Path:
```
-hello world
+S3 / bucket-id / example-s3-path / renderer-id / foo / 7e0c33c476b1089500d5f172102ec03e / 1
```
-## Build the gem locally
-
-If you want to test a modified version of the gem within your application without publishing it then you can follow these steps...
-
-- `gem uninstall alephant-publisher-queue`
-- `gem build alephant-publisher-queue.gemspec` (this will report the file generated which you reference in the next command)
-- `gem install ./alephant-publisher-queue-0.0.1.gem`
-
-Now you can test the gem from within your application as you've installed the gem from the local version rather than your published version
-
## Preview Server
-`alephant preview`
+[Alephant Preview](https://github.com/BBC-News/alephant-preview) allows you to see the HTML generated by your templates, both standalone and in the context of a page.
-The included preview server allows you to see the html generated by your
-templates, both standalone and in the context of a page.
-
-**Standalone**
-
-`/component/:id/?:fixture?`
-
-### Full page preview
-
-When viewing the component in the context of a page, you'll need to retrieve a
-mustache template to provide the page context.
-
-When performing an update a regex is applied to replace the static hostnames in
-the retrieved html.
-
-**Environment Variables**
-
-```sh
-STATIC_HOST_REGEX="static.(sandbox.dev|int|test|stage|live).yourapp(i)?.com\/"
-PREVIEW_TEMPLATE_URL="http://yourapp.com/template"
-```
-
-**Example Remote Template**
-
-`id` is the component/folder name
-
-`template` is the mustache template file name
-
-`location_in_page` should be something like (for example) `page_head` (specified within a `preview.mustache` file that the consuming application needs to create).
-
-- `http://localhost:4567/component/id/template`
-- `http://localhost:4567/preview/id/template/location_in_page`
-
-`alephant update`
-
-**In page**
-
-`/preview/:id/:region/?:fixture?`
-
## Contributing
1. [Fork it!](http://github.com/BBC-News/alephant-publisher-queue/fork)
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+2. Create your feature branch: `git checkout -b my-new-feature`
+3. Commit your changes: `git commit -am 'Add some feature'`
+4. Push to the branch: `git push origin my-new-feature`
+5. Create new [Pull Request](https://github.com/BBC-News/alephant-publisher-queue/compare).
+
+Feel free to create an [issue](https://github.com/BBC-News/alephant-publisher-queue/issues/new) if you find a bug.