populate-me 0.0.33 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA256:
-  metadata.gz: 8164c457284a0daa762745f768ba56acead4592eab6fca62547dfff4d56ad7da
-  data.tar.gz: f8fa01c9478a8be7fe04c4628f0c3785d4f089203c6eb8961565defbae6e0b66
+SHA1:
+  metadata.gz: 5046f2abc8d311d2dedd3c31fac2ac90f6ae0f36
+  data.tar.gz: 2df84aed8c576a8a2908977fde658f2ad85ae2e7
 SHA512:
-  metadata.gz: 66160cda7918beb24097e28de0189a381c7c72eaea16c184ca8a2e0e2dbb848df73a7af41feb9f195e5942090e483622961386000597a7a625becea4a3208e9b
-  data.tar.gz: cb4972cd6d06fc192ece77899110fc33533e5f2b02116562d55b60b6f7a6c62e8c4f854e654ebd047828a9ecf9cb0104278aab7cae252f8030d7d5994d1bef54
+  metadata.gz: 0f4d57c7dfc72de5c4dc08e027c498e7cee4bd4de3fa2b3cc5facb74c28aaa006e8270d5f79baa1fc0af2b48aec0b297bb0dd9ecc211a28018d37b1ca415c109
+  data.tar.gz: 71dd5a2221caa8d1e9d3761c2651e2542f1182ea30f00d50f4b0bb9d5e010d1d8f46df5695b941544aac4af5f83a306cd27243ba03e28a6a2cb4018619446081

data/.gitignore

@@ -1,5 +1,6 @@
 .DS_STORE
 *.swp
+*.sass-cache
 .ruby-version
 pkg/
 *.gem

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2017 Mickael Riga
+Copyright (c) 2016 Mickael Riga
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,9 +1,404 @@
 Populate Me
 ===========
 
-!!! WARNING : This project is under construction and therefore is not usable yet.
+Overview
+--------
 
-Nevertheless Populate Me will be a relatively complete but simple CMS.  
-It will include a Rack middleware for putting in your Rack stack, and a bespoke MongoDB ODM.    
-Stay tuned.
+`PopulateMe` is a modular system which provides an admin backend for any 
+Ruby/Rack web application. It is made with Sinatra but you can code your 
+frontend with any other Framework like Rails.
+
+Table of contents
+----------------
+
+- [Overview](#overview)
+- [Table of contents](#table-of-contents)
+- [Documents](#documents)
+  - [Schema](#schema)
+  - [Validations](#validations)
+  - [Relationships](#relationships)
+  - [Callbacks](#callbacks)
+  - [Single Documents](#single-documents)
+  - [Mongo documents](#mongo-documents)
+- [Admin](#admin)
+- [API](#api)
+
+Documents
+---------
+
+The `Document` class is a prototype. It contains all the code that is
+not specific to a database system. When using this class, documents are
+just kept in memory and therefore are lost when you restart the app.
+
+Obviously, in a real application, you would not use this class, but
+a persistent one instead. But since the purpose is to have a common 
+interface for any database system, then the following examples are 
+written using the basic `Document` class.
+
+For the moment, `PopulateMe` only ships with a [MongoDB](#mongo-documents) document, but we hope there will be others in the future, including some for SQL databases.
+
+### Schema
+
+Here is an example of a document class:
+
+```ruby
+require 'populate_me/document'
+
+class BlogArticle < PopulateMe::Document
+  
+  field :title, default: 'New blog article', required: true
+  field :content, type: :text
+  field :created_on, type: :datetime, default: proc{Time.now}
+  field :published, type: :boolean
+
+  sort_by :created_on, :desc
+
+end
+```
+
+Quite common so far. 
+The `field` method allows you to record anything about the field 
+itself, but here are the keys used by `PopulateMe`:
+
+- `:type` Defines the type of field (please find the list of types below).
+- `:form_field` Set to `false` if you do not want this field in the default form.
+- `:label` What the label in the form says (defaults to a human-friendly version of the field name)
+- `:wrap` Set it to false if you do not want the form field to be wrapped in a `div` with a label.
+- `:default` Either a default value or a `proc` to run to get the default value.
+- `:required` Set to true if you want the field to be marked as required in the form.
+
+As you can see, most of the options are made for you to tailor the form
+which `PopulateMe` will generate for you in the admin.
+
+Available types are:
+
+- `:string` Short text.
+- `:text` Multiline text.
+- `:boolean` Which is `true` or `false`.
+- `:select` Dropdown list of options (records a string).
+
+A `:list` type exists as well for nested documents, but it is not 
+fully working yet.
+
+### Validations
+
+In its simplest form, validations are done by overriding the `#validate` method and declaring errors with the `#error_on` method.
+
+```ruby
+class Person < PopulateMe::Document
+  
+  field :name
+
+  def validate
+    error_on(:name, 'Cannot be fake') if self.name=='John Doe'
+  end
+
+end
+```
+
+If you don't use the `PopulateMe` interface and create a document
+programmatically, here is what it could look like:
+
+```ruby
+person = Person.new(name: 'John Doe')
+person.new? # returns true
+person.save # fails
+person.valid? # returns false
+person.errors # returns { name: ['Cannot be fake'] }
+```
+
+### Relationships
+
+In its simplest form, when using the modules convention, relationships
+can be declared this way:
+
+```ruby
+class BlogArticle < PopulateMe::Document
+  
+  field :title
+
+  relationship :comments
+
+end
+
+class BlogArticle::Comment < PopulateMe::Document
+
+  field :author
+  field :blog_article_id, type: :hidden
+  position_field scope: :blog_article_id
+
+end
+```
+
+### Callbacks
+
+There are some classic hooks which trigger the callbacks you declare.
+Here is a basic example:
+
+```ruby
+require 'populate_me/document'
+
+class Person < PopulateMe::Document
+  
+  field :firstname
+  field :lastname
+  field :fullname, form_field: false
+
+  before :save do
+    self.fullname = "#{self.firstname} #{self.lastname}"
+  end
+
+  after :delete, :goodbye
+
+  def goodbye
+    puts "So long and thanks for all the fish"
+  end
+
+end
+```
+
+First you can note that the field option `form_field: false` makes it a field
+that does not appear in the form. This is generally the case for fields that 
+are generated from other fields.
+
+Anyway, here we define a callback which `PopulateMe` runs each time a document
+is saved. And with the second one, you can see that we can pass the name of
+a method instead of a block.
+
+The list of hooks is quite common but here it is as a reminder:
+
+- `before :validation`
+- `after :validation`
+- `before :create`
+- `after :create`
+- `before :update`
+- `after :update`
+- `before :save` (both create or update)
+- `after :save` (both create or update)
+- `before :delete`
+- `after :delete`
+
+Now you can register many callbacks for the same hook. They will be chained in
+the order you register them. However, if for any reason you need to register a
+callback and make sure it runs before the others, you can add `prepend: true`.
+
+```ruby
+before :save, prepend: true do
+  puts 'Shotgun !!!'
+end
+```
+
+If you want to go even further and create your own hooks, this is very easy.
+You can create a hook like this:
+
+```ruby
+document.exec_callback(:my_hook)
+```
+
+And you would then register a callback like this:
+
+```ruby
+register_callback :my_hook do
+  # Do something...
+end
+```
+
+You can use `before` and `after` as well. In fact this:
+
+```ruby
+after :lunch do
+  # Do something...
+end
+```
+
+Is equivalent to:
+
+```ruby
+register_callback :after_lunch do
+  # Do something...
+end
+```
+
+### Single Documents
+
+Sometimes you want a collection with only one document, like for recording
+settings for example. In this case you can use the `::is_unique` class method.
+
+```ruby
+require 'populate_me/document'
+
+class GeneralWebsiteSettings < PopulateMe::Document
+  field :main_meta_title
+  field :main_meta_description
+  field :google_analytics_ref
+end
+
+GeneralWebsiteSettings.is_unique
+```
+
+It just creates the document if it does not exist yet with the ID `unique`.
+If you want a different ID, you can pass it as an argument.
+
+Just make sure that if you have fields with `required: true`, they also have
+a `:default` value. Otherwise the creation of the document will fail because it
+is not `self.valid?`.
+
+### Mongo Documents
+
+Note: the current version works with the mongo driver version 2
+
+Now let's declare a real document class which can persist on a database,
+the `MongoDB` kind of document. The first thing we need to clarify is the
+setup. Here is a classic setup:
+
+```ruby
+# lib/db.rb
+require 'mongo'
+require 'populate_me/mongo'
+
+client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'your-database-name')
+
+PopulateMe::Mongo.set :db, client.database
+
+require 'person'
+```
+
+Then the document is pretty much the same as the prototype except that it
+subclasses `PopulateMe::Mongo` instead.
+
+```ruby
+# lib/person.rb
+require 'populate_me/mongo'
+
+class Person < PopulateMe::Mongo
+  field :firstname
+  field :lastname
+end
+```
+
+As you can see in setup, you can define inheritable settings on 
+`PopulateMe::Mongo`, meaning that any subclass after this will have the `:db`
+and you can set it only once.
+
+Nevertheless it is obviously possible to set a different `:db` for each class.
+
+```ruby
+# lib/person.rb
+require 'populate_me/mongo'
+
+class Person < PopulateMe::Mongo
+
+  set :db, $my_db
+
+  field :firstname
+  field :lastname
+
+end
+```
+
+This is particularly useful if you keep a type of documents in a different 
+location for example. Otherwise it is more convenient to set it once 
+and for all.
+
+You can also set `:collection_name`, but in most cases you would let `PopulateMe`
+defaults it to the dasherized class name. So `BlogArticle::Comment` would be
+in the collection called `blog-article--comment`.
+
+Whatever you choose, you will have access to the collection object with the
+`::collection` class method. Which allows you to do anything the driver does.
+
+```ruby
+first_pedro = Person.collection.find({ 'firstname' => 'Pedro' }).first
+mcs = Person.collection.find({ 'lastname' => /^Mc/i })
+```
+
+Although since these are methods from the driver, `first_pedro` returns a hash,
+and `mcs` returns a `Mongo::Collection::View`. If you want document object, you can use
+the `::cast` class method which takes a block in the class context/scope and
+casts either a single hash into a full featured document, or casts the items of
+an array (or anything which responds to `:map`).
+
+```ruby
+first_pedro = Person.cast{ collection.find_one({ 'firstname' => 'Pedro' }) }
+mcs = Person.cast{ collection.find({ 'lastname' => /^Mc/i }) }
+first_pedro.class # returns Person
+mcs[0].class # returns Person
+```
+
+Admin
+-----
+
+A basic admin would look like this:
+
+```ruby
+# lib/admin.rb
+require "populate_me/admin"
+
+class Admin < PopulateMe::Admin
+  # Since we are in lib we use this to move
+  # the root one level up.
+  # Not mandatory but useful if you plan to have
+  # custom views in the main views folder
+  set :root, ::File.expand_path('../..', __FILE__)
+  # Only if you use Rack::Cerberus for authentication
+  # you can pass the settings
+  set :cerberus, {company_name: 'Nintendo'}
+  # Build menu and sub-menus
+  set :menu, [ 
+    ['Settings', '/admin/form/settings/unique'],
+    ['Articles', '/admin/list/article'],
+    ['Staff', [
+      ['Designers', '/admin/list/staff-member?filter[job]=Designer'],
+      ['Developers', '/admin/list/staff-member?filter[job]=Developer'],
+    ]]
+  ]
+end
+```
+
+So the main thing you need is to define your menu. Then mount it in
+your `config.ru` whereever you want.
+
+```ruby
+# config.ru
+require 'admin'
+
+map '/admin' do
+  run Admin
+end
+```
+
+Most of the URLs in your menu will probably be for the admin itself and use
+the admin URL patterns, but this is not mandatory. A link to an external page 
+would load in a new tab. Whereas admin URLs create columns in the `PopulateMe`
+user interface. Many things are possible with these patterns but here are 
+the main ones:
+
+- `/:path_to_admin/list/:dasherized_document_class` This gives you the list of
+documents from the desired class. They are ordered as specified by `sort_by`.
+You can also filter like in the example to get only specific documents.
+- `:path_to_admin/form/:dasherized_document_class/:id` You would rarely use this
+one which directly opens the form of a specific document, since all this is 
+generally accessed from the list page. It doesn't need to be coded. The only is
+probably for [single documents](#single-documents) because they are not part of
+a list. The ID would then be litterally `unique`, or whatever ID you declared
+instead.
+
+API
+---
+
+In a normal use, you most likely don't have anything to do with the `API` module.
+It is just another middleware automatically mounted under `/api` on your `Admin`.
+So if your `Admin` path is `/admin`, then your `API` path is `/admin/api`.
+
+The purpose of the `API` module is to provide all the path patterns for creating,
+deleting and updating documents. The interface does all the job for you. But if
+you end up building your all custom interface, you probably want to [have a look 
+at the implementation](lib/populate_me/api.rb).
+
+Another aspect of the `API` is that it relies on document methods. So if you 
+want to create a subclass of `Document`, make sure that you override everything
+that the `API` or the `Admin` may need.
+
+This module is derived from a Gem I did called [rack-backend-api](https://github.com/mig-hub/backend-api). It is not maintained any more since `PopulateMe` is the evolution
+of this Gem.
 

data/Rakefile

@@ -0,0 +1,14 @@
+require 'rake/testtask'
+
+task :default => :test
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.pattern = 'test/test_*.rb'
+  unless ENV['TESTONLY'].nil?
+    t.pattern = t.pattern.sub(/\*/, ENV['TESTONLY'])
+  end
+  t.options = '--pride'
+  t.warning = false
+end
+