User Messaging Async calls, compatible with Mongoid (Ruby on Rails) gem
Ruby
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
app
lib
.gitignore
Gemfile
LICENSE
README.md
Rakefile
async-messaging.gemspec

README.md

Async::Messaging

The Async Messaging gem (Ruby on Rails) aims to simplify User notifications when handling asynchronous calls within your application, via messaging.

For example: you're using Delayed::Job (https://github.com/collectiveidea/delayed_job) and have completed a 'delayed' action, but want to notify the user about the status after it's completed. A simple flash[:notice] isn't going to work because you're outside User context.

NOTE: Currently this gem is under heavy development, function calls will change in the future

The capabilities of async-messaging are required for a private project, which is MongoDB/ Mongoid backed. Alternate messaging systems are not capable of handing these requirements (https://www.ruby-toolbox.com/categories/User_Messaging_Systems).

Roadmap

  • Version (0.0.1)

    • Functional gem to push User notifications via flash messages
    • Archive functionality with flash messages
    • View generators
  • Future features (subject to change)

    • Javascript flash message pull
    • Activerecord support
    • Email style user messaging

Installation

Add this line to your application's Gemfile:

gem 'async-messaging', github: "dblommesteijn/async-messaging"

And then execute:

$ bundle

Configuration

Generate initialize script for async-messaging

$ rails g asyncmessaging:install

Configure initializer script with your Models config/initializer/async-messaging.rb

# Async::Messaging initializer
# Use this hook to define your messaging setup

Async::Messaging.setup do |config|
  # mongoid configuration
  require 'orm_adapter/adapters/mongoid'
  # if you're using devise use:
  require 'devise/orm/mongoid'
  # provide the root user instance (system messaging source)
  # NOTE: this can/ should be a dummy account!
  config.model_root = User.find("5333f81244656eccdc020000")
  # give a lambda/ Proc to retreive the current 'active' model (logged in user)
  config.model_current = lambda{ User.current }
  # provide the model type (class) to lookup the stored message ids
  config.model_type = User
  # flash notification default archive setting (true = save flash, false = remove flash)
  config.archive_flash = true
end

Add flash handler to your Controller app/controllers/application_controller.rb

# handle flash messaging from Async::Messaging helper
include Async::Messaging::Helper

NOTE: Async::Messaging::Helper adds before_filter :help_async_messaging that collects all user flash messages from the database and creates flashes.

Cancel flash message behaviour (skip before_filter)

skip_before_filter :help_async_messaging

Prepare your flash notification view

Below is an example of flash view (in slimlang) and Bootstrap. The example will not show any values other than Strings, now we need to expand on this by switching if key == :async_messaging

div.row
  div.col-xs-12
    - flash.each do |key, value|
      - if key == :async_messaging
        / async_messaging flash
        - value.each do |notification|
          - next if notification.empty?
          div{class="alert alert-info fade in"}
            a.href{data-dismiss="alert" class="close"}
              li.fa.fa-times
            / prettify the message
            p
              strong
                = notification[:subject]
                = " ".html_safe
              = notification[:content]
      - else
        / default flash
        div{class="alert alert-info fade in"}
          a.href{data-dismiss="alert" class="close"}
            li.fa.fa-times
          = value if value.is_a? String

Generating System Messages

Notify a user, send a system message via flash.

NOTE: These messages are archived upon retreival (unless the archive options is set)

# sends a system message to a user as flash message (and keep it archived)
Async::Messaging::Notify.notify_user(User.first, subject: "System Notice", content: "How are you?", category: :flash, flags: [:info], archive: true)

Options

  • Subject: message subject
  • Content: message body
  • Category: internal mechanism to categorize messages (:message, :flash)
  • Flags: div class to use with the message (:info, :warning etc)
  • Archive: archive flash as message after notification is presented (true 'default', false)

NOTE: on page reload the flash message is collected in the ApplicationController via the before_filter in Async::Messaging::Controller.

Using User Messaging GUI

NOTE: not working yet

Configuring Routes

By default the User messaging is not exteded into the routes. By adding the following line to your config/routes.rb the Controllers and Views are enabled.

App::Application.routes.draw do
  # add the async_messaging_for to change the default settings
  # 'prefix' defines the route to the controller (http://yourhost/user/messaging)
  # 'path_names' allows to overwrite the default names of nested actions
  async_messaging_for prefix: 'user/messaging', path_names: {
    model: {prefix: "settings", show: "show", edit: "edit", create: "create"}, 
    message: {prefix: "message", show: "show", edit: "edit", create: "create", new: "new", index: "home"}}
end

Customizing Views

It's possible to customize the default views.

Add folders and files to your app/views

  • async/messaging/message/index.html.slim (overview)
  • async/messaging/message/edit.html.slim (edit a messages)
  • async/messaging/message/new.html.slim (create a new message)
  • async/messaging/message/show.html.slim (view a single message)
  • async/messaging/model/edit.html.slim (edit messaging settings)
  • async/messaging/model/show.html.slim (show messaging settings)

Examples are shown below (in slimlang)

# TODO: add example for the views here!!