hippo-fw 0.9.1

data/db/migrate/01_create_system_settings.rb

@@ -0,0 +1,10 @@
+class CreateSystemSettings < ActiveRecord::Migration[5.0]
+    def change
+
+        create_table "system_settings" do |t|
+            t.integer :configuration_id
+            t.jsonb  "settings", null: false, default: {}
+        end
+
+    end
+end

data/db/migrate/02_create_assets.rb

@@ -0,0 +1,13 @@
+class CreateAssets < ActiveRecord::Migration[5.0]
+    def change
+
+        create_table "assets" do |t|
+            t.references :owner, polymorphic: true, null: false
+            t.integer    :order
+            t.jsonb      :file_data, null: false, default: {}
+        end
+
+        add_index :assets, [:owner_id, :owner_type]
+
+    end
+end

data/db/migrate/20140615031600_create_users.rb

@@ -0,0 +1,12 @@
+class CreateUsers < ActiveRecord::Migration[5.0]
+    def change
+        create_table :users do | t |
+            t.string :login, :name, :email,  null: false
+            t.string :password_digest, null: false
+            t.string  "role_names",   array: true, null:false, default: []
+            t.jsonb   "options",      null: false, default:  {}
+            t.timestamps null:false
+        end
+        add_index  :users, :role_names, using: 'gin'
+    end
+end

data/db/seed.rb

@@ -0,0 +1 @@
+Hippo::User.seed_admin_account

data/docs/command.md

@@ -0,0 +1,114 @@
+---
+# Front matter comment to ensure Jekyll properly reads file.
+# Do not remove
+title: hippo command
+heading: The "hippo" command
+position_after: model
+---
+
+Hippo framework installs a command line application which can be used to create and modify applicatons.
+
+The command "hippo" utilizes subcommands that direct it's activities.
+
+# hippo help
+
+Built-in help can be accessed by either running `hippo help` or command specific help by prefixing the final part of the command with 'help'.  For instance `hippo generate help model` will display comphrensive help for the 'hippo generate model' subcommand.
+
+# hippo new
+
+Executing `hippo new <app name>` will create a skeleton application that contains all the components needed to develop and deploy a single page application.
+
+It generates the following directory structure:
+
+<pre class="ascii-tree">
+├── Gemfile
+├── Guardfile
+├── Rakefile
+├── config.ru
+├── tmp
+├── client
+│   └── todo
+│       ├── Extension.coffee
+│       ├── components, data, views, styles, (empty directories)
+│       ├── index.js
+│       ├── screens
+│       │   └── base
+│       │       ├── Base.coffee
+│       │       ├── index.js
+│       │       ├── index.scss
+│       │       └── layout.html
+│       └── styles.scss
+├── config
+│   ├── database.yml
+│   ├── hippo.rb
+│   └── routes.rb
+├── spec
+│   └── todo
+└── lib
+    ├── todo
+    │   ├── extension.rb
+    │   └── version.rb
+    └── todo.rb
+</pre>
+
+
+Notable directories created are:
+
+ * *lib/<app_name>*  This directory will hold all server-side Ruby files that are needed by your application such as ActiveRecord models.
+ * *config* Contains the routes and a config file for modifying Lane's behaviour.
+ * *client/<app_name>*  Contains all the client code that makes up your application.  It has directories for views, data (models and collections), and screens.  A "Base" screen is created to start you off with.  You can use that screen as a base class for further screens if your application will be complex, or simply use it for your application if there will only be a single screen.  That's how the TODO MVC Example app is written.
+
+# hippo generate
+
+Constructs either a model, component or screen.
+
+## Component
+
+`hippo generate component <name>`
+
+Will create a new component file along with an accompanying spec.  By default the content will only render a simple [I am a {class_name} component] message.
+
+
+## Model
+
+`hippo generate model <name> [field definitions]`
+
+Creates a new model server and client side, a migration, fixtures file and accompanying specs.  It may be accompanied by a list of field names, which if given will be set on the appropriate files.
+
+The field specifications are given as `field:type` and seperated by spaces.
+
+For instance, `hippo generate model comment user:references title:string{80} content:text`, when executed inside of a project called "Blog":
+
+  * Will create a Ruby ActiveRecord model called `Blog::Comment` and an accompanying migration to add a user_id, a title and content fields.
+  * Setup a client model Blog.Data.Comment and a collection Blog.Data.BlogCollection
+  * Spec files will be created to test both the ActiveRecord model and the client Model and Collection.
+
+## Screen
+
+`hippo generate screen <name>`
+
+In the Hippo lexicon, a screen is a Component that is able to be loaded on demand.  By default, the styles and Javascript code that make up a screen are not loaded as part of the applications main bundles.  Instead the screen is loaded on demand when the user clicks on a menu.
+
+Remote data events for all sub components bubble up to the screen.  This allows the screen to display a notification to the user alerting them that another user edited data that is being currently displayed somewhere on the view.
+
+# hippo update
+
+## Model
+
+`hippo update model <name>`
+
+When developing a data driven application, the data model usually undergoes several revisions.  The update command reads the schema from the database and updates the client model with the updated field names, types, null conditions.  It also reads the assocations from the ActiveRecord model and applies them to the model as well.
+
+# hippo db
+
+## Migrate
+
+`hippo db migrate`
+
+Calls rake db:migrate for each extension that is loaded.  Since hippo extensions ship with migrations, this provides an easy way to install their data structures as well as keep them up to date.
+
+## Seed
+
+`hippo db seed`
+
+Calls rake db:seed for each extension that is loaded.  Often an extension will need to ship with certain default records.  This provides a way to provision them on install.  Commands can be placed in db/seeds.rb to be executed.

data/docs/model.md

@@ -0,0 +1,217 @@
+---
+title: Model
+heading: Hippo.Models.Base
+position_after: view
+---
+
+Hippo provides a Hippo.Models.Base class that all other models extend from.
+
+A Model is an extension of [Ampersand State](http://ampersandjs.com/docs#ampersand-state), and supports all the features that AmpersandState does.
+
+<aside class="note">
+Unlike the Models in Backbonejs, Hippo' Models track their "dirty" state.  This allows them to perform true HTTP "patch" requests and only send the attributes that have been modified to the server.  They can also be interogated and only saved if they contain unsaved data.
+</aside>
+
+Models also have associations, which are lazily instantiated and can be optionally fetched along with the model/collection.
+
+Model methods that make requests to the server can specify options to control what data is returned.  An explanation of the options can be found under [Request Options](#request-options)
+
+
+### API Reference
+
+# @where
+
+Load models from server that match the query. Returns [Collection](#@query)
+
+``` coffee
+class Person extends Hippo.Models.Base
+    props:
+        id: 'integer'
+        name: 'string'
+
+
+collection = Person.where( last_name: "smith" )
+````
+
+
+# @Collection
+
+A collection definition is provided for each model.
+
+Read more about [Request Options](#request-options)
+
+``` coffee
+class Person extends Hippo.Models.Base
+    props:
+        id: 'integer'
+        name: 'string'
+
+
+collection = Person.Collection.fetch(query:{ name: "John" }, limit: 10, with: [ 'address','photo' ] )
+````
+
+
+# initialize
+
+`new Model({options})`
+
+Called by the constructor after the models initialized.  Initialize can be used by to perform additional initialization of the class.
+
+If a collection reference is provided to initalize, it will be copied onto the model.
+
+# Model.fetch(id,options)
+
+Fetches and instantiates a record.  Is useful for when you all you know is the record's ID.  The identity map is consulted, and if the record is present there the existing copy is returned.
+
+``` coffee
+class Balance extends Hippo.Models.Base
+    props:
+        id: 'integer'
+        amount: 'bigdec'
+
+balance = new Balance(id: 10, amount:42.11)
+view = new MyApp.Views.Checkbook( model: balance )
+
+Balance.fetch(10) # retrieves balance from idmap
+Balance.fetch(11) # fetches balance with id 11 from server
+```
+
+# fetch(options)
+
+Retrieves the current state of the model from the server.  Options can be any of the valid
+[load options](#request-options)
+
+# save(options)
+
+Saves record state to server.  If options.saveAll is true, then the entire data set will be sent to the server, otherwise only modified fields are saved and a `PATCH` is performed.
+
+Save also saves it's associations along with itself.
+
+``` coffee
+class Car extends Hippo.Models.Base
+    associations:
+        driver: { model: Person }
+    props:
+        id: 'integer'
+        color: 'string'
+
+driver = new Driver(name: 'Jane')
+car = new Car(color: 'red', driver: driver )
+car.color = 'Blue'
+car.save() # will send { color: 'Blue', driver:{ name: 'Jane' } }
+```
+
+# destroy()
+
+Deletes the record from the server
+
+# set()
+
+Sets field and values.  Marks the fields as unsaved and the record as "dirty".  Can be invoked as either `set(field,value)` or `set({ field:value, field2:value2 })`
+
+# unsavedData()
+
+returns the field and values that have been modified and the unsavedData from associations as well.
+
+``` coffee
+class Car extends Hippo.Models.Base
+    associations:
+        driver: { model: Person }
+    props:
+        id: 'integer'
+        color: 'string'
+
+driver = new Driver(name: 'Jane')
+car = new Car()
+car.set(color: 'red', driver: driver)
+car.unsavedData() #  { color: 'Blue', driver:{ name: 'Jane' } }
+```
+
+# isDirty
+
+True if there are unsaved fields, false otherwise.  **Note**: this does not check
+associations, only fields that belong to the record itself.
+
+# hasAttribute(attr)
+
+Checks if the given field is defined on the Model.
+
+# errorMsg(field,value)
+
+Returns a string with an appropriate error message for setting the field to value.
+
+If the change is considered valid, an empty string is returned.
+
+The default implementation only checks the 'required' status of the field.  Models inheriting from `Hippo.Models.Base` may provide an alternative implementation.
+
+# withAssociations(list...)
+
+Loads any assocations in list if they are not already present.
+
+
+# Request Options
+
+The following options can be used with any method that make requests to the server.
+
+ * **with** use an exported query scope to limit records returned.
+ * **query** an array of objects to query the record with
+ * **include** an array of exported associations that should be included with the results.
+ * **fields** an array of fields (usually methods) to include in the result set.
+ * **order** an object containing fields and ASC/DESC strings.
+ * **limit** number of records to return
+ * **offset** to start query at row
+ * **format** If set to "array", the results will be returned as an array, otherwise stand JSON objects are returned.
+
+
+Given a server-side model such as:
+
+``` ruby
+class Invoice < Hippo::Model
+   belongs_to   :customer, export: true
+   has_many     :lines,    export: true
+   export_scope :payment_reference, lambda{ | value |
+       joins(:payments).where( payments: { amount: value } )
+   }
+   def trust_factor
+       return invoke_magic_formula
+   end
+   export_methods :trust_factor
+end
+```
+
+It can be queried by the client:
+
+``` coffee
+class Invoice extends Hippo.Models.Base
+    props:
+        id: 'integer'
+        total: 'bigdec'
+    session:
+        trust_factor: 'string'
+    associations:
+        customer: { model: Customer }
+        lines:    { collection: InvoiceLines }
+
+# Fetch the Invoice with id 1 and it's associated customer and lines.
+# The results from calling the "trust_factor" method will also be included
+Invoice.fetch({
+   include: ['customer','lines'],
+   fields: ['trust_factor']
+})
+
+# Fetch using the "payment_reference" scope on the model
+Invoice.where( with: { payment_reference: 'ABRACADABRA' } )
+
+# Fetch using an fairly complex adhoc query to find
+# all invoices by a customer who's name starts with "Bob"
+Invoice.where( query: { customer: { name: { value: 'Bob%', op: 'like' } )
+
+# A simple query to find records who's "tag" field is set to "GOOD"
+# 100 records will be returned, sorted by "name" and
+# will start at the 101st record
+Invoice.where(
+  query: {tag: 'GOOD'},
+  order: { name: 'DESC' },
+  limit: 100, start: 100
+)
+```

data/docs/react.md

@@ -0,0 +1,137 @@
+---
+title: React
+heading: Hippo.React.Component
+---
+
+Hippo uses [React](reactjs.com) for the view layer.  It provides an easy-to-use data bindings between it and the data layouer's {% doc_link model %}
+
+A simple example of a React component bound to a data model:
+
+``` coffee
+
+class MyView extends Hippo.React.Component
+
+    propTypes:
+        model: Hippo.PropTypes.Model.isRequired
+
+    render: ->
+        <h1>Hello {@model.name}</h1>
+
+```
+
+Note a few interesting things about this component compared to a standard React one.  The first is the non-standard "model" propType, and the second is the @model instance variable used in the `render` method.
+
+# propType validators
+
+As show above, Hippo provides validators for it's data types.  These include:
+
+
+  * `Hippo.PropTypes.Model` Verifies that the property is an instance of `Hippo.Models.Base`
+  * `Hippo.PropTypes.State` Checks that the property is an instance of `Hippo.Models.State`.  State objects are like models, but do not have the ability to be retreived from or saved to the server.  They're usefull for storing lightweight session objects.
+  * `Hippo.PropTypes.Collection` Like the models above but for collections.
+
+Each of the validators also has a `.isRequired` helper, just like React's built in ones.
+
+# dataObjects
+
+Hippo data bindings for components will be automatically setup for any prop that is named `model`.
+
+If a property named `model` is given, it will be mapped to the `@model` instance.  Other properties can also be setup by specifying attributes for `dataObject`  In this example, a '@bank` and `@customer` objects are mapped.
+
+``` coffee
+
+class MyView extends Hippo.React.Component
+
+    dataObjects:
+        bank: 'props'
+        customer: -> GlobalCustomer.lookup('foo')
+
+    render: ->
+        <h1>{@customer.name} has {@bank.balance}</h1>
+
+```
+
+As you can see, the bank mapping will be read from the props, while the customer uses a custom lookup strategy.  It's function will be called to obtain the value whenever the component is mounted.
+
+
+
+# events
+
+By default, Hippo will listen for all events on both models and collections.
+
+Every time the events fires, Hippo will call `setState` on the component, causing a re-render.  While React is great about making the re-render as efficient as possible, it can sometimes be a good idea to only listen for events that the compoent will be interested int.
+
+The events bound can be modified by using the `bindDataEvents` attribute.  For instance this component will only render when the name is changed.  This makes sense since that's the only attribute of the model that is used.
+
+
+``` coffee
+
+class MyView extends Hippo.React.Component
+
+    bindDataEvents:
+        model: 'change:name'
+
+
+    render: ->
+        <h1>Your name is: {@model.name}</h1>
+
+```
+
+The complete list of events Hippo listens to is:
+
+  * Models:
+    * `change`:   an attribute was modified
+    * `request`: A network request was began
+    * `sync`: The network request completed
+    * `invalid`: An attempted update failed validation
+    * `error`: An error was encountered, usually only fired during network access.
+  * Collections:
+    * `add`: A model was added
+    * `remove`: Model removed
+    * `change`: one of the models was changed
+    * `sort`: The collection was re-sorted
+    * `reset`: All models were removed
+    * `request`: A network request was started
+    * `sync`: Network request completed
+    * `error`: An error occured, usually during network access
+
+# setDataState
+
+When a bound event is fired for a model, Hippo will call setState on the model with the affected model as the key. Sometimes a component would rather have other information injected into state, or perhaps wants to selectively ignore some changes.
+
+Components can do so by implementing a `setDataState` method.  If this method exists, it is soley responsible for calling `setState` to trigger a `render`
+
+``` coffee
+
+class MyView extends Hippo.React.Component
+
+    setDataState: (newState) ->
+        if newState.model?.name == 'Bob'
+            this.setState(wasBob: true)
+
+    render: ->
+        <h1>Has Bob been seen? {if @state.wasBob then 'Yes' else 'No'}</h1>
+
+```
+
+# PubSub
+
+Publish/Subscribe often abbreviated as simply PubSub is a mechanism where amodel can subscribe to updates for itself and be notified when other users modify it.
+
+By default whenever a model is bound to a React component, Hippo will also subscribe that model to updates.  When model is unbound or the component is unmounted, Hippo will remove the model from receiving updates as well.  This applies only to Models, not State object or Collections.
+
+Set `pubsub: false` if Hippo should not bind any models, or to an object with keys for the models that should not be bound
+
+
+``` coffee
+
+class MyView extends Hippo.React.Component
+
+    pubsub:
+        model: false
+
+    # could also have just been:
+    pubsub: false
+
+
+```