README

   1 MerbEMart
   2 =========
   3
   4 Please see also README.markdown.
   5
   6 A slice for the Merb framework.
   7
   8 ------------------------------------------------------------------------------
   9
  10 Instructions for installation:
  11
  12 file: config/init.rb
  13
  14 # add the slice as a regular dependency
  15
  16 dependency 'merb-E-mart'
  17
  18 # if needed, configure which slices to load and in which order
  19
  20 Merb::Plugins.config[:merb_slices] = { :queue => ["MerbEMart", ...] }
  21
  22 # optionally configure the plugins in a before_app_loads callback
  23
  24 Merb::BootLoader.before_app_loads do
  25
  26   Merb::Slices::config[:merb_E_mart] = { ... }
  27
  28 end
  29
  30 file: config/router.rb
  31
  32 # example: /merb-E-mart/:controller/:action/:id
  33
  34 r.add_slice(:MerbEMart)
  35
  36 # example: /foo/:controller/:action/:id
  37
  38 r.add_slice(:MerbEMart, 'foo') # same as :path => 'foo'
  39
  40 # example: /:lang/:controller/:action/:id (with :a param set)
  41
  42 r.add_slice(:MerbEMart, :path => ':lang', :params => { :a => 'b' })
  43
  44 # example: /:controller/:action/:id
  45
  46 r.slice(:MerbEMart)
  47
  48 Normally you should also run the following rake task:
  49
  50 rake slices:merb_E_mart:install
  51
  52 ------------------------------------------------------------------------------
  53
  54 You can put your application-level overrides in:
  55
  56 host-app/slices/merb-E-mart/app - controllers, models, views ...
  57
  58 Templates are located in this order:
  59
  60 1. host-app/slices/merb-E-mart/app/views/*
  61 2. gems/merb-E-mart/app/views/*
  62 3. host-app/app/views/*
  63
  64 You can use the host application's layout by configuring the
  65 merb-E-mart slice in a before_app_loads block:
  66
  67 Merb::Slices.config[:merb_E_mart] = { :layout => :application }
  68
  69 By default :merb_E_mart is used. If you need to override
  70 stylesheets or javascripts, just specify your own files in your layout
  71 instead/in addition to the ones supplied (if any) in
  72 host-app/public/slices/merb-E-mart.
  73
  74 In any case don't edit those files directly as they may be clobbered any time
  75 rake merb_E_mart:install is run.
  76
  77 ------------------------------------------------------------------------------
  78
  79 About Slices
  80 ================
  81
  82 Merb-Slices is a Merb plugin for using and creating application 'slices' which
  83 help you modularize your application. Usually these are reuseable extractions
  84 from your main app. In effect, a Slice is just like a regular Merb MVC
  85 application, both in functionality as well as in structure.
  86
  87 When you generate a Slice stub structure, a module is setup to serve as a
  88 namespace for your controller, models, helpers etc. This ensures maximum
  89 encapsulation. You could say a Slice is a mixture between a Merb plugin (a
  90 Gem) and a Merb application, reaping the benefits of both.
  91
  92 A host application can 'mount' a Slice inside the router, which means you have
  93 full over control how it integrates. By default a Slice's routes are prefixed
  94 by its name (a router :namespace), but you can easily provide your own prefix
  95 or leave it out, mounting it at the root of your url-schema. You can even
  96 mount a Slice multiple times and give extra parameters to customize an
  97 instance's behaviour.
  98
  99 A Slice's Application controller uses controller_for_slice to setup slice
 100 specific behaviour, which mainly affects cascaded view handling. Additionaly,
 101 this method is available to any kind of controller, so it can be used for
 102 Merb Mailer too for example.
 103
 104 There are many ways which let you customize a Slice's functionality and
 105 appearance without ever touching the Gem-level code itself. It's not only easy
 106 to add template/layout overrides, you can also add/modify controllers, models
 107 and other runtime code from within the host application.
 108
 109 To create your own Slice run this (somewhere outside of your merb app):
 110
 111 $ merb-gen slice <your-lowercase-slice-name>
 112