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.