README.markdown

   1 MerbMart README
   2 ===============
   3
   4 MerbMart is an *open-source e-commerce engine*, developed on top of the recent
   5 Ruby-language, Merb MVC framework. It takes advantage of the Merb's slices
   6 plugin, allowing you to incorporate the engine into a customized e-commerce
   7 solution.
   8
   9 Performance
  10 -----------
  11
  12 _Mom and Pop?.. or Big Box?_
  13
  14 A key goal for the MerbMart engine is performance. Although MerbMart is
  15 designed for e-commerce sites of all sizes, the speed and scalability of the
  16 Merb and DataMapper frameworks make it scalable even for large online vendors.
  17
  18 The following technologies and frameworks provide a foundation for MerbMart:
  19
  20  * **Merb**, for Model-View-Controller.
  21  * **DataMapper**, for object relation mapping (ORM) and persistence.
  22  * **ActiveMerchant**, for Credit Card, payment and shipping processing.
  23    as well as attachmerb\_fu, merb\_paginate.
  24  * **RSpec**, for behavio(u)r driven development (BDD).
  25
  26 See INSTALL or the project wiki for a full list of dependencies.
  27
  28 MerbMart is inspired by other, Rails based e-commerce applications, including
  29 [Substruct][substruct] and [Spree][spree]. Although MerbMart started out as a
  30 project to port Substruct to Merb, the initial 0.1 release of MerbMart will
  31 instead be a its own implementation of an e-commerce engine, trying to match
  32 the feature sets other e-commerce applications, but taking advantages of the
  33 unique features of Merb and DataMapper.
  34
  35 About Slices
  36 ------------
  37
  38 Merb-Slices is a Merb plugin for using and creating application 'slices' which
  39 help you modularize your application. Usually these are reuseable extractions
  40 from your main app. In effect, a Slice is just like a regular Merb MVC
  41 application, both in functionality as well as in structure.
  42
  43 When you generate a Slice stub structure, a module is setup to serve as a
  44 namespace for your controller, models, helpers etc. This ensures maximum
  45 encapsulation. You could say a Slice is a mixture between a Merb plugin (a
  46 Gem) and a Merb application, reaping the benefits of both.
  47
  48 A host application can 'mount' a Slice inside the router, which means you have
  49 full over control how it integrates. By default a Slice's routes are prefixed
  50 by its name (a router :namespace), but you can easily provide your own prefix
  51 or leave it out, mounting it at the root of your url-schema. You can even
  52 mount a Slice multiple times and give extra parameters to customize an
  53 instance's behaviour.
  54
  55 A Slice's Application controller uses controller\_for\_slice to setup slice
  56 specific behaviour, which mainly affects cascaded view handling. Additionaly,
  57 this method is available to any kind of controller, so it can be used for
  58 Merb Mailer too for example.
  59
  60 There are many ways which let you customize a Slice's functionality and
  61 appearance without ever touching the Gem-level code itself. It's not only easy
  62 to add template/layout overrides, you can also add/modify controllers, models
  63 and other runtime code from within the host application.
  64
  65 Installation and Setup
  66 ----------------------
  67
  68 Please see the INSTALL file for details on getting up and running with MerbMart.
  69
  70 Developer Notes
  71 ---------------
  72
  73 **WARNING** : MerbMart is at a very early development stages. At this stage,
  74 the application should be considered only for consumption by advanced Ruby and
  75 Merb developers. If you're looking for something for production consumption,
  76 or not yet ready to jump from Ruby on Rails, then we would strongly advise
  77 trying [Substruct][substruct] or [Spree][spree].
  78
  79 **REQUEST** : Your development support is very much appreciated. Please
  80 contact us below if you're interested in lending a hand with the development
  81 of this project. Or alternatively, clone the code, fork it, create some
  82 patches and let us know when you're done.
  83
  84 Getting the Source
  85 ------------------
  86
  87 Performing a git clone on either of the following repositories will get you
  88 the latest source:
  89
  90     git clone git://github.com/myabc/merb_mart.git
  91     git clone git://gitorious.org/merb_mart/mainline.git (on gitorious)
  92
  93 The following additional mirrors are available:
  94
  95     git://repo.or.cz/merb_mart.git
  96     http://repo.or.cz/r/merb_mart.git
  97
  98 Copyright and License
  99 ---------------------
 100
 101 MerbMart is licensed under the **GNU Public License (GPL)**:
 102
 103    > Copyright (C) 2008  Alex Coles
 104
 105    > This program is free software: you can redistribute it and/or modify
 106    > it under the terms of the GNU General Public License as published by
 107    > the Free Software Foundation, either version 2 of the License, or
 108    > (at your option) any later version.
 109
 110    > This program is distributed in the hope that it will be useful,
 111    > but WITHOUT ANY WARRANTY; without even the implied warranty of
 112    > MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 113    > GNU General Public License for more details.
 114
 115    > You should have received a copy of the GNU General Public License
 116    > along with this program.  If not, see <http://www.gnu.org/licenses/>.
 117
 118 A copy of the GPL License may be found in the GPL-LICENSE, included with
 119 the distribution.
 120
 121 Support
 122 -------
 123
 124 **WARNING REPEATED** : MerbMart is still at a very early stage of its
 125 development. You should not use this code unless you're reasonably secure with
 126 the Ruby language, and the DataMapper and Merb frameworks. That said, _please
 127 do get involved_ - and if you're happy to contribute back with bug reports and
 128 patches, then we'll be happy to help you get the application up and running.
 129
 130 Your best source for support currently is either the wiki, IRC or the mailing
 131 list:
 132
 133  * **MerbMart Wiki** (this is its temporary residence):
 134     http://github.com/myabc/merb_mart/wikis
 135  * **MerbMart mailing list**:
 136     <http://groups.google.com/group/merb_mart>
 137  * **MerbMart homepage**: _coming soon_
 138  * Contact the developers directly:
 139     - <alex@alexcolesportfolio.com> | myabc on #datamapper, #merb IRC
 140
 141 [substruct]:http://code.google.com/p/substruct/ "Substruct e-commerce project"
 142 [spree]:http://spreehq.org/ "Spree Online Commerce for Ruby on Rails"