This gem provides server-side functionality for the Netfira WebConnect protocol.
Installation
gem install web-connect
Usage
If you're using Rails, use the web-connect-rails gem.
To take your WebConnect-enabled app online, use the bundled Rack app and request filter middleware.
# config.ru
require 'web-connect'
require 'my-app'
use Netfira::WebConnect::RequestFilter
run Netfira::WebConnect::RackApp
The
RequestFilter
middleware is not essential, but can provide speed and compatibility advantages for older clients.
Configuration
This is a typical WebConnect configuration.
Netfira::WebConnect.configure do |c|
# This database configuration will be used by ActiveRecord
c.db = {
adapter: 'sqlite3',
database: 'test.sqlite3'
}
# This string will be prefixed to names of tables created by
# WebConnect
c.db_table_prefix = 'nf_'
# Enabled or disable storage of fields not included in WebConnect's
# default schema
c.custom_fields = false
# Default time zone
c.time_zone = 'Australia/Sydney'
# WebConnect activity will be logged here
c.logger = Logger.new(STDERR)
# Use any Paperclip storage configuration you like here. WebConnect
# provides the :shop_id and :model_type interpolations.
c.file_store = {
path: File.dirname(__FILE__) + '/uploads/shop_:shop_id/:model_type/:filename'
}
# This block will be passed a shop name and password whenever a client
# needs to authenticate
c.on_authenticate do |shop_name, password|
shop = Shop.find_by(name: shop_name)
shop && shop.password == password
end
# Session lifetime (omit to disable sessions)
c.session_lifetime = 5.days
# Send new-data notifications via HTTP. Options are :none, :sync, and :async.
c.http_notifications = :async
# AMQP server to use for downstream communications.
c.amqp = 'amqps://admin:Passw0rd@localhost:5672'
end
Migrations
WebConnect uses ActiveRecord migrations to manage its database. It comes with two rake tasks.
rake wc:migrate # Migrate the database
rake wc:rollback # Roll back a single migration
If your application uses ActiveRecord, these migrations will be managed independently of your application's migrations.
Run these migrations when you first install WebConnect, and whenever you update the WebConnect gem.
Data
You can access WebConnect data through the Netfira::WebConnect::Models
namespace.
product = Netfira::WebConnect::Models::Product.first
product.unit_price # BigDecimal
product.name # Netfira::WebConnect::Model::Record::TranslatedString
product.name[:en_AU] # String
You can lookup records using their original client-side identifiers using find_by_origin_id
.
shop = Netfira::WebConnect::Models::Shop.first
product = Netfira::WebConnect::Models::Product.find_by_origin_id(shop, 'product123')
# Or
product = shop.products.find_by(product_id: 'product123')
Events
Events in WebConnect are handled by delegates. Define your delegates like so:
class MyDelegate
def on_create_product(product)
# ...
end
end
Then add delegates to WebConnect:
Netfira::WebConnect.event_delegates << MyDelegate.new
The event_delegates
collection is an array. You can push, merge, delete etc as you would a normal array.
Any object can be an event delegate, and you can add as many as you like. They only need to respond any of the method signatures below.
Delegate Method Signatures
For | Example | Arguments | Remarks |
---|---|---|---|
New Records | on_create_buyer |
buyer |
Dispatched after record is created |
Record Updates | on_update_image |
image , previous_values |
Second argument is a hash of changed columns as they were before they were changed |
Deleted Records | on_delete_category |
category |
Dispatched before records are deleted |
New Relations | on_add_image_to_product |
image , product |
on_add_product_to_image also works, causing the arguments to also be swapped |
Deleted Relations | on_remove_product_from_category |
product , category |
Same as above |
Change Setting | on_change_setting |
setting , old |
setting will have shop , key , and value methods. old is the previous value. |
Except for previous_values
, all arguments above are instances of Netfira::WebConnect::Model::Record
.
Events are dispatched to delegates synchronously, on request threads. Create new threads if you want to prevent your handlers from blocking HTTP responses to WebConnect clients.