rear 0.2.0

data/docs/Deploy.md

@@ -0,0 +1,62 @@
+
+**Rear** can run in standalone mode or can be integrated/mounted into any `Espresso` application.
+
+## Running a standalone application:
+
+`$ cat config.ru`
+```ruby
+require 'rear'
+
+# model
+class Page < ActiveRecord::Base
+  # ...
+end
+
+# controller
+Rear.register Page do
+  # some setups, if any
+end
+
+run Rear
+```
+
+Then `$ rackup -s ServerName -p PortNumber` to start it.
+
+
+## Integrating Rear into existing Espresso application:
+
+```ruby
+# models
+class Page < ActiveRecord::Base
+  # ...
+end
+
+# backend controllers
+Rear.register Page
+
+# frontend controllers
+module Frontend
+  class Pages < E
+    map '/'
+    # ...
+  end
+end
+
+# Espresso application
+app = E.new
+
+# mounting frontend controllers into root URL
+app.mount Frontend, '/'
+
+# mounting backend controllers into /admin URL
+app.mount Rear.controllers, '/admin'
+
+# starting app
+app.run :server => ServerName, :port => PortNumber
+```
+
+So basically mount **Rear.controllers** wherever you need.
+
+
+**[ [contents &uarr;](https://github.com/espresso/rear#tutorial) ]**
+

data/docs/FileManager.md

@@ -0,0 +1,75 @@
+
+When you need a web file manager simply create a controller
+and set path to managed folder via `fm_root`:
+
+```ruby
+class FileManager < E
+  include Rear
+  fm_root 'path/to/files/'
+end
+```
+
+That's all. Now you have a *FileManager* menu entry. Click on it to manage your files.
+
+## Text Editor
+
+When you are dealing with files containing source code you need a specialized editor.
+
+For now, Rear is offering support for [CKEditor](http://ckeditor.com) and [Ace](http://ace.ajax.org) editors.
+
+Before using editors you'll have to install and load corresponding gems.
+
+See [`rear-ckeditor`](https://github.com/espresso/rear-ckeditor) and
+[`rear-ace`](https://github.com/espresso/rear-ace) for instructions.
+
+After installed and loaded, simply use `fm_editor` to set desired editor:
+
+```ruby
+class FileManager < E
+  include Rear
+  fm_root 'path/to/files/'
+
+  fm_editor :ace
+  # or
+  fm_editor :ckeditor
+end
+```
+
+
+## Menu Label
+
+If *FileManager* label is not suitable, use `label` to set custom menu label:
+
+```ruby
+class FileManager < E
+  include Rear
+  fm_root '../public/images'
+
+  label :Images
+end
+```
+now it will display *Images* in menu.
+
+## Multiple
+
+If you have multiple folders to manage, create a controller for each one.
+
+Optionally you can put all file managers under same menu entry by using menu grouping:
+
+```ruby
+class Templates < E
+  include Rear
+  fm_root '../views/'
+  
+  menu_group :FileManager
+end
+
+class Images < E
+  include Rear
+  fm_root '../public/images'
+
+  menu_group :FileManager
+end
+```
+now you have *FileManager* menu entry that will reveal *Templates* and *Images* links on hover.
+

data/docs/Filters.md

@@ -0,0 +1,341 @@
+
+By default **Rear** will add only the ability to filter by primary key.
+
+To add more filters, use `filter`, `quick_filter` and `decorative_filter` methods.
+
+The simplest case:
+
+```ruby
+class Photo
+  include DataMapper::Resource
+  # ...
+end
+
+Rear.register Photo do
+  filter :name
+end
+```
+
+
+## Filter Types
+
+**Rear** supports following filter types:
+
+    - :string/:text
+    - :select
+    - :radio
+    - :checkbox
+    - :date
+    - :datetime
+    - :time
+    - :boolean
+
+Filter type should be passed as second argument and should be a downcase symbol:
+
+```ruby
+
+  filter :created_at, :date
+
+```
+
+If no type given, **it will be inherited** from a column with same name, if any:
+
+```ruby
+class Page
+  include DataMapper::Resource
+  # ...
+  property :created_at, Date
+end
+
+Rear.register Page do
+  filter :created_at  # type inherited automatically
+end
+```
+
+So, laziness is a virtue... sometimes...
+
+**[ [contents ↑](https://github.com/espresso/rear#tutorial) ]**
+
+
+## Comparison Functions
+
+`:string/:text` filters will use `:like` comparison function by default,
+so `filter :name` will generate a SQL like:
+
+```
+... WHERE name LIKE '%VALUE%' ...
+```
+
+`:checkbox` filters will use `:in` comparison function by default:
+
+```
+... WHERE column IN ('VALUE1', 'VALUE2') ...
+```
+
+If you use a custom "cmp" function with a `:checkbox` filter,
+filter's column will be compared to each selected value:
+
+```
+... WHERE (column LIKE '%VALUE1%' OR column LIKE '%VALUE2%') ...
+```
+
+Filters of any other type will use equality for comparison function,
+so a filter like `filter :created_at, :date` will generate an SQL like:
+
+```
+... WHERE created_at = 'VALUE' ...
+```
+
+To use a custom comparison function pass it via `:cmp` option:
+
+```ruby
+
+  filter :created_at, cmp: :like
+
+```
+
+Supported comparison functions:
+
+    - :eql       # equal
+    - :not       # not equal
+    
+    - :gt        # greater than
+    - :gte       # greater than or equal
+    - :lt        # less than
+    - :lte       # less than or equal
+    
+    - :like      # uses left and right wildcards - "column LIKE '%VALUE%'"
+    - :unlike    # - "column NOT LIKE '%VALUE%'"
+    
+    - :_like     # use only left wildcard, exact match for end of line - "column LIKE '%VALUE'"
+    - :_unlike   # - "column NOT LIKE '%VALUE'"
+    
+    - :like_     # use only right wildcard, exact match for beginning of line - "column LIKE 'VALUE%'"
+    - :unlike_   # - "column NOT LIKE 'VALUE%'"
+
+**[ [contents ↑](https://github.com/espresso/rear#tutorial) ]**
+
+
+## Optioned Filters
+
+`:radio`, `:checkbox` and `:select` filters requires a block to run.
+
+Block should return an Array or Hash.
+
+Arrays used when stored keys are the same as displayed values:
+
+```ruby
+
+  filter :color do
+    %w[Red Green Blue]
+  end
+
+```
+
+If stored keys differs from displayed values, a `Hash` should be used:
+
+```ruby
+
+  filter :color do
+    {'r' => 'Red', 'g' => 'Green', 'b' => 'Blue'}
+  end
+
+```
+
+In example above 'r', 'g' and 'b' are db values and 'Red', 'Green', 'Blue' are displayed values.
+
+If no block given, **Rear** will search for a column with same name and inherit options from there.
+
+So if you have say a `:checkbox` column named `:colors` with defined options,
+you only need to do `filter :colors`, without specifying type and options,
+cause type and options will be inherited from earlier defined column:
+
+
+```ruby
+
+  input :colors, :checkbox do
+    options 'Red', 'Green', 'Blue'
+  end
+
+  filter :colors # type and options inherited from :colors column
+
+```
+
+So, laziness is definitely a virtue...
+
+**[ [contents ↑](https://github.com/espresso/rear#tutorial) ]**
+
+
+## Decorative Filters
+
+Sometimes you need to filter by some value that has too much options.
+
+For ex. you want to filter pages by author and there are about 1000 authors in db.
+
+Displaying all authors within a single dropdown filter is kinda cumbersome.
+
+Decorative filters allow to narrow down the options displayed on other filters.
+
+In example below authors will not be loaded until a letter selected:
+
+```ruby
+  
+  decorative_filter :letter, :select do
+    ('A'..'Z').to_a
+  end
+
+  filter :author_id, :select do
+    if letter = filter?(:letter) # use the name of decorative filter with `filter?` method
+      authors = {}
+      model.all(name: /^#{letter}/).each |a|
+        authors[a.id] = a.name
+      end
+      authors
+    else
+      {"" => "Select a letter please"}
+    end
+  end
+
+```
+
+A decorative filter will update filters every time new option selected and `filter?(:decorative_filter_name)` will return the selected option.
+
+Worth to note that decorative filters will not actually query the db,
+so you can name then as you want.
+
+Also, decorative filters does not use/support custom comparison functions.
+
+**[ [contents ↑](https://github.com/espresso/rear#tutorial) ]**
+
+
+## Quick Filters
+
+
+A.k.a Button Filters, allows to filter through items by simply clicking a button.
+
+For ex. you need to quickly display active items.
+
+A standard filter will require from user to select some value then click "Search" button.
+
+Quick filters instead will create an "Active" button that will display only active items when clicked.
+
+As per standard filters, when stored keys are the same as values, use an `Array`.
+
+```ruby
+
+  quick_filter :color, 'Red', 'Green', 'Blue'
+
+```
+
+This will create three grouped buttons that will display corresponding items on click.
+
+
+And when keys are different, use a `Hash`:
+
+```ruby
+
+  quick_filter :color, 'r' => 'Red', 'g' => 'Green', 'b' => 'Blue'
+
+```
+
+This will create three buttons - Red, Green, Blue - that on click will display items with color equal to 'r', 'g', 'b' respectively.
+
+And of course, as per standard filters, if you do not provide options, they will be inherited from a column with same name, if any:
+
+```ruby
+class Photo < ActiveRecord::Base
+  # ...
+end
+
+Rear.register Photo do
+
+  input :gamma, :checkbox do
+    options "Red", "Green", "Blue"
+  end
+  
+  quick_filter :gamma  # options are inherited from `:gamma` column
+end
+```
+
+By default, quick filters will use equality for comparison function.
+
+To use a custom comparison function, set it via `:cmp` option:
+
+```ruby
+
+  quick_filter :color, 'Red', 'Green', 'Blue', cmp: :like
+  
+```
+
+**Hint** - if you need to filter through a column that has "cmp" as db value,
+pass db value as string and cmp function as symbol:
+
+```ruby
+quick_filter :action, 'cmp' => 'Compare', 'snd' => 'Send', cmp: :like
+```
+
+It is also possible to use per filter comparison function:
+
+```ruby
+quick_filter :color, [:like, 'r'] => 'Red', 'g' => 'Green', 'b' => 'Blue'
+# when Red clicked, LIKE comparison function will be used.
+# on Green and Blue, equality will be used.
+```
+
+**[ [contents &uarr;](https://github.com/espresso/rear#tutorial) ]**
+
+
+## Internal Filters
+
+Used when you need fine-tuned control over displayed items.
+
+Internal filters wont render any inputs, they will work under the hood.
+
+`internal_filter` requires a block that should return a list of matching items.
+
+**Example:** Display only articles newer than 2010:
+
+```ruby
+class Article
+  include DataMapper::Resource
+
+  property :id, Serial
+  # ...
+  property :created_at, Date, index: true
+end
+
+Rear.register Article do
+  # ...
+
+  internal_filter do
+    Article.all(:created_at.gt => Date.new(2010))
+  end
+end
+```
+
+**Example:** Filter articles by category:
+
+```ruby
+class Article < ActiveRecord::Base
+  belongs_to :category
+end
+
+Rear.register Article do
+  
+  # firstly lets render a decorative filter
+  # that will render a list of categories to choose from
+  decorative_filter :Category do
+    Hash[ Category.all.map {|c| [c.id, c.name]} ]
+  end
+
+  # then we using internal_filter
+  # to yield selected category and filter articles
+  internal_filter do
+    if category_id = filter?(:Category)
+      Article.all(category_id: category_id.to_i)
+    end
+  end
+end
+```
+
+**[ [contents &uarr;](https://github.com/espresso/rear#tutorial) ]**