RightnowOms

Description

A common gem for managing your carts and orders. RightnowOms is a rails mountable engine. It gets a lot of benifits from Ember.JS

Requirements

Add the following gems to your Gemfile:

  gem 'jquery-rails'
  gem 'ember-rails'
  gem 'acts_as_api'
  gem 'haml-rails'
  gem 'confstruct'
  gem 'ransack'

  group :assets do
    gem 'uglifier'
    gem 'coffee-rails'
    gem 'sass-rails'
  end

Installation

Make sure that all requirements are met and add RightnowOms to your Gemfile.

  gem 'rightnow_oms'

and run bundle install

Setup

Mount rightnow_oms to your application.

  # config/routes.rb
  mount RightnowOms::Engine => "rightnow_oms", as: :rightnow_oms

Install the migrations of rightnow_oms:

  rake rightnow_oms:install:migrations
  rake db:migrate

rightnow_oms is built based on ember, ember-data and ember-i18n, so you need to install these libs first. Or you can use the files in rightnow_oms. So you need to add the following lines to your app/assets/javascripts/application.js:

  = require rightnow_oms/vendor/ember
  = require rightnow_oms/vendor/ember-data
  = require rightnow_oms/vendor/ember-i18n

After ember libs installed, you need to add rightnow_oms/application to your app/assets/javascripts/application.js:

  = require rightnow_oms/application

To enable the default theme of rightnow_oms, you need to link the default stylesheet into your app/assets/stylesheets/application.css:

  = require rightnow_oms/application

The configurations of rightnow_oms ember application are saved in key-value pairs. To override the default configurations, you only need to call RightnowOms.configure and reset the values of the configurations.

  RightnowOms.configure(function(config) {
    // Disable autoCommit
    config.set('autoCommit', false);

    // Set the default locale to zh_CN
    config.set('defaultLocale', 'zh_CN');
  });

Usage

Add a Float Cart to Your Pages

First, you need to load/create a cart for your pages. By adding a before filter load_or_create_cart to your controllers, you can get the cart.

  # This before filter will create an instance variable @cart
  before_filter :load_or_create_cart

Secondly, you need to add a place holder for your cart in your views:

  <div id="rightnow-oms">
    <script type="text/x-handlebars">
      {{ view RightnowOms.ShowCartView }}
    </script>
  </div>

And then you can load the cart:

  $(function() {
    RightnowOms.cartController.load(#{@cart.as_api_response(:default).to_json.html_safe});
  });

Add Cartable Things to Your Cart

rightnow_oms can only accept cartable model, so the things you added to the cart must be a cartable model. To define a cartable model, you just need to call the extended method acts_as_cartable in the model class.

  class Product < ActiveRecord::Base
    acts_as_cartable
  end

By default, Cart loads the name and price of cartable models by attributes named name and price. But you can define your own name and price attributes as follows:

  class Product < ActiveRecord::Base
    acts_as_cartable name: :your_name_attr, price: :your_price_attr
  end

Now you can add cartables to the cart.

  RightnowOms.cartController.addCartItem({
    cartable_id: 1,             // required
    cartable_type: 'Product',   // required
    price: '10.00',             // required
    name: 'Parent Product',    // optional
    quantity: 1,                // optional
    // optional, grouping cart items
    group: 'booking',
    // optional
    children: [{
      cartable_id: 2,             // required
      cartable_type: 'Product',   // required
      price: '5.00',              // required
      name: 'Child Product',      // optional
      quantity: 1,                // optional
      // optional, grouping cart items
      group: 'booking',
    })
  })

Manage Your Cart

Create a layout for your detailed cart view like:

  # app/views/layouts/rightnow_oms/cart.html.haml
  !!!
  %html
    %head
      %title RightnowOms
      = stylesheet_link_tag    "application"
      = javascript_include_tag "application"
      = csrf_meta_tags

    %body
      = yield

Create an Order with the Cart

To create an order, you need to specify the url of the page which the customer will add more detailed information on it. After you click the submit button on the detailed cart page, you will be redirected to the url which you have set.

  # config/initializers/rightnow_oms.rb
  RightnowOms.configure do
    new_order_url '/orders/new'
  end

Checkout

WIP

I18n

rightnow_oms supports I18n now. By default it only includes two locales: en and zh_CN, but you can create your own locales easily. First, you need to define your translations, for example:

  var zh_CN = { 
    'cart.cartable.counter': '购物车'
    'cart.total': '总计'

    'cart_item.name': '名称'
    'cart_item.price': '价格'
    'cart_item.quantity': '数量'
    'cart_item.total': '小计'

    'currency.unit': '￥'

    'buttons.check_cart': '查看我的购物车'
    'buttons.delete': '删除'
    'buttons.clean_cart': '清空购物车'
    'buttons.continue_to_shop': '继续购物'
    'buttons.new_order': '提交订单'

    'titles.cart': '我的购物车'

    'alerts.saving_cart': '正在保存购物车，请稍后。。。'

    'confirmations.delete_cart_item': '您确定要删除该商品吗？'
    'confirmations.clean_up_cart': '您确定要清空您的购物车吗？'
  };

And then add your translations to rightnow_oms and set it as the default locale:

  RightnowOms.configure(function(config) {
    config.set('locales.zh_CN', zh_CN);
    config.set('defaultLocale', 'zh_CN');
  });

It's welcome to create a pull request for your locale.

Development

RightnowOms is developed with Ruby 1.9.3-p0 and Rails 3.1.3

First of all, you need to create a database config for RightnowOms. There are already some useful templates for you under spec/dummy/config/. RightnowOms use MySQL by default. If you want to setup to use other databases, for example PostgreSQL, you need to modify the Gemfile and add the adapters by yourself.

  bundle install
  bundle exec rake app:db:migrate
  bundle exec rake app:db:seed

  # Run the tests. Please make sure you have firefox installed
  bundle exec rake app:db:test:prepare
  rspec

  # Start the dummy application
  rails s

For the javascript unit tests, you need to start the dummy application first, and then open your browser and visit http://localhost:3000/test/qunit